@hs-x/runtime

@hs-x/runtime is the server-side half of HS-X, the code that runs inside the Cloudflare Worker your app deploys to. Where @hs-x/sdk is the authoring surface you write your app against, @hs-x/runtime is what executes it: it takes the worker definition the SDK produces and turns it into a live fetch handler that HubSpot talks to.

Install

# already added by `hs-x init`; only needed for a hand-built project
bun add @hs-x/sdk @hs-x/runtime

App authors install this package alongside @hs-x/sdk; those are the two dependencies a scaffold lists. You rarely call it by hand. On deploy, hs-x generates a Worker entrypoint that imports your worker definition from src/workers/ and boots the runtime, roughly:

import { createRuntime } from "@hs-x/runtime";
import worker from "./src/workers/deals.js";

let runtime: ReturnType<typeof createRuntime> | undefined;

export default {
  fetch(request: Request, env: Record<string, unknown>) {
    runtime ??= createRuntime({ worker, env });
    return runtime.fetch(request);
  },
};

The real generated entrypoint additionally wires token stores, OAuth, rate limiting, and checkpointing from the Worker's environment bindings.

What it provides

createRuntime(options) is the headline export. Around it, the package covers the runtime concerns an HS-X app needs but should not have to reimplement:

| Concern | Key exports | | --- | --- | | Capability dispatch | createRuntime returns the fetch handler plus drainTriggerQueue / drainActionCompletionQueue for queue consumers | | Install tokens and OAuth | createRuntimeTokenService, createKvRuntimeOAuthStateStore, createSignedRuntimeOAuthStateStore | | HubSpot client wiring | Install-scoped, rate-limit-aware clients built on @hs-x/hubspot, including the batching Effect client | | Install lifecycle | Webhook dedup, sync cursors, revision routing, and dev overrides, each with an in-memory store for local dev (createMemoryRuntimeWebhookDedupStore and friends) | | Attestation and observability | createRuntimeAttestationHeartbeat, checkpoint recording via @hs-x/checkpoint | | Request signing | signHubSpotRequestV3, verifyHubSpotSignatureV3, and dev-proxy signing | | Feature flags | Edge evaluation and authoring handlers (createRuntimeFlagsContext, handleFlagsEvaluateRequest) |

Everything is built on Effect and is Worker-safe: no Node built-ins, no filesystem. The dev-time, Node-bound counterpart lives in @hs-x/hubspot-cli.

Part of HS-X

HS-X is a leaveable, type-safe HubSpot app framework on Cloudflare Workers. Deployed apps run in your own Cloudflare account; the platform is opt-in. Start with the CLI:

npm i -g @hs-x/cli
hs-x init myapp

See @hs-x/cli and the docs at hs-x.dev/docs.

License

Apache-2.0