@ingram-cloud/sdk 1.2.0 → 1.5.0

package/ts/client.ts

@@ -30,6 +30,8 @@ import type {
 	ICAgentVersion,
 	ICApproval,
 	ICAuthorizeRequest,
+	ICAutoreload,
+	ICBalance,
 	ICBudget,
 	ICBudgetStatus,
 	ICCatalogEntry,
@@ -41,13 +43,18 @@ import type {
 	ICDeploymentCreated,
 	ICDiscordApp,
 	ICEmailConfig,
+	ICEmbeddingList,
 	ICEvent,
 	ICFile,
 	ICFileList,
+	ICInboundEvent,
+	ICLedgerEntry,
 	ICMcpServer,
 	ICMintedToken,
 	ICModelCatalog,
 	ICModelKey,
+	ICOrgUsage,
+	ICOrgUsageSeries,
 	ICProject,
 	ICProvider,
 	ICRecallHit,
@@ -57,6 +64,7 @@ import type {
 	ICSlackApp,
 	ICSmith,
 	ICSmithRevision,
+	ICSpanIn,
 	ICTelegramBot,
 	ICToken,
 	ICTrace,
@@ -83,6 +91,20 @@ import type {
 	RolloutIn,
 	UiResourceIn,
 } from "./zod/agents.js";
+import type {
+	AutoreloadIn,
+	CheckoutIn,
+	CheckoutOut,
+	ConfirmIn,
+	ConfirmOut,
+	PortalOut,
+	RedeemIn,
+	RedeemOut,
+	ReloadIn,
+	ReloadOut,
+	SetupIn,
+	SetupOut,
+} from "./zod/billing.js";
 import type { BudgetIn, BudgetPatch } from "./zod/budgets.js";
 import type {
 	AuthorizeIn,
@@ -95,10 +117,11 @@ import type { CustomerCreate, CustomerPatch } from "./zod/customers.js";
 import type { DeploymentIn, DeploymentPatch } from "./zod/deployments.js";
 import type { DiscordAppIn } from "./zod/discord.js";
 import type { EmailConfigIn } from "./zod/email.js";
-import type { McpServerIn, McpServerWriteOut } from "./zod/mcp.js";
+import type { McpServerIn } from "./zod/mcp.js";
 import type { RecallBody, WorkingMemorySet } from "./zod/memories.js";
 import type { ProjectIn, ProjectTokenIn, ProjectTokenOut } from "./zod/projects.js";
 import type { RunIn, Submit } from "./zod/runs.js";
+import type { Skill, SkillUpdateIn, SkillVersion } from "./zod/skills.js";
 import type {
 	VectorStoreFileBatchIn,
 	VectorStoreFileIn,
@@ -125,6 +148,8 @@ import type {
 	WebhookIn,
 	WebhookPatch,
 	WebhookRedeliverOut,
+	WebhookRotateIn,
+	WebhookRotateOut,
 } from "./zod/tenant.js";
 import type { WhatsAppConfigIn } from "./zod/whatsapp.js";
 
@@ -141,6 +166,16 @@ export interface ICPage<T> {
 	has_more: boolean;
 }
 
+/** An OpenAI-dialect list page (`object:"list"` — files, vector stores,
+ *  conversations). Page forward by passing `last_id` back as `after`. */
+export interface ICOaiList<T> {
+	object: "list";
+	data: T[];
+	first_id: string | null;
+	last_id: string | null;
+	has_more: boolean;
+}
+
 /** 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. */
@@ -214,6 +249,66 @@ function qs(query: Query | undefined): string {
 	return s ? `?${s}` : "";
 }
 
+/** One file of a bundle, as the caller holds it. The path is relative to — and
+ *  includes — the skill's root directory, e.g. `invoice-review/SKILL.md`. */
+export interface SkillFileInput {
+	path: string;
+	content: string | Blob | Uint8Array;
+}
+
+/** A bundle to upload: its files, or the whole thing zipped. */
+export type SkillBundle = SkillFileInput[] | Blob;
+
+/** Build the multipart body `/v1/skills` accepts.
+ *
+ *  The path rides the part's *filename*, slashes and all — that is how the
+ *  bundle's directory structure survives a multipart body. `FormData` in Node,
+ *  Bun and browsers all pass it through verbatim. */
+function bundleForm(bundle: SkillBundle): FormData {
+	const form = new FormData();
+	if (bundle instanceof Blob) {
+		form.append("file", bundle, "bundle.zip");
+		return form;
+	}
+	for (const file of bundle) {
+		// A `Uint8Array`'s buffer type is generic (and may be a `SharedArrayBuffer`),
+		// which `Blob`'s constructor does not accept — copy into a fresh one, whose
+		// buffer is always a plain `ArrayBuffer`.
+		const part =
+			typeof file.content === "string" || file.content instanceof Blob
+				? file.content
+				: new Uint8Array(file.content);
+		const blob =
+			part instanceof Blob
+				? part
+				: new Blob([part], { type: mediaTypeFor(file.path) });
+		form.append("files[]", blob, file.path);
+	}
+	return form;
+}
+
+/** A `Blob` built from a string has no type of its own; the server falls back to
+ *  `application/octet-stream` when a part carries none, which would make every
+ *  text file non-indexable. Name the common ones from the extension. */
+function mediaTypeFor(path: string): string {
+	const ext = path.slice(path.lastIndexOf(".") + 1).toLowerCase();
+	const known: Record<string, string> = {
+		md: "text/markdown",
+		markdown: "text/markdown",
+		txt: "text/plain",
+		json: "application/json",
+		yaml: "text/yaml",
+		yml: "text/yaml",
+		csv: "text/csv",
+		py: "text/x-python",
+		sh: "text/x-shellscript",
+		js: "text/javascript",
+		ts: "text/typescript",
+		html: "text/html",
+	};
+	return known[ext] ?? "application/octet-stream";
+}
+
 export class IngramCloud {
 	private readonly token: IngramCloudOptions["token"];
 	private readonly base: string;
@@ -372,10 +467,10 @@ export class IngramCloud {
 		},
 
 		revisions: {
-			list: (pid: string, opts?: RequestOptions) =>
-				this.data<ICSmithRevision>(
-					"GET",
+			list: (pid: string, query?: PageOpts, opts?: RequestOptions) =>
+				this.page<ICSmithRevision>(
 					`/smiths/${enc(pid)}/revisions`,
+					query,
 					opts,
 				),
 			restore: (
@@ -395,8 +490,12 @@ export class IngramCloud {
 		},
 
 		connections: {
-			list: (pid: string, opts?: RequestOptions) =>
-				this.data<ICConnection>("GET", `/smiths/${enc(pid)}/connections`, opts),
+			list: (
+				pid: string,
+				query?: PageOpts & { provider?: string },
+				opts?: RequestOptions,
+			) =>
+				this.page<ICConnection>(`/smiths/${enc(pid)}/connections`, query, opts),
 			get: (pid: string, cid: string, opts?: RequestOptions) =>
 				this.json<ICConnection>(
 					"GET",
@@ -451,9 +550,33 @@ export class IngramCloud {
 				),
 		},
 
-		schedules: {
+		/** End-user BYOK (#170): a smith's own provider keys, resolved ahead of the
+		 *  tenant's so the end-user's provider account is billed. Never read back. */
+		modelKeys: {
 			list: (pid: string, opts?: RequestOptions) =>
-				this.data<ICSchedule>("GET", `/smiths/${enc(pid)}/schedules`, opts),
+				this.data<ICModelKey>("GET", `/smiths/${enc(pid)}/model_keys`, opts),
+			put: (
+				pid: string,
+				provider: string,
+				body: z.input<typeof ModelKeyIn>,
+				opts?: RequestOptions,
+			) =>
+				this.json<z.infer<typeof ModelKeyConfiguredOut>>(
+					"PUT",
+					`/smiths/${enc(pid)}/model_keys/${enc(provider)}`,
+					{ ...opts, body },
+				),
+			delete: (pid: string, provider: string, opts?: RequestOptions) =>
+				this.empty(
+					"DELETE",
+					`/smiths/${enc(pid)}/model_keys/${enc(provider)}`,
+					opts,
+				),
+		},
+
+		schedules: {
+			list: (pid: string, query?: PageOpts, opts?: RequestOptions) =>
+				this.page<ICSchedule>(`/smiths/${enc(pid)}/schedules`, query, opts),
 			create: (
 				pid: string,
 				body: z.input<typeof ScheduleIn>,
@@ -579,6 +702,8 @@ export class IngramCloud {
 			},
 			opts?: RequestOptions,
 		) => this.page<ICRun>("/runs", query, opts),
+		trace: (rid: string, opts?: RequestOptions) =>
+			this.json<ICTraceDetail>("GET", `/runs/${enc(rid)}/trace`, opts),
 	};
 
 	// ── Agents ──────────────────────────────────────────────────────────────
@@ -599,8 +724,8 @@ export class IngramCloud {
 			this.empty("DELETE", `/agents/${enc(aid)}`, opts),
 
 		versions: {
-			list: (aid: string, opts?: RequestOptions) =>
-				this.data<ICAgentVersion>("GET", `/agents/${enc(aid)}/versions`, opts),
+			list: (aid: string, query?: PageOpts, opts?: RequestOptions) =>
+				this.page<ICAgentVersion>(`/agents/${enc(aid)}/versions`, query, opts),
 			/** Snapshot the draft as the next immutable version. */
 			publish: (
 				aid: string,
@@ -638,7 +763,11 @@ export class IngramCloud {
 			list: (aid: string, opts?: RequestOptions) =>
 				this.data<ICUiResource>("GET", `/agents/${enc(aid)}/ui`, opts),
 			get: (aid: string, name: string, opts?: RequestOptions) =>
-				this.json<ICUiResource>("GET", `/agents/${enc(aid)}/ui/${enc(name)}`, opts),
+				this.json<ICUiResource>(
+					"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: (
@@ -650,7 +779,9 @@ export class IngramCloud {
 				const form = new FormData();
 				form.append(
 					"file",
-					html instanceof Blob ? html : new Blob([html], { type: "text/html" }),
+					html instanceof Blob
+						? html
+						: new Blob([html], { type: "text/html" }),
 					`${meta.name}.html`,
 				);
 				form.append("metadata", JSON.stringify(meta));
@@ -659,20 +790,31 @@ export class IngramCloud {
 					rawBody: form,
 				});
 			},
+			/** The template's HTML bundle — the same bytes the agent's MCP endpoint
+			 *  serves, so a host can render a panel without vendoring a copy.
+			 *  Tenant-authed: call it server-side and proxy to your chat UI. */
+			content: (aid: string, name: string, opts?: RequestOptions) =>
+				this.request("GET", `/agents/${enc(aid)}/ui/${enc(name)}/content`, {
+					...opts,
+					headers: { accept: "text/html", ...opts?.headers },
+				}).then((r) => r.text()),
 			delete: (aid: string, name: string, opts?: RequestOptions) =>
-				this.json<{ name: string; deleted: boolean }>(
-					"DELETE",
-					`/agents/${enc(aid)}/ui/${enc(name)}`,
-					opts,
-				),
+				this.empty("DELETE", `/agents/${enc(aid)}/ui/${enc(name)}`, opts),
 		},
 	};
 
 	// ── Conversations (smith-scoped: pass `{ smith }` with a tenant token) ──
 
 	readonly conversations = {
-		list: (query?: PageOpts, opts?: RequestOptions) =>
-			this.page<ICConversation>("/conversations", query, opts),
+		/** OpenAI `list` envelope; page forward with `after: page.last_id`. */
+		list: (
+			query?: { limit?: number; order?: "asc" | "desc"; after?: string },
+			opts?: RequestOptions,
+		) =>
+			this.json<ICOaiList<ICConversation>>("GET", "/conversations", {
+				...opts,
+				query,
+			}),
 		create: (
 			body: z.input<typeof ConversationCreate> = {},
 			opts?: RequestOptions,
@@ -719,6 +861,18 @@ export class IngramCloud {
 		) => this.page<ICEvent>("/events", query, opts),
 	};
 
+	/** What arrived, before anything interpreted it — including arrivals that
+	 *  matched no smith (`smith_id: ""`). The `iev_` ids `deployment.inbound`
+	 *  carries resolve here. */
+	readonly inboundEvents = {
+		list: (
+			query?: PageOpts & { source?: string; smith_id?: string; since?: string },
+			opts?: RequestOptions,
+		) => this.page<ICInboundEvent>("/inbound_events", query, opts),
+		get: (ievId: string, opts?: RequestOptions) =>
+			this.json<ICInboundEvent>("GET", `/inbound_events/${enc(ievId)}`, opts),
+	};
+
 	// ── Customers / budgets ─────────────────────────────────────────────────
 
 	readonly customers = {
@@ -739,7 +893,8 @@ export class IngramCloud {
 	};
 
 	readonly budgets = {
-		list: (opts?: RequestOptions) => this.data<ICBudget>("GET", "/budgets", opts),
+		list: (query?: PageOpts, opts?: RequestOptions) =>
+			this.page<ICBudget>("/budgets", query, opts),
 		create: (body: z.input<typeof BudgetIn>, opts?: RequestOptions) =>
 			this.json<ICBudget>("POST", "/budgets", { ...opts, body }),
 		get: (bid: string, opts?: RequestOptions) =>
@@ -788,6 +943,18 @@ export class IngramCloud {
 			this.json<ICCatalogEntry>("GET", `/catalog/${enc(slug)}`, opts),
 	};
 
+	// ── Embeddings ──────────────────────────────────────────────────────────
+
+	/** Embed one string or a batch on the OpenAI-compatible wire. Pure tenant
+	 *  compute — no smith runs. Omit `model` for the project default. Reach for
+	 *  the `openai` SDK instead if you already hold one; this is the same route. */
+	readonly embeddings = {
+		create: (
+			body: { input: string | string[]; model?: string },
+			opts?: RequestOptions,
+		) => this.json<ICEmbeddingList>("POST", "/embeddings", { ...opts, body }),
+	};
+
 	// ── Observability ───────────────────────────────────────────────────────
 
 	readonly traces = {
@@ -802,6 +969,15 @@ export class IngramCloud {
 		) => this.page<ICTrace>("/traces", query, opts),
 		get: (traceId: string, opts?: RequestOptions) =>
 			this.json<ICTraceDetail>("GET", `/traces/${enc(traceId)}`, opts),
+		/** Push spans from your own runtime or an OTel exporter. The tenant comes
+		 *  from the token; a smith-scoped token may only attribute to its own smith.
+		 *  Unknown `kind`s land as `runtime_event` rather than erroring. Returns the
+		 *  number written. */
+		ingest: (spans: ICSpanIn[], opts?: RequestOptions) =>
+			this.json<{ accepted: number }>("POST", "/traces:ingest", {
+				...opts,
+				body: { spans },
+			}),
 	};
 
 	readonly usage = {
@@ -851,7 +1027,12 @@ export class IngramCloud {
 		},
 		/** Uploads only (OpenAI `list` envelope); inline files stay unlisted. */
 		list: (
-			query?: { purpose?: string; after?: string; limit?: number; order?: "asc" | "desc" },
+			query?: {
+				purpose?: string;
+				after?: string;
+				limit?: number;
+				order?: "asc" | "desc";
+			},
 			opts?: RequestOptions,
 		) => this.json<ICFileList>("GET", "/files", { ...opts, query }),
 		get: (id: string, opts?: RequestOptions) =>
@@ -860,7 +1041,11 @@ export class IngramCloud {
 		content: (id: string, opts?: RequestOptions) =>
 			this.request("GET", `/files/${enc(id)}/content`, opts),
 		delete: (id: string, opts?: RequestOptions) =>
-			this.json<{ id: string; deleted: true }>("DELETE", `/files/${enc(id)}`, opts),
+			this.json<{ id: string; deleted: true }>(
+				"DELETE",
+				`/files/${enc(id)}`,
+				opts,
+			),
 	};
 
 	// ── Vector stores (the OpenAI Vector Stores API) ─────────────────────────
@@ -869,14 +1054,18 @@ export class IngramCloud {
 		create: (body: z.input<typeof VectorStoreIn>, opts?: RequestOptions) =>
 			this.json<ICVectorStore>("POST", "/vector_stores", { ...opts, body }),
 		list: (
-			query?: { limit?: number; order?: "asc" | "desc"; after?: string; before?: string },
+			query?: {
+				limit?: number;
+				order?: "asc" | "desc";
+				after?: string;
+				before?: string;
+			},
 			opts?: RequestOptions,
 		) =>
-			this.json<{ data: ICVectorStore[]; first_id: string | null; last_id: string | null; has_more: boolean }>(
-				"GET",
-				"/vector_stores",
-				{ ...opts, query },
-			),
+			this.json<ICOaiList<ICVectorStore>>("GET", "/vector_stores", {
+				...opts,
+				query,
+			}),
 		get: (vsId: string, opts?: RequestOptions) =>
 			this.json<ICVectorStore>("GET", `/vector_stores/${enc(vsId)}`, opts),
 		/** Modify (OpenAI uses `POST`, not `PATCH`). */
@@ -884,7 +1073,11 @@ export class IngramCloud {
 			vsId: string,
 			body: z.input<typeof VectorStorePatch>,
 			opts?: RequestOptions,
-		) => this.json<ICVectorStore>("POST", `/vector_stores/${enc(vsId)}`, { ...opts, body }),
+		) =>
+			this.json<ICVectorStore>("POST", `/vector_stores/${enc(vsId)}`, {
+				...opts,
+				body,
+			}),
 		delete: (vsId: string, opts?: RequestOptions) =>
 			this.json<{ id: string; deleted: true }>(
 				"DELETE",
@@ -896,10 +1089,14 @@ export class IngramCloud {
 			body: z.input<typeof VectorStoreSearchIn>,
 			opts?: RequestOptions,
 		) =>
-			this.json<ICVectorStoreSearchPage>("POST", `/vector_stores/${enc(vsId)}/search`, {
-				...opts,
-				body,
-			}),
+			this.json<ICVectorStoreSearchPage>(
+				"POST",
+				`/vector_stores/${enc(vsId)}/search`,
+				{
+					...opts,
+					body,
+				},
+			),
 
 		files: {
 			create: (
@@ -907,10 +1104,14 @@ export class IngramCloud {
 				body: z.input<typeof VectorStoreFileIn>,
 				opts?: RequestOptions,
 			) =>
-				this.json<ICVectorStoreFile>("POST", `/vector_stores/${enc(vsId)}/files`, {
-					...opts,
-					body,
-				}),
+				this.json<ICVectorStoreFile>(
+					"POST",
+					`/vector_stores/${enc(vsId)}/files`,
+					{
+						...opts,
+						body,
+					},
+				),
 			list: (
 				vsId: string,
 				query?: {
@@ -922,7 +1123,7 @@ export class IngramCloud {
 				},
 				opts?: RequestOptions,
 			) =>
-				this.json<{ data: ICVectorStoreFile[]; first_id: string | null; last_id: string | null; has_more: boolean }>(
+				this.json<ICOaiList<ICVectorStoreFile>>(
 					"GET",
 					`/vector_stores/${enc(vsId)}/files`,
 					{ ...opts, query },
@@ -978,7 +1179,12 @@ export class IngramCloud {
 			files: (
 				vsId: string,
 				batchId: string,
-				query?: { limit?: number; order?: "asc" | "desc"; after?: string; filter?: string },
+				query?: {
+					limit?: number;
+					order?: "asc" | "desc";
+					after?: string;
+					filter?: string;
+				},
 				opts?: RequestOptions,
 			) =>
 				this.json<{ data: ICVectorStoreFile[]; has_more: boolean }>(
@@ -989,6 +1195,81 @@ export class IngramCloud {
 		},
 	};
 
+	// ── Agent Skills — a folder anchored by SKILL.md, versioned, attached to
+	// agents. Upload takes either the bundle's files as path/content pairs, or
+	// the whole bundle as a zip Blob — the same two shapes /v1/skills accepts.
+	// Both are runtime-agnostic: nothing here touches a filesystem. ───────────
+
+	readonly skills = {
+		list: (opts?: RequestOptions) =>
+			this.json<{ object: "list"; data: z.infer<typeof Skill>[] }>(
+				"GET",
+				"/skills",
+				opts,
+			),
+		get: (id: string, opts?: RequestOptions) =>
+			this.json<z.infer<typeof Skill>>("GET", `/skills/${enc(id)}`, opts),
+		create: (bundle: SkillBundle, opts?: RequestOptions) =>
+			this.json<z.infer<typeof Skill>>("POST", "/skills", {
+				...opts,
+				rawBody: bundleForm(bundle),
+			}),
+		/** Move `default_version` to an existing version. */
+		update: (
+			id: string,
+			body: z.input<typeof SkillUpdateIn>,
+			opts?: RequestOptions,
+		) =>
+			this.json<z.infer<typeof Skill>>("POST", `/skills/${enc(id)}`, {
+				...opts,
+				body,
+			}),
+		delete: (id: string, opts?: RequestOptions) =>
+			this.request("DELETE", `/skills/${enc(id)}`, opts).then(() => undefined),
+		versions: {
+			list: (id: string, opts?: RequestOptions) =>
+				this.json<{ object: "list"; data: z.infer<typeof SkillVersion>[] }>(
+					"GET",
+					`/skills/${enc(id)}/versions`,
+					opts,
+				),
+			get: (id: string, version: number, opts?: RequestOptions) =>
+				this.json<z.infer<typeof SkillVersion>>(
+					"GET",
+					`/skills/${enc(id)}/versions/${version}`,
+					opts,
+				),
+			create: (id: string, bundle: SkillBundle, opts?: RequestOptions) =>
+				this.json<z.infer<typeof SkillVersion>>(
+					"POST",
+					`/skills/${enc(id)}/versions`,
+					{ ...opts, rawBody: bundleForm(bundle) },
+				),
+			delete: (id: string, version: number, opts?: RequestOptions) =>
+				this.request(
+					"DELETE",
+					`/skills/${enc(id)}/versions/${version}`,
+					opts,
+				).then(() => undefined),
+			/** One file's bytes, or — with no `path` — the whole version as a zip.
+			 *  The raw `Response` (matching `files.content`), so a caller streams it
+			 *  through rather than buffering the whole zip into memory. */
+			content: (
+				id: string,
+				version: number,
+				path?: string,
+				opts?: RequestOptions,
+			) =>
+				this.request(
+					"GET",
+					`/skills/${enc(id)}/versions/${version}/content${
+						path ? `?path=${encodeURIComponent(path)}` : ""
+					}`,
+					opts,
+				),
+		},
+	};
+
 	// ── Tenant config ───────────────────────────────────────────────────────
 
 	readonly tenant = {
@@ -1034,6 +1315,18 @@ export class IngramCloud {
 				}),
 			delete: (wid: string, opts?: RequestOptions) =>
 				this.empty("DELETE", `/tenant/webhooks/${enc(wid)}`, opts),
+			/** Rotate the signing secret, returning the new one exactly once. Pass
+			 *  `grace_seconds` to keep the old secret accepted during an overlap window. */
+			rotateSecret: (
+				wid: string,
+				body?: z.input<typeof WebhookRotateIn>,
+				opts?: RequestOptions,
+			) =>
+				this.json<z.infer<typeof WebhookRotateOut>>(
+					"POST",
+					`/tenant/webhooks/${enc(wid)}/rotate_secret`,
+					{ ...opts, body: body ?? {} },
+				),
 			test: (wid: string, opts?: RequestOptions) =>
 				this.json<{ delivered: boolean }>(
 					"POST",
@@ -1104,8 +1397,8 @@ export class IngramCloud {
 		},
 
 		mcp: {
-			list: (opts?: RequestOptions) =>
-				this.data<ICMcpServer>("GET", "/tenant/mcp", opts),
+			list: (query?: PageOpts, opts?: RequestOptions) =>
+				this.page<ICMcpServer>("/tenant/mcp", query, opts),
 			get: (name: string, opts?: RequestOptions) =>
 				this.json<ICMcpServer>("GET", `/tenant/mcp/${enc(name)}`, opts),
 			/** Register or replace a server (full replace; probes `tools/list`). */
@@ -1114,13 +1407,12 @@ export class IngramCloud {
 				body: z.input<typeof McpServerIn>,
 				opts?: RequestOptions,
 			) =>
-				this.json<z.infer<typeof McpServerWriteOut>>(
-					"PUT",
-					`/tenant/mcp/${enc(name)}`,
-					{ ...opts, body },
-				),
+				this.json<ICMcpServer>("PUT", `/tenant/mcp/${enc(name)}`, {
+					...opts,
+					body,
+				}),
 			refresh: (name: string, opts?: RequestOptions) =>
-				this.json<z.infer<typeof McpServerWriteOut>>(
+				this.json<ICMcpServer>(
 					"POST",
 					`/tenant/mcp/${enc(name)}/refresh`,
 					opts,
@@ -1210,12 +1502,101 @@ export class IngramCloud {
 		},
 	};
 
-	// ── Organization (org token: projects + billing) ────────────────────────
+	// ── Organization (org token: projects, tokens, billing) ─────────────────
 
 	readonly organization = {
+		/** Platform credits — the org wallet that funds every project's runs.
+		 *  Amounts are integer minor units of the wallet's `currency`. */
+		billing: {
+			balance: (opts?: RequestOptions) =>
+				this.json<ICBalance>("GET", "/organization/billing/balance", opts),
+			/** Money in (top-ups, grants, codes) and out (usage debits), newest first. */
+			ledger: (
+				query?: PageOpts & { direction?: "credit" | "debit" },
+				opts?: RequestOptions,
+			) => this.page<ICLedgerEntry>("/organization/billing/ledger", query, opts),
+			/** Per-project draw for a calendar month (`period`, `YYYY-MM`). */
+			usage: (query?: { period?: string }, opts?: RequestOptions) =>
+				this.json<ICOrgUsage>("GET", "/organization/billing/usage", {
+					...opts,
+					query,
+				}),
+			/** Daily per-project draw over a rolling window of `days`. */
+			usageSeries: (query?: { days?: number }, opts?: RequestOptions) =>
+				this.json<ICOrgUsageSeries>(
+					"GET",
+					"/organization/billing/usage/series",
+					{
+						...opts,
+						query,
+					},
+				),
+			/** Open a Stripe Checkout Session to top up; send the user to its `url`. */
+			checkout: (body: z.input<typeof CheckoutIn>, opts?: RequestOptions) =>
+				this.json<z.infer<typeof CheckoutOut>>(
+					"POST",
+					"/organization/billing/checkout",
+					{ ...opts, body },
+				),
+			/** Add a card with no charge, unlocking the one-time welcome credit. */
+			setup: (body: z.input<typeof SetupIn>, opts?: RequestOptions) =>
+				this.json<z.infer<typeof SetupOut>>(
+					"POST",
+					"/organization/billing/setup",
+					{
+						...opts,
+						body,
+					},
+				),
+			redeem: (body: z.input<typeof RedeemIn>, opts?: RequestOptions) =>
+				this.json<z.infer<typeof RedeemOut>>(
+					"POST",
+					"/organization/billing/redeem",
+					{ ...opts, body },
+				),
+			/** Credit a returning Checkout Session. Safe to call twice — the ledger
+			 *  keys on the session id, so it can't double-credit. */
+			confirm: (body: z.input<typeof ConfirmIn>, opts?: RequestOptions) =>
+				this.json<z.infer<typeof ConfirmOut>>(
+					"POST",
+					"/organization/billing/confirm",
+					{ ...opts, body },
+				),
+			autoreload: {
+				get: (opts?: RequestOptions) =>
+					this.json<ICAutoreload>(
+						"GET",
+						"/organization/billing/autoreload",
+						opts,
+					),
+				put: (body: z.input<typeof AutoreloadIn>, opts?: RequestOptions) =>
+					this.json<ICAutoreload>("PUT", "/organization/billing/autoreload", {
+						...opts,
+						body,
+					}),
+			},
+			/** Charge the saved card now. `amount_cents` defaults to the auto-reload amount. */
+			reload: (body?: z.input<typeof ReloadIn>, opts?: RequestOptions) =>
+				this.json<z.infer<typeof ReloadOut>>(
+					"POST",
+					"/organization/billing/reload",
+					{ ...opts, body: body ?? {} },
+				),
+			/** A Stripe billing-portal URL for managing cards and invoices. */
+			portal: (query: { return_url: string }, opts?: RequestOptions) =>
+				this.json<z.infer<typeof PortalOut>>(
+					"GET",
+					"/organization/billing/portal",
+					{
+						...opts,
+						query,
+					},
+				),
+		},
+
 		projects: {
-			list: (opts?: RequestOptions) =>
-				this.data<ICProject>("GET", "/organization/projects", opts),
+			list: (query?: PageOpts & { name?: string }, opts?: RequestOptions) =>
+				this.page<ICProject>("/organization/projects", query, opts),
 			create: (body: z.input<typeof ProjectIn>, opts?: RequestOptions) =>
 				this.json<ICProject>("POST", "/organization/projects", {
 					...opts,