@ingram-cloud/sdk 1.5.0 → 1.6.0

package/README.md

@@ -1,11 +1,10 @@
 # `@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.
+The Ingram Cloud `/v1` API contract in TypeScript: Zod request/response
+schemas, SSE/webhook event types, JSON response types, and a typed
+management-plane client built on them. The schemas are hand-authored; the API
+imports them 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";
@@ -33,42 +32,42 @@ const smith = await ic.smiths.create({ external_id: "user-42" });
 
 ## Exports
 
-- `.` — the `schemas` Zod map plus the SSE/webhook event types (`EVENT_TYPES`,
+- `.`: 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 }`.
+- `./schemas`: the Zod `schemas` map only.
+- `./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.
+- `./client`: `IngramCloud`, the typed management-plane REST client. Method
+  inputs are `z.input`-inferred from the schemas the API validates with. Zod-free
+  at runtime (type-only imports; transport is the global `fetch`). Auth is a
+  static bearer or a per-request minting function. Smith-scoped calls made with
+  a tenant token pass `{ smith }`, sent as the `IC-Smith-Id` header. Non-2xx
+  throws `ICError { status, code, requestId }`. A 429 or 503 that names a
+  `Retry-After` is retried, up to four attempts and a minute's wait; a 402 is
+  never retried.
 
-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 OpenAPI document is served by the API at `/openapi.json`, emitted from these
+schemas.
 
-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).
+The client covers the management plane only. Chat goes through the
+OpenAI-compatible surface: use `@ingram-cloud/ai-sdk` and the standard
+`@ai-sdk/*` types. 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.
+> and bundlers load `dist/`. Types resolve 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.
+Zod (one module per resource under `./zod`), with the `IC*` types inferred from
+them. Not in the typed surface, because no single response schema expresses
+them: the streaming/union endpoints (`/runs` stream, `/chat/completions`,
+`/responses`, each a stream or JSON from one handler), deployment webhook acks,
+and the OAuth redirect. 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.
+The OpenAI-compatible stream chunks are standard; use the `@ai-sdk/*` types for
+them.

package/dist/client.js

@@ -19,6 +19,61 @@ export class ICError extends Error {
     }
 }
 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, now) {
+    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, now) {
+    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, signal) {
+    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) {
     if (!query)
         return "";
@@ -105,14 +160,23 @@ 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;
+        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}`;

package/dist/zod/approvals.js

@@ -27,6 +27,15 @@ export const ApprovalOut = z
     tool: z.string().nullable(),
     /** The tool-call arguments awaiting a decision; `{}` when none. */
     args: z.record(z.string(), z.unknown()),
+    /** Set when the pause is a remote MCP tool asking the end-user for input
+     *  (not a gate before a tool runs): the prompt and the JSON Schema the
+     *  answer must match. Approve with `content` to answer it. */
+    elicitation: z
+        .object({
+        message: z.string(),
+        requested_schema: z.record(z.string(), z.unknown()),
+    })
+        .nullable(),
     /** pending | approved | rejected. */
     status: z.string(),
     actor: z.string().nullable(),

package/dist/zod/runs.js

@@ -124,6 +124,9 @@ export const Submit = z
     result: z.record(z.string(), z.unknown()).nullish(),
     approval_id: z.string().nullish(),
     decision: z.string().nullish(),
+    /** The answer to an approval's `elicitation`, matching its
+     *  `requested_schema`; with `decision: "approve"`. */
+    content: z.record(z.string(), z.unknown()).nullish(),
     actor: z.string().nullish(),
     reason: z.string().nullish(),
     stream: z.boolean().optional(),

package/package.json

@@ -1,26 +1,29 @@
 {
 	"name": "@ingram-cloud/sdk",
-	"version": "1.5.0",
+	"version": "1.6.0",
 	"description": "Typed wire contract + management-plane client for the Ingram Cloud API: Zod schemas to validate request/response bodies, TypeScript types for the JSON you read back, SSE/webhook event types, and a typed REST client.",
-	"license": "MIT",
-	"type": "module",
-	"homepage": "https://cloud.ingram.tech",
 	"keywords": [
-		"ingram-cloud",
+		"api",
 		"ingram",
+		"ingram-cloud",
+		"openapi",
 		"sdk",
-		"api",
 		"wire",
-		"zod",
-		"openapi"
+		"zod"
 	],
+	"homepage": "https://github.com/ingram-technologies/ingram-cloud-sdks/tree/main/packages/sdk#readme",
+	"bugs": "https://github.com/ingram-technologies/ingram-cloud-sdks/issues",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/ingram-technologies/ingram-cloud-sdks.git",
+		"directory": "packages/sdk"
+	},
 	"files": [
 		"ts",
 		"dist"
 	],
-	"publishConfig": {
-		"access": "public"
-	},
+	"type": "module",
 	"exports": {
 		".": {
 			"types": "./ts/index.ts",
@@ -48,18 +51,24 @@
 			"default": "./dist/client.js"
 		}
 	},
+	"publishConfig": {
+		"access": "public"
+	},
 	"scripts": {
 		"build": "tsc -p tsconfig.build.json",
 		"typecheck": "tsc --noEmit",
-		"lint": "nk lint",
-		"format": "nk format",
-		"prepublishOnly": "bun run build",
-		"check": "nk check"
-	},
-	"devDependencies": {
-		"@ingram-tech/nk-dev": "^0.10.0"
+		"lint": "oxlint",
+		"format": "oxfmt --write .",
+		"test": "vitest run",
+		"prepack": "bun run build"
 	},
 	"dependencies": {
 		"zod": "^4.4.3"
+	},
+	"devDependencies": {
+		"vitest": "^4.1.10"
+	},
+	"engines": {
+		"node": ">=20"
 	}
 }

package/ts/client.ts

@@ -238,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();
@@ -347,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}`;

package/ts/zod/approvals.ts

@@ -28,6 +28,15 @@ export const ApprovalOut = z
 		tool: z.string().nullable(),
 		/** The tool-call arguments awaiting a decision; `{}` when none. */
 		args: z.record(z.string(), z.unknown()),
+		/** Set when the pause is a remote MCP tool asking the end-user for input
+		 *  (not a gate before a tool runs): the prompt and the JSON Schema the
+		 *  answer must match. Approve with `content` to answer it. */
+		elicitation: z
+			.object({
+				message: z.string(),
+				requested_schema: z.record(z.string(), z.unknown()),
+			})
+			.nullable(),
 		/** pending | approved | rejected. */
 		status: z.string(),
 		actor: z.string().nullable(),

package/ts/zod/runs.ts

@@ -134,6 +134,9 @@ export const Submit = z
 		result: z.record(z.string(), z.unknown()).nullish(),
 		approval_id: z.string().nullish(),
 		decision: z.string().nullish(),
+		/** The answer to an approval's `elicitation`, matching its
+		 *  `requested_schema`; with `decision: "approve"`. */
+		content: z.record(z.string(), z.unknown()).nullish(),
 		actor: z.string().nullish(),
 		reason: z.string().nullish(),
 		stream: z.boolean().optional(),

package/ts/zod/.impeccable/hook.cache.json

@@ -1 +0,0 @@
-{"version":1,"sessions":{"409c438b-72a6-412d-9a44-013a81c0f846":{"updatedAt":1784658629665,"files":{"/home/adys/src/cloud.ingram.tech/sdk/ts/client.ts":{"editCount":2,"findings":[]}}}}}