@hs-x/sdk

@hs-x/sdk is the authoring surface for HS-X, a type-safe HubSpot app framework that deploys to Cloudflare Workers. You import it to declare your app and its capabilities: workflow actions and agent tools, card backends, triggers, syncs, app objects, and app events. The hs-x CLI compiles those declarations into HubSpot project artifacts and a Cloudflare Worker, then deploys them into your own HubSpot developer app and your own Cloudflare account.

Install

bun add @hs-x/sdk @hs-x/runtime

These are the two dependencies an HS-X app lists; hs-x init scaffolds them for you. Backend code imports from @hs-x/sdk. Card code that runs inside a HubSpot iframe imports from @hs-x/sdk/ui.

Thirty seconds

An app is an hsx.config.ts plus one or more workers. This is the default scaffold, a workflow action that tags high-value deals:

// hsx.config.ts
import { defineApp } from "@hs-x/sdk";

export default defineApp({
  name: "deal-tagger",
  distribution: "private",
  auth: "oauth",
  platformVersion: "2026.03",
  scopes: ["crm.objects.deals.read", "crm.objects.deals.write"],
});

// src/workers/deals.ts
import { defineWorker, ok } from "@hs-x/sdk";

const worker = defineWorker("deals");

worker.tool("tag-high-value-deals", {
  label: "Tag high value deals",
  objectType: "deal",
  input: {
    threshold: { type: "number", label: "Amount threshold", default: 50000 },
  },
  output: {
    tagged: { type: "boolean" },
  },
  async handler({ input, enrolledObject }) {
    const amount = Number(enrolledObject.properties.amount ?? 0);
    return ok({ tagged: amount >= input.threshold });
  },
});

export default worker;

hs-x dev runs the local loop, hs-x dev invoke tag-high-value-deals exercises the handler through the same dispatch path a deployed Worker uses, and hs-x deploy ships it.

Exports

Declaration factories:

| Export | Declares | | --- | --- | | defineApp | The app: name, distribution, auth mode, platform version, scopes, cards, app objects/events (hsx.config.ts) | | defineWorker | A worker grouping; its builder methods (tool, action, cardBackend, trigger, sync, use) register capabilities | | tool | A HubSpot custom workflow action; an agent block additionally exposes it to agents | | action | Exact alias of tool for people who think in HubSpot's native term | | cardBackend | A backend handler a UI card calls over the dispatch route | | trigger | A HubSpot webhook/event handler, keyed by eventType | | sync | A scheduled or event-driven sync into a HubSpot object | | defineSource | A pull source with a fetch({ cursor, http }) function; defineSource.push declares a webhook push source with receive({ event }) | | card | A UI-extension card, passed to defineApp in cards | | appObject, appObjectAssociation, appEvent | App-owned CRM schema declarations | | usesScopes | Honor-system scope annotation for raw HubSpot calls |

Result helpers, returned from a handler: ok, failContinue, failStop, retryLater, block. A handler may also return a plain output object, which the runtime normalizes to ok(output). There is no ctx.success() or ctx.fail(); the helpers are standalone functions.

Feature-flag evaluators, pure functions with no I/O: evaluateFlag, evaluateFlags, evaluateBooleanFlag, evaluateStringFlag, evaluateNumberFlag, evaluateJsonFlag, and createHsxOpenFeatureProvider, which wraps the same evaluator as an OpenFeature-compatible provider.

Field-type helpers: normalizeHubSpotFieldType, defaultHubSpotFieldType, HUBSPOT_FIELD_TYPE_MAP. The package also exports SDK_VERSION and re-exports the key types (AppDefinition, WorkerDefinition, ToolDefinition, TriggerDefinition, SyncDefinition, CardBackendDefinition, HandlerContext, InstallContext, ActionResult, and friends).

The handler context

Every capability handler receives a single HandlerContext value. Destructure what you need:

async handler({ input, enrolledObject, install, hubspot, flags, logger }) {
  const config = await install.config<{ datasetId: string }>();
  const useV2 = (await flags?.getBoolean("enrichment-v2", false)) ?? false;
  // ...
  return ok();
}

Its fields: input (resolved input values, never HubSpot property references), enrolledObject (id, objectType, properties), install (install id, portal id, state, and config<T>()), env, hubspot (an install-scoped, rate-limit-aware HubSpot client), appObjects, appEvents, http, logger, request, plus optional billing, sync, and flags. The flags getters (getBoolean, getString, getNumber, getJson) run an edge evaluation and fail safe to the default you pass, so a flag read can never break a handler.

Syncs

A source owns auth and fetching; worker.sync owns the HubSpot-facing target, schema, and schedule. Pull sources page with an opaque cursor:

import { defineSource, defineWorker } from "@hs-x/sdk";

const tickets = defineSource({
  name: "tickets",
  auth: { type: "bearer", token: process.env.TICKETS_TOKEN },
  async fetch({ cursor, http }) {
    const { body } = await http.get(`https://api.example.com/tickets?since=${cursor ?? ""}`);
    const page = body as { items: { id: string; subject: string }[]; next?: string };
    return {
      cursor: page.next,
      rows: page.items.map((t) => ({ key: t.id, data: { subject: t.subject } })),
    };
  },
});

const worker = defineWorker("sync");

worker.sync(tickets, {
  schedule: "*/15 * * * *",
  into: "p_ticket",
  schema: { subject: "string" },
  manageSchema: "full",
});

Each row's key is the stable identity used to upsert, so re-running a sync updates rather than duplicates. defineSource.push({ auth: { type: "hmac", ... }, receive }) declares a webhook-driven source instead, turning inbound events into rows through its receive({ event }) function. With manageSchema, deploy plans portal property creation from the declared schema (hs-x deploy --apply-schema applies the managed changes).

Agent tools

A tool with an agent block is also surfaced to HubSpot agents. Exposure is explicit: only the inputs you list in expose become agent-callable arguments, so adding a workflow input later never silently widens the agent surface.

worker.tool("enrich-company", {
  label: "Enrich company firmographics",
  objectType: "company",
  input: {
    depth: { type: "enumeration", options: ["basic", "full"], default: "basic" },
  },
  agent: {
    description: "Use when a company record is missing firmographic data.",
    expose: ["depth"],
  },
  async handler({ input }) {
    return ok({});
  },
});

The @hs-x/sdk/ui surface

Card code runs inside a HubSpot iframe, not in your Worker, and imports from the /ui subpath (the main entry is backend-only):

import { logger, createFlagsClient } from "@hs-x/sdk/ui";

logger.info("card mounted");

const flags = createFlagsClient({ endpoint: "https://your-worker.example.com" });
const showBeta = await flags.getBoolean("enrichment-v2", false);

logger mirrors the @hubspot/ui-extensions logger and, when running under HubSpot's local dev server, also forwards each line to the HS-X dev sidecar so it lands in your terminal. enableHsxDev(url?) and disableHsxDev() override the auto-detection. createFlagsClient lets a pure-UI card resolve feature flags by calling its own tenant Worker's evaluate endpoint; every getter fails safe to the supplied default. @hubspot/ui-extensions is an optional peer dependency, imported dynamically.

The @hs-x/sdk/experimental surface

Helpers that are declared but not yet delivered end-to-end live under @hs-x/sdk/experimental so the main entry only advertises what ships. Today that is the feature-flag CRM projection family (featureFlagAppObject, flagDefinitionToAppObjectRecord, flagToCompanyAssociation, flagToContactAssociation, and related constants). Expect this surface to change between releases.

Leaveable by design

The compiled Worker runs in your Cloudflare account and talks to HubSpot directly with your tokens; HS-X is not in the request path. The generated .hs-x/alchemy.run.ts, checked into your repo, describes the Cloudflare resources your app owns, so the app keeps running and stays deployable even if you stop using HS-X.

Docs

Guides and reference live at hs-x.dev/docs, starting with the getting-started guide. The CLI is @hs-x/cli on npm (the installed command is hs-x); the Worker runtime is @hs-x/runtime.

License

Apache-2.0