@cargo-ai/worker-sdk 1.0.1

package/README.md

@@ -0,0 +1,90 @@
+# @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
+
+```sh
+npm install @cargo-ai/worker-sdk
+```
+
+## Write a worker
+
+```ts
+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](https://docs.getcargo.ai/integration/custom-integration) 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`](https://www.npmjs.com/package/@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:
+
+```sh
+# 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/`:
+
+```sh
+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`](https://github.com/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.

package/build/src/createWorker.d.ts

@@ -0,0 +1,51 @@
+import { type HonoOpenAPIRouterType } from "chanfana";
+import { Hono } from "hono";
+import type { WorkerEnv } from "./types.js";
+export interface CreateWorkerOptions {
+    /** Title shown in the generated OpenAPI spec. */
+    title: string;
+    /** Defaults to `"0.0.1"`. */
+    version?: string;
+    /** Optional long description shown in the generated OpenAPI spec. */
+    description?: string;
+    /** Path where Swagger UI is served. Defaults to `/docs`. */
+    docsUrl?: string;
+    /** Path where the OpenAPI 3.1 document is served. Defaults to `/openapi.json`. */
+    openapiUrl?: string;
+}
+export type WorkerApp<Env extends WorkerEnv = WorkerEnv> = Hono<{
+    Bindings: Env;
+}>;
+export type WorkerOpenAPI<Env extends WorkerEnv = WorkerEnv> = HonoOpenAPIRouterType<{
+    Bindings: Env;
+}>;
+/**
+ * Creates a Hono app wrapped with Chanfana so every route you register on the
+ * returned `openapi` handle is automatically described in the generated
+ * OpenAPI 3.1 spec served at `openapiUrl` (and browsable at `docsUrl`).
+ *
+ * `app` and `openapi` are two views of the same router: use `app` to add
+ * un-described Hono middleware / routes, and use `openapi` to register typed
+ * endpoints that extend `OpenAPIRoute`.
+ *
+ * ```ts
+ * import { createWorker, OpenAPIRoute } from "@cargo-ai/worker-sdk";
+ * import { z } from "zod";
+ *
+ * const { app, openapi } = createWorker({ title: "my-worker" });
+ *
+ * class GetHello extends OpenAPIRoute {
+ *   schema = { ... };
+ *   async handle(c) { ... }
+ * }
+ *
+ * openapi.get("/hello", GetHello);
+ *
+ * export default app;
+ * ```
+ */
+export declare const createWorker: <Env extends WorkerEnv = WorkerEnv>(options: CreateWorkerOptions) => {
+    app: WorkerApp<Env>;
+    openapi: WorkerOpenAPI<Env>;
+};
+//# sourceMappingURL=createWorker.d.ts.map

package/build/src/createWorker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createWorker.d.ts","sourceRoot":"","sources":["../../src/createWorker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAChE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE5B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,MAAM,WAAW,mBAAmB;IAClC,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC;IACd,6BAA6B;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,MAAM,SAAS,CAAC,GAAG,SAAS,SAAS,GAAG,SAAS,IAAI,IAAI,CAAC;IAC9D,QAAQ,EAAE,GAAG,CAAC;CACf,CAAC,CAAC;AAEH,MAAM,MAAM,aAAa,CAAC,GAAG,SAAS,SAAS,GAAG,SAAS,IACzD,qBAAqB,CAAC;IAAE,QAAQ,EAAE,GAAG,CAAA;CAAE,CAAC,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,YAAY,+CACd,mBAAmB;;;CAoB7B,CAAC"}

package/build/src/createWorker.js

@@ -0,0 +1,44 @@
+import { fromHono } from "chanfana";
+import { Hono } from "hono";
+/**
+ * Creates a Hono app wrapped with Chanfana so every route you register on the
+ * returned `openapi` handle is automatically described in the generated
+ * OpenAPI 3.1 spec served at `openapiUrl` (and browsable at `docsUrl`).
+ *
+ * `app` and `openapi` are two views of the same router: use `app` to add
+ * un-described Hono middleware / routes, and use `openapi` to register typed
+ * endpoints that extend `OpenAPIRoute`.
+ *
+ * ```ts
+ * import { createWorker, OpenAPIRoute } from "@cargo-ai/worker-sdk";
+ * import { z } from "zod";
+ *
+ * const { app, openapi } = createWorker({ title: "my-worker" });
+ *
+ * class GetHello extends OpenAPIRoute {
+ *   schema = { ... };
+ *   async handle(c) { ... }
+ * }
+ *
+ * openapi.get("/hello", GetHello);
+ *
+ * export default app;
+ * ```
+ */
+export const createWorker = (options) => {
+    const app = new Hono();
+    const openapi = fromHono(app, {
+        docs_url: options.docsUrl !== undefined ? options.docsUrl : "/docs",
+        openapi_url: options.openapiUrl !== undefined ? options.openapiUrl : "/openapi.json",
+        schema: {
+            info: {
+                title: options.title,
+                version: options.version !== undefined ? options.version : "0.0.1",
+                ...(options.description !== undefined
+                    ? { description: options.description }
+                    : {}),
+            },
+        },
+    });
+    return { app, openapi };
+};

package/build/src/customIntegration.d.ts

@@ -0,0 +1,97 @@
+import type { ConnectionTypes } from "@cargo-ai/types";
+import { z } from "zod";
+import { type WorkerApp, type WorkerOpenAPI } from "./createWorker.js";
+import type { WorkerEnv } from "./types.js";
+/**
+ * A single Custom Integration action — e.g. "Create Record". The zod
+ * `ConfigSchema` is the source of truth for the action's per-invocation config
+ * and 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 interface CustomIntegrationAction<ConnectorConfig, ConfigSchema extends z.ZodType = z.ZodType> {
+    name: string;
+    description: string;
+    config: {
+        schema: ConfigSchema;
+        uiSchema?: Record<string, unknown>;
+    };
+    execute: (payload: ConnectionTypes.IntegrationActionExecutePayload<ConnectorConfig, z.infer<ConfigSchema>>) => Promise<ConnectionTypes.IntegrationActionExecuteResult>;
+}
+/**
+ * A single Custom Integration extractor — e.g. "List Records". Both
+ * `ConfigSchema` and `MetaSchema` are source-of-truth for the manifest +
+ * OpenAPI + runtime validation.
+ */
+export interface CustomIntegrationExtractor<ConnectorConfig, ConfigSchema extends z.ZodType = z.ZodType, MetaSchema extends z.ZodType = z.ZodType> {
+    name: string;
+    description: string;
+    config: {
+        schema: ConfigSchema;
+        uiSchema?: Record<string, unknown>;
+    };
+    meta: {
+        schema: MetaSchema;
+    };
+    mode: ConnectionTypes.IntegrationExtractorMode;
+    preview: "none" | "records" | "count";
+    fetch: (payload: ConnectionTypes.IntegrationExtractorFetchPayload<ConnectorConfig, z.infer<ConfigSchema>, z.infer<MetaSchema>>) => Promise<ConnectionTypes.IntegrationExtractorFetchResult<z.infer<MetaSchema>>>;
+    count: (payload: ConnectionTypes.IntegrationExtractorCountPayload<ConnectorConfig, z.infer<ConfigSchema>>) => Promise<ConnectionTypes.IntegrationExtractorCountResult>;
+}
+export type CustomIntegrationAutocomplete<ConnectorConfig> = (payload: ConnectionTypes.IntegrationAutocompletePayload<ConnectorConfig>) => Promise<ConnectionTypes.IntegrationAutocompleteResult>;
+export type CustomIntegrationDynamicSchema<ConnectorConfig> = (payload: ConnectionTypes.IntegrationDynamicSchemaGetPayload<ConnectorConfig>) => Promise<{
+    jsonSchema: Record<string, unknown>;
+    uiSchema?: Record<string, unknown>;
+}>;
+export interface CustomIntegration<ConnectorConfigSchema extends z.ZodType> {
+    info: {
+        name: string;
+        description: string;
+        icon?: string;
+        color?: string;
+        url?: string;
+        version?: string;
+    };
+    connector: {
+        config: {
+            schema: ConnectorConfigSchema;
+            uiSchema?: Record<string, unknown>;
+        };
+        rateLimit?: {
+            unit: "second" | "minute" | "hour";
+            max: number;
+        };
+    };
+    authenticate: (payload: ConnectionTypes.IntegrationAuthenticatePayload<z.infer<ConnectorConfigSchema>>) => Promise<ConnectionTypes.IntegrationAuthenticateResult>;
+    listUsers?: (payload: ConnectionTypes.IntegrationListUsersPayload<z.infer<ConnectorConfigSchema>>) => Promise<ConnectionTypes.IntegrationUserData[]>;
+    completeOauth?: (payload: ConnectionTypes.IntegrationCompleteOauthPayload) => Promise<ConnectionTypes.IntegrationCompleteOauthResult>;
+    actions?: Record<string, CustomIntegrationAction<z.infer<ConnectorConfigSchema>, any>>;
+    extractors?: Record<string, CustomIntegrationExtractor<z.infer<ConnectorConfigSchema>, any, any>>;
+    autocompletes?: Record<string, CustomIntegrationAutocomplete<z.infer<ConnectorConfigSchema>>>;
+    dynamicSchemas?: Record<string, CustomIntegrationDynamicSchema<z.infer<ConnectorConfigSchema>>>;
+}
+/**
+ * Build a Cargo Custom Integration worker from a declarative spec. Produces a
+ * Hono app that serves:
+ *
+ * - `GET /manifest`                            — Cargo-native connector manifest
+ *   (actions/extractors/autocompletes/dynamicSchemas with JSON Schema configs).
+ * - `GET /openapi.json` + `GET /docs`          — OpenAPI 3.1 spec + Swagger UI
+ *   derived from the same Zod schemas.
+ * - `POST /authenticate`                       — runs `spec.authenticate`.
+ * - `POST /listUsers`                          — runs `spec.listUsers` (if set).
+ * - `POST /completeOauth`                      — runs `spec.completeOauth` (if set).
+ * - `POST /actions/<slug>/execute`             — one route per action.
+ * - `POST /extractors/<slug>/{fetch,count}`    — two routes per extractor.
+ * - `POST /autocompletes/<slug>`               — one route per autocomplete.
+ * - `POST /dynamicSchemas/<slug>`              — one route per dynamic schema.
+ *
+ * Per-handler request `config` payloads are validated against their Zod
+ * schemas; validation errors respond 400 with Chanfana's standard format.
+ */
+export declare const createCustomIntegration: <ConnectorConfigSchema extends z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, Env extends WorkerEnv = WorkerEnv>(spec: CustomIntegration<ConnectorConfigSchema>) => {
+    app: WorkerApp<Env>;
+    openapi: WorkerOpenAPI<Env>;
+};
+//# sourceMappingURL=customIntegration.d.ts.map

package/build/src/customIntegration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"customIntegration.d.ts","sourceRoot":"","sources":["../../src/customIntegration.ts"],"names":[],"mappings":"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"}

package/build/src/customIntegration.js

@@ -0,0 +1,212 @@
+import { OpenAPIRoute } from "chanfana";
+import { z } from "zod";
+import { createWorker, } from "./createWorker.js";
+// --- Route helpers -----------------------------------------------------------
+// The Cargo backend controls the envelope shape, so we don't re-declare every
+// field here — we just accept the envelope permissively and let the action /
+// extractor Zod schemas validate the one field the worker author owns.
+const looseEnvelope = z.object({}).passthrough();
+const jsonResponse = (schema) => ({
+    "200": {
+        description: "OK",
+        content: { "application/json": { schema } },
+    },
+});
+const jsonBody = (schema) => ({
+    content: { "application/json": { schema } },
+});
+const makeRoute = (schema, handle) => {
+    return class extends OpenAPIRoute {
+        schema = schema;
+        async handle(c) {
+            return handle(c);
+        }
+    };
+};
+// --- Manifest builder --------------------------------------------------------
+const buildManifest = (spec) => {
+    return {
+        name: spec.info.name,
+        description: spec.info.description,
+        ...(spec.info.icon !== undefined ? { icon: spec.info.icon } : {}),
+        ...(spec.info.color !== undefined ? { color: spec.info.color } : {}),
+        ...(spec.info.url !== undefined ? { url: spec.info.url } : {}),
+        connector: {
+            config: {
+                jsonSchema: z.toJSONSchema(spec.connector.config.schema),
+                ...(spec.connector.config.uiSchema !== undefined
+                    ? { uiSchema: spec.connector.config.uiSchema }
+                    : {}),
+            },
+            ...(spec.connector.rateLimit !== undefined
+                ? { rateLimit: spec.connector.rateLimit }
+                : {}),
+        },
+        actions: Object.fromEntries(Object.entries(spec.actions !== undefined ? spec.actions : {}).map(([slug, action]) => [
+            slug,
+            {
+                name: action.name,
+                description: action.description,
+                config: {
+                    jsonSchema: z.toJSONSchema(action.config.schema),
+                    ...(action.config.uiSchema !== undefined
+                        ? { uiSchema: action.config.uiSchema }
+                        : {}),
+                },
+            },
+        ])),
+        extractors: Object.fromEntries(Object.entries(spec.extractors !== undefined ? spec.extractors : {}).map(([slug, extractor]) => [
+            slug,
+            {
+                name: extractor.name,
+                description: extractor.description,
+                config: {
+                    jsonSchema: z.toJSONSchema(extractor.config.schema),
+                    ...(extractor.config.uiSchema !== undefined
+                        ? { uiSchema: extractor.config.uiSchema }
+                        : {}),
+                },
+                mode: extractor.mode,
+                preview: extractor.preview,
+            },
+        ])),
+        autocompletes: Object.fromEntries(Object.keys(spec.autocompletes !== undefined ? spec.autocompletes : {}).map((slug) => [
+            slug,
+            { params: { jsonSchema: {} }, cacheExpirationInSeconds: 300 },
+        ])),
+        dynamicSchemas: Object.fromEntries(Object.keys(spec.dynamicSchemas !== undefined ? spec.dynamicSchemas : {}).map((slug) => [slug, { params: { jsonSchema: {} } }])),
+    };
+};
+// --- createCustomIntegration -------------------------------------------------
+/**
+ * Build a Cargo Custom Integration worker from a declarative spec. Produces a
+ * Hono app that serves:
+ *
+ * - `GET /manifest`                            — Cargo-native connector manifest
+ *   (actions/extractors/autocompletes/dynamicSchemas with JSON Schema configs).
+ * - `GET /openapi.json` + `GET /docs`          — OpenAPI 3.1 spec + Swagger UI
+ *   derived from the same Zod schemas.
+ * - `POST /authenticate`                       — runs `spec.authenticate`.
+ * - `POST /listUsers`                          — runs `spec.listUsers` (if set).
+ * - `POST /completeOauth`                      — runs `spec.completeOauth` (if set).
+ * - `POST /actions/<slug>/execute`             — one route per action.
+ * - `POST /extractors/<slug>/{fetch,count}`    — two routes per extractor.
+ * - `POST /autocompletes/<slug>`               — one route per autocomplete.
+ * - `POST /dynamicSchemas/<slug>`              — one route per dynamic schema.
+ *
+ * Per-handler request `config` payloads are validated against their Zod
+ * schemas; validation errors respond 400 with Chanfana's standard format.
+ */
+export const createCustomIntegration = (spec) => {
+    const { app, openapi } = createWorker({
+        title: spec.info.name,
+        version: spec.info.version !== undefined ? spec.info.version : "0.0.1",
+        description: spec.info.description,
+    });
+    const manifest = buildManifest(spec);
+    openapi.get("/manifest", makeRoute({
+        tags: ["manifest"],
+        summary: "Cargo connector manifest.",
+        responses: jsonResponse(z.object({}).passthrough()),
+    }, async (c) => c.json(manifest)));
+    openapi.post("/authenticate", makeRoute({
+        tags: ["connector"],
+        summary: "Validate the connector config against the upstream API.",
+        request: { body: jsonBody(looseEnvelope) },
+        responses: jsonResponse(z.object({}).passthrough()),
+    }, async (c) => {
+        const payload = (await c.req.json());
+        return c.json(await spec.authenticate(payload));
+    }));
+    if (spec.listUsers !== undefined) {
+        const { listUsers } = spec;
+        openapi.post("/listUsers", makeRoute({
+            tags: ["connector"],
+            summary: "List users visible to the connected account.",
+            request: { body: jsonBody(looseEnvelope) },
+            responses: jsonResponse(z.array(z.object({}).passthrough())),
+        }, async (c) => {
+            const payload = (await c.req.json());
+            return c.json(await listUsers(payload));
+        }));
+    }
+    if (spec.completeOauth !== undefined) {
+        const { completeOauth } = spec;
+        openapi.post("/completeOauth", makeRoute({
+            tags: ["connector"],
+            summary: "Exchange OAuth params for a credential.",
+            request: { body: jsonBody(looseEnvelope) },
+            responses: jsonResponse(z.object({}).passthrough()),
+        }, async (c) => {
+            const payload = (await c.req.json());
+            return c.json(await completeOauth(payload));
+        }));
+    }
+    for (const [slug, action] of Object.entries(spec.actions !== undefined ? spec.actions : {})) {
+        const capturedAction = action;
+        openapi.post(`/actions/${slug}/execute`, makeRoute({
+            tags: ["actions"],
+            summary: capturedAction.name,
+            description: capturedAction.description,
+            request: {
+                body: jsonBody(z.object({ config: capturedAction.config.schema }).passthrough()),
+            },
+            responses: jsonResponse(z.object({}).passthrough()),
+        }, async (c) => {
+            const payload = (await c.req.json());
+            return c.json(await capturedAction.execute(payload));
+        }));
+    }
+    for (const [slug, extractor] of Object.entries(spec.extractors !== undefined ? spec.extractors : {})) {
+        const captured = extractor;
+        openapi.post(`/extractors/${slug}/fetch`, makeRoute({
+            tags: ["extractors"],
+            summary: `${captured.name} — fetch`,
+            description: captured.description,
+            request: {
+                body: jsonBody(z.object({ config: captured.config.schema }).passthrough()),
+            },
+            responses: jsonResponse(z.object({}).passthrough()),
+        }, async (c) => {
+            const payload = (await c.req.json());
+            return c.json(await captured.fetch(payload));
+        }));
+        openapi.post(`/extractors/${slug}/count`, makeRoute({
+            tags: ["extractors"],
+            summary: `${captured.name} — count`,
+            description: captured.description,
+            request: {
+                body: jsonBody(z.object({ config: captured.config.schema }).passthrough()),
+            },
+            responses: jsonResponse(z.object({}).passthrough()),
+        }, async (c) => {
+            const payload = (await c.req.json());
+            return c.json(await captured.count(payload));
+        }));
+    }
+    for (const [slug, handler] of Object.entries(spec.autocompletes !== undefined ? spec.autocompletes : {})) {
+        const captured = handler;
+        openapi.post(`/autocompletes/${slug}`, makeRoute({
+            tags: ["autocompletes"],
+            summary: `Autocomplete: ${slug}`,
+            request: { body: jsonBody(looseEnvelope) },
+            responses: jsonResponse(z.object({}).passthrough()),
+        }, async (c) => {
+            const payload = (await c.req.json());
+            return c.json(await captured(payload));
+        }));
+    }
+    for (const [slug, handler] of Object.entries(spec.dynamicSchemas !== undefined ? spec.dynamicSchemas : {})) {
+        const captured = handler;
+        openapi.post(`/dynamicSchemas/${slug}`, makeRoute({
+            tags: ["dynamicSchemas"],
+            summary: `Dynamic schema: ${slug}`,
+            request: { body: jsonBody(looseEnvelope) },
+            responses: jsonResponse(z.object({}).passthrough()),
+        }, async (c) => {
+            const payload = (await c.req.json());
+            return c.json(await captured(payload));
+        }));
+    }
+    return { app, openapi };
+};

package/build/src/index.d.ts

@@ -0,0 +1,9 @@
+export type { CreateWorkerOptions, WorkerApp, WorkerOpenAPI, } from "./createWorker.js";
+export { createWorker } from "./createWorker.js";
+export type { CustomIntegration, CustomIntegrationAction, CustomIntegrationAutocomplete, CustomIntegrationDynamicSchema, CustomIntegrationExtractor, } from "./customIntegration.js";
+export { createCustomIntegration } from "./customIntegration.js";
+export type { WorkerEnv, WorkerManifest } from "./types.js";
+export { fromHono, OpenAPIRoute } from "chanfana";
+export type { Context } from "hono";
+export { Hono } from "hono";
+//# sourceMappingURL=index.d.ts.map

package/build/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,mBAAmB,EACnB,SAAS,EACT,aAAa,GACd,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,YAAY,EACV,iBAAiB,EACjB,uBAAuB,EACvB,6BAA6B,EAC7B,8BAA8B,EAC9B,0BAA0B,GAC3B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACjE,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAClD,YAAY,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACpC,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC"}

package/build/src/index.js

@@ -0,0 +1,4 @@
+export { createWorker } from "./createWorker.js";
+export { createCustomIntegration } from "./customIntegration.js";
+export { fromHono, OpenAPIRoute } from "chanfana";
+export { Hono } from "hono";

package/build/src/types.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `env` shape passed to every handler by the Cargo Hosting runtime. Keys come
+ * from the worker's configured secrets / bindings. Override with a stricter
+ * interface in your worker if you want type-safety on individual env values.
+ */
+export type WorkerEnv = Record<string, string | undefined>;
+/**
+ * `manifest.json` at the root of the deployed bundle. Tells the Cargo Hosting
+ * sandbox which outbound hosts the worker is allowed to call (defence in depth
+ * — the runtime blocks `fetch(...)` calls to anything not on the allowlist).
+ */
+export interface WorkerManifest {
+    outboundAllowlist: string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/build/src/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAE3D;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,iBAAiB,EAAE,MAAM,EAAE,CAAC;CAC7B"}

package/build/src/types.js

@@ -0,0 +1 @@
+export {};