@particle-academy/hubspot-js 0.3.3 → 0.4.0

package/CHANGELOG.md

@@ -7,6 +7,42 @@ 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.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
+
+- **Requires `fancy-connector-core` ≥ 0.4.0** — `particle-academy/fancy-connector-core` for php, `@particle-academy/fancy-connector-core` for js. The flow executors now pass a provider's declared `idempotencyMaxLength` through to the core's key derivation, and a named argument an older core does not accept is a fatal rather than a no-op, so the floor moves with it. This connector declares no limit and passes nothing, so nothing else changes for it; the bump is the floor alone.
+
 ## [0.3.3] — 2026-09-11
 
 ### Added

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,148 @@ 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 |
+
 ## 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>