@ingram-tech/ingram-cloud-sdk 0.1.0

package/package.json

@@ -0,0 +1,35 @@
+{
+	"name": "@ingram-tech/ingram-cloud-sdk",
+	"version": "0.1.0",
+	"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.",
+	"license": "MIT",
+	"type": "module",
+	"homepage": "https://cloud.ingram.tech",
+	"keywords": ["ingram-cloud", "ingram", "sdk", "api", "wire", "zod", "openapi"],
+	"files": ["ts", "openapi.json"],
+	"publishConfig": {
+		"access": "public"
+	},
+	"exports": {
+		".": "./ts/index.ts",
+		"./schemas": "./ts/schemas.ts",
+		"./responses": "./ts/responses.ts",
+		"./openapi.json": "./openapi.json"
+	},
+	"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"
+	},
+	"dependencies": {
+		"zod": "^4.4.3"
+	}
+}

package/ts/events.ts

@@ -0,0 +1,114 @@
+/**
+ * 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") ────────
+export const EVENT_TYPES = [
+	"run.started",
+	"run.paused",
+	"run.completed",
+	"run.failed",
+	"run.cancelled",
+	"tool_call.requested",
+	"tool_call.completed",
+	"approval.required",
+	"approval.resolved",
+	"connection.required",
+	"unbound_message",
+	"message.completed",
+	"memory.consolidated",
+	"budget.threshold",
+	"usage.summary",
+	"channel.bound",
+	"channel.inbound",
+	"slack.app_provisioned",
+	"slack.install",
+	"slack.uninstalled",
+	"email.send_failed",
+	"webhook.test",
+] as const;
+
+export const eventType = z.enum(EVENT_TYPES);
+export type EventType = z.infer<typeof eventType>;
+
+/**
+ * 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();
+export type WebhookEvent = z.infer<typeof webhookEvent>;
+
+// ─── 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` are live-only (no feed
+// mirror) — the one thing no standard expresses yet (see CLAUDE.md).
+export const STREAM_EVENTS = [
+	"run.started",
+	"message.delta",
+	"tool.executing",
+	"tool.completed",
+	"run.paused",
+	"approval.required",
+	"tool_call.requested",
+	"run.completed",
+	"run.failed",
+	"run.cancelled",
+	"run.duplicate",
+	"message.completed",
+] as const;
+
+export const streamEventName = z.enum(STREAM_EVENTS);
+export type StreamEventName = z.infer<typeof streamEventName>;
+
+export const streamFrame = z
+	.object({
+		event: z.string(),
+		v: z.number().optional(),
+		run_id: z.string().optional(),
+	})
+	.passthrough();
+export type StreamFrame = z.infer<typeof streamFrame>;
+
+// ─── 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/ts/index.ts

@@ -0,0 +1,21 @@
+/**
+ * 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:
+ *
+ *     bun run generate                # regenerate schemas.ts from openapi.json
+ *
+ * `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.
+ *
+ * See `../README.md`.
+ */
+export { schemas } from "./schemas";
+export * from "./events";
+export type * from "./responses";

package/ts/responses.ts

@@ -0,0 +1,434 @@
+/**
+ * Hand-authored TypeScript types for the `/v1` JSON response bodies.
+ *
+ * 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.
+ */
+
+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;
+	source: string | null;
+	created_at: string | null;
+	updated_at: string | null;
+}
+export interface ICToolCall {
+	tool_call_id: string;
+	tool: string;
+	args: Record<string, unknown>;
+	execution: string;
+}
+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: Record<string, number> | 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;
+	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;
+}