@cargo-ai/worker-sdk

Build Cargo Hosting workers — serverless edge HTTP handlers running on *.worker.getcargo.io — with automatic OpenAPI 3.1 generation. Hono + Chanfana + Zod are wrapped in two opinionated factories so you define routes once and get runtime validation, a Cargo-native manifest, and live OpenAPI docs for free.

Install

npm install @cargo-ai/worker-sdk

Write a worker

import { type Context, createWorker, OpenAPIRoute } from "@cargo-ai/worker-sdk";
import { z } from "zod";

const { app, openapi } = createWorker({ title: "my-worker" });

class GetHello extends OpenAPIRoute {
  override schema = {
    request: {
      query: z.object({ name: z.string().default("world") }),
    },
    responses: {
      "200": {
        description: "Greeting.",
        content: {
          "application/json": {
            schema: z.object({ message: z.string() }),
          },
        },
      },
    },
  };

  override async handle(c: Context): Promise<Response> {
    const { query } = await this.getValidatedData<typeof this.schema>();
    return c.json({ message: `Hello, ${query.name}!` });
  }
}

openapi.get("/hello", GetHello);

export default app;

createWorker gives you:

• GET /openapi.json — OpenAPI 3.1 spec derived from every route's Zod schema.
• GET /docs — Swagger UI.

Write a custom integration

createCustomIntegration({ info, connector, authenticate, actions, extractors, ... }) builds a worker that implements the Cargo Custom Integration HTTP contract from a single declarative spec. The same Zod schemas feed GET /manifest (Cargo-native wire format) and GET /openapi.json. See templates/custom-integration/.

Integration-domain types (IntegrationActionExecutePayload, IntegrationExtractorFetchResult, …) live in @cargo-ai/types under the ConnectionTypes namespace — you rarely need to import them directly because the SDK's CustomIntegrationAction / CustomIntegrationExtractor types wire them in for you.

Scaffold a project

You almost never want to wire this from scratch. Use the CLI:

# Blank edge handler
npx @cargo-ai/cli hosting worker init my-worker --template blank

# Worker that implements the Cargo Custom Integration HTTP contract
npx @cargo-ai/cli hosting worker init my-integration --template custom-integration

The CLI copies the matching template from @cargo-ai/worker-sdk/templates/<slug>/ into your target directory.

Build & deploy

Templates ship with a build script that runs tsc and copies manifest.json, package.json, and package-lock.json into dist/. The bundle uploaded to Cargo Hosting is the contents of dist/:

npm install
npm run build
cargo-ai hosting deployment create --worker-uuid <workerUuid> --source ./dist
cargo-ai hosting deployment promote --uuid <deploymentUuid>

The Cargo Hosting build pipeline runs npm ci against dist/package.json and esbuild dist/index.js --bundle --format=esm --platform=neutral --target=es2022 to produce the final edge bundle. So you can ship multi-file TypeScript projects — esbuild will tree-shake everything into a single ESM file at deploy time.

Available templates

• blank — a ready-to-extend Hono app built by createWorker(), with one sample route and /openapi.json + /docs out of the box. Use this when the worker just responds to inbound HTTP and doesn't need to integrate into the Cargo connector catalog.
• custom-integration — a ready-to-extend spec passed to createCustomIntegration(). Handles /manifest, /openapi.json, /docs, /authenticate, /actions/<slug>/execute, /extractors/<slug>/{fetch,count}, /autocompletes/<slug>, /dynamicSchemas/<slug>, /completeOauth, /listUsers from a single declaration. Edge-native equivalent of getcargohq/dummy-integration. After deploying, register it as a connector with cargo-ai connection custom-integration create --kind worker --worker-uuid <workerUuid>.

See each template's own README.md for the file layout and how to extend it.