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

package/ts/zod/agents.ts

@@ -0,0 +1,132 @@
+/**
+ * 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";
+
+/** 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" });
+
+/** 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()),
+		auto_memory: z.boolean().nullable(),
+		variables: z.array(AgentVariable),
+	})
+	.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 = z
+	.object({ data: z.array(AgentOut) })
+	.meta({ id: "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(),
+			auto_memory: z.boolean().nullish(),
+			variables: z.array(AgentVariable).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(),
+		auto_memory: 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(),
+		auto_memory: 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" });
+
+// ── 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>;

package/ts/zod/approvals.ts

@@ -0,0 +1,45 @@
+/**
+ * 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";
+
+/** 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 = z
+	.object({ data: z.array(ApprovalOut) })
+	.meta({ id: "ApprovalListOut" });
+
+// ── Inferred consumer-facing types (re-exported by ../responses) ─────────────
+
+export type ICApproval = z.infer<typeof ApprovalOut>;

package/ts/zod/budgets.ts

@@ -0,0 +1,70 @@
+/**
+ * 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; `smith`/`customer` budgets carry the id in `scope_id`. */
+export const BudgetScope = z.enum(["tenant", "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. */
+export const BudgetOut = z
+	.object({
+		id: z.string(),
+		scope: BudgetScope,
+		scope_id: z.string().nullish(),
+		period: z.string(),
+		limit_usd: z.number(),
+		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(),
+		limit_usd: z.number(),
+		action: z.string().default("warn"),
+		period: z.string().default("monthly"),
+	})
+	.meta({ id: "BudgetIn" });
+
+export const BudgetPatch = z
+	.object({
+		limit_usd: 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>;

package/ts/zod/channels.ts

@@ -0,0 +1,84 @@
+/**
+ * Hand-authored Zod schemas for the `channels` 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: `ChannelOut` is the plain serializer
+ * (`api/src/runtime/channels.ts::publicChannel`) returned by GET/list, PATCH,
+ * and the email `provision` create. `ChannelCreatedOut` 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 `ChannelOut` did NOT document these create-only fields; the
+ * handler is the truth, so they live here as optionals.
+ */
+import { z } from "zod";
+
+export const ChannelOut = z
+	.object({
+		id: z.string(),
+		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: "ChannelOut" });
+
+export const ChannelListOut = z
+	.object({ data: z.array(ChannelOut) })
+	.meta({ id: "ChannelListOut" });
+
+/**
+ * The richer create response. Beyond the base `ChannelOut`, 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 `ChannelOut`).
+ * All are optional — which appear depends on the kind + setup mode.
+ */
+export const ChannelCreatedOut = ChannelOut.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: "ChannelCreatedOut" });
+
+// ── Request bodies ──────────────────────────────────────────────────────────
+
+export const ChannelIn = z
+	.object({
+		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: "ChannelIn" });
+
+export const ChannelPatch = z
+	.object({
+		display_name: z.string().nullish(),
+		owner_email: z.string().nullish(),
+	})
+	.meta({ id: "ChannelPatch" });
+
+// ── Inferred consumer-facing types (re-exported by ../responses) ─────────────
+
+export type ICChannel = z.infer<typeof ChannelOut>;
+export type ICChannelCreated = z.infer<typeof ChannelCreatedOut>;

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/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/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/index.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 "./agents";
+export * from "./approvals";
+export * from "./budgets";
+export * from "./catalog";
+export * from "./channels";
+export * from "./connections";
+export * from "./customers";
+export * from "./email";
+export * from "./mcp";
+export * from "./memories";
+export * from "./observability";
+export * from "./projects";
+export * from "./runs";
+export * from "./schedules";
+export * from "./slack";
+export * from "./smith-revisions";
+export * from "./smiths";
+export * from "./telegram";
+export * from "./tenant";
+export * from "./whatsapp";