@particle-academy/hubspot-js 0.3.4 → 0.5.0

package/CHANGELOG.md

@@ -7,6 +7,67 @@ The four packages share one version, because they are generated from one
 `provider/` definition and a version that meant something different in each
 would be a version nobody could reason about.
 
+## [0.5.0] — 2026-11-01
+
+### Added
+
+- **`crm_event`: HubSpot's CRM webhooks, verified.** HubSpot pushes a BATCH of
+  events (deal, contact and company created, property changed, deleted,
+  merged, restored, re-associated; which ones is set in the HubSpot app) to
+  the app's target URL. Each delivery is verified with **signature v3**
+  before anything reads it: base64 HMAC-SHA256 of method + URI + body +
+  timestamp under the app's `clientSecret`. The timestamp
+  (`X-HubSpot-Request-Timestamp`) is in MILLISECONDS, with a 5-minute window,
+  and the URI has only its query percent-decoded. HubSpot's own published
+  example verifies in TypeScript, PHP and Python; a changed byte, another
+  method, a late delivery and a missing request line are each refused.
+- **The host must pass the request line.** `verifyHubspotDelivery({raw,
+  headers, method, url})` (js), `CrmEvent::verifyDelivery($raw, $headers,
+  $secret, method: …, url: …)` (php) and `verify_delivery(raw, headers,
+  secret, method=…, url=…)` (python) take the URL exactly as it arrived.
+  Without them a delivery is refused by name, never verified with a gap.
+- **Routing is DECLARED** (`route: {by: "portalId", path: "[].portalId"}`,
+  on the descriptor, as `ROUTE`, and in the registry index). One URL serves
+  every portal that installed the app, so route each event by `portalId`
+  ONLY after the signature verifies, and only to a connection minted when
+  that portal installed. Drop an unmapped portal with a 2xx and a log line,
+  and create nothing.
+
+### Changed
+
+- **Requires `fancy-connector-core` ≥ 0.12.0**, which verifies a signed
+  request line and millisecond timestamps.
+
+## [0.4.0] — 2026-11-01
+
+### Added
+
+- **The CRM core, read and write: 17 new actions.** For deals, contacts and
+  companies:
+  - `*_search`: property `filterGroups` and `sorts` (nested JSON), a text
+    `query`, the properties to return, and HubSpot's `after` cursor;
+  - `*_list`: page through every record, with `after` in and
+    `paging.next.after` out;
+  - `*_get`: one record, with `associations` when asked;
+  - `deal_create` and `company_create`;
+  - `*_update`: a PATCH of the given properties, declared `idempotent`.
+
+  `contact_create` is unchanged, because saved workflows depend on its
+  fields. Alongside them: `owner_list` (owner ids are NOT user ids; both are
+  published), `pipeline_list` (every deal pipeline with its stages in order)
+  and `property_list` (the property definitions of deals, contacts or
+  companies). Record ids are numeric STRINGS in every runtime.
+
+### Changed
+
+- **Scopes:** the CRM core's read and write scopes for the three objects,
+  plus `crm.objects.owners.read` and `crm.schemas.*.read`. An installation made
+  under 0.3.x granted only `crm.objects.contacts.write`, so it **must be
+  re-authorised** before any new action works.
+- **Drift now checks every action against HubSpot's own v3 documents:**
+  Contacts, Companies, Deals, Owners, Pipelines and Properties. That needs
+  the six documents, because HubSpot publishes the CRM one area per document.
+
 ## [0.3.4] — 2026-09-12
 
 ### Changed

package/README.md

@@ -1,5 +1,7 @@
 # HubSpot
 
+[![Fancified](art/fancified.svg)](https://particle.academy)
+
 HubSpot for [fancy-flow][flow] — as **four imported, versioned packages**, one
 per runtime. Not vendored source: a copy cannot be upgraded, and third-party APIs
 change.
@@ -50,7 +52,7 @@ HubSpot uses OAuth2 (authorization_code). The package DECLARES the exchange; the
 
 - **Authorize URL** — https://app.hubspot.com/oauth/authorize
 - **Token URL** — https://api.hubapi.com/oauth/v1/token
-- **Scopes** — `crm.objects.contacts.write`
+- **Scopes** — `crm.objects.contacts.read`, `crm.objects.contacts.write`, `crm.objects.companies.read`, `crm.objects.companies.write`, `crm.objects.deals.read`, `crm.objects.deals.write`, `crm.objects.owners.read`, `crm.schemas.contacts.read`, `crm.schemas.companies.read`, `crm.schemas.deals.read`
 - **Access token lifetime** — 1800 seconds (30 minutes). A host that never refreshes works all afternoon and is broken by morning.
 
 The refresh tokens do **not** rotate: the same one is reusable, so a refresh may safely be retried and may run concurrently. Stated rather than assumed, because the opposite — a provider that spends the token and revokes the grant on a replay — looks identical until it happens.
@@ -65,6 +67,67 @@ HubSpot has a test estate on the same host, reached with credentials from a SEPA
 
 ### Actions
 
+#### `company_create` — Create company
+
+Create a company in HubSpot.
+
+`POST /crm/v3/objects/companies` · **unsafe to replay** — a retried durable run does it TWICE
+
+| Input | Required | What it is |
+|---|---|---|
+| `properties` | yes | HubSpot property name → value for the new company. Values are sent as strings, which is how HubSpot stores every property. |
+
+#### `company_get` — Get company
+
+Read one company, with its associations when asked.
+
+`GET /crm/v3/objects/companies/{companyId}` · reads only — safe to replay
+
+| Input | Required | What it is |
+|---|---|---|
+| `companyId` | yes | The company's HubSpot id (a numeric string). |
+| `properties` | no | Comma-separated property names to return. HubSpot returns a small default set otherwise. |
+| `associations` | no | Comma-separated object types whose associated ids to return. |
+
+#### `company_list` — List companies
+
+Page through every company in the portal.
+
+`GET /crm/v3/objects/companies` · reads only — safe to replay
+
+| Input | Required | What it is |
+|---|---|---|
+| `limit` | no | How many records per page, 1 to 100. HubSpot's own default is 10. |
+| `after` | no | The cursor from the previous page's paging.next.after. Leave empty for the first page. |
+| `properties` | no | Comma-separated property names to return. HubSpot returns a small default set otherwise. |
+| `associations` | no | Comma-separated object types whose associated ids to return. |
+
+#### `company_search` — Search companies
+
+Find companies by property filters, sorts or a text query.
+
+`POST /crm/v3/objects/companies/search` · reads only — safe to replay
+
+| Input | Required | What it is |
+|---|---|---|
+| `filterGroups` | no | HubSpot's filterGroups: groups are ORed, filters inside a group are ANDed. Example: [{"filters":[{"propertyName":"amount","operator":"GT","value":"1000"}]}]. |
+| `sorts` | no | Example: [{"propertyName":"createdate","direction":"DESCENDING"}]. |
+| `query` | no | Searches the object's default text properties. |
+| `properties` | no | Comma-separated property names to return. |
+| `limit` | no | 1 to 200. |
+| `after` | no | The cursor from the previous page's paging.next.after. |
+
+#### `company_update` — Update company
+
+Change properties on an existing company.
+
+`PATCH /crm/v3/objects/companies/{companyId}` · idempotent — safe to replay
+
+| Input | Required | What it is |
+|---|---|---|
+| `companyId` | yes | The company's HubSpot id (a numeric string). |
+| `properties` | yes | HubSpot property name → value for the company. Values are sent as strings, which is how HubSpot stores every property. |
+
 #### `contact_create` — Create contact
 
 Create a contact in HubSpot.
@@ -80,6 +143,160 @@ Create a contact in HubSpot.
 | `phone` | no | Phone |
 | `lifecycleStage` | no | HubSpot's own stage names. A value it does not recognise is refused at write time, not at setup. |
 
+#### `contact_get` — Get contact
+
+Read one contact, with its associations when asked.
+
+`GET /crm/v3/objects/contacts/{contactId}` · reads only — safe to replay
+
+| Input | Required | What it is |
+|---|---|---|
+| `contactId` | yes | The contact's HubSpot id (a numeric string). |
+| `properties` | no | Comma-separated property names to return. HubSpot returns a small default set otherwise. |
+| `associations` | no | Comma-separated object types whose associated ids to return. |
+
+#### `contact_list` — List contacts
+
+Page through every contact in the portal.
+
+`GET /crm/v3/objects/contacts` · reads only — safe to replay
+
+| Input | Required | What it is |
+|---|---|---|
+| `limit` | no | How many records per page, 1 to 100. HubSpot's own default is 10. |
+| `after` | no | The cursor from the previous page's paging.next.after. Leave empty for the first page. |
+| `properties` | no | Comma-separated property names to return. HubSpot returns a small default set otherwise. |
+| `associations` | no | Comma-separated object types whose associated ids to return. |
+
+#### `contact_search` — Search contacts
+
+Find contacts by property filters, sorts or a text query.
+
+`POST /crm/v3/objects/contacts/search` · reads only — safe to replay
+
+| Input | Required | What it is |
+|---|---|---|
+| `filterGroups` | no | HubSpot's filterGroups: groups are ORed, filters inside a group are ANDed. Example: [{"filters":[{"propertyName":"amount","operator":"GT","value":"1000"}]}]. |
+| `sorts` | no | Example: [{"propertyName":"createdate","direction":"DESCENDING"}]. |
+| `query` | no | Searches the object's default text properties. |
+| `properties` | no | Comma-separated property names to return. |
+| `limit` | no | 1 to 200. |
+| `after` | no | The cursor from the previous page's paging.next.after. |
+
+#### `contact_update` — Update contact
+
+Change properties on an existing contact.
+
+`PATCH /crm/v3/objects/contacts/{contactId}` · idempotent — safe to replay
+
+| Input | Required | What it is |
+|---|---|---|
+| `contactId` | yes | The contact's HubSpot id (a numeric string). |
+| `properties` | yes | HubSpot property name → value for the contact. Values are sent as strings, which is how HubSpot stores every property. |
+
+#### `deal_create` — Create deal
+
+Create a deal in HubSpot.
+
+`POST /crm/v3/objects/deals` · **unsafe to replay** — a retried durable run does it TWICE
+
+| Input | Required | What it is |
+|---|---|---|
+| `properties` | yes | HubSpot property name → value for the new deal. Values are sent as strings, which is how HubSpot stores every property. |
+
+#### `deal_get` — Get deal
+
+Read one deal, with its associations when asked.
+
+`GET /crm/v3/objects/deals/{dealId}` · reads only — safe to replay
+
+| Input | Required | What it is |
+|---|---|---|
+| `dealId` | yes | The deal's HubSpot id (a numeric string). |
+| `properties` | no | Comma-separated property names to return. HubSpot returns a small default set otherwise. |
+| `associations` | no | Comma-separated object types whose associated ids to return. |
+
+#### `deal_list` — List deals
+
+Page through every deal in the portal.
+
+`GET /crm/v3/objects/deals` · reads only — safe to replay
+
+| Input | Required | What it is |
+|---|---|---|
+| `limit` | no | How many records per page, 1 to 100. HubSpot's own default is 10. |
+| `after` | no | The cursor from the previous page's paging.next.after. Leave empty for the first page. |
+| `properties` | no | Comma-separated property names to return. HubSpot returns a small default set otherwise. |
+| `associations` | no | Comma-separated object types whose associated ids to return. |
+
+#### `deal_search` — Search deals
+
+Find deals by property filters, sorts or a text query.
+
+`POST /crm/v3/objects/deals/search` · reads only — safe to replay
+
+| Input | Required | What it is |
+|---|---|---|
+| `filterGroups` | no | HubSpot's filterGroups: groups are ORed, filters inside a group are ANDed. Example: [{"filters":[{"propertyName":"amount","operator":"GT","value":"1000"}]}]. |
+| `sorts` | no | Example: [{"propertyName":"createdate","direction":"DESCENDING"}]. |
+| `query` | no | Searches the object's default text properties. |
+| `properties` | no | Comma-separated property names to return. |
+| `limit` | no | 1 to 200. |
+| `after` | no | The cursor from the previous page's paging.next.after. |
+
+#### `deal_update` — Update deal
+
+Change properties on an existing deal.
+
+`PATCH /crm/v3/objects/deals/{dealId}` · idempotent — safe to replay
+
+| Input | Required | What it is |
+|---|---|---|
+| `dealId` | yes | The deal's HubSpot id (a numeric string). |
+| `properties` | yes | HubSpot property name → value for the deal. Values are sent as strings, which is how HubSpot stores every property. |
+
+#### `owner_list` — List owners
+
+Page through the portal's owners: the users records can be assigned to.
+
+`GET /crm/v3/owners` · reads only — safe to replay
+
+| Input | Required | What it is |
+|---|---|---|
+| `email` | no | Only the owner with this email. |
+| `limit` | no | How many records per page, 1 to 100. HubSpot's own default is 10. |
+| `after` | no | The cursor from the previous page's paging.next.after. Leave empty for the first page. |
+
+#### `pipeline_list` — List deal pipelines
+
+Every deal pipeline in the portal, with its stages in order.
+
+`GET /crm/v3/pipelines/deals` · reads only — safe to replay
+
+Takes no input.
+
+#### `property_list` — List property definitions
+
+Every property defined on deals, contacts or companies: name, label, type and the options of an enumeration.
+
+`GET /crm/v3/properties/{objectType}` · reads only — safe to replay
+
+| Input | Required | What it is |
+|---|---|---|
+| `objectType` | yes | Object |
+
+### Triggers
+
+#### `crm_event` — HubSpot CRM event
+
+Start when HubSpot reports deals, contacts or companies created, changed, deleted, merged, restored or re-associated.
+
+Delivered by webhook, and the signature is verified before anything runs.
+
+**You have to set this up with the provider first:**
+
+In the HubSpot app's webhook settings, set the target URL to the route your host mounts for this trigger and subscribe to the deal, contact and company events you want. Deliveries are signed with the app's client secret, already on the connection as `clientSecret`. ONE URL serves every portal that installed the app, so route each event by its portalId, and only after the signature has verified: map portalId to the connection created when that portal installed, and drop an unmapped portalId with a 2xx and a log line, creating nothing.
+
 ## Run it before you have credentials
 
 Every operation ships a **faker**, whether or not HubSpot has a sandbox. Set a

package/art/fancified.svg

@@ -0,0 +1,26 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="128" height="28" role="img" aria-label="Fancified — built with Fancy UI">
+  <title>Fancified · built with Fancy UI</title>
+  <defs>
+    <linearGradient id="fcdBg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#6d28d9"/>
+      <stop offset=".5" stop-color="#9333ea"/>
+      <stop offset="1" stop-color="#d946ef"/>
+    </linearGradient>
+    <linearGradient id="fcdGloss" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#ffffff" stop-opacity=".30"/>
+      <stop offset=".55" stop-color="#ffffff" stop-opacity="0"/>
+    </linearGradient>
+    <clipPath id="fcdClip"><rect width="128" height="28" rx="7"/></clipPath>
+  </defs>
+  <g clip-path="url(#fcdClip)">
+    <rect width="128" height="28" fill="url(#fcdBg)"/>
+    <rect width="34" height="28" fill="#3b0764" fill-opacity=".5"/>
+    <rect width="128" height="13" fill="url(#fcdGloss)"/>
+    <g fill="#fff">
+      <path transform="translate(17 14)" d="M0 -7 C.6 -2.2 2.2 -.6 7 0 C2.2 .6 .6 2.2 0 7 C-.6 2.2 -2.2 .6 -7 0 C-2.2 -.6 -.6 -2.2 0 -7 Z"/>
+      <path transform="translate(25.5 7.5) scale(.34)" fill-opacity=".85" d="M0 -7 C.6 -2.2 2.2 -.6 7 0 C2.2 .6 .6 2.2 0 7 C-.6 2.2 -2.2 .6 -7 0 C-2.2 -.6 -.6 -2.2 0 -7 Z"/>
+    </g>
+    <text x="81" y="18.5" fill="#ffffff" text-anchor="middle" font-family="'Segoe UI',Verdana,'DejaVu Sans',sans-serif" font-size="12" font-weight="700" letter-spacing=".3">Fancified</text>
+  </g>
+  <rect x=".5" y=".5" width="127" height="27" rx="6.5" fill="none" stroke="#ffffff" stroke-opacity=".22"/>
+</svg>