@ingram-cloud/sdk 1.0.0

package/ts/zod/memories.ts

@@ -0,0 +1,53 @@
+/**
+ * Hand-authored Zod schemas for the `memory` resource — the wire's source of
+ * truth, imported by the API's `createRoute` definitions (validation + emitted
+ * OpenAPI) and `z.infer`red into the consumer-facing `IC*` types re-exported by
+ * `../responses`.
+ *
+ * Memory is Mastra-native (workstream #65): a smith has one **working-memory**
+ * doc (structured, auto-maintained) plus automatic **semantic recall** over its
+ * past messages. There is no standalone "file a fact" CRUD — recall is over the
+ * conversation history the smith already produced.
+ *
+ * `.meta({ id })` names the component so the emitted OpenAPI references it as
+ * `#/components/schemas/<id>`.
+ */
+import { z } from "zod";
+
+/** A smith's working-memory doc — the structured text the agent maintains about
+ *  its end user, shared across the smith's threads (resource-scoped). */
+export const WorkingMemoryOut = z
+	.object({ content: z.string() })
+	.meta({ id: "WorkingMemoryOut" });
+
+/** Replace a smith's working-memory doc. */
+export const WorkingMemorySet = z
+	.object({ content: z.string() })
+	.meta({ id: "WorkingMemorySet" });
+
+/** Recall query over a smith's past messages. */
+export const RecallBody = z
+	.object({
+		query: z.string(),
+		limit: z.number().int().default(10),
+	})
+	.meta({ id: "RecallBody" });
+
+/** One recall hit — a relevant past message range with its similarity `score`. */
+export const RecallHit = z
+	.object({
+		thread_id: z.string(),
+		content: z.string(),
+		score: z.number(),
+	})
+	.meta({ id: "RecallHit" });
+
+/** Recall response envelope — ranked hits. */
+export const RecallOut = z
+	.object({ data: z.array(RecallHit) })
+	.meta({ id: "RecallOut" });
+
+// ── Inferred consumer-facing types (re-exported by ../responses) ─────────────
+
+export type ICWorkingMemory = z.infer<typeof WorkingMemoryOut>;
+export type ICRecallHit = z.infer<typeof RecallHit>;

package/ts/zod/observability.ts

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

package/ts/zod/projects.ts

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

package/ts/zod/runs.ts

@@ -0,0 +1,135 @@
+/**
+ * Hand-authored Zod schemas for the `runs` resource — the wire's source of
+ * truth, replacing the inline `IC*` run shapes previously declared in
+ * `../responses`.
+ *
+ * One source, three outputs: the API imports these into its `createRoute`
+ * definitions (validation + emitted OpenAPI), and the consumer-facing `IC*`
+ * types are `z.infer`red from them here and re-exported by `../responses`. No
+ * Zod is pulled into a type-only consumer — `responses.ts` re-exports these as
+ * `export type`.
+ *
+ * `.meta({ id })` names the component so the emitted OpenAPI references it as
+ * `#/components/schemas/<id>` rather than inlining it. `RunUsage` is standalone
+ * (`$ref`'d) so the inferred `ICRunUsage` comes out identical to its hand-written
+ * interface ancestor.
+ *
+ * Only the JSON shapes are modelled here: the run object, the run list, run
+ * events + their list, and the create/submit request bodies. The streaming
+ * surfaces emit the native `{v:1}` SSE envelope (not a single JSON schema) and
+ * are deliberately not modelled.
+ */
+import { z } from "zod";
+import { pageOut } from "./_page.js";
+
+/** One message in a run's `input`. `content` is a plain string for a text-only
+ *  turn, or an array of content parts (`{type:"text"|"file"|"image", …}`) for a
+ *  multimodal turn — the OpenAI-compatible surface and inline-file offloading both
+ *  persist the array form, so the read schema must accept both. */
+export const InputMessage = z
+	.object({
+		role: z.string(),
+		content: z.union([
+			z.string(),
+			z.array(z.record(z.string(), z.unknown())),
+		]),
+	})
+	.meta({ id: "InputMessage" });
+
+/** One run's own token usage (the `usage` map on a run). Distinct from the
+ *  tenant's aggregated billing summary. Plain numbers, not ints: provider/cache
+ *  token math can be fractional, and an int assertion on a read surface buys
+ *  nothing but a 500 risk. */
+export const RunUsage = z
+	.object({
+		input_tokens: z.number(),
+		output_tokens: z.number(),
+		total_tokens: z.number(),
+		// This turn's priced cost in the account currency, computed at finish from the
+		// model's price book entry. Optional: runs metered before pricing landed — and
+		// any turn with no resolvable model — carry tokens but no `cost`.
+		cost: z.number().optional(),
+	})
+	.meta({ id: "RunUsage" });
+
+export const RunOut = z
+	.object({
+		id: z.string(),
+		smith_id: z.string(),
+		thread_id: z.string(),
+		status: z.string(),
+		channel: z.string(),
+		input: z.array(InputMessage),
+		// `tool_calls` is an array of surface-specific call objects: the OpenAI
+		// `{id,type,function}` shape for a client-tools turn, a pending-call dict for
+		// an approval pause. Modelled loosely on purpose — a single strict struct here
+		// would 500 the read surface on the shapes actually stored.
+		output: z
+			.object({
+				content: z.string().optional(),
+				// Set by a structured (`response_format`) run: the media type of `content`
+				// (e.g. `application/json`), so a reader knows to parse it.
+				content_type: z.string().optional(),
+				tool_calls: z.array(z.record(z.string(), z.unknown())).optional(),
+				// Quick-reply chips the agent offered for this reply (via the
+				// `suggest_replies` tool). Channels with native support render them as
+				// tappable buttons; a tap arrives as the user's next message.
+				suggested_replies: z.array(z.string()).optional(),
+			})
+			.nullable(),
+		stop_reason: z.string().nullable(),
+		usage: RunUsage.nullable(),
+		metadata: z.record(z.string(), z.unknown()).optional(),
+		created_at: z.string().nullable(),
+		updated_at: z.string().nullable(),
+	})
+	.meta({ id: "RunOut" });
+
+export const RunListOut = pageOut(RunOut, "RunListOut");
+
+/** One recorded run event, as replayed from the event log. */
+export const RunEventOut = z
+	.object({
+		seq: z.number().int(),
+		type: z.string(),
+		data: z.record(z.string(), z.unknown()),
+		created_at: z.string().nullable(),
+	})
+	.meta({ id: "RunEventOut" });
+
+export const RunEventListOut = z
+	.object({ data: z.array(RunEventOut) })
+	.meta({ id: "RunEventListOut" });
+
+// ── Request bodies ──────────────────────────────────────────────────────────
+
+export const RunIn = z
+	.object({
+		input: z.array(InputMessage).optional(),
+		thread_id: z.string().nullish(),
+		stream: z.boolean().optional(),
+		channel: z.string().optional(),
+		metadata: z.record(z.string(), z.unknown()).optional(),
+		response_format: z.record(z.string(), z.unknown()).nullish(),
+	})
+	.meta({ id: "RunIn" });
+
+export const Submit = z
+	.object({
+		kind: z.string(),
+		tool_call_id: z.string().nullish(),
+		result: z.record(z.string(), z.unknown()).nullish(),
+		approval_id: z.string().nullish(),
+		decision: z.string().nullish(),
+		actor: z.string().nullish(),
+		reason: z.string().nullish(),
+		stream: z.boolean().optional(),
+	})
+	.meta({ id: "Submit" });
+
+// ── Inferred consumer-facing types (re-exported by ../responses) ─────────────
+
+export type ICInputMessage = z.infer<typeof InputMessage>;
+export type ICRunUsage = z.infer<typeof RunUsage>;
+export type ICRun = z.infer<typeof RunOut>;
+export type ICRunEvent = z.infer<typeof RunEventOut>;

package/ts/zod/schedules.ts

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

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,50 @@
+/**
+ * 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(),
+			vector_store_ids: z.array(z.string()).optional(),
+			auto_memory: z.boolean().optional(),
+			memory_consolidation: 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>;