feat: add HubSpot action

[nicosammito]

Summary

Adds a HubSpot CRM action so Hercules flows can react to HubSpot webhooks and drive CRM records (create/update/search/associate/annotate). Implements issue #41, mirroring the existing actions' conventions (shopify-action for Rest webhook triggers; gls-action/twilio-action for functions, config, and helpers.ts).

SDK / schema source (rule 1)

Uses the official @hubspot/api-client ^14 SDK for all API logic. HubSpot CRM objects (contacts, deals, companies, notes) all share the SDK's SimplePublicObject envelope (id, properties, timestamps, archived), so the object data types are modeled once on that shape and reused rather than hand-duplicated per object. Every API response is validated with zod .parse() before being returned to a flow.

Triggers (4, extends Rest)

• HubSpotContactCreatedWebhook — contact.creation
• HubSpotDealCreatedWebhook — deal.creation
• HubSpotDealStageChangedWebhook — deal.propertyChange on dealstage
• HubSpotFormSubmittedWebhook — form submission (lead capture)

Functions (9)

hubspotCreateContact, hubspotUpdateContact, hubspotGetContactByEmail, hubspotCreateDeal, hubspotUpdateDeal, hubspotCreateCompany, hubspotAddNote, hubspotAssociate, hubspotSearchObjects.

Data types (6)

HUBSPOT_CONTACT, HUBSPOT_DEAL, HUBSPOT_COMPANY, HUBSPOT_NOTE, HUBSPOT_SEARCH_RESULT, HUBSPOT_WEBHOOK_EVENT.

Config

access_token (required, Bearer private-app token), app_id (optional), client_secret (optional, for webhook signature validation).

Registration

Added hubspot-action to .node-actions in .gitlab-ci.yml and a row to the root README.md "Available Actions" table.

Design choices (noted)

• HubSpot properties are a dynamic key/value bag, so functions accept extra properties as a JSON object string parameter (coerced to strings) rather than a fixed set of typed parameters.
• hubspotAssociate uses the v4 default-association endpoint (createDefault) to avoid hard-coding version-specific association type ids.

Validation

Run in actions/hubspot-action/:

• npm install — OK (210 packages)
• npm run typecheck — ✅ PASS (0 errors; typechecks against the real @hubspot/api-client@14 types, confirming the SDK method paths)
• npm run build — ✅ PASS (dist/index.js, 33.7 kB)
• npm run test — ✅ PASS (8/8 vitest specs)

Note

⚠️ AI-generated — needs human review before merging.

One follow-up required: package-lock.json was generated locally but is not in this commit (too large to include via the automation). CI's test-node job runs npm ci, which requires it — please run npm install in actions/hubspot-action/ and commit the lockfile before merge.

Closes #41

[github-actions]

GitLab Pipeline Action

General information

Link to pipeline: https://gitlab.com/code0-tech/development/centaurus/-/pipelines/2701104114

Status: Failed
Duration: 3 minutes

Job summaries

docs:preview

Documentation preview available at https://code0-tech.gitlab.io/-/development/telescopium/-/jobs/15504651190/artifacts/out/index.html