# HubSpot

Source module: `app/connectors/hubspot.py`. Kind: **both** (declared; claims are not produced yet — see limitations). Display name: "HubSpot".

## Purpose

Reads ticket pipeline-stage history, meetings and deals as **facts** so that resolution, meeting-booked and lead-qualified outcomes can be checked against HubSpot. Intended to also ingest Breeze Customer Agent resolutions as claims when an export is available.

## Auth and scopes

| Item | Value |
|---|---|
| Method | Access token: a service key (Settings → Integrations → Service keys, the replacement for private apps on newer accounts) or a private app token, with read scopes only, sent as `Authorization: Bearer`, against `https://api.hubapi.com` |
| Credentials stored (encrypted) | `access_token`; optional `base_url` |
| Least-privilege scopes | **`tickets`** (read), **`crm.objects.deals.read`**, **`crm.objects.meetings.read`**, **`crm.objects.contacts.read`** (declared for email hashing; see limitations). No write scopes. |
| Connection test | `GET /crm/v3/objects/tickets?limit=1` |
| Non-secret config | none |

## Fields pulled and why

| Object / endpoint | Properties | Used for |
|---|---|---|
| `POST /crm/v3/objects/tickets/search` (filter `hs_lastmodifieddate GT since`) | `hs_pipeline_stage`, `createdate`, `hs_lastmodifieddate`, `closed_date`, `hs_ticket_priority`, `source_type` | Subject id, watermark, channel |
| `GET /crm/v3/objects/tickets/{id}?propertiesWithHistory=hs_pipeline_stage` | stage history (`value`, `timestamp`) | Status-change and reopen facts |
| `POST /crm/v3/objects/meetings/search` | `hs_meeting_outcome`, `hs_meeting_start_time`, `hs_timestamp` | Meeting facts |
| `POST /crm/v3/objects/deals/search` | `dealstage`, `closedate`, `hs_lastmodifieddate` | Opportunity-stage facts |

Ticket subject/content, notes, emails, calls, contact names and any other properties are not requested.

## What is hashed / never stored

- No raw identifiers are stored. The connector declares the contacts read scope for hashing contact emails, but the current implementation does not fetch contact records; facts from HubSpot therefore carry no `customer_hid` and link to other sources only by exact subject id.
- The access token is stored only as ciphertext.

## Incremental sync and watermark

- All three searches filter on `hs_lastmodifieddate > <watermark in epoch ms>` (0 on first sync), page size 100, cursor via `paging.next.after`.
- One additional request per ticket fetches the pipeline-stage history.
- Watermark = maximum ticket `hs_lastmodifieddate` (meetings and deals do not advance it).
- Upserts are idempotent.

## Rate-limit handling

Shared `HttpClient` (Retry-After, exponential backoff on `429`/`5xx`, 6 attempts, immediate `reauth` failure on `401`/`403`). HubSpot private apps have per-10-second and daily request limits; the per-ticket history request dominates.

## Fact types produced

| `fact_type` | Subject / kind | When | Attributes | `raw_ref` |
|---|---|---|---|---|
| `status_change` | `hubspot_ticket_{id}` / `ticket` | Each pipeline-stage history entry, in timestamp order | `from` (previous stage or null), `to` (stage id or name, lower-cased), `actor: "agent"`, `channel: <source_type>` | `hubspot:ticket:{id}:stage:{i}` |
| `reopen` | `hubspot_ticket_{id}` / `ticket` | Stage moves from `closed` or `4` (default closed stage id) to another stage | — | `hubspot:ticket:{id}:reopen:{i}` |
| `meeting_event` | `hubspot_meeting_{id}` / `customer` | Each meeting | `status: occurred` when `hs_meeting_outcome == completed`, otherwise the outcome value, or `scheduled` | `hubspot:meeting:{id}` |
| `opportunity_stage` | `hubspot_deal_{id}` / `opportunity` | Each deal (current stage) | `stage: <dealstage lower-cased>` | `hubspot:deal:{id}:{dealstage}` |

## Claims produced

None yet. Breeze Customer Agent resolutions must currently be uploaded via CSV mapped to `hubspot_breeze_customer_agent_resolution`, with `subject_id` values of the form `hubspot_ticket_{id}` so they match the facts above.

## Subject id format

`hubspot_ticket_{ticketId}`, `hubspot_meeting_{meetingId}`, `hubspot_deal_{dealId}`.

## Known limitations

- **No claims.** The connector is declared `kind = both`, but Breeze resolution export ingestion is not implemented.
- **No `customer_hid`.** Contact emails are not fetched, so HubSpot facts cannot be linked to other sources by hashed email; they link by exact subject id only.
- Pipeline stage values are HubSpot stage ids unless the portal uses labels; contracts that test `record_status_in: [closed, …]` need the closed stage to be literally `closed` or `4`. Map stages through a CSV upload if the portal uses custom ids.
- Meeting facts are keyed by meeting id, not by the associated contact or ticket; associations are not fetched, so a meeting cannot be linked to a lead claim without an explicit subject link.
- Deal stage facts record the current stage at sync time, not the full stage history; the `occurred_at` is the deal's `hs_lastmodifieddate`.
- No `customer_message`, `human_reply`, `escalation` or `csat_response` facts.