@ingram-cloud/sdk 1.4.0 → 1.6.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,
@@ -143,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. */
@@ -205,6 +238,61 @@ export interface PageOpts {
 
 const enc = encodeURIComponent;
 
+/** Attempts per request, including the first. Small on purpose: the server
+ *  tells us when to come back, so this is a bound on pathological cases, not
+ *  a backoff strategy. */
+const MAX_ATTEMPTS = 4;
+
+/** Longest we will sit out one `Retry-After`. A server (or an intermediary that
+ *  never heard of this API) can name an hour; a client library must not silently
+ *  block a caller for one. Past this we stop retrying and surface the refusal, so
+ *  the caller decides. */
+const MAX_WAIT_MS = 60_000;
+
+/**
+ * How long this response says to wait, or null if it does not say — which is
+ * itself the answer: a 402 carries no `Retry-After` because the wallet will not
+ * refill because we asked twice.
+ *
+ * RFC 9110 allows both forms, and intermediaries do send the date one, so parse
+ * both. Anything unparseable is "no usable instruction", never a zero-delay
+ * hammer at an upstream that is already struggling.
+ */
+function retryAfterMs(res: Response, now: number): number | null {
+	const raw = res.headers.get("retry-after")?.trim();
+	if (!raw) return null;
+	const seconds = Number(raw);
+	const ms = Number.isFinite(seconds) ? seconds * 1000 : Date.parse(raw) - now;
+	if (!Number.isFinite(ms)) return null;
+	return Math.max(0, ms);
+}
+
+/** Retry only what retrying can fix, and only when told how long to wait. */
+function retryDelay(res: Response, now: number): number | null {
+	if (res.status !== 429 && res.status !== 503) return null;
+	const ms = retryAfterMs(res, now);
+	return ms === null || ms > MAX_WAIT_MS ? null : ms;
+}
+
+/** The `Retry-After` wait, abortable: a caller cancelling mid-wait should not
+ *  sit out the rest of a Retry-After that can be tens of seconds — reject as
+ *  soon as `signal` fires, the same way an aborted `transport()` call would. */
+function sleep(ms: number, signal: AbortSignal | undefined): Promise<void> {
+	if (!signal) return new Promise((resolve) => setTimeout(resolve, ms));
+	if (signal.aborted) return Promise.reject(signal.reason ?? new Error("aborted"));
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => {
+			signal.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(signal.reason ?? new Error("aborted"));
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+	});
+}
+
 function qs(query: Query | undefined): string {
 	if (!query) return "";
 	const p = new URLSearchParams();
@@ -216,6 +304,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;
@@ -254,15 +402,22 @@ export class IngramCloud {
 			...(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,
-		});
+		let res!: Response;
+		for (let attempt = 1; ; attempt++) {
+			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 || attempt >= MAX_ATTEMPTS) break;
+			const wait = retryDelay(res, Date.now());
+			if (wait === null) break;
+			await sleep(wait, opts.signal);
+		}
 		if (!res.ok) {
 			const body = await res.text().catch(() => "");
 			let code = `http_${res.status}`;
@@ -374,10 +529,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: (
@@ -397,8 +552,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",
@@ -478,8 +637,8 @@ export class IngramCloud {
 		},
 
 		schedules: {
-			list: (pid: string, opts?: RequestOptions) =>
-				this.data<ICSchedule>("GET", `/smiths/${enc(pid)}/schedules`, opts),
+			list: (pid: string, query?: PageOpts, opts?: RequestOptions) =>
+				this.page<ICSchedule>(`/smiths/${enc(pid)}/schedules`, query, opts),
 			create: (
 				pid: string,
 				body: z.input<typeof ScheduleIn>,
@@ -605,6 +764,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 ──────────────────────────────────────────────────────────────
@@ -625,8 +786,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,
@@ -664,7 +825,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: (
@@ -676,7 +841,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));
@@ -694,19 +861,22 @@ export class IngramCloud {
 					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,
@@ -753,6 +923,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 = {
@@ -773,7 +955,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) =>
@@ -822,6 +1005,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 = {
@@ -836,6 +1031,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 = {
@@ -885,7 +1089,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) =>
@@ -894,7 +1103,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) ─────────────────────────
@@ -903,14 +1116,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`). */
@@ -918,7 +1135,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",
@@ -930,10 +1151,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: (
@@ -941,10 +1166,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?: {
@@ -956,7 +1185,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 },
@@ -1012,7 +1241,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 }>(
@@ -1023,6 +1257,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 = {
@@ -1150,8 +1459,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`). */
@@ -1160,13 +1469,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,
@@ -1256,13 +1564,101 @@ export class IngramCloud {
 		},
 	};
 
-	// ── Organization (org token: projects + tokens) ─────────────────────────
-	// Note: the `/v1/organization/billing/*` surface is not yet wrapped here.
+	// ── 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,