@particle-academy/hubspot-js 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -7,6 +7,75 @@ 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.6.0] — 2026-11-05
+
+### Added
+
+- **`contact_create` takes a `properties` map, as `company_create` and
+  `deal_create` do**, so a contact is created with ANY property (`jobtitle`,
+  an address, a custom property) in one call. Additive: the named fields
+  (Email, First name, Last name, Company, Phone, Lifecycle stage) work
+  exactly as before and merge into the map. `email` is still required, and
+  may be given in Email OR as `email` in Properties; missing from both, the
+  refusal names both places. The same property given both ways with
+  DIFFERENT values is refused by name rather than guessed. The editor no
+  longer marks Email required, because the map can satisfy it. Found by MOIC
+  (their #905): `properties` given the company_create way was refused as a
+  missing email.
+
+### Fixed
+
+- **PHP: a `properties` map passed as an OBJECT is read, not dropped.** The
+  generated PHP read a map that arrived as a decoded JSON OBJECT (`stdClass`,
+  e.g. an upstream node's value or `json_decode(..., false)`) as "not an
+  array" and sent it EMPTY, without an error: silent data loss. It now reads
+  the object's properties. **Affected:** PHP callers passing the map as an
+  object. **Not affected:** callers passing an array, which always worked;
+  they need do nothing. TypeScript and Python were never affected.
+- **`crm_event` no longer tells a host to dedupe on `eventId`.** HubSpot's
+  field table says `eventId` "is not guaranteed to be unique", so deduping on
+  it can drop a DIFFERENT event that shares one, such as two properties of one
+  deal changing together. The setup text and the `eventId` / `attemptNumber`
+  descriptions now say what a retry is: the same event resent, differing only
+  in `attemptNumber`, so a host compares every other field. Found by MOIC.
+- **The setup guidance now says a host does not copy this connector's scope
+  list into its consent URL.** The list covers every action, read and write.
+  HubSpot requires the scopes an app marks required in the authorize URL's
+  `scope` parameter and shows an error otherwise, so a read-only host asks for
+  its read scopes only. On the `accessToken` credential's help and in
+  `crm_event`'s setup. Found by MOIC. The list itself is unchanged.
+
+## [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

package/README.md

@@ -43,7 +43,7 @@ A HubSpot connection holds 4 values.
 |---|---|---|---|
 | **App client ID** | per installation | not secret | From your HubSpot app's Auth tab. ONE value for the whole installation -- the same app serves every connected account. |
 | **App client secret** | per installation | **secret** | From the same Auth tab. Used to exchange the code and to refresh; never sent with an API request. |
-| **Access token** | per connected account | **secret** | Obtained by the host's OAuth exchange, PER CONNECTED ACCOUNT. Expires after 30 minutes -- a host that does not refresh will work all afternoon and be broken by morning. |
+| **Access token** | per connected account | **secret** | Obtained by the host's OAuth exchange, PER CONNECTED ACCOUNT. Expires after 30 minutes -- a host that does not refresh will work all afternoon and be broken by morning. This connector's scope list covers every action, read and write, and is not what your consent URL must ask for: HubSpot requires your app's required scopes in the authorize URL's `scope` parameter and shows an error otherwise, so build it from your own app's configuration. A read-only host asks for its read scopes only. |
 | **Refresh token** *(optional)* | per connected account | **secret** | Also per account. Does not expire, so it is the credential worth protecting most: it mints access tokens indefinitely until the install is revoked. |
 
 ### Authorising
@@ -136,12 +136,13 @@ Create a contact in HubSpot.
 
 | Input | Required | What it is |
 |---|---|---|
-| `email` | yes | HubSpot de-duplicates contacts on email within an account. A contact created without one cannot be de-duplicated, and a retry will make a second. |
+| `email` | yes | HubSpot de-duplicates contacts on email within an account. A contact created without one cannot be de-duplicated, and a retry will make a second. Required here OR as email in Properties. |
 | `firstName` | no | First name |
 | `lastName` | no | Last name |
 | `company` | no | Company |
 | `phone` | no | Phone |
 | `lifecycleStage` | no | HubSpot's own stage names. A value it does not recognise is refused at write time, not at setup. |
+| `properties` | no | Any other HubSpot property name → value for the new contact (jobtitle, an address, a custom property), sent in the same call. Values are sent as strings, which is how HubSpot stores every property. The fields above merge into this map; email may be given here instead of in Email, and the same property given both ways with different values is refused rather than guessed. |
 
 #### `contact_get` — Get contact
 
@@ -285,6 +286,18 @@ Every property defined on deals, contacts or companies: name, label, type and th
 |---|---|---|
 | `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. HubSpot retries a failed delivery, and eventId is not guaranteed to be unique, so never dedupe on eventId alone: a retry is the same event resent, differing only in attemptNumber, so compare every other field. This connector's scope list covers every action, read and write, and is not what your consent URL must ask for: HubSpot requires your app's required scopes in the authorize URL's `scope` parameter and shows an error otherwise, so build it from your own app's configuration. A read-only host asks for its read scopes only.
+
 ## Run it before you have credentials
 
 Every operation ships a **faker**, whether or not HubSpot has a sandbox. Set a

package/dist/{chunk-FFT5OGGS.js → chunk-AVMPFAVL.js}

@@ -1,4 +1,4 @@
-import { callConnector } from '@particle-academy/fancy-connector-core';
+import { callConnector, verifyDelivery } from '@particle-academy/fancy-connector-core';
 
 // src/faker.ts
 function fakeCompanyCreate({ config, fake }) {
@@ -392,6 +392,37 @@ function fakePropertyList({ config, fake }) {
     ]
   };
 }
+function fakeCrmEvent({ config, fake }) {
+  return [
+    {
+      "eventId": 531833541,
+      "subscriptionId": 3923621,
+      "portalId": 48807704,
+      "appId": 16111050,
+      "occurredAt": 1752613920733,
+      "subscriptionType": "contact.creation",
+      "attemptNumber": 0,
+      "objectId": 138017612137,
+      "changeFlag": "CREATED",
+      "changeSource": "CRM_UI",
+      "sourceId": "userId:76023669"
+    },
+    {
+      "eventId": 531833542,
+      "subscriptionId": 3923622,
+      "portalId": 48807704,
+      "appId": 16111050,
+      "occurredAt": 1752613921e3,
+      "subscriptionType": "deal.propertyChange",
+      "attemptNumber": 0,
+      "objectId": 9876543210,
+      "propertyName": "dealstage",
+      "propertyValue": "closedwon",
+      "changeSource": "CRM_UI",
+      "sourceId": "userId:76023669"
+    }
+  ];
+}
 var hubspotFaker = (operation, request) => {
   switch (operation) {
     case "company_create":
@@ -430,6 +461,8 @@ var hubspotFaker = (operation, request) => {
       return fakePipelineList(request);
     case "property_list":
       return fakePropertyList(request);
+    case "crm_event":
+      return fakeCrmEvent(request);
     default:
       throw new Error(
         `hubspot: no fake response is defined for "${operation}". Add a fixture under provider/fixtures/ and regenerate \u2014 a connector without a faker cannot be developed against, tested, or demonstrated.`
@@ -640,8 +673,44 @@ function propertiesMap2(value) {
 var CONTACT_CREATE_OPERATION = "contact_create";
 async function hubspotContactCreate(options) {
   const config = options.config ?? {};
-  if (config.email === void 0 || config.email === null || config.email === "") {
-    throw new Error(`contact_create: "email" is required (Email).`);
+  if ((config.email === void 0 || config.email === null || config.email === "") && propertiesMap3(config.properties)["email"] === void 0) {
+    throw new Error(`contact_create: "email" is required \u2014 as Email, or as "email" in Properties.`);
+  }
+  {
+    const inMap = propertiesMap3(config.properties)["email"];
+    if (config.email !== void 0 && config.email !== null && config.email !== "" && inMap !== void 0 && inMap !== String(config.email).trim()) {
+      throw new Error(`contact_create: "email" was given twice with different values \u2014 as Email and as "email" in Properties.`);
+    }
+  }
+  {
+    const inMap = propertiesMap3(config.properties)["firstname"];
+    if (config.firstName !== void 0 && config.firstName !== null && config.firstName !== "" && inMap !== void 0 && inMap !== String(config.firstName)) {
+      throw new Error(`contact_create: "firstName" was given twice with different values \u2014 as First name and as "firstname" in Properties.`);
+    }
+  }
+  {
+    const inMap = propertiesMap3(config.properties)["lastname"];
+    if (config.lastName !== void 0 && config.lastName !== null && config.lastName !== "" && inMap !== void 0 && inMap !== String(config.lastName)) {
+      throw new Error(`contact_create: "lastName" was given twice with different values \u2014 as Last name and as "lastname" in Properties.`);
+    }
+  }
+  {
+    const inMap = propertiesMap3(config.properties)["company"];
+    if (config.company !== void 0 && config.company !== null && config.company !== "" && inMap !== void 0 && inMap !== String(config.company)) {
+      throw new Error(`contact_create: "company" was given twice with different values \u2014 as Company and as "company" in Properties.`);
+    }
+  }
+  {
+    const inMap = propertiesMap3(config.properties)["phone"];
+    if (config.phone !== void 0 && config.phone !== null && config.phone !== "" && inMap !== void 0 && inMap !== String(config.phone)) {
+      throw new Error(`contact_create: "phone" was given twice with different values \u2014 as Phone and as "phone" in Properties.`);
+    }
+  }
+  {
+    const inMap = propertiesMap3(config.properties)["lifecyclestage"];
+    if (config.lifecycleStage !== void 0 && config.lifecycleStage !== null && config.lifecycleStage !== "" && inMap !== void 0 && inMap !== String(config.lifecycleStage)) {
+      throw new Error(`contact_create: "lifecycleStage" was given twice with different values \u2014 as Lifecycle stage and as "lifecyclestage" in Properties.`);
+    }
   }
   return callConnector(HUBSPOT, {
     operation: CONTACT_CREATE_OPERATION,
@@ -655,15 +724,15 @@ async function hubspotContactCreate(options) {
     request: {
       method: "POST",
       path: "/crm/v3/objects/contacts",
-      json: nestFields({
-        "properties.email": String(config.email).trim(),
+      json: mergeInto(nestFields({
+        ...config.email !== void 0 && config.email !== null && config.email !== "" ? { "properties.email": String(config.email).trim() } : {},
         ...config.firstName !== void 0 && config.firstName !== null && config.firstName !== "" ? { "properties.firstname": String(config.firstName) } : {},
         ...config.lastName !== void 0 && config.lastName !== null && config.lastName !== "" ? { "properties.lastname": String(config.lastName) } : {},
         ...config.company !== void 0 && config.company !== null && config.company !== "" ? { "properties.company": String(config.company) } : {},
         ...config.phone !== void 0 && config.phone !== null && config.phone !== "" ? { "properties.phone": String(config.phone) } : {},
         ...config.lifecycleStage !== void 0 && config.lifecycleStage !== null && config.lifecycleStage !== "" ? { "properties.lifecyclestage": String(config.lifecycleStage) } : {},
         "associations": []
-      })
+      }), "properties", propertiesMap3(config.properties))
     }
   });
 }
@@ -682,6 +751,18 @@ function nestFields(flat) {
   }
   return out;
 }
+function mergeInto(body, key, map) {
+  const named = body[key];
+  return { ...body, [key]: { ...map, ...named !== null && typeof named === "object" ? named : {} } };
+}
+function propertiesMap3(value) {
+  if (!value || typeof value !== "object") return {};
+  const out = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (item !== void 0 && item !== null && item !== "") out[key] = String(item);
+  }
+  return out;
+}
 var CONTACT_GET_OPERATION = "contact_get";
 async function hubspotContactGet(options) {
   const config = options.config ?? {};
@@ -815,12 +896,12 @@ async function hubspotContactUpdate(options) {
       method: "PATCH",
       path: `/crm/v3/objects/contacts/${encodeURIComponent(String(config.contactId))}`,
       json: {
-        "properties": propertiesMap3(config.properties)
+        "properties": propertiesMap4(config.properties)
       }
     }
   });
 }
-function propertiesMap3(value) {
+function propertiesMap4(value) {
   if (!value || typeof value !== "object") return {};
   const out = {};
   for (const [key, item] of Object.entries(value)) {
@@ -847,13 +928,13 @@ async function hubspotDealCreate(options) {
       method: "POST",
       path: "/crm/v3/objects/deals",
       json: {
-        "properties": propertiesMap4(config.properties),
+        "properties": propertiesMap5(config.properties),
         "associations": []
       }
     }
   });
 }
-function propertiesMap4(value) {
+function propertiesMap5(value) {
   if (!value || typeof value !== "object") return {};
   const out = {};
   for (const [key, item] of Object.entries(value)) {
@@ -994,12 +1075,12 @@ async function hubspotDealUpdate(options) {
       method: "PATCH",
       path: `/crm/v3/objects/deals/${encodeURIComponent(String(config.dealId))}`,
       json: {
-        "properties": propertiesMap5(config.properties)
+        "properties": propertiesMap6(config.properties)
       }
     }
   });
 }
-function propertiesMap5(value) {
+function propertiesMap6(value) {
   if (!value || typeof value !== "object") return {};
   const out = {};
   for (const [key, item] of Object.entries(value)) {
@@ -1080,7 +1161,34 @@ async function hubspotPropertyList(options) {
     }
   });
 }
+var HUBSPOT_CRM_EVENT_SIGNATURE_HEADER = "X-HubSpot-Signature-v3";
+var HUBSPOT_CRM_EVENT_TOLERANCE = 300;
+var HUBSPOT_CRM_EVENT_SCHEME = {
+  algorithm: "SHA-256",
+  payload: (raw, timestamp, _id, request) => `${request?.method ?? ""}${request?.uri ?? ""}${raw}${timestamp}`,
+  tolerance: HUBSPOT_CRM_EVENT_TOLERANCE,
+  timestampUnit: "ms",
+  signsRequestLine: true,
+  uri: "hubspot-v3",
+  encoding: "base64"
+};
+var HUBSPOT_CRM_EVENT = {
+  service: "hubspot",
+  operation: "crm_event",
+  delivery: "webhook",
+  setup: "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. HubSpot retries a failed delivery, and eventId is not guaranteed to be unique, so never dedupe on eventId alone: a retry is the same event resent, differing only in attemptNumber, so compare every other field. This connector's scope list covers every action, read and write, and is not what your consent URL must ask for: HubSpot requires your app's required scopes in the authorize URL's `scope` parameter and shows an error otherwise, so build it from your own app's configuration. A read-only host asks for its read scopes only.",
+  verification: {
+    signatureHeader: HUBSPOT_CRM_EVENT_SIGNATURE_HEADER,
+    scheme: HUBSPOT_CRM_EVENT_SCHEME,
+    timestampHeader: "X-HubSpot-Request-Timestamp"
+  },
+  route: { by: "portalId", path: "[].portalId" },
+  faker: hubspotFaker
+};
+function verifyHubspotDelivery(delivery, clientSecret, now) {
+  return verifyDelivery(HUBSPOT_CRM_EVENT, delivery, clientSecret, now);
+}
 
-export { COMPANY_CREATE_OPERATION, COMPANY_GET_OPERATION, COMPANY_LIST_OPERATION, COMPANY_SEARCH_OPERATION, COMPANY_UPDATE_OPERATION, CONNECTOR_API_VERSION, CONTACT_CREATE_OPERATION, CONTACT_GET_OPERATION, CONTACT_LIST_OPERATION, CONTACT_SEARCH_OPERATION, CONTACT_UPDATE_OPERATION, DEAL_CREATE_OPERATION, DEAL_GET_OPERATION, DEAL_LIST_OPERATION, DEAL_SEARCH_OPERATION, DEAL_UPDATE_OPERATION, HUBSPOT, HUBSPOT_BASE_URLS, HUBSPOT_REQUIRES, OWNER_LIST_OPERATION, PIPELINE_LIST_OPERATION, PROPERTY_LIST_OPERATION, hubspotAuthorize, hubspotCompanyCreate, hubspotCompanyGet, hubspotCompanyList, hubspotCompanySearch, hubspotCompanyUpdate, hubspotContactCreate, hubspotContactGet, hubspotContactList, hubspotContactSearch, hubspotContactUpdate, hubspotDealCreate, hubspotDealGet, hubspotDealList, hubspotDealSearch, hubspotDealUpdate, hubspotFaker, hubspotOwnerList, hubspotPipelineList, hubspotPropertyList };
-//# sourceMappingURL=chunk-FFT5OGGS.js.map
-//# sourceMappingURL=chunk-FFT5OGGS.js.map
+export { COMPANY_CREATE_OPERATION, COMPANY_GET_OPERATION, COMPANY_LIST_OPERATION, COMPANY_SEARCH_OPERATION, COMPANY_UPDATE_OPERATION, CONNECTOR_API_VERSION, CONTACT_CREATE_OPERATION, CONTACT_GET_OPERATION, CONTACT_LIST_OPERATION, CONTACT_SEARCH_OPERATION, CONTACT_UPDATE_OPERATION, DEAL_CREATE_OPERATION, DEAL_GET_OPERATION, DEAL_LIST_OPERATION, DEAL_SEARCH_OPERATION, DEAL_UPDATE_OPERATION, HUBSPOT, HUBSPOT_BASE_URLS, HUBSPOT_CRM_EVENT, HUBSPOT_CRM_EVENT_SCHEME, HUBSPOT_CRM_EVENT_SIGNATURE_HEADER, HUBSPOT_CRM_EVENT_TOLERANCE, HUBSPOT_REQUIRES, OWNER_LIST_OPERATION, PIPELINE_LIST_OPERATION, PROPERTY_LIST_OPERATION, hubspotAuthorize, hubspotCompanyCreate, hubspotCompanyGet, hubspotCompanyList, hubspotCompanySearch, hubspotCompanyUpdate, hubspotContactCreate, hubspotContactGet, hubspotContactList, hubspotContactSearch, hubspotContactUpdate, hubspotDealCreate, hubspotDealGet, hubspotDealList, hubspotDealSearch, hubspotDealUpdate, hubspotFaker, hubspotOwnerList, hubspotPipelineList, hubspotPropertyList, verifyHubspotDelivery };
+//# sourceMappingURL=chunk-AVMPFAVL.js.map
+//# sourceMappingURL=chunk-AVMPFAVL.js.map