feat: add hubspot action (#41)

Author: nicosammito

.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 {}