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

package/ts/zod/slack.ts

@@ -0,0 +1,79 @@
+/**
+ * Hand-authored Zod schemas for the `slack` channel-config resource — the
+ * wire's source of truth for `PUT/GET /v1/tenant/slack`.
+ *
+ * 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 here and re-exported by `../responses`. No Zod is pulled
+ * into a type-only consumer — `responses.ts` re-exports this 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";
+
+// ── Config status (GET/PUT response) ─────────────────────────────────────────
+
+/** App factory posture: whether the tenant has minted-app credentials stored. */
+export const SlackFactoryStatus = z
+	.object({ configured: z.boolean() })
+	.meta({ id: "SlackFactoryStatus" });
+
+/**
+ * The tenant's Slack posture, as `tenantStatus` builds it. `configured`,
+ * `factory`, and `oauth_redirect_url` are always emitted; the shared-app
+ * details (`bot_user_id`, `team_id`, `events_url`, `oauth_ready`) only appear
+ * once a shared app is configured, and `return_url` only when one is set.
+ */
+export const SlackAppOut = z
+	.object({
+		configured: z.boolean(),
+		bot_user_id: z.string().optional(),
+		team_id: z.string().optional(),
+		events_url: z.string().optional(),
+		/** Shared app's OAuth client is set — "Add to Slack" installs work. */
+		oauth_ready: z.boolean().optional(),
+		oauth_redirect_url: z.string().optional(),
+		/** Where the OAuth redirect sends installers back (?slack=… appended). */
+		return_url: z.string().optional(),
+		/** App factory: mints per-smith Slack apps from the manifest template. */
+		factory: SlackFactoryStatus.optional(),
+	})
+	.meta({ id: "SlackAppOut" });
+
+// ── Request bodies (PUT /v1/tenant/slack) ────────────────────────────────────
+
+/**
+ * The app-factory block: a delegated app-config token pair plus the Slack app
+ * manifest template that minted per-smith apps are instantiated from.
+ */
+export const SlackFactoryIn = z
+	.object({
+		config_token: z.string(),
+		config_refresh_token: z.string().nullish(),
+		manifest_template: z.record(z.string(), z.unknown()),
+	})
+	.meta({ id: "SlackFactoryIn" });
+
+/**
+ * Register or rotate the tenant's Slack posture: a shared app (bot_token +
+ * signing_secret, optionally the OAuth client fields), a factory block, and/or
+ * the return_url. Every field is optional — the handler applies whichever
+ * blocks are present.
+ */
+export const SlackAppIn = z
+	.object({
+		bot_token: z.string().nullish(),
+		signing_secret: z.string().nullish(),
+		client_id: z.string().nullish(),
+		client_secret: z.string().nullish(),
+		oauth_scopes: z.string().nullish(),
+		oauth_user_scopes: z.string().nullish(),
+		return_url: z.string().nullish(),
+		factory: SlackFactoryIn.nullish(),
+	})
+	.meta({ id: "SlackAppIn" });
+
+// ── Inferred consumer-facing type (re-exported by ../responses) ──────────────
+
+export type ICSlackApp = z.infer<typeof SlackAppOut>;

package/ts/zod/smith-revisions.ts

@@ -0,0 +1,48 @@
+/**
+ * Hand-authored Zod schemas for the `smith-revisions` resource — the wire's
+ * source of truth for `/v1/smiths/{id}/revisions`.
+ *
+ * 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 as types.
+ *
+ * A smith's behaviour config (instructions / model / hosted tools / auto-memory)
+ * is mutable; every change is snapshotted as an immutable *revision* and an
+ * operator can roll back. History is append-only — a *restore* re-applies an old
+ * snapshot as a brand-new revision.
+ *
+ * `.meta({ id })` names the component so the emitted OpenAPI references it as
+ * `#/components/schemas/<id>` rather than inlining it.
+ */
+import { z } from "zod";
+
+/** An immutable snapshot of a smith's effective behaviour config at one revision. */
+export const SmithRevisionOut = 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().optional(),
+		}),
+		created_by: z.string().nullish(),
+		note: z.string().nullish(),
+		created_at: z.string().nullish(),
+	})
+	.meta({ id: "SmithRevisionOut" });
+
+export const RevisionListOut = z
+	.object({ data: z.array(SmithRevisionOut) })
+	.meta({ id: "RevisionListOut" });
+
+// ── Request bodies ──────────────────────────────────────────────────────────
+
+export const RestoreIn = z
+	.object({ note: z.string().nullish() })
+	.meta({ id: "RestoreIn" });
+
+// ── Inferred consumer-facing types (re-exported by ../responses) ─────────────
+
+export type ICSmithRevision = z.infer<typeof SmithRevisionOut>;

package/ts/zod/smiths.ts

@@ -0,0 +1,131 @@
+/**
+ * Hand-authored Zod schemas for the `smiths` 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`.
+ *
+ * A smith is one running clone of an agent (`/v1/smiths`, `smt_` ids), the unit
+ * of data isolation. Its identity fields live alongside its *effective* agent
+ * config (model/instructions/tools), flattened onto the resource. Memory blocks
+ * (`/v1/smiths/{id}/blocks`) are the smith's in-context "what the agent always
+ * knows" sub-resource.
+ *
+ * `.meta({ id })` names the component so the emitted OpenAPI references it as
+ * `#/components/schemas/<id>` rather than inlining it.
+ */
+import { z } from "zod";
+
+// ── Smith response ───────────────────────────────────────────────────────────
+
+export const SmithOut = z
+	.object({
+		id: z.string(),
+		external_id: z.string().nullable(),
+		display_name: z.string().nullable(),
+		locale: z.string().nullable(),
+		timezone: z.string().nullable(),
+		/** The customer (billable party) this smith's usage rolls up to. */
+		customer_id: z.string().nullish(),
+		metadata: z.record(z.string(), z.unknown()).optional(),
+		// The *effective* agent config (agent-resolved when attached).
+		model: z.string(),
+		/** The raw instructions template (may contain {{ variables }}). */
+		instructions: z.string(),
+		/** What this smith actually runs with — {{ variables }} bound per-smith. */
+		rendered_instructions: z.string().nullish(),
+		enabled_hosted_tools: z.array(z.string()).optional(),
+		auto_memory: z.boolean().optional(),
+		/** How the config resolved: by reference, with overrides, or embedded. */
+		config_source: z.enum(["agent", "override", "custom"]).optional(),
+		agent_id: z.string().nullish(),
+		agent_version: z.number().int().nullish(),
+		pin: z.number().int().nullish(),
+		created_at: z.string(),
+	})
+	.meta({ id: "SmithOut" });
+
+/** Cursor-paginated smith list: `data` + `has_more` (+ opaque `next_cursor`). */
+export const SmithListOut = z
+	.object({
+		data: z.array(SmithOut),
+		has_more: z.boolean(),
+		next_cursor: z.string().nullish(),
+	})
+	.meta({ id: "SmithListOut" });
+
+// ── Memory blocks (smith sub-resource) ───────────────────────────────────────
+
+/** A core memory block — pinned, in-context text bounded by `char_limit`. */
+export const BlockOut = z
+	.object({
+		id: z.string(),
+		label: z.string(),
+		description: z.string(),
+		value: z.string(),
+		char_limit: z.number().int(),
+		updated_at: z.string().nullable(),
+	})
+	.meta({ id: "BlockOut" });
+
+/** Block list — the plain `{ data }` envelope (blocks don't paginate). */
+export const BlockListOut = z
+	.object({ data: z.array(BlockOut) })
+	.meta({ id: "BlockListOut" });
+
+/** Block-edit response — a single block wrapped in the `{ data }` envelope (the
+ *  one-block sibling of the array `BlockListOut` that the block PATCH returns). */
+export const BlockSingleOut = z
+	.object({ data: BlockOut })
+	.meta({ id: "BlockSingleOut" });
+
+// ── Request bodies ──────────────────────────────────────────────────────────
+
+export const SmithCreate = z
+	.object({
+		external_id: z.string().nullish(),
+		display_name: z.string().nullish(),
+		locale: z.string().nullish(),
+		timezone: z.string().nullish(),
+		customer_id: z.string().nullish(),
+		metadata: z.record(z.string(), z.unknown()).optional(),
+		agent_id: z.string().nullish(),
+		pin: z.number().int().nullish(),
+		model: z.string().nullish(),
+		instructions: z.string().nullish(),
+		enabled_hosted_tools: z.array(z.string()).nullish(),
+		auto_memory: z.boolean().nullish(),
+	})
+	.meta({ id: "SmithCreate" });
+
+export const SmithPatch = z
+	.object({
+		display_name: z.string().nullish(),
+		locale: z.string().nullish(),
+		timezone: z.string().nullish(),
+		customer_id: z.string().nullish(),
+		metadata: z.record(z.string(), z.unknown()).nullish(),
+		agent_id: z.string().nullish(),
+		pin: z.number().int().nullish(),
+		model: z.string().nullish(),
+		instructions: z.string().nullish(),
+		enabled_hosted_tools: z.array(z.string()).nullish(),
+		auto_memory: z.boolean().nullish(),
+	})
+	.meta({ id: "SmithPatch" });
+
+/** Edit a block's value — `replace` (default) or `append`. */
+export const BlockPatch = z
+	.object({
+		value: z.string(),
+		mode: z.enum(["replace", "append"]).default("replace"),
+	})
+	.meta({ id: "BlockPatch" });
+
+// ── Inferred consumer-facing types (re-exported by ../responses) ─────────────
+
+export type ICSmith = z.infer<typeof SmithOut>;
+export type ICBlock = z.infer<typeof BlockOut>;

package/ts/zod/telegram.ts

@@ -0,0 +1,43 @@
+/**
+ * Hand-authored Zod schemas for the `telegram` channel-config 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`.
+ *
+ * `.meta({ id })` names the component so the emitted OpenAPI references it as
+ * `#/components/schemas/<id>` rather than inlining it.
+ */
+import { z } from "zod";
+
+/**
+ * The tenant's Telegram bot config status. The token itself is never returned;
+ * the optional fields are present only once `configured` is true (`has_token`
+ * appears on the read path, not the just-configured write response).
+ */
+export const TelegramBotOut = z
+	.object({
+		configured: z.boolean(),
+		bot_username: z.string().optional(),
+		bot_id: z.number().int().optional(),
+		has_token: z.boolean().optional(),
+		webhook_url: z.string().optional(),
+	})
+	.meta({ id: "TelegramBotOut" });
+
+// ── Request bodies ──────────────────────────────────────────────────────────
+
+export const TelegramBotIn = z
+	.object({
+		bot_token: z.string(),
+		webhook_secret: z.string().nullish(),
+	})
+	.meta({ id: "TelegramBotIn" });
+
+// ── Inferred consumer-facing types (re-exported by ../responses) ─────────────
+
+export type ICTelegramBot = z.infer<typeof TelegramBotOut>;

package/ts/zod/tenant.ts

@@ -0,0 +1,272 @@
+/**
+ * Hand-authored Zod schemas for the `tenant` config plane — the grab-bag router
+ * (`api/src/routes/tenant.ts`) serving the events feed, hosted-tool catalog,
+ * BYOK model keys, the model catalog, OAuth client providers, minted tokens, the
+ * usage summary, and webhooks.
+ *
+ * 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`.
+ *
+ * `.meta({ id })` names the component so the emitted OpenAPI references it as
+ * `#/components/schemas/<id>` rather than inlining it.
+ */
+import { z } from "zod";
+
+// ── Events (poll mirror of the webhook firehose) ─────────────────────────────
+
+/** One event in the `/v1/events` feed — the `{v:1}` envelope (sans `tenant_id`,
+ *  which the feed omits since the tenant is implicit in the token). */
+export const EventOut = z
+	.object({
+		/** Envelope schema version (always `1` today). */
+		v: z.number().int(),
+		id: z.string(),
+		type: z.string(),
+		smith_id: z.string().nullable(),
+		data: z.record(z.string(), z.unknown()),
+		created_at: z.string().nullable(),
+	})
+	.meta({ id: "EventOut" });
+
+export const EventListOut = z
+	.object({ data: z.array(EventOut) })
+	.meta({ id: "EventListOut" });
+
+// ── Webhooks ─────────────────────────────────────────────────────────────────
+
+export const WebhookOut = z
+	.object({
+		id: z.string(),
+		url: z.string(),
+		events: z.array(z.string()),
+		active: z.boolean(),
+		created_at: z.string().nullable(),
+	})
+	.meta({ id: "WebhookOut" });
+
+export const WebhookListOut = z
+	.object({ data: z.array(WebhookOut) })
+	.meta({ id: "WebhookListOut" });
+
+/** The create response — the signing `secret` is returned EXACTLY ONCE, here. */
+export const WebhookCreateOut = z
+	.object({
+		id: z.string(),
+		url: z.string(),
+		events: z.array(z.string()),
+		active: z.boolean(),
+		secret: z.string(),
+	})
+	.meta({ id: "WebhookCreateOut" });
+
+/** The patch/delete-adjacent ack shape (just the id). */
+export const WebhookIdOut = z
+	.object({ id: z.string() })
+	.meta({ id: "WebhookIdOut" });
+
+export const WebhookIn = z
+	.object({
+		url: z.string(),
+		events: z.array(z.string()).default([]),
+		active: z.boolean().default(true),
+	})
+	.meta({ id: "WebhookIn" });
+
+export const WebhookPatch = z
+	.object({
+		url: z.string().nullish(),
+		events: z.array(z.string()).nullish(),
+		active: z.boolean().nullish(),
+	})
+	.meta({ id: "WebhookPatch" });
+
+// ── Tokens (mint / list / revoke RS256 JWTs) ─────────────────────────────────
+
+/** A minted-token *summary* — the list/listing shape. The secret `token` is
+ *  NEVER echoed here; it only appears in {@link MintedTokenOut} on create. */
+export const TokenOut = z
+	.object({
+		id: z.string(),
+		name: z.string().nullable(),
+		sub: z.string(),
+		scopes: z.array(z.string()),
+		prefix: z.string().nullable(),
+		created_at: z.string().nullable(),
+		expires_at: z.string().nullable(),
+		revoked_at: z.string().nullable(),
+	})
+	.meta({ id: "TokenOut" });
+
+export const TokenListOut = z
+	.object({ data: z.array(TokenOut) })
+	.meta({ id: "TokenListOut" });
+
+/** The create response — carries the secret `token` exactly once. */
+export const MintedTokenOut = z
+	.object({
+		id: z.string(),
+		token: z.string(),
+		scope: z.string(),
+		sub: z.string(),
+		scopes: z.array(z.string()),
+		expires_at: z.string().nullable(),
+	})
+	.meta({ id: "MintedTokenOut" });
+
+export const TokenIn = z
+	.object({
+		scope: z.string().default("smith"),
+		smith_id: z.string().nullish(),
+		permissions: z.array(z.string()).nullish(),
+		ttl_seconds: z.number().int().nullish(),
+		name: z.string().nullish(),
+	})
+	.meta({ id: "TokenIn" });
+
+// ── Usage (aggregated token usage across the tenant's runs, by day) ──────────
+
+export const UsageOut = z
+	.object({
+		totals: z.object({
+			runs: z.number().int(),
+			input_tokens: z.number().int(),
+			output_tokens: z.number().int(),
+			total_tokens: z.number().int(),
+		}),
+		series: z.array(
+			z.object({
+				date: z.string(),
+				runs: z.number().int(),
+				total_tokens: z.number().int(),
+			}),
+		),
+	})
+	.meta({ id: "UsageOut" });
+
+// ── Model catalog + BYOK keys ────────────────────────────────────────────────
+
+/** One selectable model in the `/v1/tenant/models` catalog. */
+export const ModelOut = z
+	.object({
+		id: z.string(),
+		provider: z.string(),
+		label: z.string(),
+		available: z.boolean(),
+		/** Whose key a run would use: the tenant's ("byok") or IC's ("platform"). */
+		source: z.enum(["byok", "platform"]).nullish(),
+	})
+	.meta({ id: "ModelOut" });
+
+/** A runnable backend in the model catalog (NB `base_url` is a *bool flag* — does
+ *  the provider accept a base-url override — not a URL). */
+export const ModelProviderOut = z
+	.object({
+		id: z.string(),
+		label: z.string(),
+		base_url: z.boolean(),
+		/** True when the platform fallback covers this provider (no tenant key). */
+		platform_key: z.boolean().optional(),
+	})
+	.meta({ id: "ModelProviderOut" });
+
+export const ModelsListOut = z
+	.object({
+		data: z.array(ModelOut),
+		providers: z.array(ModelProviderOut),
+	})
+	.meta({ id: "ModelsListOut" });
+
+/** A BYOK model key — the `api_key` is NEVER echoed, only its presence. */
+export const ModelKeyOut = z
+	.object({
+		provider: z.string(),
+		base_url: z.string().nullable(),
+		has_key: z.boolean(),
+		updated_at: z.string().nullable(),
+	})
+	.meta({ id: "ModelKeyOut" });
+
+export const ModelKeyListOut = z
+	.object({ data: z.array(ModelKeyOut) })
+	.meta({ id: "ModelKeyListOut" });
+
+/** The PUT ack — never echoes the key, only presence + the (non-secret) base_url. */
+export const ModelKeyConfiguredOut = z
+	.object({
+		provider: z.string(),
+		configured: z.boolean(),
+		base_url: z.string().nullable(),
+	})
+	.meta({ id: "ModelKeyConfiguredOut" });
+
+export const ModelKeyIn = z
+	.object({
+		api_key: z.string(),
+		base_url: z.string().nullish(),
+	})
+	.meta({ id: "ModelKeyIn" });
+
+// ── Providers (tenant OAuth client credentials) ──────────────────────────────
+
+/** A provider's OAuth client config — the `client_secret` is NEVER echoed, only
+ *  `has_client_secret`. */
+export const ProviderOut = z
+	.object({
+		provider: z.string(),
+		client_id: z.string().nullable(),
+		token_uri: z.string().nullable(),
+		scopes_allowed: z.array(z.string()),
+		refresh_webhook: z.string().nullable(),
+		has_client_secret: z.boolean(),
+	})
+	.meta({ id: "ProviderOut" });
+
+export const ProviderListOut = z
+	.object({ data: z.array(ProviderOut) })
+	.meta({ id: "ProviderListOut" });
+
+/** The PUT ack. */
+export const ProviderConfiguredOut = z
+	.object({
+		provider: z.string(),
+		configured: z.boolean(),
+	})
+	.meta({ id: "ProviderConfiguredOut" });
+
+export const ProviderIn = z
+	.object({
+		client_id: z.string().nullish(),
+		client_secret: z.string().nullish(),
+		token_uri: z.string().nullish(),
+		scopes_allowed: z.array(z.string()).default([]),
+		refresh_webhook: z.string().nullish(),
+	})
+	.meta({ id: "ProviderIn" });
+
+// ── Hosted-tool catalog ──────────────────────────────────────────────────────
+
+/** One IC-hosted tool the catalog advertises. */
+export const HostedToolOut = z
+	.object({
+		name: z.string(),
+		description: z.string(),
+	})
+	.meta({ id: "HostedToolOut" });
+
+export const HostedToolsListOut = z
+	.object({ data: z.array(HostedToolOut) })
+	.meta({ id: "HostedToolsListOut" });
+
+// ── Inferred consumer-facing types (re-exported by ../responses) ─────────────
+
+export type ICEvent = z.infer<typeof EventOut>;
+export type ICWebhook = z.infer<typeof WebhookOut>;
+export type ICToken = z.infer<typeof TokenOut>;
+export type ICMintedToken = z.infer<typeof MintedTokenOut>;
+export type ICUsage = z.infer<typeof UsageOut>;
+export type ICModel = z.infer<typeof ModelOut>;
+export type ICModelProvider = z.infer<typeof ModelProviderOut>;
+export type ICModelCatalog = z.infer<typeof ModelsListOut>;
+export type ICModelKey = z.infer<typeof ModelKeyOut>;
+export type ICProvider = z.infer<typeof ProviderOut>;

package/ts/zod/whatsapp.ts

@@ -0,0 +1,55 @@
+/**
+ * Hand-authored Zod schemas for the `whatsapp` channel-config 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`.
+ *
+ * `.meta({ id })` names the component so the emitted OpenAPI references it as
+ * `#/components/schemas/<id>` rather than inlining it.
+ */
+import { z } from "zod";
+
+/**
+ * The tenant's WhatsApp Cloud API config status. Secrets are never returned;
+ * the optional fields are present only once `configured` is true.
+ *
+ * Two response paths share this shape: `GET /v1/tenant/whatsapp` (config
+ * status, exposes `has_app_secret`) and the just-configured `PUT` response
+ * (echoes back the `verify_token` to paste into Meta). `display_phone_number`
+ * is the E.164 number Meta has on file for the registered `phone_number_id`,
+ * and can be null until Meta reports it.
+ */
+export const WhatsAppConfigOut = z
+	.object({
+		configured: z.boolean(),
+		phone_number_id: z.string().optional(),
+		display_phone_number: z.string().nullable().optional(),
+		has_app_secret: z.boolean().optional(),
+		webhook_url: z.string().optional(),
+		verify_token: z.string().optional(),
+	})
+	.meta({ id: "WhatsAppConfigOut" });
+
+// ── Request bodies ──────────────────────────────────────────────────────────
+
+export const WhatsAppConfigIn = z
+	.object({
+		// Optional at the shape layer so the handler's own validation runs and
+		// returns its specific `empty_config` code (rather than a pre-handler
+		// `invalid_request`); the handler requires both to be non-empty.
+		phone_number_id: z.string().optional(),
+		access_token: z.string().optional(),
+		app_secret: z.string().nullish(),
+		verify_token: z.string().nullish(),
+		business_id: z.string().nullish(),
+	})
+	.meta({ id: "WhatsAppConfigIn" });
+
+// ── Inferred consumer-facing types (re-exported by ../responses) ─────────────
+
+export type ICWhatsAppConfig = z.infer<typeof WhatsAppConfigOut>;