@ingram-tech/ingram-cloud-sdk 0.1.2 → 0.2.0

package/README.md

@@ -1,10 +1,10 @@
 # `@ingram-tech/ingram-cloud-sdk`
 
 The Ingram Cloud `/v1` API wire contract in TypeScript: **Zod request/response
-schemas + SSE/webhook event types + JSON response types**. The `schemas` map is
-generated from the OpenAPI document — the source of truth for the wire — and the
-event/response types are hand-authored. This package is the **source of truth for
-the wire shapes**, not an HTTP client.
+schemas + SSE/webhook event types + JSON response types**. 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. This package is not an HTTP client.
 
 ```ts
 import { schemas } from "@ingram-tech/ingram-cloud-sdk";
@@ -26,10 +26,13 @@ function render(smith: ICSmith) {
 
 - `.` — the `schemas` Zod map plus the SSE/webhook event types (`EVENT_TYPES`,
   `webhookEvent`, `streamFrame`, …).
-- `./schemas` — just the generated Zod `schemas` map.
+- `./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.
-- `./openapi.json` — the raw OpenAPI document.
+
+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.
 
 This is **not** an HTTP client — there is no `createApiClient` and no
 `@ai-sdk/*`-style provider here. Application code talks to the API over the
@@ -43,16 +46,13 @@ OpenAI-compatible surface; use `@ingram-tech/ai-sdk-adapter` and the standard
 
 ## Coverage
 
-The contract is in two halves — generated + hand-authored:
-
-- **Generated, from the OpenAPI document:** every path, method, param, **request
-  body**, and **non-streaming JSON response** is typed. ~28 of 124 operations
-  stay `unknown` by design — the **streaming/union** endpoints (`/runs`,
-  `/chat/completions`, `/responses` — a stream *or* JSON from one handler),
-  channel **webhook acks**, and the OAuth **redirect**. None are expressible as a
-  single response schema.
-- **Hand-authored:** the `{v:1}` webhook/feed envelope and the SSE run-stream
-  frames, which OpenAPI can't describe, plus the `IC*` response types.
+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), channel
+**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/package.json

@@ -1,30 +1,28 @@
 {
 	"name": "@ingram-tech/ingram-cloud-sdk",
-	"version": "0.1.2",
-	"description": "The Ingram Cloud /v1 API wire contract in TypeScript: Zod request/response schemas (generated from the OpenAPI spec), hand-authored SSE/webhook event types, and the JSON response types. The source of truth for the wire shapes.",
+	"version": "0.2.0",
+	"description": "Typed wire contract for the Ingram Cloud API: Zod schemas to validate request/response bodies, TypeScript types for the JSON you read back, and SSE/webhook event types.",
 	"license": "MIT",
 	"type": "module",
 	"homepage": "https://cloud.ingram.tech",
 	"keywords": ["ingram-cloud", "ingram", "sdk", "api", "wire", "zod", "openapi"],
-	"files": ["ts", "openapi.json"],
+	"files": ["ts"],
 	"publishConfig": {
 		"access": "public"
 	},
 	"exports": {
 		".": "./ts/index.ts",
 		"./schemas": "./ts/schemas.ts",
-		"./responses": "./ts/responses.ts",
-		"./openapi.json": "./openapi.json"
+		"./zod": "./ts/zod/index.ts",
+		"./responses": "./ts/responses.ts"
 	},
 	"scripts": {
-		"generate": "mkdir -p ts && openapi-zod-client openapi.json -o ts/schemas.ts --export-schemas && bun scripts/strip-client.ts",
 		"typecheck": "tsc --noEmit",
 		"lint": "oxlint",
 		"format": "oxfmt --write ."
 	},
 	"devDependencies": {
 		"@ingram-tech/oxlint-config": "^0.2.1",
-		"openapi-zod-client": "^1.18.3",
 		"oxfmt": "^0.54.0",
 		"oxlint": "^1.70.0",
 		"typescript": "^6.0.0"

package/ts/index.ts

@@ -1,18 +1,17 @@
 /**
  * The Ingram Cloud API wire contract, in TypeScript.
  *
- * GENERATED — do not edit `schemas.ts` by hand. It is produced from
- * `../openapi.json`, the hand-maintained source of truth for the wire:
+ * `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.
  *
- *     bun run generate                # regenerate schemas.ts from openapi.json
+ * `./responses` is the matching `IC*` TypeScript types (inferred from the same
+ * schemas), for typing the JSON you read back without pulling in Zod.
  *
- * `schemas` is the named map of Zod schemas for the request/response bodies.
- * It's used to validate the API's wire shapes in the `api/` test suite; this
- * package is the source of truth for those shapes, not an HTTP client.
- *
- * `./events` is the hand-authored half: the `{v:1}` webhook/feed envelope and the
- * SSE run-stream frames, which OpenAPI can't express. Together they make the
- * contract complete — generated request/response bodies + hand-authored streams.
+ * `./events` is the hand-authored `{v:1}` webhook/feed envelope and the SSE
+ * run-stream frames, which OpenAPI can't express.
  *
  * See `../README.md`.
  */

package/ts/responses.ts

@@ -1,454 +1,66 @@
 /**
- * Hand-authored TypeScript types for the `/v1` JSON response bodies.
+ * TypeScript types for the `/v1` JSON response bodies — the consumer-facing
+ * companion to the wire schemas, imported by API consumers (e.g. the console) to
+ * type the JSON they read back.
  *
- * The consumer-facing companion to the generated `schemas.ts` Zod schemas: these
- * are lightweight, ergonomic mirrors of the wire response shapes, meant to be
- * imported by API consumers (e.g. the console) to type the JSON they read back.
- * `schemas.ts` validates wire shapes in the api/ test suite; these describe the
- * same bodies as plain TS interfaces with no runtime/Zod dependency.
+ * The `IC*` types are `z.infer`red from the hand-authored Zod in
+ * `./zod/<resource>` (the wire's source of truth) and re-exported here as
+ * **types** — so this module stays Zod-free for `import type` consumers. Only the
+ * list-envelope generics ({@link ICList}/{@link ICPaginatedResponse}) are
+ * declared inline, since they're generic over any resource.
  */
 
-export interface ICSmith {
-	id: string;
-	external_id: string | null;
-	display_name: string | null;
-	locale: string | null;
-	timezone: string | null;
-	/** The customer (billable party) this smith's usage rolls up to. */
-	customer_id?: string | null;
-	metadata?: Record<string, unknown>;
-	// The *effective* agent config (agent-resolved when attached).
-	model: string;
-	/** The raw instructions template (may contain {{ variables }}). */
-	instructions: string;
-	/** What this smith actually runs with — {{ variables }} bound per-smith. */
-	rendered_instructions?: string | null;
-	enabled_hosted_tools?: string[];
-	auto_memory?: boolean;
-	/** How the config resolved: by reference, with overrides, or embedded. */
-	config_source?: "agent" | "override" | "custom";
-	agent_id?: string | null;
-	agent_version?: number | null;
-	pin?: number | null;
-	created_at: string;
-}
-export interface ICBlock {
-	id: string;
-	label: string;
-	description: string;
-	value: string;
-	char_limit: number;
-	updated_at: string | null;
-}
-export interface ICMemory {
-	id: string;
-	category: string | null;
-	subject: string | null;
-	content: string;
-	/** Extraction confidence (0–1); null when not scored. */
-	confidence?: number | null;
-	source: string | null;
-	/** Relevance score — only present on `/memories/search` hits. */
-	score?: number | null;
-	metadata?: Record<string, unknown> | null;
-	created_at: string | null;
-	updated_at: string | null;
-}
-export interface ICToolCall {
-	tool_call_id: string;
-	tool: string;
-	args: Record<string, unknown>;
-	execution: string;
-}
-/** One run's own token usage (the `usage` map on a run). Distinct from
- *  {@link ICUsage}, which is the tenant's aggregated *billing* summary. */
-export interface ICRunUsage {
-	input_tokens: number;
-	output_tokens: number;
-	total_tokens: number;
-}
-export interface ICRun {
-	id: string;
-	smith_id: string;
-	thread_id: string;
-	status: string;
-	channel: string;
-	input: Array<{ role: string; content: string }>;
-	output: { content?: string; tool_calls?: ICToolCall[] } | null;
-	stop_reason: string | null;
-	usage: ICRunUsage | null;
-	metadata?: Record<string, unknown>;
-	created_at: string | null;
-	updated_at: string | null;
-}
-export interface ICRunEvent {
-	seq: number;
-	type: string;
-	data: Record<string, unknown>;
-	created_at: string | null;
-}
-export interface ICConnection {
-	id: string;
-	provider: string;
-	scopes: string[];
-	status: string;
-	expires_at: string | null;
-	metadata?: Record<string, unknown>;
-	created_at: string | null;
-}
-export interface ICChannel {
-	id: string;
-	kind: string;
-	address: string;
-	provider: string | null;
-	provider_metadata?: Record<string, unknown>;
-	/** Names of the encrypted secret fields that are set (values never returned). */
-	secret_keys?: string[];
-	status: string;
-	created_at: string | null;
-}
-export interface ICSchedule {
-	id: string;
-	name: string | null;
-	cron: string;
-	timezone: string;
-	/** Messages replayed as the run input on each fire. */
-	input: Array<Record<string, unknown>>;
-	/** Thread the fired runs append to; null mints a fresh thread per fire. */
-	thread_id: string | null;
-	/** Max overlapping fired runs before new fires are skipped. */
-	max_concurrent: number;
-	/** What a failed fire does next (e.g. `continue`, `pause`). */
-	on_failure: string;
-	enabled: boolean;
-	next_fire_at: string | null;
-	last_fire_at: string | null;
-	created_at: string | null;
-}
-export interface ICApproval {
-	id: string;
-	run_id: string | null;
-	smith_id: string | null;
-	tool_call_id: string | null;
-	tool: string | null;
-	args: Record<string, unknown>;
-	status: string;
-	actor: string | null;
-	reason: string | null;
-	created_at: string | null;
-	resolved_at: string | null;
-}
-export interface ICEvent {
-	id: string;
-	type: string;
-	smith_id: string | null;
-	data: Record<string, unknown>;
-	created_at: string | null;
-}
-export interface ICMcpTool {
-	name: string;
-	description: string | null;
-	/** Effective gate: server destructiveHint OR an approval_policy match. */
-	requires_approval: boolean;
-	/** Passes the default-deny tool_allowlist (always true when no allow-list). */
-	enabled: boolean;
-}
-export interface ICApprovalRule {
-	match: string;
-	require?: string;
-}
-export interface ICMcpServer {
-	id: string;
-	name: string;
-	url: string;
-	auth: { kind: string; provider: string | null; client_mode?: string };
-	/** tenant_owned | tenant_registered | catalog. */
-	origin?: string;
-	catalog_slug?: string | null;
-	/** null = expose all discovered tools; otherwise the default-deny set. */
-	tool_allowlist?: string[] | null;
-	approval_policy?: ICApprovalRule[];
-	tools: ICMcpTool[];
-	tools_refreshed_at: string | null;
-	/** `degraded` when the edge failed discovery or its secret can't be decoded at
-	 *  run time; otherwise the stored lifecycle status. */
-	status: string;
-	/** Last discovery/runtime-load failure, or null when the edge is healthy. */
-	discovery_error: string | null;
-	created_at: string | null;
-}
-export interface ICCatalogEntry {
-	slug: string;
-	display_name: string;
-	description: string;
-	mcp_url: string;
-	auth: { kind: string; provider: string | null; client_mode: string };
-	scopes: string[];
-	default_allowlist: string[] | null;
-	default_approval_policy: ICApprovalRule[];
-	logo_url: string | null;
-	docs_url: string | null;
-}
-export interface ICWebhook {
-	id: string;
-	url: string;
-	events: string[];
-	active: boolean;
-	created_at: string | null;
-}
-export interface ICToken {
-	id: string;
-	name: string | null;
-	sub: string;
-	scopes: string[];
-	prefix: string | null;
-	created_at: string | null;
-	expires_at: string | null;
-	revoked_at: string | null;
-}
-export interface ICUsage {
-	totals: {
-		runs: number;
-		input_tokens: number;
-		output_tokens: number;
-		total_tokens: number;
-	};
-	series: Array<{ date: string; runs: number; total_tokens: number }>;
-}
-export interface ICProvider {
-	provider: string;
-	client_id: string | null;
-	has_client_secret: boolean;
-	token_uri: string | null;
-	scopes_allowed: string[];
-	refresh_webhook: string | null;
-}
-export interface ICModel {
-	id: string;
-	provider: string;
-	label: string;
-	available: boolean;
-	/** Whose key a run would use: the tenant's ("byok") or IC's ("platform"). */
-	source?: "byok" | "platform" | null;
-}
-export interface ICModelProvider {
-	id: string;
-	label: string;
-	base_url: boolean;
-	/** True when the platform fallback covers this provider (no tenant key). */
-	platform_key?: boolean;
-}
-export interface ICModelCatalog {
-	data: ICModel[];
-	providers: ICModelProvider[];
-}
-export interface ICModelKey {
-	provider: string;
-	base_url: string | null;
-	has_key: boolean;
-	updated_at: string | null;
-}
-
-/** Span kinds emitted by the observability backend. */
-export type ICSpanKind =
-	| "run"
-	| "model_call"
-	| "tool_call"
-	| "memory_op"
-	| "retrieval"
-	| "sub_agent"
-	| "runtime_event";
-
-/** A single timed unit of work inside a trace. */
-export interface ICSpan {
-	id: string;
-	trace_id: string;
-	parent_span_id: string | null;
-	kind: ICSpanKind;
-	name: string;
-	status: string;
-	started_at: string;
-	ended_at: string | null;
-	duration_ms: number | null;
-	model: string | null;
-	input_tokens: number | null;
-	output_tokens: number | null;
-	cost: number | null;
-	attributes: Record<string, unknown>;
-}
-
-/** A span node in the nested `span_tree` (same shape + children). */
-export interface ICSpanNode extends ICSpan {
-	children: ICSpanNode[];
-}
-
-/** Top-level trace — one end-to-end agent operation. */
-export interface ICTrace {
-	id: string;
-	smith_id: string;
-	app_id: string | null;
-	root_kind: ICSpanKind;
-	name: string;
-	status: string;
-	started_at: string;
-	ended_at: string | null;
-	duration_ms: number | null;
-	total_tokens: number | null;
-	total_cost: number | null;
-	attributes: Record<string, unknown>;
-}
-
-/** A trace plus its flat spans and nested tree. */
-export interface ICTraceDetail extends ICTrace {
-	spans: ICSpan[];
-	span_tree: ICSpanNode[];
-}
-
-/** Aggregated usage grouped by app, smith, model, or customer. */
-export interface ICUsageBreakdown {
-	group_by: "app" | "smith" | "model" | "customer";
-	totals: { tokens: number; cost: number; run_count: number };
-	groups: Array<{
-		app?: string | null;
-		smith?: string | null;
-		model?: string | null;
-		// Customer-grouped views label unassigned usage `principal:<smith id>`.
-		customer?: string | null;
-		tokens: number;
-		cost: number;
-		run_count: number;
-	}>;
-	/** Custom billable events aggregated per meter over the same filters. */
-	meters?: Array<{
-		meter: string;
-		customer?: string | null;
-		quantity: number;
-		events: number;
-	}>;
-}
-
-export interface ICMintedToken {
-	id: string;
-	token: string;
-	scope: string;
-	sub: string;
-	scopes: string[];
-	expires_at: string | null;
-}
-
-export interface ICTelegramBot {
-	configured: boolean;
-	bot_username?: string;
-	bot_id?: number;
-	has_token?: boolean;
-	webhook_url?: string;
-}
-
-export interface ICSlackApp {
-	configured: boolean;
-	bot_user_id?: string;
-	team_id?: string;
-	events_url?: string;
-	/** Shared app's OAuth client is set — "Add to Slack" installs work. */
-	oauth_ready?: boolean;
-	oauth_redirect_url?: string;
-	/** Where the OAuth redirect sends installers back (?slack=… appended). */
-	return_url?: string;
-	/** App factory: mints per-smith Slack apps from the manifest template. */
-	factory?: { configured: boolean };
-}
-
-export interface ICEmailConfig {
-	configured: boolean;
-	from_domain?: string;
-	display_name?: string | null;
-	has_token?: boolean;
-	inbound_url?: string;
-	/** Only present on PUT (shown once) — wire it into the inbound worker. */
-	inbound_secret?: string;
-}
-
-export interface ICCustomer {
-	id: string;
-	name: string;
-	external_ids: Record<string, string>;
-	metadata: Record<string, unknown>;
-	smith_count?: number;
-	created_at: string | null;
-}
-
-export interface ICBudget {
-	id: string;
-	scope: "tenant" | "smith" | "customer";
-	scope_id?: string | null;
-	period: string;
-	limit_usd: number;
-	action: "warn" | "block";
-	created_at?: string | null;
-}
-export interface ICBudgetStatus extends ICBudget {
-	period_start: string;
-	period_key: string;
-	spent: number;
-	pct: number;
-	over: boolean;
-}
-
-export interface ICSmithRevision {
-	version: number;
-	snapshot: {
-		instructions?: string | null;
-		model?: string | null;
-		enabled_hosted_tools?: string[];
-		auto_memory?: boolean;
-	};
-	created_by?: string | null;
-	note?: string | null;
-	created_at?: string | null;
-}
-
-/** A per-smith variable an agent declares; bound at run time. */
-export interface ICAgentVariable {
-	name: string;
-	default?: string | null;
-	description?: string | null;
-	required?: boolean;
-}
-
-export interface ICAgent {
-	id: string;
-	/** Immutable, project-unique IaC reconcile key. Null for the default agent. */
-	slug: string | null;
-	/** Free, mutable display label (not unique). */
-	name: string;
-	/** True for the lazily-created default agent (can't be deleted). */
-	is_default: boolean;
-	/** The mutable draft head — what the next publish snapshots. */
-	draft: {
-		instructions: string | null;
-		model: string | null;
-		enabled_hosted_tools: string[];
-		auto_memory: boolean | null;
-		variables: ICAgentVariable[];
-	};
-	active_version: number | null;
-	rollout_version: number | null;
-	rollout_percent: number;
-	smith_count?: number;
-	created_at: string | null;
-	updated_at: string | null;
-}
-
-export interface ICAgentVersion {
-	version: number;
-	snapshot: {
-		instructions?: string | null;
-		model?: string | null;
-		enabled_hosted_tools?: string[];
-		auto_memory?: boolean | null;
-		variables?: ICAgentVariable[];
-	};
-	created_by?: string | null;
-	note?: string | null;
-	created_at?: string | null;
-}
+/** The standard list envelope — a `data` array and nothing else. Most list
+ *  endpoints return this. */
+export interface ICList<T> {
+	data: T[];
+}
+
+/** A cursor-paginated list. The endpoints that page (smiths, memories,
+ *  customers) add `has_more`, and some a `next_cursor`; the rest return the
+ *  plain {@link ICList}. */
+export interface ICPaginatedResponse<T> {
+	data: T[];
+	has_more: boolean;
+	next_cursor?: string | null;
+}
+
+// ── Re-exported from the hand-authored Zod source of truth (./zod/*) ──────────
+export type { ICAgent, ICAgentVariable, ICAgentVersion } from "./zod/agents";
+export type { ICApproval } from "./zod/approvals";
+export type { ICBudget, ICBudgetStatus } from "./zod/budgets";
+export type { ICCatalogEntry } from "./zod/catalog";
+export type { ICChannel, ICChannelCreated } from "./zod/channels";
+export type { ICConnection } from "./zod/connections";
+export type { ICCustomer } from "./zod/customers";
+export type { ICEmailConfig } from "./zod/email";
+export type { ICMcpServer, ICMcpTool, ICApprovalRule } from "./zod/mcp";
+export type { ICMemory } from "./zod/memories";
+export type {
+	ICSpanKind,
+	ICSpan,
+	ICSpanNode,
+	ICTrace,
+	ICTraceDetail,
+	ICUsageBreakdown,
+} from "./zod/observability";
+export type { ICProject } from "./zod/projects";
+export type { ICRun, ICRunUsage, ICToolCall, ICRunEvent } from "./zod/runs";
+export type { ICSchedule } from "./zod/schedules";
+export type { ICSlackApp } from "./zod/slack";
+export type { ICSmith, ICBlock } from "./zod/smiths";
+export type { ICSmithRevision } from "./zod/smith-revisions";
+export type { ICTelegramBot } from "./zod/telegram";
+export type {
+	ICEvent,
+	ICWebhook,
+	ICToken,
+	ICMintedToken,
+	ICUsage,
+	ICModel,
+	ICModelProvider,
+	ICModelCatalog,
+	ICModelKey,
+	ICProvider,
+} from "./zod/tenant";
+export type { ICWhatsAppConfig } from "./zod/whatsapp";