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

package/ts/zod/mcp.ts

@@ -0,0 +1,123 @@
+/**
+ * Hand-authored Zod schemas for the `mcp` resource — the tenant config plane for
+ * registering third-party MCP tool servers (`/v1/tenant/mcp/...`).
+ *
+ * One source, three outputs: the API imports these into its `createRoute`
+ * definitions (validation + emitted OpenAPI), and the consumer-facing `IC*`
+ * types are `z.infer`red from them here and re-exported by `../responses`. No
+ * Zod is pulled into a type-only consumer — `responses.ts` re-exports these as
+ * `export type`.
+ *
+ * `.meta({ id })` names the component so the emitted OpenAPI references it as
+ * `#/components/schemas/<id>` rather than inlining it. `ApprovalRule` and
+ * `McpTool` are standalone named schemas referenced by `McpServerOut`, so they
+ * emit as `$ref` components rather than inlined objects.
+ */
+import { z } from "zod";
+
+/** One approval-policy rule: a name glob that gates matching tools behind a
+ *  human approval. `require` is always `"approval"` today (the only supported
+ *  value); arg-conditional (`when`) gating is rejected, not stored. */
+export const ApprovalRule = z
+	.object({
+		match: z.string(),
+		require: z.string().optional(),
+	})
+	.meta({ id: "ApprovalRule" });
+
+/** The rule shape on *input* (`McpServerIn.approval_policy`). Loose, so unknown
+ *  clauses (e.g. an arg-conditional `when`) reach the handler, which rejects them
+ *  with its own `unsupported_policy_rule` (422) rather than being silently
+ *  stripped by a strict object. */
+export const ApprovalRuleIn = z.looseObject({
+	match: z.string(),
+	require: z.string().optional(),
+});
+
+/** A discovered MCP tool, with its *effective* gating folded in by the
+ *  serializer: `enabled` reflects the default-deny `tool_allowlist`,
+ *  `requires_approval` folds the server's destructive hint with the approval
+ *  policy. */
+export const McpTool = z
+	.object({
+		name: z.string(),
+		description: z.string().nullable(),
+		/** Effective gate: server destructiveHint OR an approval_policy match. */
+		requires_approval: z.boolean(),
+		/** Passes the default-deny tool_allowlist (always true when no allow-list). */
+		enabled: z.boolean(),
+	})
+	.meta({ id: "McpTool" });
+
+/** Secret-free auth descriptor returned for a registered server. */
+export const McpAuth = z
+	.object({
+		kind: z.string(),
+		provider: z.string().nullable(),
+		client_mode: z.string().optional(),
+	})
+	.meta({ id: "McpAuth" });
+
+export const McpServerOut = z
+	.object({
+		id: z.string(),
+		name: z.string(),
+		url: z.string(),
+		auth: McpAuth,
+		/** tenant_owned | tenant_registered | catalog. */
+		origin: z.string().optional(),
+		catalog_slug: z.string().nullish(),
+		/** null = expose all discovered tools; otherwise the default-deny set. */
+		tool_allowlist: z.array(z.string()).nullish(),
+		approval_policy: z.array(ApprovalRule).optional(),
+		tools: z.array(McpTool),
+		tools_refreshed_at: z.string().nullable(),
+		/** `degraded` when the edge failed discovery or its secret can't be decoded
+		 *  at run time; otherwise the stored lifecycle status. */
+		status: z.string(),
+		/** Last discovery/runtime-load failure, or null when the edge is healthy. */
+		discovery_error: z.string().nullable(),
+		created_at: z.string().nullable(),
+	})
+	.meta({ id: "McpServerOut" });
+
+export const McpServerListOut = z
+	.object({ data: z.array(McpServerOut) })
+	.meta({ id: "McpServerListOut" });
+
+/** Register/replace and refresh echo the server back plus the count of tools
+ *  discovered in the just-run `tools/list`. */
+export const McpServerWriteOut = McpServerOut.extend({
+	tools_discovered: z.number().int(),
+}).meta({ id: "McpServerWriteOut" });
+
+// ── Request bodies ──────────────────────────────────────────────────────────
+
+/** Auth block on a register/replace body. `secret` is write-only (a static
+ *  bearer) — never echoed back. */
+export const McpAuthIn = z
+	.object({
+		kind: z.string().nullish(),
+		provider: z.string().nullish(),
+		secret: z.string().nullish(),
+		client_mode: z.string().nullish(),
+	})
+	.meta({ id: "McpAuthIn" });
+
+/** Register or replace a server: supply a raw `url` + `auth`, or a `catalog`
+ *  slug (catalog defaults are stamped down, body fields override). */
+export const McpServerIn = z
+	.object({
+		url: z.string().nullish(),
+		catalog: z.string().nullish(),
+		auth: McpAuthIn.nullish(),
+		tool_allowlist: z.array(z.string()).nullish(),
+		approval_policy: z.array(ApprovalRuleIn).nullish(),
+	})
+	.meta({ id: "McpServerIn" });
+
+// ── Inferred consumer-facing types (re-exported by ../responses) ─────────────
+
+export type ICMcpTool = z.infer<typeof McpTool>;
+export type ICApprovalRule = z.infer<typeof ApprovalRule>;
+export type ICMcpServer = z.infer<typeof McpServerOut>;

package/ts/zod/memories.ts

@@ -0,0 +1,98 @@
+/**
+ * Hand-authored Zod schemas for the `memories` resource — the wire's source of
+ * truth, replacing the loose generated `schemas.ts` shapes for this resource.
+ *
+ * One source, three outputs: the API imports these into its `createRoute`
+ * definitions (validation + emitted OpenAPI), and the consumer-facing `IC*`
+ * types are `z.infer`red from them here and re-exported by `../responses`. No
+ * Zod is pulled into a type-only consumer — `responses.ts` re-exports these as
+ * `export type`.
+ *
+ * `.meta({ id })` names the component so the emitted OpenAPI references it as
+ * `#/components/schemas/<id>` rather than inlining it.
+ *
+ * Two derived response views share one stored shape: `score` is present ONLY on
+ * search hits, so it's `.optional()` on `MemoryOut`. The list envelope is
+ * paginated (`{ data, has_more }`); search returns just `{ data }`.
+ */
+import { z } from "zod";
+
+/** A durable, typed fact about a smith. `score` rides only on search hits. */
+export const MemoryOut = z
+	.object({
+		id: z.string(),
+		category: z.string().nullable(),
+		subject: z.string().nullable(),
+		content: z.string(),
+		source: z.string().nullable(),
+		/** Extraction confidence (0–1); null when not scored. */
+		confidence: z.number().nullish(),
+		/** Relevance score — only present on `/memories/search` hits. */
+		score: z.number().nullish(),
+		metadata: z.record(z.string(), z.unknown()).nullish(),
+		created_at: z.string().nullable(),
+		updated_at: z.string().nullable(),
+	})
+	.meta({ id: "MemoryOut" });
+
+/** Paginated list envelope. */
+export const MemoryListOut = z
+	.object({
+		data: z.array(MemoryOut),
+		has_more: z.boolean(),
+	})
+	.meta({ id: "MemoryListOut" });
+
+/** Search envelope — ranked hits, each carrying a `score`. */
+export const MemorySearchOut = z
+	.object({ data: z.array(MemoryOut) })
+	.meta({ id: "MemorySearchOut" });
+
+/** Result of a batch create. */
+export const MemoryBatchOut = z
+	.object({ memories: z.array(MemoryOut) })
+	.meta({ id: "MemoryBatchOut" });
+
+// ── Request bodies ──────────────────────────────────────────────────────────
+
+/** One memory to create. `content` is the only required field. */
+export const MemoryIn = z
+	.object({
+		category: z.string().nullish(),
+		subject: z.string().nullish(),
+		content: z.string(),
+		source: z.string().nullish(),
+		confidence: z.number().nullish(),
+		metadata: z.record(z.string(), z.unknown()).optional(),
+	})
+	.meta({ id: "MemoryIn" });
+
+/** Batch create body. */
+export const MemoryBatch = z
+	.object({ memories: z.array(MemoryIn) })
+	.meta({ id: "MemoryBatch" });
+
+/** Partial update — every field optional; nulls clear where the column allows. */
+export const MemoryPatch = z
+	.object({
+		category: z.string().nullish(),
+		subject: z.string().nullish(),
+		content: z.string().nullish(),
+		source: z.string().nullish(),
+		confidence: z.number().nullish(),
+		metadata: z.record(z.string(), z.unknown()).nullish(),
+	})
+	.meta({ id: "MemoryPatch" });
+
+/** Semantic/keyword search body. */
+export const SearchBody = z
+	.object({
+		query: z.string(),
+		categories: z.array(z.string()).nullish(),
+		limit: z.number().int().default(10),
+	})
+	.meta({ id: "SearchBody" });
+
+// ── Inferred consumer-facing type (re-exported by ../responses) ──────────────
+
+export type ICMemory = z.infer<typeof MemoryOut>;

package/ts/zod/observability.ts

@@ -0,0 +1,156 @@
+/**
+ * Hand-authored Zod schemas for the `observability` resource — traces, spans,
+ * and the usage breakdown. The wire's source of truth, replacing the loose
+ * generated shapes for this resource.
+ *
+ * One source, three outputs: the API imports these into its `createRoute`
+ * definitions (validation + emitted OpenAPI), and the consumer-facing `IC*`
+ * types are `z.infer`red from them here and re-exported by `../responses`. No
+ * Zod is pulled into a type-only consumer — `responses.ts` re-exports these as
+ * `export type`.
+ *
+ * `.meta({ id })` names the component so the emitted OpenAPI references it as
+ * `#/components/schemas/<id>` rather than inlining it.
+ *
+ * Shapes follow the `responses.ts` interfaces (the source of truth), not the
+ * relic's looser `SpanOut`/`TraceOut`: the relic flattened `children`, `spans`,
+ * and `span_tree` onto every span/trace and made `kind`/timestamps nullable. We
+ * split them — `SpanOut` has no `children`, the recursive `SpanNodeOut` adds
+ * it; `TraceOut` carries no `spans`/`span_tree`, `TraceDetailOut` adds them.
+ */
+import { z } from "zod";
+
+/** Span kinds emitted by the observability backend. */
+export const ICSpanKindEnum = z
+	.enum([
+		"run",
+		"model_call",
+		"tool_call",
+		"memory_op",
+		"retrieval",
+		"sub_agent",
+		"runtime_event",
+	])
+	.meta({ id: "SpanKind" });
+
+/** A single timed unit of work inside a trace. */
+export const SpanOut = z
+	.object({
+		id: z.string(),
+		trace_id: z.string(),
+		parent_span_id: z.string().nullable(),
+		kind: ICSpanKindEnum,
+		name: z.string(),
+		status: z.string(),
+		started_at: z.string(),
+		ended_at: z.string().nullable(),
+		duration_ms: z.number().int().nullable(),
+		model: z.string().nullable(),
+		input_tokens: z.number().int().nullable(),
+		output_tokens: z.number().int().nullable(),
+		cost: z.number().nullable(),
+		attributes: z.record(z.string(), z.unknown()),
+	})
+	.meta({ id: "SpanOut" });
+
+/** A span node in the nested `span_tree` (same shape + recursive children). */
+export const SpanNodeOut = SpanOut.extend({
+	get children() {
+		return z.array(SpanNodeOut);
+	},
+}).meta({ id: "SpanNodeOut" });
+
+/** Top-level trace — one end-to-end agent operation. */
+export const TraceOut = z
+	.object({
+		id: z.string(),
+		smith_id: z.string(),
+		app_id: z.string().nullable(),
+		root_kind: ICSpanKindEnum,
+		name: z.string(),
+		status: z.string(),
+		started_at: z.string(),
+		ended_at: z.string().nullable(),
+		duration_ms: z.number().int().nullable(),
+		total_tokens: z.number().int().nullable(),
+		total_cost: z.number().nullable(),
+		attributes: z.record(z.string(), z.unknown()),
+	})
+	.meta({ id: "TraceOut" });
+
+/** A trace plus its flat spans and nested tree. */
+export const TraceDetailOut = TraceOut.extend({
+	spans: z.array(SpanOut),
+	span_tree: z.array(SpanNodeOut),
+}).meta({ id: "TraceDetailOut" });
+
+export const TraceListOut = z
+	.object({ data: z.array(TraceOut) })
+	.meta({ id: "TraceListOut" });
+
+/** Aggregated usage grouped by app, smith, model, or customer. */
+export const UsageBreakdownOut = z
+	.object({
+		group_by: z.enum(["app", "smith", "model", "customer"]),
+		totals: z.object({
+			tokens: z.number(),
+			cost: z.number(),
+			run_count: z.number(),
+		}),
+		groups: z.array(
+			z.object({
+				app: z.string().nullable().optional(),
+				smith: z.string().nullable().optional(),
+				model: z.string().nullable().optional(),
+				// Customer-grouped views label unassigned usage `principal:<smith id>`.
+				customer: z.string().nullable().optional(),
+				tokens: z.number(),
+				cost: z.number(),
+				run_count: z.number(),
+			}),
+		),
+		/** Custom billable events aggregated per meter over the same filters. */
+		meters: z
+			.array(
+				z.object({
+					meter: z.string(),
+					customer: z.string().nullable().optional(),
+					quantity: z.number(),
+					events: z.number(),
+				}),
+			)
+			.optional(),
+	})
+	.meta({ id: "UsageBreakdownOut" });
+
+/** One recorded billable usage event. */
+export const UsageEventOut = z
+	.object({
+		id: z.string(),
+		smith_id: z.string(),
+		customer_id: z.string().nullable(),
+		meter: z.string(),
+		quantity: z.number(),
+		day: z.string(),
+		metadata: z.record(z.string(), z.unknown()),
+		created_at: z.string().nullable(),
+	})
+	.meta({ id: "UsageEventOut" });
+
+/** A page of usage events (keyset pagination). */
+export const UsageEventListOut = z
+	.object({
+		data: z.array(UsageEventOut),
+		next_cursor: z.string().nullable(),
+		has_more: z.boolean(),
+	})
+	.meta({ id: "UsageEventListOut" });
+
+// ── Inferred consumer-facing types (re-exported by ../responses) ─────────────
+
+export type ICSpanKind = z.infer<typeof ICSpanKindEnum>;
+export type ICSpan = z.infer<typeof SpanOut>;
+export type ICSpanNode = z.infer<typeof SpanNodeOut>;
+export type ICTrace = z.infer<typeof TraceOut>;
+export type ICTraceDetail = z.infer<typeof TraceDetailOut>;
+export type ICUsageBreakdown = z.infer<typeof UsageBreakdownOut>;

package/ts/zod/projects.ts

@@ -0,0 +1,68 @@
+/**
+ * Hand-authored Zod schemas for the `projects` resource — the org control-plane
+ * surface (`/v1/organization/projects`). A project's `id` is the `tenant` that
+ * scopes all of its runtime data.
+ *
+ * Source of truth is the handler (`api/src/routes/projects.ts`): `serialize`
+ * emits the project shape, and minting (`api/src/tokens.ts::mintToken`) returns
+ * the token shape. The relic `sdk/openapi.json` supplied field/required hints
+ * only.
+ *
+ * `.meta({ id })` names the component so the emitted OpenAPI references it as
+ * `#/components/schemas/<id>` rather than inlining it.
+ */
+import { z } from "zod";
+
+export const ProjectOut = z
+	.object({
+		id: z.string(),
+		organization: z.string(),
+		name: z.string(),
+		metadata: z.record(z.string(), z.unknown()),
+		/** ISO timestamp; null only if the row predates the column being set. */
+		created_at: z.string().nullable(),
+		/** Set when the project is archived (soft-deleted); null while live. */
+		archived_at: z.string().nullable(),
+	})
+	.meta({ id: "ProjectOut" });
+
+export const ProjectListOut = z
+	.object({ data: z.array(ProjectOut) })
+	.meta({ id: "ProjectListOut" });
+
+/**
+ * The secret minted when an org mints a project (tenant-admin) token. Shape
+ * matches `mintToken`'s return; the `tenant` module owns the canonical
+ * `ICMintedToken` re-export, so this stays project-named and project-scoped.
+ */
+export const ProjectTokenOut = z
+	.object({
+		id: z.string(),
+		/** The branded secret handle (`tha_live_…`). Shown once. */
+		token: z.string(),
+		scope: z.string(),
+		sub: z.string(),
+		scopes: z.array(z.string()),
+		expires_at: z.string().nullable(),
+	})
+	.meta({ id: "ProjectTokenOut" });
+
+// ── Request bodies ──────────────────────────────────────────────────────────
+
+export const ProjectIn = z
+	.object({
+		name: z.string(),
+		metadata: z.record(z.string(), z.unknown()).nullish(),
+	})
+	.meta({ id: "ProjectIn" });
+
+export const ProjectTokenIn = z
+	.object({
+		ttl_seconds: z.number().int().nullish(),
+		name: z.string().nullish(),
+	})
+	.meta({ id: "ProjectTokenIn" });
+
+// ── Inferred consumer-facing type ────────────────────────────────────────────
+
+export type ICProject = z.infer<typeof ProjectOut>;

package/ts/zod/runs.ts

@@ -0,0 +1,115 @@
+/**
+ * Hand-authored Zod schemas for the `runs` resource — the wire's source of
+ * truth, replacing the inline `IC*` run shapes previously declared in
+ * `../responses`.
+ *
+ * One source, three outputs: the API imports these into its `createRoute`
+ * definitions (validation + emitted OpenAPI), and the consumer-facing `IC*`
+ * types are `z.infer`red from them here and re-exported by `../responses`. No
+ * Zod is pulled into a type-only consumer — `responses.ts` re-exports these as
+ * `export type`.
+ *
+ * `.meta({ id })` names the component so the emitted OpenAPI references it as
+ * `#/components/schemas/<id>` rather than inlining it. `ToolCall` and
+ * `RunUsage` are standalone (`$ref`'d) so the inferred `ICToolCall`/`ICRunUsage`
+ * come out identical to their hand-written interface ancestors.
+ *
+ * Only the JSON shapes are modelled here: the run object, the run list, run
+ * events + their list, and the create/submit request bodies. The streaming
+ * surfaces emit the native `{v:1}` SSE envelope (not a single JSON schema) and
+ * are deliberately not modelled.
+ */
+import { z } from "zod";
+
+/** A tool call attached to a run's output. */
+export const ToolCall = z
+	.object({
+		tool_call_id: z.string(),
+		tool: z.string(),
+		args: z.record(z.string(), z.unknown()),
+		execution: z.string(),
+	})
+	.meta({ id: "ToolCall" });
+
+/** One run's own token usage (the `usage` map on a run). Distinct from the
+ *  tenant's aggregated billing summary. */
+export const RunUsage = z
+	.object({
+		input_tokens: z.number().int(),
+		output_tokens: z.number().int(),
+		total_tokens: z.number().int(),
+	})
+	.meta({ id: "RunUsage" });
+
+export const RunOut = z
+	.object({
+		id: z.string(),
+		smith_id: z.string(),
+		thread_id: z.string(),
+		status: z.string(),
+		channel: z.string(),
+		input: z.array(z.object({ role: z.string(), content: z.string() })),
+		output: z
+			.object({
+				content: z.string().optional(),
+				tool_calls: z.array(ToolCall).optional(),
+			})
+			.nullable(),
+		stop_reason: z.string().nullable(),
+		usage: RunUsage.nullable(),
+		metadata: z.record(z.string(), z.unknown()).optional(),
+		created_at: z.string().nullable(),
+		updated_at: z.string().nullable(),
+	})
+	.meta({ id: "RunOut" });
+
+export const RunListOut = z
+	.object({ data: z.array(RunOut) })
+	.meta({ id: "RunListOut" });
+
+/** One recorded run event, as replayed from the event log. */
+export const RunEventOut = z
+	.object({
+		seq: z.number().int(),
+		type: z.string(),
+		data: z.record(z.string(), z.unknown()),
+		created_at: z.string().nullable(),
+	})
+	.meta({ id: "RunEventOut" });
+
+export const RunEventListOut = z
+	.object({ data: z.array(RunEventOut) })
+	.meta({ id: "RunEventListOut" });
+
+// ── Request bodies ──────────────────────────────────────────────────────────
+
+export const RunIn = z
+	.object({
+		input: z.array(z.object({ role: z.string(), content: z.string() })).optional(),
+		thread_id: z.string().nullish(),
+		stream: z.boolean().optional(),
+		channel: z.string().optional(),
+		metadata: z.record(z.string(), z.unknown()).optional(),
+		response_format: z.record(z.string(), z.unknown()).nullish(),
+	})
+	.meta({ id: "RunIn" });
+
+export const Submit = z
+	.object({
+		kind: z.string(),
+		tool_call_id: z.string().nullish(),
+		result: z.record(z.string(), z.unknown()).nullish(),
+		approval_id: z.string().nullish(),
+		decision: z.string().nullish(),
+		actor: z.string().nullish(),
+		reason: z.string().nullish(),
+		stream: z.boolean().optional(),
+	})
+	.meta({ id: "Submit" });
+
+// ── Inferred consumer-facing types (re-exported by ../responses) ─────────────
+
+export type ICToolCall = z.infer<typeof ToolCall>;
+export type ICRunUsage = z.infer<typeof RunUsage>;
+export type ICRun = z.infer<typeof RunOut>;
+export type ICRunEvent = z.infer<typeof RunEventOut>;

package/ts/zod/schedules.ts

@@ -0,0 +1,83 @@
+/**
+ * Hand-authored Zod schemas for the `schedules` resource — cron-triggered runs
+ * on a smith's agent — the wire's source of truth, replacing the loose
+ * generated `schemas.ts` shapes for this resource.
+ *
+ * One source, three outputs: the API imports these into its `createRoute`
+ * definitions (validation + emitted OpenAPI), and the consumer-facing `IC*`
+ * types are `z.infer`red from them here and re-exported by `../responses`. No
+ * Zod is pulled into a type-only consumer — `responses.ts` re-exports these as
+ * `export type`.
+ *
+ * `.meta({ id })` names the component so the emitted OpenAPI references it as
+ * `#/components/schemas/<id>` rather than inlining it.
+ */
+import { z } from "zod";
+
+/** A schedule's stored input: messages replayed as the run input on each fire. */
+const ScheduleInput = z.array(z.record(z.string(), z.unknown()));
+
+export const ScheduleOut = z
+	.object({
+		id: z.string(),
+		name: z.string().nullable(),
+		cron: z.string(),
+		timezone: z.string(),
+		/** Messages replayed as the run input on each fire. */
+		input: ScheduleInput,
+		/** Thread the fired runs append to; null mints a fresh thread per fire. */
+		thread_id: z.string().nullable(),
+		/** Max overlapping fired runs before new fires are skipped. */
+		max_concurrent: z.number().int(),
+		/** What a failed fire does next (e.g. `continue`, `pause`). */
+		on_failure: z.string(),
+		enabled: z.boolean(),
+		next_fire_at: z.string().nullable(),
+		last_fire_at: z.string().nullable(),
+		created_at: z.string().nullable(),
+	})
+	.meta({ id: "ScheduleOut" });
+
+export const ScheduleListOut = z
+	.object({ data: z.array(ScheduleOut) })
+	.meta({ id: "ScheduleListOut" });
+
+/** `POST .../:sid/run_now` — the schedule's id plus the run it just fired. */
+export const ScheduleRunNowOut = z
+	.object({
+		schedule_id: z.string(),
+		run: z.record(z.string(), z.unknown()),
+	})
+	.meta({ id: "ScheduleRunNowOut" });
+
+// ── Request bodies ──────────────────────────────────────────────────────────
+
+export const ScheduleIn = z
+	.object({
+		cron: z.string(),
+		name: z.string().nullish(),
+		timezone: z.string().default("UTC"),
+		input: ScheduleInput.default([]),
+		thread_id: z.string().nullish(),
+		max_concurrent: z.number().int().default(1),
+		on_failure: z.string().default("webhook"),
+		enabled: z.boolean().default(true),
+	})
+	.meta({ id: "ScheduleIn" });
+
+export const SchedulePatch = z
+	.object({
+		name: z.string().nullish(),
+		cron: z.string().nullish(),
+		timezone: z.string().nullish(),
+		input: ScheduleInput.nullish(),
+		thread_id: z.string().nullish(),
+		max_concurrent: z.number().int().nullish(),
+		on_failure: z.string().nullish(),
+		enabled: z.boolean().nullish(),
+	})
+	.meta({ id: "SchedulePatch" });
+
+// ── Inferred consumer-facing types (re-exported by ../responses) ─────────────
+
+export type ICSchedule = z.infer<typeof ScheduleOut>;