@ingram-cloud/sdk 1.0.0

package/README.md

@@ -0,0 +1,74 @@
+# `@ingram-cloud/sdk`
+
+The Ingram Cloud `/v1` API wire contract in TypeScript — **Zod request/response
+schemas + SSE/webhook event types + JSON response types** — plus a typed
+**management-plane client** built on it. The schemas are hand-authored and are
+the **source of truth for the wire**: the API imports the same schemas to
+validate requests and to emit its OpenAPI document, and the `IC*` response
+types are inferred from them.
+
+```ts
+import { schemas } from "@ingram-cloud/sdk";
+
+// Runtime-validate a request/response body against the contract.
+const agent = schemas.AgentIn.parse(input);
+```
+
+```ts
+import type { ICSmith, ICRun, ICAgent } from "@ingram-cloud/sdk/responses";
+
+// Type a /v1 JSON response — no zod is pulled in.
+function render(smith: ICSmith) {
+	/* … */
+}
+```
+
+```ts
+import { IngramCloud } from "@ingram-cloud/sdk/client";
+
+// Typed CRUD over the management plane (smiths, agents, tenant config, …).
+const ic = new IngramCloud({ token: process.env.INGRAM_CLOUD_TOKEN! });
+const smith = await ic.smiths.create({ external_id: "user-42" });
+```
+
+## Exports
+
+- `.` — the `schemas` Zod map plus the SSE/webhook event types (`EVENT_TYPES`,
+  `webhookEvent`, `streamFrame`, …).
+- `./schemas` — just the Zod `schemas` map.
+- `./zod` — the same schemas as individual named exports, one module per resource.
+- `./responses` — the `IC*` TypeScript types for the JSON response bodies.
+  Zod-free; `import type` these to stay dependency-light.
+- `./client` — `IngramCloud`, the typed management-plane REST client. Method
+  inputs are `z.input`-inferred from the same schemas the API validates with,
+  so the client can't drift from the contract. Zod-free at runtime (type-only
+  imports; transport is the global `fetch`). Auth is a pluggable token seam:
+  a static bearer or a per-request minting function; smith-scoped calls made
+  with a tenant token pass `{ smith }` (the `IC-Smith-Id` header). Non-2xx
+  throws `ICError { status, code, requestId }`.
+
+The OpenAPI document is served by the API itself (`/openapi.json`), emitted from
+these schemas — it is no longer shipped as a file in this package.
+
+The client is the **management plane** only. The **data plane** stays on
+industry standards: chat rides the OpenAI-compatible surface — use
+`@ingram-cloud/ai-sdk` and the standard `@ai-sdk/*` types for that. The
+native run stream is exposed raw (`smiths.runs.stream` returns the SSE
+`Response` unconsumed).
+
+> Ships compiled ESM (`dist/`) alongside the TypeScript source (`ts/`). Node
+> and bundlers load `dist/` — no transpile config needed. Types resolve straight
+> to the source, and Bun (the `bun` export condition) runs the source directly.
+
+## Coverage
+
+Every resource's request bodies and non-streaming JSON responses are typed as
+precise Zod (one module per resource under `./zod`), and the `IC*` types are
+inferred from them. The **streaming/union** endpoints (`/runs` stream,
+`/chat/completions`, `/responses` — a stream *or* JSON from one handler), deployment
+**webhook acks**, and the OAuth **redirect** are not expressible as a single
+response schema, so they're not in the typed surface; the `{v:1}` webhook/feed
+envelope and the SSE run-stream frames are the hand-authored `./events` half.
+
+The OpenAI-compatible stream chunks themselves are standard — use the `@ai-sdk/*`
+types rather than redefining them here.

package/dist/client.js

@@ -0,0 +1,460 @@
+export const DEFAULT_BASE_URL = "https://api.cloud.ingram.tech";
+/** The `/v1` API version this client pins (`IC-Api-Version`). */
+export const DEFAULT_API_VERSION = "2026-05-01";
+/** A non-2xx `/v1` response: HTTP status + the error envelope's `code`.
+ *  `message` carries the full context (method, path, status); `detail` is the
+ *  envelope's bare `error.message`, suitable for user-facing copy. */
+export class ICError extends Error {
+    status;
+    code;
+    requestId;
+    detail;
+    constructor(status, code, message, requestId, detail) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.requestId = requestId;
+        this.detail = detail;
+        this.name = "ICError";
+    }
+}
+const enc = encodeURIComponent;
+function qs(query) {
+    if (!query)
+        return "";
+    const p = new URLSearchParams();
+    for (const [k, v] of Object.entries(query)) {
+        if (v === undefined || v === null || v === "")
+            continue;
+        p.set(k, String(v));
+    }
+    const s = p.toString();
+    return s ? `?${s}` : "";
+}
+export class IngramCloud {
+    token;
+    base;
+    apiVersion;
+    transport;
+    requestInit;
+    constructor(opts) {
+        this.token = opts.token;
+        this.base = (opts.baseURL ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.apiVersion = opts.apiVersion ?? DEFAULT_API_VERSION;
+        this.transport = opts.fetch ?? ((url, init) => fetch(url, init));
+        this.requestInit = opts.requestInit ?? {};
+    }
+    /** Low-level escape hatch: an authenticated `/v1` call (path without the
+     *  `/v1` prefix). Throws {@link ICError} on a non-2xx. */
+    async request(method, path, opts = {}) {
+        const token = opts.token ??
+            (typeof this.token === "function" ? await this.token() : this.token);
+        const headers = {
+            accept: "application/json",
+            "ic-api-version": this.apiVersion,
+            authorization: `Bearer ${token}`,
+            ...(opts.body !== undefined && opts.rawBody === undefined
+                ? { "content-type": "application/json" }
+                : {}),
+            ...(opts.smith ? { "ic-smith-id": opts.smith } : {}),
+            ...opts.headers,
+        };
+        const res = await this.transport(`${this.base}/v1${path}${qs(opts.query)}`, {
+            ...this.requestInit,
+            method,
+            headers,
+            body: opts.rawBody ??
+                (opts.body !== undefined ? JSON.stringify(opts.body) : undefined),
+            signal: opts.signal,
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => "");
+            let code = `http_${res.status}`;
+            let detail;
+            try {
+                const parsed = JSON.parse(body);
+                code = parsed.error?.code ?? code;
+                detail = parsed.error?.message;
+            }
+            catch { }
+            const requestId = res.headers.get("x-request-id") ?? undefined;
+            throw new ICError(res.status, code, `IC ${method} ${path} → ${res.status} ${code}: ${detail ?? body.slice(0, 300)}${requestId ? ` [${requestId}]` : ""}`, requestId, detail);
+        }
+        return res;
+    }
+    /** {@link request}, parsed as JSON. */
+    async json(method, path, opts = {}) {
+        const res = await this.request(method, path, opts);
+        return res.json();
+    }
+    async page(path, query, opts) {
+        const r = await this.json("GET", path, { ...opts, query });
+        return {
+            data: r.data ?? [],
+            next_cursor: r.next_cursor ?? null,
+            has_more: r.has_more ?? false,
+        };
+    }
+    async data(method, path, opts = {}) {
+        const r = await this.json(method, path, opts);
+        return r.data ?? [];
+    }
+    async empty(method, path, opts = {}) {
+        await this.request(method, path, opts);
+    }
+    // ── Smiths ──────────────────────────────────────────────────────────────
+    smiths = {
+        list: (query, opts) => this.page("/smiths", query, opts),
+        create: (body, opts) => this.json("POST", "/smiths", { ...opts, body }),
+        get: (pid, opts) => this.json("GET", `/smiths/${enc(pid)}`, opts),
+        update: (pid, body, opts) => this.json("PATCH", `/smiths/${enc(pid)}`, { ...opts, body }),
+        delete: (pid, opts) => this.empty("DELETE", `/smiths/${enc(pid)}`, opts),
+        memory: {
+            get: (pid, opts) => this.json("GET", `/smiths/${enc(pid)}/memory`, opts),
+            set: (pid, body, opts) => this.json("PUT", `/smiths/${enc(pid)}/memory`, {
+                ...opts,
+                body,
+            }),
+            recall: (pid, body, opts) => this.data("POST", `/smiths/${enc(pid)}/memory/recall`, {
+                ...opts,
+                body,
+            }),
+        },
+        revisions: {
+            list: (pid, opts) => this.data("GET", `/smiths/${enc(pid)}/revisions`, opts),
+            restore: (pid, version, body = {}, opts) => this.json("POST", `/smiths/${enc(pid)}/revisions/${version}/restore`, {
+                ...opts,
+                body,
+            }),
+        },
+        connections: {
+            list: (pid, opts) => this.data("GET", `/smiths/${enc(pid)}/connections`, opts),
+            get: (pid, cid, opts) => this.json("GET", `/smiths/${enc(pid)}/connections/${enc(cid)}`, opts),
+            create: (pid, body, opts) => this.json("POST", `/smiths/${enc(pid)}/connections`, {
+                ...opts,
+                body,
+            }),
+            update: (pid, cid, body, opts) => this.json("PATCH", `/smiths/${enc(pid)}/connections/${enc(cid)}`, { ...opts, body }),
+            delete: (pid, cid, opts) => this.empty("DELETE", `/smiths/${enc(pid)}/connections/${enc(cid)}`, opts),
+            refresh: (pid, cid, opts) => this.json("POST", `/smiths/${enc(pid)}/connections/${enc(cid)}/refresh`, opts),
+            /** Mint a hosted-consent authorize URL the end user is sent to. */
+            authorize: (pid, body, opts) => this.json("POST", `/smiths/${enc(pid)}/connections/authorize`, {
+                ...opts,
+                body,
+            }),
+        },
+        schedules: {
+            list: (pid, opts) => this.data("GET", `/smiths/${enc(pid)}/schedules`, opts),
+            create: (pid, body, opts) => this.json("POST", `/smiths/${enc(pid)}/schedules`, {
+                ...opts,
+                body,
+            }),
+            update: (pid, sid, body, opts) => this.json("PATCH", `/smiths/${enc(pid)}/schedules/${enc(sid)}`, { ...opts, body }),
+            delete: (pid, sid, opts) => this.empty("DELETE", `/smiths/${enc(pid)}/schedules/${enc(sid)}`, opts),
+            runNow: (pid, sid, opts) => this.json("POST", `/smiths/${enc(pid)}/schedules/${enc(sid)}/run_now`, opts),
+        },
+        runs: {
+            list: (pid, query, opts) => this.page(`/smiths/${enc(pid)}/runs`, query, opts),
+            /** Non-streaming run: returns the completed (or paused) run record. */
+            create: (pid, body, opts) => this.json("POST", `/smiths/${enc(pid)}/runs`, {
+                ...opts,
+                body: { ...body, stream: false },
+            }),
+            /** Streaming run: returns the raw SSE `Response`, body unconsumed. */
+            stream: (pid, body, opts) => this.request("POST", `/smiths/${enc(pid)}/runs`, {
+                ...opts,
+                body: { ...body, stream: true },
+            }),
+            get: (pid, rid, opts) => this.json("GET", `/smiths/${enc(pid)}/runs/${enc(rid)}`, opts),
+            /** Resume a paused run (approval decision, tool result, cancel). */
+            submit: (pid, rid, body, opts) => this.json("POST", `/smiths/${enc(pid)}/runs/${enc(rid)}/submit`, { ...opts, body }),
+            /** Re-run a recorded run's input as a fresh run. */
+            replay: (pid, rid, opts) => this.json("POST", `/smiths/${enc(pid)}/runs/${enc(rid)}/replay`, { ...opts, body: {} }),
+            /** The recorded run events (the SSE replay endpoint, parsed). */
+            events: async (pid, rid, opts) => {
+                const res = await this.request("GET", `/smiths/${enc(pid)}/runs/${enc(rid)}/events`, opts);
+                const text = await res.text();
+                const out = [];
+                for (const block of text.split(/\r?\n\r?\n/)) {
+                    let seq = 0;
+                    let type = "";
+                    let data = "";
+                    for (const line of block.split(/\r?\n/)) {
+                        if (line.startsWith("id:"))
+                            seq = Number(line.slice(3).trim());
+                        else if (line.startsWith("event:"))
+                            type = line.slice(6).trim();
+                        else if (line.startsWith("data:"))
+                            data += line.slice(5).trim();
+                    }
+                    if (!data)
+                        continue;
+                    try {
+                        out.push({
+                            seq,
+                            type,
+                            data: JSON.parse(data),
+                            created_at: null,
+                        });
+                    }
+                    catch { }
+                }
+                return out;
+            },
+        },
+    };
+    // ── Runs (tenant-wide feed) ─────────────────────────────────────────────
+    runs = {
+        list: (query, opts) => this.page("/runs", query, opts),
+    };
+    // ── Agents ──────────────────────────────────────────────────────────────
+    agents = {
+        list: (query, opts) => this.page("/agents", query, opts),
+        create: (body, opts) => this.json("POST", "/agents", { ...opts, body }),
+        get: (aid, opts) => this.json("GET", `/agents/${enc(aid)}`, opts),
+        update: (aid, body, opts) => this.json("PATCH", `/agents/${enc(aid)}`, { ...opts, body }),
+        delete: (aid, opts) => this.empty("DELETE", `/agents/${enc(aid)}`, opts),
+        versions: {
+            list: (aid, opts) => this.data("GET", `/agents/${enc(aid)}/versions`, opts),
+            /** Snapshot the draft as the next immutable version. */
+            publish: (aid, body = {}, opts) => this.json("POST", `/agents/${enc(aid)}/versions`, {
+                ...opts,
+                body,
+            }),
+        },
+        /** Point smiths at a version (`percent < 100` stages a sticky rollout). */
+        rollout: (aid, body, opts) => this.json("POST", `/agents/${enc(aid)}/rollout`, {
+            ...opts,
+            body,
+        }),
+        /** Seed a new agent from an existing smith's effective config. */
+        import: (body, opts) => this.json("POST", "/agents/import", { ...opts, body }),
+        /** Adopt existing smiths onto this agent. */
+        attach: (aid, body, opts) => this.json("POST", `/agents/${enc(aid)}/attach`, { ...opts, body }),
+        /** MCP Apps UI templates (SEP-1865) attached to the agent's draft. */
+        ui: {
+            list: (aid, opts) => this.data("GET", `/agents/${enc(aid)}/ui`, opts),
+            get: (aid, name, opts) => this.json("GET", `/agents/${enc(aid)}/ui/${enc(name)}`, opts),
+            /** Upload/replace a template — `html` is the bundle, `meta` its
+             *  `{ name, csp?, permissions?, tool? }` sidecar. Replaces by name. */
+            put: (aid, html, meta, opts) => {
+                const form = new FormData();
+                form.append("file", html instanceof Blob ? html : new Blob([html], { type: "text/html" }), `${meta.name}.html`);
+                form.append("metadata", JSON.stringify(meta));
+                return this.json("POST", `/agents/${enc(aid)}/ui`, {
+                    ...opts,
+                    rawBody: form,
+                });
+            },
+            delete: (aid, name, opts) => this.json("DELETE", `/agents/${enc(aid)}/ui/${enc(name)}`, opts),
+        },
+    };
+    // ── Conversations (smith-scoped: pass `{ smith }` with a tenant token) ──
+    conversations = {
+        list: (query, opts) => this.page("/conversations", query, opts),
+        create: (body = {}, opts) => this.json("POST", "/conversations", { ...opts, body }),
+        get: (cnvId, opts) => this.json("GET", `/conversations/${enc(cnvId)}`, opts),
+        /** OpenAI-style modify — a POST, not a PATCH. */
+        update: (cnvId, body, opts) => this.json("POST", `/conversations/${enc(cnvId)}`, {
+            ...opts,
+            body,
+        }),
+        delete: (cnvId, opts) => this.empty("DELETE", `/conversations/${enc(cnvId)}`, opts),
+        /** The faithful transcript (message / function_call / mcp_call items). */
+        items: (cnvId, query, opts) => this.data("GET", `/conversations/${enc(cnvId)}/items`, {
+            ...opts,
+            query,
+        }),
+    };
+    // ── Approvals / events ──────────────────────────────────────────────────
+    approvals = {
+        list: (query, opts) => this.page("/approvals", query, opts),
+        get: (aprId, opts) => this.json("GET", `/approvals/${enc(aprId)}`, opts),
+    };
+    events = {
+        list: (query, opts) => this.page("/events", query, opts),
+    };
+    // ── Customers / budgets ─────────────────────────────────────────────────
+    customers = {
+        list: (query, opts) => this.page("/customers", query, opts),
+        create: (body, opts) => this.json("POST", "/customers", { ...opts, body }),
+        get: (cid, opts) => this.json("GET", `/customers/${enc(cid)}`, opts),
+        update: (cid, body, opts) => this.json("PATCH", `/customers/${enc(cid)}`, { ...opts, body }),
+        delete: (cid, opts) => this.empty("DELETE", `/customers/${enc(cid)}`, opts),
+    };
+    budgets = {
+        list: (opts) => this.data("GET", "/budgets", opts),
+        create: (body, opts) => this.json("POST", "/budgets", { ...opts, body }),
+        get: (bid, opts) => this.json("GET", `/budgets/${enc(bid)}`, opts),
+        update: (bid, body, opts) => this.json("PATCH", `/budgets/${enc(bid)}`, { ...opts, body }),
+        delete: (bid, opts) => this.empty("DELETE", `/budgets/${enc(bid)}`, opts),
+        status: (bid, opts) => this.json("GET", `/budgets/${enc(bid)}/status`, opts),
+    };
+    // ── Deployments (smith/agent bound to a messaging surface) ──────────────
+    deployments = {
+        list: (query, opts) => this.page("/deployments", query, opts),
+        create: (body, opts) => this.json("POST", "/deployments", { ...opts, body }),
+        get: (depId, opts) => this.json("GET", `/deployments/${enc(depId)}`, opts),
+        update: (depId, body, opts) => this.json("PATCH", `/deployments/${enc(depId)}`, {
+            ...opts,
+            body,
+        }),
+        delete: (depId, opts) => this.empty("DELETE", `/deployments/${enc(depId)}`, opts),
+    };
+    // ── Catalog (Ingram-curated MCP integration presets) ────────────────────
+    catalog = {
+        list: (opts) => this.data("GET", "/catalog", opts),
+        get: (slug, opts) => this.json("GET", `/catalog/${enc(slug)}`, opts),
+    };
+    // ── Observability ───────────────────────────────────────────────────────
+    traces = {
+        list: (query, opts) => this.page("/traces", query, opts),
+        get: (traceId, opts) => this.json("GET", `/traces/${enc(traceId)}`, opts),
+    };
+    usage = {
+        /** Token/cost/run totals grouped by app, smith, model, or customer. */
+        breakdown: (query, opts) => this.json("GET", "/usage", { ...opts, query }),
+    };
+    // ── Files (the OpenAI Files API) ─────────────────────────────────────────
+    files = {
+        /** Multipart upload. `file` is a `File`/`Blob`; `purpose` defaults to
+         *  `assistants` (the vector-store source purpose). */
+        upload: (file, opts) => {
+            const form = new FormData();
+            form.set("file", file, opts?.filename ?? (file instanceof File ? file.name : "file"));
+            form.set("purpose", opts?.purpose ?? "assistants");
+            return this.json("POST", "/files", { ...opts, rawBody: form });
+        },
+        /** Uploads only (OpenAI `list` envelope); inline files stay unlisted. */
+        list: (query, opts) => this.json("GET", "/files", { ...opts, query }),
+        get: (id, opts) => this.json("GET", `/files/${enc(id)}`, opts),
+        /** The raw bytes `Response` (follows the presigned-URL redirect). */
+        content: (id, opts) => this.request("GET", `/files/${enc(id)}/content`, opts),
+        delete: (id, opts) => this.json("DELETE", `/files/${enc(id)}`, opts),
+    };
+    // ── Vector stores (the OpenAI Vector Stores API) ─────────────────────────
+    vectorStores = {
+        create: (body, opts) => this.json("POST", "/vector_stores", { ...opts, body }),
+        list: (query, opts) => this.json("GET", "/vector_stores", { ...opts, query }),
+        get: (vsId, opts) => this.json("GET", `/vector_stores/${enc(vsId)}`, opts),
+        /** Modify (OpenAI uses `POST`, not `PATCH`). */
+        update: (vsId, body, opts) => this.json("POST", `/vector_stores/${enc(vsId)}`, { ...opts, body }),
+        delete: (vsId, opts) => this.json("DELETE", `/vector_stores/${enc(vsId)}`, opts),
+        search: (vsId, body, opts) => this.json("POST", `/vector_stores/${enc(vsId)}/search`, {
+            ...opts,
+            body,
+        }),
+        files: {
+            create: (vsId, body, opts) => this.json("POST", `/vector_stores/${enc(vsId)}/files`, {
+                ...opts,
+                body,
+            }),
+            list: (vsId, query, opts) => this.json("GET", `/vector_stores/${enc(vsId)}/files`, { ...opts, query }),
+            get: (vsId, fileId, opts) => this.json("GET", `/vector_stores/${enc(vsId)}/files/${enc(fileId)}`, opts),
+            update: (vsId, fileId, body, opts) => this.json("POST", `/vector_stores/${enc(vsId)}/files/${enc(fileId)}`, { ...opts, body }),
+            delete: (vsId, fileId, opts) => this.json("DELETE", `/vector_stores/${enc(vsId)}/files/${enc(fileId)}`, opts),
+        },
+        fileBatches: {
+            create: (vsId, body, opts) => this.json("POST", `/vector_stores/${enc(vsId)}/file_batches`, { ...opts, body }),
+            get: (vsId, batchId, opts) => this.json("GET", `/vector_stores/${enc(vsId)}/file_batches/${enc(batchId)}`, opts),
+            cancel: (vsId, batchId, opts) => this.json("POST", `/vector_stores/${enc(vsId)}/file_batches/${enc(batchId)}/cancel`, opts),
+            files: (vsId, batchId, query, opts) => this.json("GET", `/vector_stores/${enc(vsId)}/file_batches/${enc(batchId)}/files`, { ...opts, query }),
+        },
+    };
+    // ── Tenant config ───────────────────────────────────────────────────────
+    tenant = {
+        usage: (opts) => this.json("GET", "/tenant/usage", opts),
+        models: (opts) => this.json("GET", "/tenant/models", opts),
+        hostedTools: (opts) => this.data("GET", "/tenant/hosted_tools", opts),
+        tokens: {
+            list: (query, opts) => this.page("/tenant/tokens", query, opts),
+            /** Mint a tenant-admin or smith token (secret shown once). */
+            create: (body, opts) => this.json("POST", "/tenant/tokens", { ...opts, body }),
+            revoke: (tid, opts) => this.empty("DELETE", `/tenant/tokens/${enc(tid)}`, opts),
+        },
+        webhooks: {
+            list: (query, opts) => this.page("/tenant/webhooks", query, opts),
+            /** Returns the signing `secret` exactly once. */
+            create: (body, opts) => this.json("POST", "/tenant/webhooks", { ...opts, body }),
+            update: (wid, body, opts) => this.json("PATCH", `/tenant/webhooks/${enc(wid)}`, {
+                ...opts,
+                body,
+            }),
+            delete: (wid, opts) => this.empty("DELETE", `/tenant/webhooks/${enc(wid)}`, opts),
+            test: (wid, opts) => this.json("POST", `/tenant/webhooks/${enc(wid)}/test`, opts),
+        },
+        providers: {
+            list: (opts) => this.data("GET", "/tenant/providers", opts),
+            get: (provider, opts) => this.json("GET", `/tenant/providers/${enc(provider)}`, opts),
+            put: (provider, body, opts) => this.json("PUT", `/tenant/providers/${enc(provider)}`, {
+                ...opts,
+                body,
+            }),
+            delete: (provider, opts) => this.empty("DELETE", `/tenant/providers/${enc(provider)}`, opts),
+        },
+        modelKeys: {
+            list: (opts) => this.data("GET", "/tenant/model_keys", opts),
+            /** Store a BYOK model-provider key (never read back). */
+            put: (provider, body, opts) => this.json("PUT", `/tenant/model_keys/${enc(provider)}`, {
+                ...opts,
+                body,
+            }),
+            delete: (provider, opts) => this.empty("DELETE", `/tenant/model_keys/${enc(provider)}`, opts),
+        },
+        mcp: {
+            list: (opts) => this.data("GET", "/tenant/mcp", opts),
+            get: (name, opts) => this.json("GET", `/tenant/mcp/${enc(name)}`, opts),
+            /** Register or replace a server (full replace; probes `tools/list`). */
+            put: (name, body, opts) => this.json("PUT", `/tenant/mcp/${enc(name)}`, { ...opts, body }),
+            refresh: (name, opts) => this.json("POST", `/tenant/mcp/${enc(name)}/refresh`, opts),
+            delete: (name, opts) => this.empty("DELETE", `/tenant/mcp/${enc(name)}`, opts),
+        },
+        telegram: {
+            get: (opts) => this.json("GET", "/tenant/telegram", opts),
+            put: (body, opts) => this.json("PUT", "/tenant/telegram", { ...opts, body }),
+            delete: (opts) => this.empty("DELETE", "/tenant/telegram", opts),
+        },
+        slack: {
+            get: (opts) => this.json("GET", "/tenant/slack", opts),
+            put: (body, opts) => this.json("PUT", "/tenant/slack", { ...opts, body }),
+            delete: (opts) => this.empty("DELETE", "/tenant/slack", opts),
+        },
+        discord: {
+            get: (opts) => this.json("GET", "/tenant/discord", opts),
+            put: (body, opts) => this.json("PUT", "/tenant/discord", { ...opts, body }),
+            delete: (opts) => this.empty("DELETE", "/tenant/discord", opts),
+        },
+        whatsapp: {
+            get: (opts) => this.json("GET", "/tenant/whatsapp", opts),
+            put: (body, opts) => this.json("PUT", "/tenant/whatsapp", {
+                ...opts,
+                body,
+            }),
+            delete: (opts) => this.empty("DELETE", "/tenant/whatsapp", opts),
+        },
+        email: {
+            get: (opts) => this.json("GET", "/tenant/email", opts),
+            put: (body, opts) => this.json("PUT", "/tenant/email", { ...opts, body }),
+            delete: (opts) => this.empty("DELETE", "/tenant/email", opts),
+        },
+    };
+    // ── Organization (org token: projects + billing) ────────────────────────
+    organization = {
+        projects: {
+            list: (opts) => this.data("GET", "/organization/projects", opts),
+            create: (body, opts) => this.json("POST", "/organization/projects", {
+                ...opts,
+                body,
+            }),
+            get: (pid, opts) => this.json("GET", `/organization/projects/${enc(pid)}`, opts),
+            delete: (pid, opts) => this.empty("DELETE", `/organization/projects/${enc(pid)}`, opts),
+            tokens: {
+                create: (pid, body, opts) => this.json("POST", `/organization/projects/${enc(pid)}/tokens`, {
+                    ...opts,
+                    body,
+                }),
+                delete: (pid, tid, opts) => this.empty("DELETE", `/organization/projects/${enc(pid)}/tokens/${enc(tid)}`, opts),
+            },
+        },
+    };
+}

package/dist/events.js

@@ -0,0 +1,108 @@
+/**
+ * The Ingram Cloud event types — HAND-AUTHORED (not generated).
+ *
+ * Two event surfaces ride the native `{v:1}` envelope and are deliberately NOT in
+ * `openapi.json`: OpenAPI can't describe an SSE frame sequence (even OpenAI's own
+ * spec doesn't type its stream chunks — SDKs hand-define them). So these live
+ * here, hand-authored, and must be kept in step with
+ * `web/src/content/docs/events.md` (the canonical catalog).
+ *
+ * 1. {@link webhookEvent} — the append-only feed / webhook delivery envelope
+ *    (`GET /v1/events`, signed webhook POSTs).
+ * 2. {@link streamFrame} — the live SSE run-stream frames (`POST .../runs` with
+ *    `stream:true`), i.e. `runs.py::_stream`.
+ *
+ * `data` is `.passthrough()` on purpose: the catalog documents the *notable*
+ * fields per type, not an exhaustive closed shape — same philosophy as the
+ * `extra="allow"` response models. Consumers narrow on `type` / `event`.
+ */
+import { z } from "zod";
+// ─── Feed / webhook event types (docs/events.md "Event type catalog") ────────
+// Only these reach the `/v1/events` feed and signed webhooks. Pure run-stream frames
+// — `run.started`, `message.delta`, `message.completed`, `run.cancelled` — ride the
+// live SSE stream and the per-run timeline only; they are NOT feed events (see
+// {@link STREAM_EVENTS}). `tool.executing` / `tool.completed` are both: a live frame
+// AND a feed event.
+export const EVENT_TYPES = [
+    "run.paused",
+    "run.completed",
+    "run.failed",
+    "tool.executing",
+    "tool.completed",
+    "approval.required",
+    "approval.resolved",
+    "connection.required",
+    "unbound_message",
+    "budget.threshold",
+    "credit.exhausted",
+    "deployment.bound",
+    "deployment.inbound",
+    "slack.app_provisioned",
+    "slack.install",
+    "slack.uninstalled",
+    "email.send_failed",
+    "webhook.test",
+];
+export const eventType = z.enum(EVENT_TYPES);
+/**
+ * The envelope carried identically by the `/v1/events` feed and signed webhook
+ * POSTs. `type` is a plain string (not the enum) so a forward-added type still
+ * parses; compare against {@link EVENT_TYPES} / {@link eventType} when narrowing.
+ */
+export const webhookEvent = z
+    .object({
+    v: z.literal(1),
+    id: z.string(),
+    type: z.string(),
+    created_at: z.string(),
+    tenant_id: z.string(),
+    smith_id: z.string().nullable().optional(),
+    data: z.record(z.string(), z.unknown()).default({}),
+})
+    .passthrough();
+// ─── Native SSE run-stream frames (runs.py::_stream `{v:1, run_id, ...}`) ─────
+// The SSE `event:` line becomes `event`; the frame's data fields sit alongside
+// `v` / `run_id`. `tool.executing` / `tool.completed` ride the live stream as they
+// happen AND are mirrored to the run timeline + feed (see EVENT_TYPES) so a run's
+// tool activity is auditable after the fact. The standard surface expresses the same
+// live status on the OpenAI Responses API (`/v1/responses`) as `mcp_call` items
+// (`response.mcp_call.in_progress` / `.completed`); those are standard OpenAI shapes,
+// so we don't re-type them here — consume them with the OpenAI/AI SDK. These native
+// frames are the place to retire as that lands everywhere (see CLAUDE.md).
+export const STREAM_EVENTS = [
+    "run.started",
+    "message.delta",
+    "tool.executing",
+    "tool.completed",
+    "run.paused",
+    "approval.required",
+    "run.completed",
+    "run.failed",
+    "run.cancelled",
+    "run.duplicate",
+    "message.completed",
+];
+export const streamEventName = z.enum(STREAM_EVENTS);
+export const streamFrame = z
+    .object({
+    event: z.string(),
+    v: z.number().optional(),
+    run_id: z.string().optional(),
+})
+    .passthrough();
+// ─── A few well-known `data` shapes (convenience; still passthrough) ─────────
+export const messageDeltaData = z.object({ delta: z.string() }).passthrough();
+export const runCompletedData = z
+    .object({
+    stop_reason: z.string(),
+    usage: z.record(z.string(), z.unknown()).optional(),
+})
+    .passthrough();
+export const approvalRequiredData = z
+    .object({
+    approval_id: z.string(),
+    tool: z.string().nullable().optional(),
+    args: z.record(z.string(), z.unknown()).optional(),
+})
+    .passthrough();
+export const toolActivityData = z.object({ tool: z.string().nullable() }).passthrough();

package/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * The Ingram Cloud API wire contract, in TypeScript.
+ *
+ * `schemas` is the named map of hand-authored Zod schemas for the request and
+ * response bodies (defined in `./zod`, one module per resource). It's the source
+ * of truth for the wire shapes — the API imports the same schemas to validate
+ * requests and to emit its OpenAPI document — and you can use it to validate a
+ * body against the contract. This package is not an HTTP client.
+ *
+ * `./responses` is the matching `IC*` TypeScript types (inferred from the same
+ * schemas), for typing the JSON you read back without pulling in Zod.
+ *
+ * `./events` is the hand-authored `{v:1}` webhook/feed envelope and the SSE
+ * run-stream frames, which OpenAPI can't express.
+ *
+ * See `../README.md`.
+ */
+export { schemas } from "./schemas.js";
+export * from "./events.js";