@cargo-ai/worker-sdk 1.0.1

package/templates/blank/README.md

@@ -0,0 +1,112 @@
+# **APP_NAME**
+
+A Cargo Hosting worker (edge HTTP handler), scaffolded by `cargo-ai hosting worker init`.
+
+Built on [`@cargo-ai/worker-sdk`](https://www.npmjs.com/package/@cargo-ai/worker-sdk), which wires [Hono](https://hono.dev) + [Chanfana](https://chanfana.com) so every route you declare automatically shows up in an OpenAPI 3.1 spec.
+
+## Layout
+
+```
+__APP_NAME__/
+├── manifest.json           # outboundAllowlist (hosts the worker may call)
+├── package.json
+├── tsconfig.json
+├── scripts/
+│   └── copy-runtime-files.mjs
+└── src/
+    └── index.ts            # declares routes on the app returned by createWorker(...)
+```
+
+`npm run build` runs `tsc` (compiles `src/` into `dist/`) and copies `manifest.json`, `package.json`, and `package-lock.json` into `dist/`. The contents of `dist/` are what get uploaded as the deployment source.
+
+## Get started
+
+```sh
+npm install
+```
+
+## Deploy
+
+```sh
+# Provision a worker slot in your Cargo workspace:
+cargo-ai hosting worker create --name "__APP_NAME__" --slug your-slug
+
+# Build, then deploy:
+npm run build
+cargo-ai hosting deployment create --worker-uuid <workerUuid> --source ./dist
+
+# Promote the resulting deployment to live:
+cargo-ai hosting deployment promote --uuid <deploymentUuid>
+```
+
+The worker is then served at `https://<your-slug>.worker.getcargo.run` (or whatever the hosting domain is for your environment).
+
+## OpenAPI + docs
+
+Out of the box:
+
+- `GET /openapi.json` — OpenAPI 3.1 spec derived from your route definitions.
+- `GET /docs` — Swagger UI.
+
+Adding a new documented route is a class declaration:
+
+```ts
+import { type Context, OpenAPIRoute } from "@cargo-ai/worker-sdk";
+import { z } from "zod";
+
+class GetThing extends OpenAPIRoute {
+  override schema = {
+    request: { params: z.object({ id: z.string().uuid() }) },
+    responses: {
+      "200": {
+        description: "The thing.",
+        content: {
+          "application/json": {
+            schema: z.object({ id: z.string(), name: z.string() }),
+          },
+        },
+      },
+    },
+  };
+
+  override async handle(c: Context): Promise<Response> {
+    const { params } = await this.getValidatedData<typeof this.schema>();
+    return c.json({ id: params.id, name: "example" });
+  }
+}
+
+openapi.get("/things/:id", GetThing);
+```
+
+Params, query, body, and responses are validated at runtime and described in the generated spec.
+
+## Talk to the Cargo API
+
+`env.CARGO_API_TOKEN` is injected by Cargo Hosting at runtime. Never hardcode credentials.
+
+```ts
+openapi.get(
+  "/segments",
+  class extends OpenAPIRoute {
+    override schema = {
+      responses: {
+        "200": {
+          description: "OK",
+          content: {
+            "application/json": { schema: z.object({}).passthrough() },
+          },
+        },
+      },
+    };
+    override async handle(c: Context): Promise<Response> {
+      const res = await fetch(
+        "https://api.getcargo.io/v1/segmentation/segments/list",
+        { headers: { Authorization: `Bearer ${c.env.CARGO_API_TOKEN}` } },
+      );
+      return c.json(await res.json());
+    }
+  },
+);
+```
+
+Add `api.getcargo.io` to `manifest.json#outboundAllowlist` before the worker can call it.

package/templates/blank/manifest.json

@@ -0,0 +1,3 @@
+{
+  "outboundAllowlist": []
+}

package/templates/blank/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "__APP_NAME__",
+  "private": true,
+  "version": "0.0.1",
+  "type": "module",
+  "description": "A Cargo Hosting worker (edge HTTP handler) with automatic OpenAPI generation via @cargo-ai/worker-sdk (Hono + Chanfana under the hood).",
+  "scripts": {
+    "build": "tsc && node ./scripts/copy-runtime-files.mjs",
+    "type:check": "tsc --noEmit",
+    "deploy": "npm run build && cargo-ai hosting deployment create --worker-uuid $CARGO_WORKER_UUID --source ./dist"
+  },
+  "dependencies": {
+    "@cargo-ai/worker-sdk": "^0.1.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.8",
+    "typescript": "5.3.2"
+  }
+}

package/templates/blank/scripts/copy-runtime-files.mjs

@@ -0,0 +1,25 @@
+// Copies the non-TypeScript files the deploy pipeline needs (manifest.json,
+// package.json, package-lock.json) into ./dist alongside the compiled JS.
+//
+// Cargo Hosting builds the worker by running `npm ci` + `esbuild index.js`
+// against the contents of the directory you pass to `--source`, so everything
+// has to live in one place.
+
+import { copyFile } from "node:fs/promises";
+import path from "node:path";
+
+const files = ["manifest.json", "package.json", "package-lock.json"];
+const distDir = "dist";
+
+for (const file of files) {
+  try {
+    await copyFile(file, path.join(distDir, file));
+    console.log(`copied ${file} -> ${distDir}/${file}`);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      console.warn(`skipping missing ${file}`);
+      continue;
+    }
+    throw error;
+  }
+}

package/templates/blank/src/index.ts

@@ -0,0 +1,46 @@
+import { type Context, createWorker, OpenAPIRoute } from "@cargo-ai/worker-sdk";
+import { z } from "zod";
+
+const { app, openapi } = createWorker({
+  title: "__APP_NAME__",
+  description: "A Cargo Hosting worker.",
+});
+
+class GetHello extends OpenAPIRoute {
+  override schema = {
+    tags: ["hello"],
+    summary: "Greet the caller.",
+    request: {
+      query: z.object({
+        name: z.string().default("world").describe("Name to greet."),
+      }),
+    },
+    responses: {
+      "200": {
+        description: "Greeting.",
+        content: {
+          "application/json": {
+            schema: z.object({
+              ok: z.literal(true),
+              message: z.string(),
+              worker: z.string(),
+            }),
+          },
+        },
+      },
+    },
+  };
+
+  override async handle(c: Context): Promise<Response> {
+    const { query } = await this.getValidatedData<typeof this.schema>();
+    return c.json({
+      ok: true as const,
+      message: `Hello, ${query.name}!`,
+      worker: "__APP_NAME__",
+    });
+  }
+}
+
+openapi.get("/", GetHello);
+
+export default app;

package/templates/blank/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "nodenext",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "strict": true,
+    "noImplicitAny": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitReturns": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": false,
+    "sourceMap": false,
+    "noEmitOnError": true
+  },
+  "include": ["src/**/*.ts"]
+}

package/templates/custom-integration/.env.example

@@ -0,0 +1,5 @@
+# Set on the worker via `cargo-ai hosting worker update --uuid <workerUuid> --env KEY=value`
+# (or whatever your env-injection mechanism is).
+#
+# Example: a third-party API key the integration calls on behalf of the connector.
+EXAMPLE_API_KEY=

package/templates/custom-integration/README.md

@@ -0,0 +1,136 @@
+# **APP_NAME**
+
+A Cargo Hosting **worker** that implements the [Cargo Custom Integration](https://docs.getcargo.io/integration/custom-integration) HTTP contract, built on [`@cargo-ai/worker-sdk`](https://www.npmjs.com/package/@cargo-ai/worker-sdk) (Hono + Chanfana under the hood).
+
+After it's deployed you register it as a connector with `cargo-ai connection custom-integration create --kind worker --worker-uuid <workerUuid>`, and it shows up in your Cargo workspace's connector catalog.
+
+## Layout
+
+```
+__APP_NAME__/
+├── manifest.json               # outboundAllowlist (hosts the worker may call)
+├── package.json
+├── tsconfig.json
+├── scripts/
+│   └── copy-runtime-files.mjs
+└── src/
+    ├── index.ts                # createCustomIntegration({ ... }) — that's the whole router
+    ├── connectorConfig.ts      # zod schema + type for the connector config
+    ├── authenticate.ts         # POST /authenticate
+    ├── listUsers.ts            # POST /listUsers
+    ├── completeOauth.ts        # POST /completeOauth
+    ├── actions/
+    │   ├── index.ts            # registers each action handler under a slug
+    │   └── createRecord.ts
+    ├── extractors/
+    │   ├── index.ts            # registers each extractor handler under a slug
+    │   └── listRecords.ts
+    ├── autocompletes/
+    │   └── index.ts
+    └── dynamicSchemas/
+        └── index.ts
+```
+
+`npm run build` runs `tsc` and copies `manifest.json`, `package.json`, and `package-lock.json` into `dist/`. The contents of `dist/` are what get uploaded as the deployment source — Cargo Hosting then runs `npm ci` + `esbuild` against them to produce the final edge bundle.
+
+## What the SDK gives you for free
+
+`createCustomIntegration({ ... })` returns a ready-to-export Hono app that serves:
+
+| Endpoint                                      | Purpose                                                             |
+| --------------------------------------------- | ------------------------------------------------------------------- |
+| `GET /manifest`                               | Cargo-native connector manifest consumed by the Cargo backend.      |
+| `GET /openapi.json`                           | OpenAPI 3.1 spec derived from the same Zod schemas.                 |
+| `GET /docs`                                   | Swagger UI.                                                         |
+| `POST /authenticate`                          | Calls `spec.authenticate`.                                          |
+| `POST /listUsers`                             | Calls `spec.listUsers` (if provided).                               |
+| `POST /completeOauth`                         | Calls `spec.completeOauth` (if provided).                           |
+| `POST /actions/<slug>/execute`                | Dispatches to `spec.actions[slug]`. Body `config` is Zod-validated. |
+| `POST /extractors/<slug>/fetch` + `.../count` | Dispatches to `spec.extractors[slug]`.                              |
+| `POST /autocompletes/<slug>`                  | Dispatches to `spec.autocompletes[slug]`.                           |
+| `POST /dynamicSchemas/<slug>`                 | Dispatches to `spec.dynamicSchemas[slug]`.                          |
+
+Zod schemas are the single source of truth — the same schema drives the runtime validation, the `GET /manifest` JSON Schema the Cargo UI renders, and the `GET /openapi.json` description.
+
+## End-to-end flow
+
+```sh
+# 1. Install deps:
+npm install
+
+# 2. Provision a worker slot in your Cargo workspace:
+cargo-ai hosting worker create --name "__APP_NAME__" --slug your-slug
+
+# 3. Build, then deploy the bundle:
+npm run build
+cargo-ai hosting deployment create --worker-uuid <workerUuid> --source ./dist
+
+# 4. Promote the deployment to live:
+cargo-ai hosting deployment promote --uuid <deploymentUuid>
+
+# 5. Register the worker as a custom integration so it appears as a connector:
+cargo-ai connection custom-integration create \
+  --kind worker \
+  --worker-uuid <workerUuid>
+```
+
+## Iterate
+
+Edit any `src/**/*.ts` file, then re-run:
+
+```sh
+npm run build
+cargo-ai hosting deployment create --worker-uuid <workerUuid> --source ./dist
+cargo-ai hosting deployment promote --uuid <deploymentUuid>
+```
+
+The next call to `GET https://<your-slug>.worker.getcargo.run/manifest` reflects the new manifest, and `GET .../openapi.json` / `.../docs` reflect the new schemas.
+
+## Calling third-party APIs
+
+Add the host to `manifest.json#outboundAllowlist` (the Cargo Hosting sandbox blocks unrelated outbound traffic):
+
+```json
+{
+  "outboundAllowlist": ["api.example.com"]
+}
+```
+
+Then `fetch` it from any handler. The connector config (whatever you defined in `src/connectorConfig.ts`) reaches your handler as `payload.connector.config`:
+
+```ts
+import type { CustomIntegrationAction } from "@cargo-ai/worker-sdk";
+import { z } from "zod";
+
+import type { ConnectorConfig } from "../connectorConfig.js";
+
+const schema = z.object({
+  name: z.string().meta({ title: "Name" }),
+});
+
+export const createRecord: CustomIntegrationAction<
+  ConnectorConfig,
+  typeof schema
+> = {
+  name: "Create Record",
+  description: "Creates a new record.",
+  config: { schema },
+  execute: async (payload) => {
+    const { apiKey } = payload.connector.config;
+    const res = await fetch("https://api.example.com/records", {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        Authorization: `Bearer ${apiKey}`,
+      },
+      body: JSON.stringify({ name: payload.config.name }),
+    });
+    const created = (await res.json()) as { id: string; name: string };
+    return {
+      outcome: "executed",
+      title: `Created ${created.name}`,
+      data: created,
+    };
+  },
+};
+```

package/templates/custom-integration/manifest.json

@@ -0,0 +1,3 @@
+{
+  "outboundAllowlist": []
+}

package/templates/custom-integration/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "__APP_NAME__",
+  "private": true,
+  "version": "0.0.1",
+  "type": "module",
+  "description": "A Cargo Hosting worker that implements the Cargo Custom Integration HTTP contract, built on @cargo-ai/worker-sdk with automatic OpenAPI generation.",
+  "scripts": {
+    "build": "tsc && node ./scripts/copy-runtime-files.mjs",
+    "type:check": "tsc --noEmit",
+    "deploy": "npm run build && cargo-ai hosting deployment create --worker-uuid $CARGO_WORKER_UUID --source ./dist"
+  },
+  "dependencies": {
+    "@cargo-ai/types": "^1.0.22",
+    "@cargo-ai/worker-sdk": "^0.1.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.8",
+    "typescript": "5.3.2"
+  }
+}

package/templates/custom-integration/scripts/copy-runtime-files.mjs

@@ -0,0 +1,25 @@
+// Copies the non-TypeScript files the deploy pipeline needs (manifest.json,
+// package.json, package-lock.json) into ./dist alongside the compiled JS.
+//
+// Cargo Hosting builds the worker by running `npm ci` + `esbuild index.js`
+// against the contents of the directory you pass to `--source`, so everything
+// has to live in one place.
+
+import { copyFile } from "node:fs/promises";
+import path from "node:path";
+
+const files = ["manifest.json", "package.json", "package-lock.json"];
+const distDir = "dist";
+
+for (const file of files) {
+  try {
+    await copyFile(file, path.join(distDir, file));
+    console.log(`copied ${file} -> ${distDir}/${file}`);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      console.warn(`skipping missing ${file}`);
+      continue;
+    }
+    throw error;
+  }
+}

package/templates/custom-integration/src/actions/createRecord.ts

@@ -0,0 +1,34 @@
+import type { CustomIntegrationAction } from "@cargo-ai/worker-sdk";
+import { z } from "zod";
+
+import type { ConnectorConfig } from "../connectorConfig.js";
+
+const schema = z.object({
+  name: z.string().meta({ title: "Name" }),
+});
+
+export const createRecord: CustomIntegrationAction<
+  ConnectorConfig,
+  typeof schema
+> = {
+  name: "Create Record",
+  description: "Creates a new record in the connected service.",
+  config: {
+    schema,
+  },
+  execute: async (payload) => {
+    const { name } = payload.config;
+
+    // TODO: call the third-party API using `payload.connector.config.apiKey`.
+
+    return {
+      outcome: "executed",
+      title: `Created ${name}`,
+      data: {
+        id: crypto.randomUUID(),
+        name,
+        createdAt: new Date().toISOString(),
+      },
+    };
+  },
+};

package/templates/custom-integration/src/actions/index.ts

@@ -0,0 +1,20 @@
+import type { CustomIntegrationAction } from "@cargo-ai/worker-sdk";
+
+import type { ConnectorConfig } from "../connectorConfig.js";
+import { createRecord } from "./createRecord.js";
+
+/**
+ * Register action handlers here, keyed by the slug that Cargo should call.
+ * Cargo routes `POST /actions/<slug>/execute` at this worker to the matching
+ * handler. The zod config schema on each handler drives:
+ *   - runtime validation of `payload.config`
+ *   - the JSON Schema exposed at `GET /manifest#actions[slug].config.jsonSchema`
+ *   - the OpenAPI schema for `POST /actions/<slug>/execute`
+ */
+export const actions: Record<
+  string,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  CustomIntegrationAction<ConnectorConfig, any>
+> = {
+  createRecord,
+};

package/templates/custom-integration/src/authenticate.ts

@@ -0,0 +1,27 @@
+import type { ConnectionTypes } from "@cargo-ai/types";
+
+import type { ConnectorConfig } from "./connectorConfig.js";
+
+export const authenticate = async (
+  payload: ConnectionTypes.IntegrationAuthenticatePayload<ConnectorConfig>,
+): Promise<ConnectionTypes.IntegrationAuthenticateResult> => {
+  const { apiKey } = payload.connector.config;
+
+  if (apiKey.length === 0) {
+    return {
+      outcome: "error",
+      reason: "unauthenticated",
+      errorMessage: "Missing API key",
+    };
+  }
+
+  // TODO: call the third-party API to validate `apiKey`.
+  // const res = await fetch("https://api.example.com/me", {
+  //   headers: { Authorization: `Bearer ${apiKey}` },
+  // });
+  // if (res.ok === false) {
+  //   return { outcome: "error", reason: "unauthenticated", errorMessage: "Invalid API key" };
+  // }
+
+  return { outcome: "success" };
+};

package/templates/custom-integration/src/autocompletes/index.ts

@@ -0,0 +1,13 @@
+import type { CustomIntegrationAutocomplete } from "@cargo-ai/worker-sdk";
+
+import type { ConnectorConfig } from "../connectorConfig.js";
+
+/**
+ * Register autocomplete handlers here, keyed by the slug that Cargo should
+ * call. Cargo routes `POST /autocompletes/<slug>` at this worker; the handler
+ * receives `{ connector, slug, params, value? }` and returns `{ results }`.
+ */
+export const autocompletes: Record<
+  string,
+  CustomIntegrationAutocomplete<ConnectorConfig>
+> = {};

package/templates/custom-integration/src/completeOauth.ts

@@ -0,0 +1,10 @@
+import type { ConnectionTypes } from "@cargo-ai/types";
+
+export const completeOauth = async (
+  _payload: ConnectionTypes.IntegrationCompleteOauthPayload,
+): Promise<ConnectionTypes.IntegrationCompleteOauthResult> => {
+  // TODO: exchange the OAuth params (e.g. `code`, `redirectUri`) supplied in
+  // `payload.params` for a token via the third-party OAuth endpoint, then
+  // return the token (which Cargo will store in the connector config).
+  return { value: "" };
+};

package/templates/custom-integration/src/connectorConfig.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+
+/**
+ * Shape of the connector config — what Cargo collects from the workspace user
+ * when they create a connector against this integration.
+ *
+ * Cargo passes this object as `payload.connector.config` to every action,
+ * extractor, autocomplete, dynamic schema, and `authenticate` call. Add fields
+ * here as you need them; the matching JSON Schema is generated automatically
+ * for the `GET /manifest` wire format and for `GET /openapi.json`.
+ */
+export const zodConnectorConfig = z.object({
+  apiKey: z.string().meta({ title: "API Key" }),
+});
+
+export type ConnectorConfig = z.infer<typeof zodConnectorConfig>;

package/templates/custom-integration/src/dynamicSchemas/index.ts

@@ -0,0 +1,13 @@
+import type { CustomIntegrationDynamicSchema } from "@cargo-ai/worker-sdk";
+
+import type { ConnectorConfig } from "../connectorConfig.js";
+
+/**
+ * Register dynamic-schema handlers here, keyed by the slug that Cargo should
+ * call. Cargo routes `POST /dynamicSchemas/<slug>` at this worker with
+ * `{ connector, params }` and expects `{ jsonSchema, uiSchema? }` back.
+ */
+export const dynamicSchemas: Record<
+  string,
+  CustomIntegrationDynamicSchema<ConnectorConfig>
+> = {};

package/templates/custom-integration/src/extractors/index.ts

@@ -0,0 +1,18 @@
+import type { CustomIntegrationExtractor } from "@cargo-ai/worker-sdk";
+
+import type { ConnectorConfig } from "../connectorConfig.js";
+import { listRecords } from "./listRecords.js";
+
+/**
+ * Register extractor handlers here, keyed by the slug that Cargo should call.
+ * Cargo routes `POST /extractors/<slug>/fetch` and `POST /extractors/<slug>/count`
+ * at this worker to the matching handler. The zod config/meta schemas drive
+ * the manifest, the OpenAPI spec, and runtime validation.
+ */
+export const extractors: Record<
+  string,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  CustomIntegrationExtractor<ConnectorConfig, any, any>
+> = {
+  listRecords,
+};

package/templates/custom-integration/src/extractors/listRecords.ts

@@ -0,0 +1,51 @@
+import type { ConnectionTypes } from "@cargo-ai/types";
+import type { CustomIntegrationExtractor } from "@cargo-ai/worker-sdk";
+import { z } from "zod";
+
+import type { ConnectorConfig } from "../connectorConfig.js";
+
+const configSchema = z.object({});
+const metaSchema = z.object({});
+
+const COLUMNS: ConnectionTypes.IntegrationColumn[] = [
+  { slug: "id", type: "string", label: "ID" },
+  { slug: "name", type: "string", label: "Name" },
+  { slug: "createdAt", type: "date", label: "Created At" },
+];
+
+export const listRecords: CustomIntegrationExtractor<
+  ConnectorConfig,
+  typeof configSchema,
+  typeof metaSchema
+> = {
+  name: "List Records",
+  description: "Pulls records from the connected service into a Cargo dataset.",
+  config: {
+    schema: configSchema,
+  },
+  meta: {
+    schema: metaSchema,
+  },
+  mode: {
+    kind: "fetch",
+    isIncremental: false,
+  },
+  preview: "records",
+  fetch: async (_payload) => {
+    // TODO: call the third-party API and map results into the columns above.
+    return {
+      outcome: "fetched",
+      columns: COLUMNS,
+      idColumnSlug: "id",
+      titleColumnSlug: "name",
+      data: {
+        kind: "records",
+        records: [],
+        hasMore: false,
+      },
+    };
+  },
+  count: async (_payload) => {
+    return { count: 0 };
+  },
+};