feat: add HubSpot action

.gitlab-ci.yml

@@ -25,6 +25,7 @@ include:
   - woocommerce-action
   - shopware-action
   - twilio-action
+  - hubspot-action
 
 test-node:
   image: node:24.10.0

README.md

@@ -7,6 +7,7 @@ The "central" place for all actions — a monorepo containing integrations provi
 | Action | Description |
 |--------|-------------|
 | [GLS](docs/Actions/GLS/overview.md) | GLS ShipIT integration for creating and managing shipments |
+| HubSpot | HubSpot CRM integration: webhooks for contacts/deals/companies plus create, update, search, associate, and note functions |
 
 ## ENV
 

actions/hubspot-action/.gitignore

@@ -0,0 +1,3 @@
+.env
+node_modules/
+dist/

actions/hubspot-action/Dockerfile

@@ -0,0 +1,13 @@
+FROM node:24.10.0-alpine
+
+WORKDIR /app
+
+COPY package.json package-lock.json* ./
+
+RUN npm install
+
+COPY . .
+
+RUN npm run build
+
+CMD ["npm", "run", "start"]

actions/hubspot-action/README.md

@@ -0,0 +1,81 @@
+# HubSpot Action
+
+HubSpot CRM integration for the **Hercules** automation platform. Lets flows
+react to HubSpot webhook events and create, update, search, associate, and
+annotate CRM records through the official
+[`@hubspot/api-client`](https://www.npmjs.com/package/@hubspot/api-client) SDK
+(HubSpot CRM v3 API).
+
+## Configuration
+
+Configured via the action's `ConfigurationDefinition`s:
+
+| Identifier | Type | Required | Description |
+|------------|------|----------|-------------|
+| `access_token` | TEXT | yes | Private-app access token (Bearer) for the HubSpot CRM API. |
+| `app_id` | TEXT | no | HubSpot app id, used when managing webhook subscriptions. |
+| `client_secret` | TEXT | no | HubSpot app client secret, used to validate the `X-HubSpot-Signature` on inbound webhooks. |
+
+Beyond the shared Hercules variables (`HERCULES_AUTH_TOKEN`,
+`HERCULES_AQUILA_URL`, `HERCULES_ACTION_ID`, `HERCULES_SDK_VERSION`), the only
+provider-specific credential required is the HubSpot private-app access token.
+
+### Creating a private app
+
+1. In HubSpot, go to **Settings → Integrations → Private Apps**.
+2. Create a private app and grant the CRM scopes you need
+   (`crm.objects.contacts.*`, `crm.objects.deals.*`, `crm.objects.companies.*`,
+   `crm.schemas.*`, and note/engagement scopes for `hubspotAddNote`).
+3. Copy the access token into the action's `access_token` config.
+
+### Webhooks (triggers)
+
+The triggers use the shared `Rest` (webhook) event pattern. Point a HubSpot app
+**webhook subscription** at the URL generated for the trigger. HubSpot delivers
+a JSON array of change events; each event is exposed to the flow as a
+`HUBSPOT_WEBHOOK_EVENT`. To verify signatures, configure `client_secret`.
+
+## Triggers
+
+| Identifier | Fires on |
+|------------|----------|
+| `HubSpotContactCreatedWebhook` | `contact.creation` |
+| `HubSpotDealCreatedWebhook` | `deal.creation` |
+| `HubSpotDealStageChangedWebhook` | `deal.propertyChange` on `dealstage` |
+| `HubSpotFormSubmittedWebhook` | form submission (lead capture) |
+
+## Functions
+
+| Identifier | Signature | Description |
+|------------|-----------|-------------|
+| `hubspotCreateContact` | `(Email, PropertiesJson?): HUBSPOT_CONTACT` | Create a contact. |
+| `hubspotUpdateContact` | `(ContactId, PropertiesJson): HUBSPOT_CONTACT` | Update a contact. |
+| `hubspotGetContactByEmail` | `(Email): HUBSPOT_CONTACT` | Look up a contact by email. |
+| `hubspotCreateDeal` | `(Name, Pipeline, Stage, Amount?, PropertiesJson?): HUBSPOT_DEAL` | Create a deal. |
+| `hubspotUpdateDeal` | `(DealId, PropertiesJson): HUBSPOT_DEAL` | Update a deal. |
+| `hubspotCreateCompany` | `(Name, PropertiesJson?): HUBSPOT_COMPANY` | Create a company. |
+| `hubspotAddNote` | `(Body, PropertiesJson?): HUBSPOT_NOTE` | Create a note engagement. |
+| `hubspotAssociate` | `(FromObjectType, FromId, ToObjectType, ToId): BOOLEAN` | Create the default association between two objects. |
+| `hubspotSearchObjects` | `(ObjectType, Query): HUBSPOT_SEARCH_RESULT` | Full-text search a CRM object type. |
+
+### Property maps
+
+HubSpot CRM properties are a dynamic key/value bag, so functions accept extra
+properties as a **JSON object string** (e.g.
+`{"firstname":"Ada","lifecyclestage":"lead"}`) rather than a fixed set of typed
+parameters. Values are coerced to strings, matching the HubSpot API.
+
+## Data types
+
+`HUBSPOT_CONTACT`, `HUBSPOT_DEAL`, `HUBSPOT_COMPANY`, `HUBSPOT_NOTE` (all share
+the SDK's `SimplePublicObject` envelope: `id`, `properties`, timestamps,
+`archived`), plus `HUBSPOT_SEARCH_RESULT` and `HUBSPOT_WEBHOOK_EVENT`.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm run build
+npm run test
+```

actions/hubspot-action/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@code0-tech/hubspot-action",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "build": "vite build",
+    "test": "vitest run",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@code0-tech/hercules": "^1.1.1",
+    "@hubspot/api-client": "^14.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.9.3",
+    "vite": "^8.0.3",
+    "vitest": "^4.1.10"
+  }
+}

actions/hubspot-action/src/data_types/hubspotCompany.ts

@@ -0,0 +1,12 @@
+import { DisplayMessage, Identifier, Name, Schema } from "@code0-tech/hercules";
+import { z } from "zod";
+import { hubSpotObjectSchema } from "./hubspotObjectBase.js";
+
+export const HubSpotCompanySchema = hubSpotObjectSchema();
+export type HubSpotCompany = z.infer<typeof HubSpotCompanySchema>;
+
+@Identifier("HUBSPOT_COMPANY")
+@Name({ code: "en-US", content: "HubSpot company" })
+@DisplayMessage({ code: "en-US", content: "HubSpot company" })
+@Schema(HubSpotCompanySchema)
+export class HubSpotCompanyDataType {}

actions/hubspot-action/src/data_types/hubspotContact.ts

@@ -0,0 +1,12 @@
+import { DisplayMessage, Identifier, Name, Schema } from "@code0-tech/hercules";
+import { z } from "zod";
+import { hubSpotObjectSchema } from "./hubspotObjectBase.js";
+
+export const HubSpotContactSchema = hubSpotObjectSchema();
+export type HubSpotContact = z.infer<typeof HubSpotContactSchema>;
+
+@Identifier("HUBSPOT_CONTACT")
+@Name({ code: "en-US", content: "HubSpot contact" })
+@DisplayMessage({ code: "en-US", content: "HubSpot contact" })
+@Schema(HubSpotContactSchema)
+export class HubSpotContactDataType {}

actions/hubspot-action/src/data_types/hubspotDeal.ts

@@ -0,0 +1,12 @@
+import { DisplayMessage, Identifier, Name, Schema } from "@code0-tech/hercules";
+import { z } from "zod";
+import { hubSpotObjectSchema } from "./hubspotObjectBase.js";
+
+export const HubSpotDealSchema = hubSpotObjectSchema();
+export type HubSpotDeal = z.infer<typeof HubSpotDealSchema>;
+
+@Identifier("HUBSPOT_DEAL")
+@Name({ code: "en-US", content: "HubSpot deal" })
+@DisplayMessage({ code: "en-US", content: "HubSpot deal" })
+@Schema(HubSpotDealSchema)
+export class HubSpotDealDataType {}

actions/hubspot-action/src/data_types/hubspotNote.ts

@@ -0,0 +1,12 @@
+import { DisplayMessage, Identifier, Name, Schema } from "@code0-tech/hercules";
+import { z } from "zod";
+import { hubSpotObjectSchema } from "./hubspotObjectBase.js";
+
+export const HubSpotNoteSchema = hubSpotObjectSchema();
+export type HubSpotNote = z.infer<typeof HubSpotNoteSchema>;
+
+@Identifier("HUBSPOT_NOTE")
+@Name({ code: "en-US", content: "HubSpot note" })
+@DisplayMessage({ code: "en-US", content: "HubSpot note" })
+@Schema(HubSpotNoteSchema)
+export class HubSpotNoteDataType {}

actions/hubspot-action/src/data_types/hubspotObjectBase.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+
+/**
+ * Base shape shared by all HubSpot CRM objects returned by the official
+ * `@hubspot/api-client` SDK (its `SimplePublicObject`): a stable `id`, a flat
+ * bag of string `properties`, lifecycle timestamps, and an `archived` flag.
+ *
+ * HubSpot CRM objects (contacts, deals, companies, notes, ...) all share this
+ * envelope and differ only in which property keys are populated, so we model
+ * the SDK's response type once and reuse it for every object data type rather
+ * than duplicating a near-identical schema per object.
+ */
+export const hubSpotObjectSchema = () =>
+    z.object({
+        id: z.string().describe("The unique HubSpot object id."),
+        properties: z
+            .record(z.string(), z.string().nullable())
+            .describe("Flat map of HubSpot property names to their (string) values."),
+        createdAt: z.string().nullable().optional().describe("ISO-8601 creation timestamp."),
+        updatedAt: z.string().nullable().optional().describe("ISO-8601 last-update timestamp."),
+        archived: z.boolean().nullable().optional().describe("Whether the object is archived."),
+    });
+
+export type HubSpotObject = z.infer<ReturnType<typeof hubSpotObjectSchema>>;

actions/hubspot-action/src/data_types/hubspotSearchResult.ts

@@ -0,0 +1,15 @@
+import { DisplayMessage, Identifier, Name, Schema } from "@code0-tech/hercules";
+import { z } from "zod";
+import { hubSpotObjectSchema } from "./hubspotObjectBase.js";
+
+export const HubSpotSearchResultSchema = z.object({
+    total: z.number().describe("Total number of objects matching the search."),
+    results: z.array(hubSpotObjectSchema()).describe("The page of matching objects."),
+});
+export type HubSpotSearchResult = z.infer<typeof HubSpotSearchResultSchema>;
+
+@Identifier("HUBSPOT_SEARCH_RESULT")
+@Name({ code: "en-US", content: "HubSpot search result" })
+@DisplayMessage({ code: "en-US", content: "HubSpot search result (${total} matches)" })
+@Schema(HubSpotSearchResultSchema)
+export class HubSpotSearchResultDataType {}

actions/hubspot-action/src/data_types/hubspotWebhookEvent.ts

@@ -0,0 +1,32 @@
+import { Identifier, Name, Schema } from "@code0-tech/hercules";
+import { z } from "zod";
+
+/**
+ * A single HubSpot app-webhook change event. HubSpot delivers webhook
+ * subscriptions as a JSON array of these event objects; the Rest trigger
+ * exposes the individual event to the flow. The schema is intentionally
+ * permissive (most fields optional) because the exact set of fields depends on
+ * the `subscriptionType` (property-change events carry `propertyName` /
+ * `propertyValue`, creation events do not).
+ * See https://developers.hubspot.com/docs/api/webhooks
+ */
+export const HubSpotWebhookEventSchema = z.object({
+    eventId: z.number().optional(),
+    subscriptionId: z.number().optional(),
+    portalId: z.number().optional(),
+    appId: z.number().optional(),
+    occurredAt: z.number().optional(),
+    subscriptionType: z.string().optional(),
+    attemptNumber: z.number().optional(),
+    objectId: z.number().optional(),
+    changeSource: z.string().optional(),
+    changeFlag: z.string().optional(),
+    propertyName: z.string().optional(),
+    propertyValue: z.string().optional(),
+});
+export type HubSpotWebhookEvent = z.infer<typeof HubSpotWebhookEventSchema>;
+
+@Identifier("HUBSPOT_WEBHOOK_EVENT")
+@Name({ code: "en-US", content: "HubSpot webhook event" })
+@Schema(HubSpotWebhookEventSchema)
+export class HubSpotWebhookEventDataType {}

actions/hubspot-action/src/events/hubspotContactCreatedWebhook.ts

@@ -0,0 +1,23 @@
+import { Description, DisplayIcon, DisplayMessage, EventSetting, Identifier, Name, Rest, Signature } from "@code0-tech/hercules";
+
+@Identifier("HubSpotContactCreatedWebhook")
+@DisplayIcon("simple:hubspot")
+@Name({ code: "en-US", content: "HubSpot contact created" })
+@Description({ code: "en-US", content: "Triggered when a new contact is created in HubSpot (subscription type contact.creation)." })
+@DisplayMessage({ code: "en-US", content: "HubSpot contact created on ${httpURL}" })
+@Signature("<A extends REST_AUTH_TYPE>(httpSchema: HTTP_SCHEMA, httpURL: HTTP_URL, httpMethod: HTTP_METHOD, httpAuth: A, httpAuthValue: REST_AUTH_VALUE<A>, input_schema?: HUBSPOT_WEBHOOK_EVENT): REST_ADAPTER_INPUT<HUBSPOT_WEBHOOK_EVENT>")
+@EventSetting({
+    identifier: "input_schema",
+    hidden: true
+})
+@EventSetting({
+    identifier: "httpMethod",
+    hidden: true,
+    defaultValue: "POST"
+})
+@EventSetting({
+    identifier: "httpSchema",
+    hidden: true,
+    defaultValue: "application/json"
+})
+export class HubSpotContactCreatedWebhook extends Rest {}

actions/hubspot-action/src/events/hubspotDealCreatedWebhook.ts

@@ -0,0 +1,23 @@
+import { Description, DisplayIcon, DisplayMessage, EventSetting, Identifier, Name, Rest, Signature } from "@code0-tech/hercules";
+
+@Identifier("HubSpotDealCreatedWebhook")
+@DisplayIcon("simple:hubspot")
+@Name({ code: "en-US", content: "HubSpot deal created" })
+@Description({ code: "en-US", content: "Triggered when a new deal is created in HubSpot (subscription type deal.creation)." })
+@DisplayMessage({ code: "en-US", content: "HubSpot deal created on ${httpURL}" })
+@Signature("<A extends REST_AUTH_TYPE>(httpSchema: HTTP_SCHEMA, httpURL: HTTP_URL, httpMethod: HTTP_METHOD, httpAuth: A, httpAuthValue: REST_AUTH_VALUE<A>, input_schema?: HUBSPOT_WEBHOOK_EVENT): REST_ADAPTER_INPUT<HUBSPOT_WEBHOOK_EVENT>")
+@EventSetting({
+    identifier: "input_schema",
+    hidden: true
+})
+@EventSetting({
+    identifier: "httpMethod",
+    hidden: true,
+    defaultValue: "POST"
+})
+@EventSetting({
+    identifier: "httpSchema",
+    hidden: true,
+    defaultValue: "application/json"
+})
+export class HubSpotDealCreatedWebhook extends Rest {}

actions/hubspot-action/src/events/hubspotDealStageChangedWebhook.ts

@@ -0,0 +1,23 @@
+import { Description, DisplayIcon, DisplayMessage, EventSetting, Identifier, Name, Rest, Signature } from "@code0-tech/hercules";
+
+@Identifier("HubSpotDealStageChangedWebhook")
+@DisplayIcon("simple:hubspot")
+@Name({ code: "en-US", content: "HubSpot deal stage changed" })
+@Description({ code: "en-US", content: "Triggered when a deal's stage changes in HubSpot (subscription type deal.propertyChange on dealstage)." })
+@DisplayMessage({ code: "en-US", content: "HubSpot deal stage changed on ${httpURL}" })
+@Signature("<A extends REST_AUTH_TYPE>(httpSchema: HTTP_SCHEMA, httpURL: HTTP_URL, httpMethod: HTTP_METHOD, httpAuth: A, httpAuthValue: REST_AUTH_VALUE<A>, input_schema?: HUBSPOT_WEBHOOK_EVENT): REST_ADAPTER_INPUT<HUBSPOT_WEBHOOK_EVENT>")
+@EventSetting({
+    identifier: "input_schema",
+    hidden: true
+})
+@EventSetting({
+    identifier: "httpMethod",
+    hidden: true,
+    defaultValue: "POST"
+})
+@EventSetting({
+    identifier: "httpSchema",
+    hidden: true,
+    defaultValue: "application/json"
+})
+export class HubSpotDealStageChangedWebhook extends Rest {}

actions/hubspot-action/src/events/hubspotFormSubmittedWebhook.ts

@@ -0,0 +1,23 @@
+import { Description, DisplayIcon, DisplayMessage, EventSetting, Identifier, Name, Rest, Signature } from "@code0-tech/hercules";
+
+@Identifier("HubSpotFormSubmittedWebhook")
+@DisplayIcon("simple:hubspot")
+@Name({ code: "en-US", content: "HubSpot form submitted" })
+@Description({ code: "en-US", content: "Triggered when a HubSpot form is submitted (lead capture). Delivered as a HubSpot webhook event." })
+@DisplayMessage({ code: "en-US", content: "HubSpot form submitted on ${httpURL}" })
+@Signature("<A extends REST_AUTH_TYPE>(httpSchema: HTTP_SCHEMA, httpURL: HTTP_URL, httpMethod: HTTP_METHOD, httpAuth: A, httpAuthValue: REST_AUTH_VALUE<A>, input_schema?: HUBSPOT_WEBHOOK_EVENT): REST_ADAPTER_INPUT<HUBSPOT_WEBHOOK_EVENT>")
+@EventSetting({
+    identifier: "input_schema",
+    hidden: true
+})
+@EventSetting({
+    identifier: "httpMethod",
+    hidden: true,
+    defaultValue: "POST"
+})
+@EventSetting({
+    identifier: "httpSchema",
+    hidden: true,
+    defaultValue: "application/json"
+})
+export class HubSpotFormSubmittedWebhook extends Rest {}

actions/hubspot-action/src/functions/hubspotAddNoteFunction.ts

@@ -0,0 +1,26 @@
+import {
+    Description, DisplayIcon, DisplayMessage, Documentation, FunctionContext,
+    Identifier, Name, Parameter, RuntimeError, Signature,
+} from "@code0-tech/hercules";
+import { addNote } from "../helpers.js";
+import { HubSpotNote } from "../data_types/hubspotNote.js";
+
+@Identifier("hubspotAddNote")
+@DisplayIcon("simple:hubspot")
+@Signature("(Body: string, PropertiesJson?: string): HUBSPOT_NOTE")
+@Name({ code: "en-US", content: "Add note" })
+@DisplayMessage({ code: "en-US", content: "Add HubSpot note" })
+@Documentation({ code: "en-US", content: "Creates a HubSpot note engagement with the given body. The note timestamp defaults to now. Extra properties may be passed as a JSON object string." })
+@Description({ code: "en-US", content: "Creates a HubSpot note." })
+@Parameter({ runtimeName: "Body", name: [{ code: "en-US", content: "Body" }], description: [{ code: "en-US", content: "The note text (hs_note_body)." }] })
+@Parameter({ runtimeName: "PropertiesJson", name: [{ code: "en-US", content: "Properties (JSON)" }], description: [{ code: "en-US", content: "Optional JSON object of additional note properties." }], optional: true })
+export class HubSpotAddNoteFunction {
+    async run(context: FunctionContext, Body: string, PropertiesJson?: string): Promise<HubSpotNote> {
+        try {
+            return await addNote(Body, PropertiesJson, context);
+        } catch (error) {
+            if (error instanceof RuntimeError) throw error;
+            throw new RuntimeError("ERROR_CREATING_HUBSPOT_NOTE", error instanceof Error ? error.message : "unknown error");
+        }
+    }
+}