@ingram-cloud/sdk 1.0.0

package/ts/events.ts

@@ -0,0 +1,119 @@
+/**
+ * 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") ────────
+// Only these reach the `/v1/events` feed and signed webhooks. Pure run-stream frames
+// — `run.started`, `message.delta`, `message.completed`, `run.cancelled` — ride the
+// live SSE stream and the per-run timeline only; they are NOT feed events (see
+// {@link STREAM_EVENTS}). `tool.executing` / `tool.completed` are both: a live frame
+// AND a feed event.
+export const EVENT_TYPES = [
+	"run.paused",
+	"run.completed",
+	"run.failed",
+	"tool.executing",
+	"tool.completed",
+	"approval.required",
+	"approval.resolved",
+	"connection.required",
+	"unbound_message",
+	"budget.threshold",
+	"credit.exhausted",
+	"deployment.bound",
+	"deployment.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` ride the live stream as they
+// happen AND are mirrored to the run timeline + feed (see EVENT_TYPES) so a run's
+// tool activity is auditable after the fact. The standard surface expresses the same
+// live status on the OpenAI Responses API (`/v1/responses`) as `mcp_call` items
+// (`response.mcp_call.in_progress` / `.completed`); those are standard OpenAI shapes,
+// so we don't re-type them here — consume them with the OpenAI/AI SDK. These native
+// frames are the place to retire as that lands everywhere (see CLAUDE.md).
+export const STREAM_EVENTS = [
+	"run.started",
+	"message.delta",
+	"tool.executing",
+	"tool.completed",
+	"run.paused",
+	"approval.required",
+	"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,20 @@
+/**
+ * The Ingram Cloud API wire contract, in TypeScript.
+ *
+ * `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.
+ *
+ * `./responses` is the matching `IC*` TypeScript types (inferred from the same
+ * schemas), for typing the JSON you read back without pulling in Zod.
+ *
+ * `./events` is the hand-authored `{v:1}` webhook/feed envelope and the SSE
+ * run-stream frames, which OpenAPI can't express.
+ *
+ * See `../README.md`.
+ */
+export { schemas } from "./schemas.js";
+export * from "./events.js";
+export type * from "./responses.js";

package/ts/responses.ts

@@ -0,0 +1,83 @@
+/**
+ * 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 `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.
+ */
+
+/** 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,
+	ICUiResource,
+	ICUiResourceTool,
+} from "./zod/agents.js";
+export type { ICApproval } from "./zod/approvals.js";
+export type { ICBudget, ICBudgetStatus } from "./zod/budgets.js";
+export type { ICCatalogEntry } from "./zod/catalog.js";
+export type { ICConnection } from "./zod/connections.js";
+export type { ICConversation, ICConversationItem } from "./zod/conversations.js";
+export type { ICCustomer } from "./zod/customers.js";
+export type { ICDeployment, ICDeploymentCreated } from "./zod/deployments.js";
+export type { ICDiscordApp } from "./zod/discord.js";
+export type { ICEmailConfig } from "./zod/email.js";
+export type { ICFile, ICFileList } from "./zod/files.js";
+export type { ICMcpServer, ICMcpTool, ICApprovalRule } from "./zod/mcp.js";
+export type { ICWorkingMemory, ICRecallHit } from "./zod/memories.js";
+export type {
+	ICSpanKind,
+	ICSpan,
+	ICSpanNode,
+	ICTrace,
+	ICTraceDetail,
+	ICUsageBreakdown,
+} from "./zod/observability.js";
+export type { ICProject } from "./zod/projects.js";
+export type { ICRun, ICRunUsage, ICInputMessage, ICRunEvent } from "./zod/runs.js";
+export type { ICSchedule } from "./zod/schedules.js";
+export type { ICSlackApp } from "./zod/slack.js";
+export type { ICSmith } from "./zod/smiths.js";
+export type { ICSmithRevision } from "./zod/smith-revisions.js";
+export type { ICTelegramBot } from "./zod/telegram.js";
+export type {
+	ICEvent,
+	ICWebhook,
+	ICToken,
+	ICMintedToken,
+	ICUsage,
+	ICModel,
+	ICModelProvider,
+	ICModelCatalog,
+	ICModelKey,
+	ICProvider,
+} from "./zod/tenant.js";
+export type { ICWhatsAppConfig } from "./zod/whatsapp.js";
+export type {
+	ICVectorStore,
+	ICVectorStoreFile,
+	ICVectorStoreFileBatch,
+	ICVectorStoreSearchPage,
+	ICVectorStoreAttributes,
+	ICVectorStoreFilter,
+} from "./zod/vector-stores.js";

package/ts/schemas.ts

@@ -0,0 +1,4 @@
+/** The wire's Zod schema map — the hand-authored schemas in ./zod, keyed by
+ *  export name. Source of truth; consumed by the api test suite to validate
+ *  wire shapes. (Replaces the former openapi-zod-client-generated file.) */
+export * as schemas from "./zod/index.js";

package/ts/zod/_page.ts

@@ -0,0 +1,18 @@
+/**
+ * The shared cursor-paginated list envelope. One definition so every paginated
+ * `/v1` list reads back the same shape: `data` + the opaque `next_cursor` (null
+ * on the last page) + `has_more`. The cursor is an opaque, short-lived token —
+ * pass it straight back as `?cursor=`, never parse it.
+ */
+import { z } from "zod";
+
+/** Wrap an item schema as a cursor-paginated list out, named `id` in the spec. */
+export function pageOut<T extends z.ZodTypeAny>(item: T, id: string) {
+	return z
+		.object({
+			data: z.array(item),
+			next_cursor: z.string().nullish(),
+			has_more: z.boolean(),
+		})
+		.meta({ id });
+}

package/ts/zod/agents.ts

@@ -0,0 +1,202 @@
+/**
+ * Hand-authored Zod schemas for the `agents` 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.
+ */
+import { z } from "zod";
+import { pageOut } from "./_page.js";
+
+/** A per-smith variable an agent declares; bound at run time. */
+export const AgentVariable = z
+	.object({
+		name: z.string(),
+		default: z.string().nullish(),
+		description: z.string().nullish(),
+		required: z.boolean().optional(),
+	})
+	.meta({ id: "AgentVariable" });
+
+/** A predeclared UI-backed capability (Rung 2) bound to a UI template — the MCP
+ *  host's model calls it as a typed tool and the template renders the result. */
+export const UiResourceTool = z
+	.object({
+		description: z.string(),
+		/** JSON Schema for the tool's arguments (host-supplied). */
+		input_schema: z.record(z.string(), z.unknown()).optional(),
+		/** Scoped instruction the smith runs with when this tool is called. */
+		instruction: z.string().nullish(),
+		/** Writes gate through approval; reads flow freely (OpenUI Query/Mutation). */
+		mutating: z.boolean().optional(),
+	})
+	.meta({ id: "UiResourceTool" });
+
+/** CSP domain allowlists for the sandboxed iframe — the MCP Apps `_meta.ui.csp`
+ *  shape (each key a list of allowed origins), passed through to the host verbatim. */
+export const UiCsp = z
+	.object({
+		connectDomains: z.array(z.string()).optional(),
+		resourceDomains: z.array(z.string()).optional(),
+		frameDomains: z.array(z.string()).optional(),
+		baseUriDomains: z.array(z.string()).optional(),
+	})
+	.meta({ id: "UiCsp" });
+
+/** A tenant-authored interactive UI template (MCP Apps, SEP-1865) attached to an
+ *  agent. The HTML bundle lives in blob storage; this is its wire metadata (the
+ *  internal blob ref is never exposed). `csp`/`permissions` mirror the standard
+ *  `_meta.ui` shape and are echoed to the host on `resources/read`. */
+export const UiResource = z
+	.object({
+		name: z.string(),
+		content_hash: z.string(),
+		csp: UiCsp.optional(),
+		/** Host permissions the template requests, a Permissions-Policy-style map
+		 *  (e.g. `{ "camera": {}, "microphone": {} }`). */
+		permissions: z.record(z.string(), z.unknown()).optional(),
+		tool: UiResourceTool.nullish(),
+	})
+	.meta({ id: "UiResource" });
+
+/** The mutable draft head — what the next publish snapshots. */
+export const AgentDraft = z
+	.object({
+		instructions: z.string().nullable(),
+		model: z.string().nullable(),
+		enabled_hosted_tools: z.array(z.string()),
+		vector_store_ids: z.array(z.string()),
+		auto_memory: z.boolean().nullable(),
+		memory_consolidation: z.boolean().nullable(),
+		variables: z.array(AgentVariable),
+		ui_resources: z.array(UiResource),
+	})
+	.meta({ id: "AgentDraft" });
+
+export const AgentOut = z
+	.object({
+		id: z.string(),
+		/** Immutable, project-unique IaC reconcile key. Null for the default agent. */
+		slug: z.string().nullable(),
+		/** Free, mutable display label (not unique). */
+		name: z.string(),
+		/** True for the lazily-created default agent (can't be deleted). */
+		is_default: z.boolean(),
+		draft: AgentDraft,
+		active_version: z.number().int().nullable(),
+		rollout_version: z.number().int().nullable(),
+		rollout_percent: z.number().int(),
+		smith_count: z.number().int().optional(),
+		created_at: z.string().nullable(),
+		updated_at: z.string().nullable(),
+	})
+	.meta({ id: "AgentOut" });
+
+export const AgentListOut = pageOut(AgentOut, "AgentListOut");
+
+/** A published, immutable version snapshot of an agent. */
+export const AgentVersionOut = z
+	.object({
+		version: z.number().int(),
+		snapshot: z.object({
+			instructions: z.string().nullish(),
+			model: z.string().nullish(),
+			enabled_hosted_tools: z.array(z.string()).optional(),
+			vector_store_ids: z.array(z.string()).optional(),
+			auto_memory: z.boolean().nullish(),
+			memory_consolidation: z.boolean().nullish(),
+			variables: z.array(AgentVariable).optional(),
+			ui_resources: z.array(UiResource).optional(),
+		}),
+		created_by: z.string().nullable(),
+		note: z.string().nullable(),
+		created_at: z.string().nullable(),
+	})
+	.meta({ id: "AgentVersionOut" });
+
+export const AgentVersionListOut = z
+	.object({ data: z.array(AgentVersionOut) })
+	.meta({ id: "AgentVersionListOut" });
+
+// ── Request bodies ──────────────────────────────────────────────────────────
+
+export const AgentIn = z
+	.object({
+		name: z.string(),
+		slug: z.string().nullish(),
+		instructions: z.string().nullish(),
+		model: z.string().nullish(),
+		enabled_hosted_tools: z.array(z.string()).nullish(),
+		vector_store_ids: z.array(z.string()).nullish(),
+		auto_memory: z.boolean().nullish(),
+		memory_consolidation: z.boolean().nullish(),
+		variables: z.array(AgentVariable).nullish(),
+	})
+	.meta({ id: "AgentIn" });
+
+export const AgentPatch = z
+	.object({
+		name: z.string().nullish(),
+		instructions: z.string().nullish(),
+		model: z.string().nullish(),
+		enabled_hosted_tools: z.array(z.string()).nullish(),
+		vector_store_ids: z.array(z.string()).nullish(),
+		auto_memory: z.boolean().nullish(),
+		memory_consolidation: z.boolean().nullish(),
+		variables: z.array(AgentVariable).nullish(),
+	})
+	.meta({ id: "AgentPatch" });
+
+export const RolloutIn = z
+	.object({
+		version: z.number().int(),
+		percent: z.number().int().min(0).max(100).default(100),
+	})
+	.meta({ id: "RolloutIn" });
+
+export const PublishIn = z
+	.object({ note: z.string().nullish() })
+	.meta({ id: "PublishIn" });
+
+export const ImportIn = z
+	.object({ from_smith: z.string(), name: z.string() })
+	.meta({ id: "ImportIn" });
+
+export const AttachIn = z
+	.object({
+		all: z.boolean().default(false),
+		smith_ids: z.array(z.string()).nullish(),
+	})
+	.meta({ id: "AttachIn" });
+
+/** The JSON `metadata` part of a UI-template multipart upload (the HTML bundle
+ *  rides the `file` part). */
+export const UiResourceIn = z
+	.object({
+		name: z
+			.string()
+			.regex(/^[a-z0-9][a-z0-9_-]*$/, "lowercase letters, digits, - and _")
+			.max(63),
+		csp: UiCsp.nullish(),
+		permissions: z.record(z.string(), z.unknown()).nullish(),
+		tool: UiResourceTool.nullish(),
+	})
+	.meta({ id: "UiResourceIn" });
+
+export const UiResourceListOut = z
+	.object({ data: z.array(UiResource) })
+	.meta({ id: "UiResourceListOut" });
+
+// ── Inferred consumer-facing types (re-exported by ../responses) ─────────────
+
+export type ICAgentVariable = z.infer<typeof AgentVariable>;
+export type ICAgent = z.infer<typeof AgentOut>;
+export type ICAgentVersion = z.infer<typeof AgentVersionOut>;
+export type ICUiResource = z.infer<typeof UiResource>;
+export type ICUiResourceTool = z.infer<typeof UiResourceTool>;

package/ts/zod/approvals.ts

@@ -0,0 +1,44 @@
+/**
+ * Hand-authored Zod schemas for the `approvals` 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.
+ *
+ * The approvals route is read-only (list + get); there is no decision/submit
+ * body here — approvals are resolved on the standard tool-call channel via the
+ * run's `/submit`, not a bespoke endpoint.
+ */
+import { z } from "zod";
+import { pageOut } from "./_page.js";
+
+/** A first-class human-in-the-loop decision raised by a paused run. */
+export const ApprovalOut = z
+	.object({
+		id: z.string(),
+		run_id: z.string().nullable(),
+		smith_id: z.string().nullable(),
+		tool_call_id: z.string().nullable(),
+		tool: z.string().nullable(),
+		/** The tool-call arguments awaiting a decision; `{}` when none. */
+		args: z.record(z.string(), z.unknown()),
+		/** pending | approved | rejected. */
+		status: z.string(),
+		actor: z.string().nullable(),
+		reason: z.string().nullable(),
+		created_at: z.string().nullable(),
+		resolved_at: z.string().nullable(),
+	})
+	.meta({ id: "ApprovalOut" });
+
+export const ApprovalListOut = pageOut(ApprovalOut, "ApprovalListOut");
+
+// ── Inferred consumer-facing types (re-exported by ../responses) ─────────────
+
+export type ICApproval = z.infer<typeof ApprovalOut>;

package/ts/zod/budgets.ts

@@ -0,0 +1,75 @@
+/**
+ * Hand-authored Zod schemas for the `budgets` 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.
+ */
+import { z } from "zod";
+
+/** What a budget caps; `agent`/`smith`/`customer` budgets carry the id in
+ *  `scope_id` (an agent design, a single smith, or one of your customers). */
+export const BudgetScope = z.enum(["tenant", "agent", "smith", "customer"]);
+
+/** Whether crossing the cap warns or blocks new runs. */
+export const BudgetAction = z.enum(["warn", "block"]);
+
+/** A monthly spend cap on a scope. `limit` is in `currency` — the platform billing
+ *  currency (EUR by default), not necessarily USD; the field is currency-agnostic. */
+export const BudgetOut = z
+	.object({
+		id: z.string(),
+		scope: BudgetScope,
+		scope_id: z.string().nullish(),
+		period: z.string(),
+		limit: z.number(),
+		// ISO-4217, lower-case. The denomination of `limit` and `/status`'s `spent`.
+		currency: z.string(),
+		action: BudgetAction,
+		created_at: z.string().nullish(),
+	})
+	.meta({ id: "BudgetOut" });
+
+/** A budget plus its month-to-date spend, computed by `/status`. */
+export const BudgetStatusOut = BudgetOut.extend({
+	period_start: z.string(),
+	period_key: z.string(),
+	spent: z.number(),
+	pct: z.number(),
+	over: z.boolean(),
+}).meta({ id: "BudgetStatusOut" });
+
+export const BudgetListOut = z
+	.object({ data: z.array(BudgetOut) })
+	.meta({ id: "BudgetListOut" });
+
+// ── Request bodies ──────────────────────────────────────────────────────────
+
+export const BudgetIn = z
+	.object({
+		scope: z.string(),
+		scope_id: z.string().nullish(),
+		// The cap, in the platform billing currency (EUR by default).
+		limit: z.number(),
+		action: z.string().default("warn"),
+		period: z.string().default("monthly"),
+	})
+	.meta({ id: "BudgetIn" });
+
+export const BudgetPatch = z
+	.object({
+		limit: z.number().nullish(),
+		action: z.string().nullish(),
+	})
+	.meta({ id: "BudgetPatch" });
+
+// ── Inferred consumer-facing types (re-exported by ../responses) ─────────────
+
+export type ICBudget = z.infer<typeof BudgetOut>;
+export type ICBudgetStatus = z.infer<typeof BudgetStatusOut>;

package/ts/zod/catalog.ts

@@ -0,0 +1,57 @@
+/**
+ * Hand-authored Zod schemas for the `catalog` resource — the Ingram-curated MCP
+ * integration presets exposed at `GET /v1/catalog`.
+ *
+ * One source, three outputs: the API imports these into its `createRoute`
+ * definitions (validation + emitted OpenAPI), and the consumer-facing `IC*`
+ * type is `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";
+
+/**
+ * The approval-rule shape a catalog entry carries as its `default_approval_policy`.
+ *
+ * Defined inline (not imported from `./mcp`) to keep this module independent of
+ * the parallel mcp authoring. It mirrors the canonical mcp `ApprovalRule`:
+ * a tool-name `match` glob and an optional `require` mode.
+ */
+const ApprovalRule = z.object({
+	match: z.string(),
+	require: z.string().optional(),
+});
+
+/** How a catalog integration authenticates; surfaced flattened on the wire. */
+const CatalogAuth = z.object({
+	kind: z.string(),
+	provider: z.string().nullable(),
+	client_mode: z.string(),
+});
+
+export const CatalogEntryOut = z
+	.object({
+		slug: z.string(),
+		display_name: z.string(),
+		description: z.string(),
+		mcp_url: z.string(),
+		auth: CatalogAuth,
+		scopes: z.array(z.string()),
+		/** null = expose all discovered tools; otherwise the default-deny set. */
+		default_allowlist: z.array(z.string()).nullable(),
+		default_approval_policy: z.array(ApprovalRule),
+		logo_url: z.string().nullable(),
+		docs_url: z.string().nullable(),
+	})
+	.meta({ id: "CatalogEntryOut" });
+
+export const CatalogListOut = z
+	.object({ data: z.array(CatalogEntryOut) })
+	.meta({ id: "CatalogListOut" });
+
+// ── Inferred consumer-facing type (re-exported by ../responses) ──────────────
+
+export type ICCatalogEntry = z.infer<typeof CatalogEntryOut>;