@ingram-cloud/sdk 1.0.0

package/ts/zod/connections.ts

@@ -0,0 +1,87 @@
+/**
+ * Hand-authored Zod schemas for the `connections` resource — per-smith OAuth
+ * grants under `/v1/smiths/:pid/connections`. 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`.
+ *
+ * SECURITY INVARIANT: `ConnectionOut` NEVER carries the secret credential
+ * material — only `id`, `provider`, `scopes`, `status`, `expires_at`,
+ * `metadata`, `created_at`. The handler's `toPublic` serializer is validated
+ * against this schema.
+ *
+ * `.meta({ id })` names the component so the emitted OpenAPI references it as
+ * `#/components/schemas/<id>` rather than inlining it.
+ */
+import { z } from "zod";
+
+/** OAuth token material the tenant pushes in; IC stores it encrypted and never
+ *  echoes it back. Only `kind: "oauth_tokens"` is accepted. */
+export const Credential = z
+	.object({
+		kind: z.string().optional(),
+		access_token: z.string().nullish(),
+		refresh_token: z.string().nullish(),
+		expires_at: z.string().nullish(),
+		token_uri: z.string().nullish(),
+	})
+	.meta({ id: "Credential" });
+
+/** A connection WITHOUT the secret credential material. */
+export const ConnectionOut = z
+	.object({
+		id: z.string(),
+		provider: z.string(),
+		scopes: z.array(z.string()),
+		status: z.string(),
+		expires_at: z.string().nullable(),
+		metadata: z.record(z.string(), z.unknown()).optional(),
+		created_at: z.string().nullable(),
+	})
+	.meta({ id: "ConnectionOut" });
+
+export const ConnectionListOut = z
+	.object({ data: z.array(ConnectionOut) })
+	.meta({ id: "ConnectionListOut" });
+
+// ── Request bodies ──────────────────────────────────────────────────────────
+
+export const ConnectionIn = z
+	.object({
+		provider: z.string(),
+		scopes: z.array(z.string()).optional(),
+		credential: Credential,
+		metadata: z.record(z.string(), z.unknown()).optional(),
+	})
+	.meta({ id: "ConnectionIn" });
+
+export const ConnectionPatch = z
+	.object({
+		scopes: z.array(z.string()).nullish(),
+		credential: Credential.nullish(),
+		status: z.string().nullish(),
+		metadata: z.record(z.string(), z.unknown()).nullish(),
+	})
+	.meta({ id: "ConnectionPatch" });
+
+/** The `authorize` 200 body: the minted authorize URL + echoed provider. */
+export const AuthorizeOut = z
+	.object({ authorize_url: z.string().nullable(), provider: z.string() })
+	.meta({ id: "AuthorizeOut" });
+
+/** Body for the OAuth consent broker: `POST …/connections/authorize`. */
+export const AuthorizeIn = z
+	.object({
+		provider: z.string(),
+		return_url: z.string().nullish(),
+		mcp_server: z.string().nullish(),
+	})
+	.meta({ id: "AuthorizeIn" });
+
+// ── Inferred consumer-facing types (re-exported by ../responses) ─────────────
+
+export type ICConnection = z.infer<typeof ConnectionOut>;

package/ts/zod/conversations.ts

@@ -0,0 +1,103 @@
+/**
+ * Hand-authored Zod schemas for the `conversations` resource — the wire's source
+ * of truth, mapped onto the OpenAI **Conversations API** so an OpenAI client
+ * library talks to it unchanged.
+ *
+ * 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 here and re-exported by `../responses`.
+ *
+ * Standards mapping: the object matches OpenAI's `conversation`
+ * (`id`/`object`/`created_at`/`metadata`); `title`, `smith_id`, and `updated_at`
+ * are documented IC extensions OpenAI omits (OpenAI has no title and no list
+ * endpoint, both of which a console conversation list needs). `created_at`/
+ * `updated_at` are unix-second integers like every OpenAI object, not the ISO
+ * strings the native `ic_*` resources use. Items are read-only and reconstructed
+ * from the conversation's runs — they accrue from `/v1/responses`, not a write
+ * endpoint.
+ */
+import { z } from "zod";
+import { pageOut } from "./_page.js";
+
+/** A conversation — the OpenAI Conversations object + IC extensions. */
+export const ConversationOut = z
+	.object({
+		id: z.string(),
+		object: z.literal("conversation"),
+		/** Unix seconds, like every OpenAI object. */
+		created_at: z.number().int(),
+		/** Unix seconds of the last run in the conversation (IC extension). */
+		updated_at: z.number().int(),
+		/** Auto-set from the first user turn of a Responses-API run that names this
+		 *  conversation; null until then. Set it yourself any time. IC extension. */
+		title: z.string().nullable(),
+		/** The smith that owns this conversation. IC extension. */
+		smith_id: z.string(),
+		metadata: z.record(z.string(), z.unknown()),
+	})
+	.meta({ id: "ConversationOut" });
+
+export const ConversationListOut = pageOut(ConversationOut, "ConversationListOut");
+
+/** The delete acknowledgement, in OpenAI's `*.deleted` shape. */
+export const ConversationDeleted = z
+	.object({
+		id: z.string(),
+		object: z.literal("conversation.deleted"),
+		deleted: z.literal(true),
+	})
+	.meta({ id: "ConversationDeleted" });
+
+/** One reconstructed item in a conversation. Modelled loosely on the Responses
+ *  output items: a `message` carries `content` parts (`input_text`/`output_text`);
+ *  the tool-step items mirror their wire shapes — `function_call`
+ *  (`call_id`/`name`/`arguments`) and `function_call_output` (`call_id`/`output`) for
+ *  client-side tools, `mcp_call` (`name`/`arguments`/`output`/`server_label`) for a
+ *  tool the run loop executed server-side. */
+export const ConversationItem = z
+	.object({
+		id: z.string(),
+		type: z.string(),
+		role: z.string().optional(),
+		status: z.string().optional(),
+		content: z.array(z.record(z.string(), z.unknown())).optional(),
+		// Tool-step fields (present on function_call / function_call_output / mcp_call).
+		call_id: z.string().optional(),
+		name: z.string().optional(),
+		arguments: z.string().optional(),
+		output: z.string().optional(),
+		server_label: z.string().optional(),
+	})
+	.meta({ id: "ConversationItem" });
+
+/** A conversation's items, in OpenAI's `list` envelope (not the IC cursor page). */
+export const ConversationItemListOut = z
+	.object({
+		object: z.literal("list"),
+		data: z.array(ConversationItem),
+		first_id: z.string().nullable(),
+		last_id: z.string().nullable(),
+		has_more: z.boolean(),
+	})
+	.meta({ id: "ConversationItemListOut" });
+
+/** Create body — OpenAI accepts `metadata`; `title` is the IC extension. */
+export const ConversationCreate = z
+	.object({
+		title: z.string().optional(),
+		metadata: z.record(z.string(), z.unknown()).optional(),
+	})
+	.meta({ id: "ConversationCreate" });
+
+/** Update body — set the title and/or merge metadata. */
+export const ConversationUpdate = z
+	.object({
+		title: z.string().optional(),
+		metadata: z.record(z.string(), z.unknown()).optional(),
+	})
+	.meta({ id: "ConversationUpdate" });
+
+// ── Inferred consumer-facing types (re-exported by ../responses) ─────────────
+
+export type ICConversation = z.infer<typeof ConversationOut>;
+export type ICConversationItem = z.infer<typeof ConversationItem>;

package/ts/zod/customers.ts

@@ -0,0 +1,62 @@
+/**
+ * Hand-authored Zod schemas for the `customers` resource — 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`.
+ *
+ * A customer is the *tenant's* billable party for its smiths (never ours); many
+ * smiths roll up to one customer, so `smith_count` is a correlated count.
+ *
+ * `.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 CustomerOut = z
+	.object({
+		id: z.string(),
+		name: z.string(),
+		/** Opaque external system → id map (e.g. CRM/billing keys). */
+		external_ids: z.record(z.string(), z.string()),
+		/** Free-form tenant annotations. */
+		metadata: z.record(z.string(), z.unknown()),
+		/** Active smiths rolling up to this customer; present on single-customer reads. */
+		smith_count: z.number().int().optional(),
+		created_at: z.string().nullable(),
+	})
+	.meta({ id: "CustomerOut" });
+
+/** Paginated list envelope: keyset cursor over `created_at, id` (desc). */
+export const CustomerListOut = z
+	.object({
+		data: z.array(CustomerOut),
+		next_cursor: z.string().nullable(),
+		has_more: z.boolean(),
+	})
+	.meta({ id: "CustomerListOut" });
+
+// ── Request bodies ──────────────────────────────────────────────────────────
+
+export const CustomerCreate = z
+	.object({
+		name: z.string(),
+		external_ids: z.record(z.string(), z.string()).optional(),
+		metadata: z.record(z.string(), z.unknown()).optional(),
+	})
+	.meta({ id: "CustomerCreate" });
+
+export const CustomerPatch = z
+	.object({
+		name: z.string().nullish(),
+		external_ids: z.record(z.string(), z.string()).nullish(),
+		metadata: z.record(z.string(), z.unknown()).nullish(),
+	})
+	.meta({ id: "CustomerPatch" });
+
+// ── Inferred consumer-facing types (re-exported by ../responses) ─────────────
+
+export type ICCustomer = z.infer<typeof CustomerOut>;

package/ts/zod/deployments.ts

@@ -0,0 +1,93 @@
+/**
+ * Hand-authored Zod schemas for the `deployments` resource — messaging endpoints
+ * attached to a smith (Telegram/WhatsApp/Slack/SMS/voice/email).
+ *
+ * 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 response shapes on purpose: `DeploymentOut` is the plain serializer
+ * (`api/src/runtime/deployments.ts::publicDeployment`) returned by GET/list, PATCH,
+ * and the email `provision` create. `DeploymentCreatedOut` is the richer create
+ * response — the deferred-setup gateways (telegram/whatsapp `start_token`,
+ * slack `provision`/`oauth_install`) hand back binding affordances on top of
+ * the base shape (`start_token` + `deep_link`, slack's `install_url`/`state`,
+ * …). The relic `DeploymentOut` did NOT document these create-only fields; the
+ * handler is the truth, so they live here as optionals.
+ */
+import { z } from "zod";
+import { pageOut } from "./_page.js";
+
+/** A deployment's target: a fixed `smith` (one running clone) or an `agent`
+ *  catch-all that mints a fresh smith per inbound sender. */
+export const DeploymentTarget = z
+	.object({ type: z.enum(["smith", "agent"]), id: z.string() })
+	.meta({ id: "DeploymentTarget" });
+
+export const DeploymentOut = z
+	.object({
+		id: z.string(),
+		target: DeploymentTarget,
+		kind: z.string(),
+		address: z.string().nullable(),
+		provider: z.string().nullable(),
+		provider_metadata: z.record(z.string(), z.unknown()).optional(),
+		/** Names of the encrypted secret fields that are set (values never returned). */
+		secret_keys: z.array(z.string()).optional(),
+		status: z.string(),
+		created_at: z.string().nullable(),
+	})
+	.meta({ id: "DeploymentOut" });
+
+export const DeploymentListOut = pageOut(DeploymentOut, "DeploymentListOut");
+
+/**
+ * The richer create response. Beyond the base `DeploymentOut`, the setup gateways
+ * attach provider-specific binding affordances:
+ * - telegram `start_token`: `start_token`, `deep_link` (t.me link).
+ * - whatsapp `start_token`: `start_token`, `prefilled_message`, `deep_link` (wa.me link).
+ * - slack `provision`/`oauth_install`: `install_url`, `state`, optional `slack_app_id`.
+ * - email `provision`: no extras (plain `DeploymentOut`).
+ * All are optional — which appear depends on the kind + setup mode.
+ */
+export const DeploymentCreatedOut = DeploymentOut.extend({
+	start_token: z.string().optional(),
+	deep_link: z.string().optional(),
+	prefilled_message: z.string().optional(),
+	install_url: z.string().optional(),
+	state: z.string().optional(),
+	slack_app_id: z.string().optional(),
+}).meta({ id: "DeploymentCreatedOut" });
+
+// ── Request bodies ──────────────────────────────────────────────────────────
+
+export const DeploymentIn = z
+	.object({
+		/** Who the deployment binds: a `smith` (fixed) or an `agent` (mints a smith
+		 *  per inbound sender). A smith token may only target its own smith. */
+		target: DeploymentTarget,
+		kind: z.string(),
+		address: z.string().nullish(),
+		provider: z.string().nullish(),
+		provider_metadata: z.record(z.string(), z.unknown()).optional(),
+		secrets: z.record(z.string(), z.unknown()).optional(),
+		setup: z.record(z.string(), z.unknown()).nullish(),
+	})
+	.meta({ id: "DeploymentIn" });
+
+export const DeploymentPatch = z
+	.object({
+		display_name: z.string().nullish(),
+		owner_email: z.string().nullish(),
+	})
+	.meta({ id: "DeploymentPatch" });
+
+// ── Inferred consumer-facing types (re-exported by ../responses) ─────────────
+
+export type ICDeployment = z.infer<typeof DeploymentOut>;
+export type ICDeploymentCreated = z.infer<typeof DeploymentCreatedOut>;

package/ts/zod/discord.ts

@@ -0,0 +1,39 @@
+/**
+ * Hand-authored Zod schemas for the `discord` channel-config resource — the wire's
+ * source of truth, mirroring `telegram.ts`.
+ *
+ * Discord is delivered over its HTTP Interactions endpoint: the tenant registers one
+ * Discord application (its public key + a bot token) and Ingram Cloud verifies every
+ * inbound interaction's Ed25519 signature with that public key, so there is no shared
+ * webhook secret. Secrets are never returned.
+ */
+import { z } from "zod";
+
+/**
+ * The tenant's Discord app config status. The bot token is never returned; the
+ * optional fields are present once `configured` is true. `webhook_url` is the
+ * Interactions Endpoint URL to register in the Discord Developer Portal.
+ */
+export const DiscordAppOut = z
+	.object({
+		configured: z.boolean(),
+		application_id: z.string().optional(),
+		public_key: z.string().optional(),
+		has_bot_token: z.boolean().optional(),
+		webhook_url: z.string().optional(),
+	})
+	.meta({ id: "DiscordAppOut" });
+
+// ── Request bodies ──────────────────────────────────────────────────────────
+
+export const DiscordAppIn = z
+	.object({
+		application_id: z.string(),
+		public_key: z.string(),
+		bot_token: z.string(),
+	})
+	.meta({ id: "DiscordAppIn" });
+
+// ── Inferred consumer-facing types (re-exported by ../responses) ─────────────
+
+export type ICDiscordApp = z.infer<typeof DiscordAppOut>;

package/ts/zod/email.ts

@@ -0,0 +1,52 @@
+/**
+ * Hand-authored Zod schemas for the `email` channel-config resource — the
+ * wire's source of truth for the tenant Cloudflare sending config.
+ *
+ * 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 `EmailConfigOut` here and re-exported by
+ * `../responses` as `export type` — no Zod is pulled into a type-only consumer.
+ *
+ * `.meta({ id })` names the component so the emitted OpenAPI references it as
+ * `#/components/schemas/<id>` rather than inlining it.
+ *
+ * The out shape is the union of two builders in `api/src/routes/email.ts`
+ * (via `runtime/email.ts`):
+ *  - GET `/v1/tenant/email` (`configStatus`) — `{ configured: false }`, or
+ *    `{ configured: true, from_domain, display_name, has_token, inbound_url }`.
+ *  - PUT `/v1/tenant/email` (`configureEmail`) — `{ configured: true,
+ *    from_domain, display_name, inbound_url, inbound_secret }`.
+ * Hence `configured` is the only required field; everything else is optional,
+ * and `inbound_secret` is present only on the PUT response (shown once).
+ */
+import { z } from "zod";
+
+export const EmailConfigOut = z
+	.object({
+		/** False when the tenant has no email config; true otherwise. */
+		configured: z.boolean(),
+		from_domain: z.string().optional(),
+		display_name: z.string().nullish(),
+		/** Present on GET when configured — the API token is never returned. */
+		has_token: z.boolean().optional(),
+		inbound_url: z.string().optional(),
+		/** Only present on PUT (shown once) — wire it into the inbound worker. */
+		inbound_secret: z.string().optional(),
+	})
+	.meta({ id: "EmailConfigOut" });
+
+// ── Request body ─────────────────────────────────────────────────────────────
+
+export const EmailConfigIn = z
+	.object({
+		cloudflare_account_id: z.string(),
+		cloudflare_api_token: z.string(),
+		from_domain: z.string(),
+		display_name: z.string().nullish(),
+		inbound_secret: z.string().nullish(),
+	})
+	.meta({ id: "EmailConfigIn" });
+
+// ── Inferred consumer-facing type (re-exported by ../responses) ──────────────
+
+export type ICEmailConfig = z.infer<typeof EmailConfigOut>;

package/ts/zod/files.ts

@@ -0,0 +1,62 @@
+/**
+ * Hand-authored Zod schemas for the `files` resource — the wire's source of
+ * truth, mapped onto the OpenAI **Files API** so an OpenAI client library talks
+ * to it unchanged.
+ *
+ * The File object is exactly OpenAI's (`status`/`status_details` included, inert
+ * upstream and here). Upload is `multipart/form-data`, so there is no `In`
+ * schema — the route reads the form directly. The list uses OpenAI's `list`
+ * envelope with `after`/`limit`/`order` paging and enumerates Files-API uploads
+ * only; files inlined into a conversation stay reachable by id but are not
+ * listed.
+ */
+import { z } from "zod";
+
+/** OpenAI's upload purposes. Vector-store source files are `assistants`. */
+export const FilePurpose = z.enum([
+	"assistants",
+	"batch",
+	"fine-tune",
+	"vision",
+	"user_data",
+	"evals",
+]);
+
+/** The OpenAI File object. */
+export const FileOut = z
+	.object({
+		id: z.string(),
+		object: z.literal("file"),
+		bytes: z.number().int(),
+		/** Unix seconds, like every OpenAI object. */
+		created_at: z.number().int(),
+		filename: z.string(),
+		purpose: z.string(),
+		/** Deprecated upstream; always `processed` here. */
+		status: z.literal("processed"),
+		status_details: z.null(),
+	})
+	.meta({ id: "FileOut" });
+
+/** Files, in OpenAI's `list` envelope (not the IC cursor page). */
+export const FileListOut = z
+	.object({
+		object: z.literal("list"),
+		data: z.array(FileOut),
+		first_id: z.string().nullable(),
+		last_id: z.string().nullable(),
+		has_more: z.boolean(),
+	})
+	.meta({ id: "FileListOut" });
+
+/** The delete acknowledgement, in OpenAI's `*.deleted` shape. */
+export const FileDeleted = z
+	.object({
+		id: z.string(),
+		object: z.literal("file"),
+		deleted: z.literal(true),
+	})
+	.meta({ id: "FileDeleted" });
+
+export type ICFile = z.infer<typeof FileOut>;
+export type ICFileList = z.infer<typeof FileListOut>;

package/ts/zod/index.ts

@@ -0,0 +1,35 @@
+/**
+ * Hand-authored Zod schemas — the wire's source of truth, one resource module
+ * per file. The API imports these into its `createRoute` definitions (runtime
+ * validation + emitted OpenAPI); `../responses` re-exports the `z.infer`red
+ * `IC*` types from them.
+ *
+ * Resources are migrated here off the generated `../schemas.ts` one at a time;
+ * when the last one lands, the generated file and the `openapi-zod-client` step
+ * are deleted and this becomes the sole `schemas` source.
+ */
+export * from "./_page.js";
+export * from "./agents.js";
+export * from "./approvals.js";
+export * from "./budgets.js";
+export * from "./catalog.js";
+export * from "./connections.js";
+export * from "./conversations.js";
+export * from "./deployments.js";
+export * from "./customers.js";
+export * from "./discord.js";
+export * from "./email.js";
+export * from "./files.js";
+export * from "./mcp.js";
+export * from "./memories.js";
+export * from "./observability.js";
+export * from "./projects.js";
+export * from "./runs.js";
+export * from "./schedules.js";
+export * from "./slack.js";
+export * from "./smith-revisions.js";
+export * from "./smiths.js";
+export * from "./telegram.js";
+export * from "./tenant.js";
+export * from "./vector-stores.js";
+export * from "./whatsapp.js";

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>;