@to11ai/sdk 0.1.2 → 0.3.0

package/src/prompts/types.ts

@@ -1,73 +1,35 @@
-/**
- * Per-row pointer carried on 422 validation envelopes.
- *
- * The published `@to11ai/sdk` package does NOT depend on the internal
- * `@to11/shared-kernel` workspace package (it would pull workspace-only
- * types into a public npm release). The shape below is therefore
- * declared identically to `RowError` in
- * `packages/shared-kernel/src/schemas/api-schemas.ts` — keep them in
- * lockstep when adding new fields.
- *
- * 422 responses for prompt-version writes carry an optional
- * `error.rowErrors` array — one entry per failing field. Each row
- * carries:
- *
- *   - `path`: JSON-pointer-equivalent array, e.g.
- *     `["messages", 3, "name"]`.
- *   - `code`: stable identifier such as `tool_name_invalid_charset`
- *     or `messages_empty` — see the platform spec for the full set.
- *   - `message`: a human-readable summary.
- *
- * SDK consumers can detect the structured shape by inspecting
- * `error.code === "validation_failed"` and walking `error.rowErrors`
- * (always optional; absent on non-validation 422s).
- */
+import type {
+	ProjectPromptLabel as GenProjectPromptLabel,
+	ProjectPromptLabelUsage as GenProjectPromptLabelUsage,
+	Prompt as GenPrompt,
+	PromptLabelEvent as GenPromptLabelEvent,
+	PromptLabelPointer as GenPromptLabelPointer,
+	PromptVersion as GenPromptVersion,
+	RenderedChatPrompt as GenRenderedChatPrompt,
+	RenderedPrompt as GenRenderedPrompt,
+	ResolvedPrompt as GenResolvedPrompt,
+} from "../generated/types.gen";
+
 export interface RowError {
 	path: ReadonlyArray<string | number>;
 	code: string;
 	message: string;
 }
 
-// ─── Shared primitives ─────────────────────────────────────────────────────
-
-export type PromptStatus = "active" | "archived";
-export type PromptFormat = "text" | "chat";
+export type Prompt = GenPrompt;
+export type PromptStatus = Prompt["status"];
+export type PromptVersion = GenPromptVersion;
+export type PromptFormat = PromptVersion["format"];
+export type PromptLabelPointer = GenPromptLabelPointer;
 
-/**
- * Roles supported by `TextChatMessage`.
- *
- * V1 server contract: `developer` is accepted at the wire boundary and
- * rendered as `user` in `:resolve` responses. The literal is preserved
- * here so SDK consumers can author developer-tagged messages today and
- * V2 can flip the rendered role without a wire-level break.
- */
 export type TextChatRole = "system" | "user" | "assistant" | "developer";
 
-/**
- * Text-style chat message. Carries a Liquid template body in `content`.
- *
- * `disabled` skips the message at render time but preserves it through
- * edit / list / get round-trips so authors can toggle messages without
- * losing them.
- */
 export interface TextChatMessage {
 	role: TextChatRole;
 	content: string;
 	disabled?: boolean;
 }
 
-/**
- * Tool-call chat message. Structurally distinct from text messages: it
- * carries `name` / `description` / `parameters` instead of `content`.
- *
- * - `name`: 1..200 chars, matches the tool name the gateway exposes to
- *   providers.
- * - `description`: optional human-readable summary surfaced in the
- *   provider's tool-choice UI.
- * - `parameters`: JSON Schema (an object) describing the tool's
- *   arguments. Not validated against the JSON Schema meta-schema at
- *   edit time — the gateway is the source of truth.
- */
 export interface ToolChatMessage {
 	role: "tool";
 	name: string;
@@ -76,85 +38,16 @@ export interface ToolChatMessage {
 	disabled?: boolean;
 }
 
-/**
- * Discriminated union of text and tool chat messages.
- *
- * Legacy `{role: "tool", content: "..."}` rows are auto-upgraded by the
- * server on read: they decode as `{role: "tool", name: "(unnamed)",
- * description: <legacy content>, parameters: {}}`. Writes always emit
- * the new shape.
- */
 export type ChatMessage = TextChatMessage | ToolChatMessage;
 
-// ─── Prompt ────────────────────────────────────────────────────────────────
-
-export interface Prompt {
-	id: string;
-	projectId: string;
-	name: string;
-	slug: string;
-	description: string | null;
-	tags: string[];
-	status: PromptStatus;
-	createdByUserId: string;
-	createdAt: string;
-	updatedAt: string;
-}
-
-// ─── PromptVersion ─────────────────────────────────────────────────────────
-
-export interface PromptVersion {
-	id: string;
-	promptId: string;
-	version: number;
-	format: PromptFormat;
-	templateJson: unknown;
-	variablesSchema: unknown;
-	modelConfig: unknown;
-	changelog: string | null;
-	createdByUserId: string;
-	createdAt: string;
-}
-
-// ─── PromptLabelPointer ────────────────────────────────────────────────────
+export type RenderedChatMessage = GenRenderedChatPrompt["messages"][number];
 
-export interface PromptLabelPointer {
-	promptId: string;
-	label: string;
-	versionId: string;
-	updatedByUserId: string;
-	updatedAt: string;
-}
-
-// ─── ResolvedPrompt ────────────────────────────────────────────────────────
-
-/**
- * A single message in a rendered chat prompt returned by `:resolve`.
- *
- * Always carries a flat `{role, content}` shape — even tool/developer
- * messages, since the server normalises them at render time
- * (V1 contract: tool messages are filtered, developer is mapped to user).
- * The `role` literal stays wide so V2 changes are wire-compatible.
- */
-export interface RenderedChatMessage {
-	role: "system" | "user" | "assistant" | "developer" | "tool";
-	content: string;
-}
-
-export type RenderedPrompt =
-	| { format: "text"; text: string }
-	| { format: "chat"; messages: RenderedChatMessage[] };
-
-export interface ResolvedPrompt {
-	promptId: string;
-	versionId: string;
-	version: number;
-	labels: string[];
-	contentHash: string;
-	rendered: RenderedPrompt;
-}
+export type RenderedPrompt = GenRenderedPrompt;
 
-// ─── Pagination ────────────────────────────────────────────────────────────
+export type ResolvedPrompt = Pick<
+	GenResolvedPrompt,
+	"promptId" | "versionId" | "version" | "labels" | "contentHash" | "rendered"
+>;
 
 export interface PaginationInfo {
 	page: number;
@@ -168,8 +61,6 @@ export interface PaginatedResult<T> {
 	pagination: PaginationInfo;
 }
 
-// ─── Input types ──────────────────────────────────────────────────────────
-
 export interface CreatePromptInput {
 	projectId: string;
 	name: string;
@@ -180,8 +71,6 @@ export interface CreatePromptInput {
 
 export type CreatePromptResult = Prompt;
 
-// ─────────────────────────────────────────────────────────────────────────
-
 export interface ListPromptsInput {
 	projectId: string;
 	status?: PromptStatus;
@@ -193,8 +82,6 @@ export interface ListPromptsInput {
 
 export type ListPromptsResult = Prompt;
 
-// ─────────────────────────────────────────────────────────────────────────
-
 export interface GetPromptInput {
 	projectId: string;
 	promptId: string;
@@ -202,8 +89,6 @@ export interface GetPromptInput {
 
 export type GetPromptResult = Prompt;
 
-// ─────────────────────────────────────────────────────────────────────────
-
 export interface UpdatePromptInput {
 	projectId: string;
 	promptId: string;
@@ -214,8 +99,6 @@ export interface UpdatePromptInput {
 
 export type UpdatePromptResult = Prompt;
 
-// ─────────────────────────────────────────────────────────────────────────
-
 export interface ArchivePromptInput {
 	projectId: string;
 	promptId: string;
@@ -223,8 +106,6 @@ export interface ArchivePromptInput {
 
 export type ArchivePromptResult = Prompt;
 
-// ─────────────────────────────────────────────────────────────────────────
-
 export interface CreatePromptVersionInput {
 	projectId: string;
 	promptId: string;
@@ -237,8 +118,6 @@ export interface CreatePromptVersionInput {
 
 export type CreatePromptVersionResult = PromptVersion;
 
-// ─────────────────────────────────────────────────────────────────────────
-
 export interface ListPromptVersionsInput {
 	projectId: string;
 	promptId: string;
@@ -246,8 +125,6 @@ export interface ListPromptVersionsInput {
 
 export type ListPromptVersionsResult = PromptVersion[];
 
-// ─────────────────────────────────────────────────────────────────────────
-
 export interface GetPromptVersionInput {
 	projectId: string;
 	promptId: string;
@@ -256,8 +133,6 @@ export interface GetPromptVersionInput {
 
 export type GetPromptVersionResult = PromptVersion;
 
-// ─────────────────────────────────────────────────────────────────────────
-
 export interface MovePromptLabelInput {
 	projectId: string;
 	promptId: string;
@@ -268,8 +143,6 @@ export interface MovePromptLabelInput {
 
 export type MovePromptLabelResult = PromptLabelPointer;
 
-// ─────────────────────────────────────────────────────────────────────────
-
 export interface ListPromptLabelsInput {
 	projectId: string;
 	promptId: string;
@@ -277,8 +150,6 @@ export interface ListPromptLabelsInput {
 
 export type ListPromptLabelsResult = PromptLabelPointer[];
 
-// ─────────────────────────────────────────────────────────────────────────
-
 export interface ResolvePromptInput {
 	projectId: string;
 	slug: string;
@@ -292,84 +163,46 @@ export interface ResolvePromptInput {
 
 export type ResolvePromptResult = ResolvedPrompt;
 
-// ─── Project label registry (TO11-666 / phase 2) ───────────────────────────
-//
-// Wire shapes mirror the API's `ProjectPromptLabel`, `ProjectPromptLabelUsage`,
-// and `PromptLabelEvent` schemas. The palette token enum is kept in lockstep
-// with the DB CHECK constraint introduced in the prompt-label-registry
-// migration.
-
-/** Palette token assigned to a project label for UI rendering. */
-export type PaletteToken =
-	| "accent"
-	| "red"
-	| "orange"
-	| "amber"
-	| "green"
-	| "teal"
-	| "blue"
-	| "indigo"
-	| "purple"
-	| "pink";
-
-/**
- * Project-level label registry entry.
- *
- * System labels (`isSystem: true`) cannot be archived. `archivedAt` is
- * non-null for soft-deleted entries; the list endpoint excludes archived
- * entries by default — pass `includeArchived: true` if the call site needs
- * them (e.g. admin / history affordances).
- */
-export interface ProjectPromptLabel {
-	projectId: string;
-	label: string;
-	isSystem: boolean;
-	isDefault: boolean;
-	description: string | null;
-	displayColor: PaletteToken;
-	createdByUserId: string;
-	createdAt: string;
-	updatedAt: string;
-	archivedAt: string | null;
-}
+export const ENV_SLUG_REGEX = /^[a-z0-9-]{1,63}$/;
+
+export type BlockRenderRecord = Record<string, "rendered" | "dimmed">;
 
-/**
- * A single prompt currently pointed at by a given project label.
- *
- * Returned by `GET /v1/projects/:projectId/prompt-labels/:label/usages`.
- * `updatedAt` / `updatedByUserId` carry the last-move metadata so the UI
- * can render a "moved 3 days ago by …" affordance without a second
- * roundtrip.
- */
-export interface ProjectPromptLabelUsage {
+export type PromptContext = Record<string, string | number | boolean>;
+
+export interface FetchedPrompt {
+	messages: RenderedChatMessage[];
+	version: number;
+	releaseId: string | null;
+	variantName?: string;
+	blockRenderRecord: BlockRenderRecord;
 	promptId: string;
-	promptSlug: string;
-	promptName: string;
 	versionId: string;
-	version: number;
-	updatedAt: string;
-	updatedByUserId: string;
+	contentHash: string;
+	labels: string[];
+	rendered: RenderedPrompt;
 }
 
-/**
- * An immutable history row for a single label movement.
- *
- * `fromVersionId` is `null` for the first time the label is pointed at a
- * version (no prior pointer). `reason` is the optional caller-supplied
- * audit string.
- */
-export interface PromptLabelEvent {
-	id: string;
-	promptId: string;
-	label: string;
-	fromVersionId: string | null;
-	toVersionId: string;
-	movedByUserId: string;
-	movedAt: string;
-	reason: string | null;
+export type ResolvedPromptEnvelope = GenResolvedPrompt & {
+	/** Active release strategy. Used to decide weighted-no-subject cache bypass (D8). */
+	strategy?: "single" | "weighted";
+};
+
+export interface FetchPromptOptions {
+	env?: string;
+	context?: PromptContext;
+	subject?: string;
+	variables?: Record<string, unknown>;
+	cache?: boolean;
+	fallback?: ResolvedPrompt | FetchedPrompt;
 }
 
-// ─── Project label registry inputs ─────────────────────────────────────────
+export type PaletteToken = ProjectPromptLabel["displayColor"];
+
+export type ProjectPromptLabel = GenProjectPromptLabel;
+
+export type ProjectPromptLabelUsage = GenProjectPromptLabelUsage;
+
+export type PromptLabelEvent = GenPromptLabelEvent;
 
 export interface ListProjectPromptLabelsInput {
 	projectId: string;
@@ -411,12 +244,6 @@ export interface DeleteProjectPromptLabelInput {
 	label: string;
 }
 
-/**
- * The DELETE endpoint returns 200 with the archived row (mirrors the
- * `archivePrompt` pattern — call sites can show "archived just now"
- * without a follow-up GET). System labels (`isSystem: true`) cannot be
- * archived; the server returns 409 `PROJECT_LABEL_SYSTEM_NOT_DELETABLE`.
- */
 export type DeleteProjectPromptLabelResult = ProjectPromptLabel;
 
 export interface ListProjectPromptLabelUsagesInput {
@@ -426,14 +253,6 @@ export interface ListProjectPromptLabelUsagesInput {
 
 export type ListProjectPromptLabelUsagesResult = ProjectPromptLabelUsage[];
 
-// ─── Label event history (TO11-668 / phase 4) ──────────────────────────────
-//
-// One polymorphic SDK method `listLabelEvents` covers all three URL shapes
-// the server exposes. The `scope` discriminator selects between:
-//   - `"label"`   → `/v1/projects/:p/prompts/:pp/labels/:l/events`
-//   - `"prompt"`  → `/v1/projects/:p/prompts/:pp/label-events`
-//   - `"project"` → `/v1/projects/:p/label-events`
-
 export type ListLabelEventsInput =
 	| {
 			scope: "label";

package/src/routingRules/resource.ts

@@ -1,3 +1,5 @@
+import { z } from "zod";
+import { zRuleRelease, zRuleVersion } from "../generated/zod.gen";
 import type { ApiEnvelope, Transport } from "../transport";
 import type {
 	CreateRuleVersionInput,
@@ -118,6 +120,9 @@ export class RoutingRuleVersionResource {
 		const envelope = await this.transport.request<GetRuleVersionResult>(
 			"GET",
 			versionPath(input.projectId, input.ruleId, input.versionId),
+			{
+				decode: (data) => zRuleVersion.parse(data) as GetRuleVersionResult,
+			},
 		);
 		return unwrap(envelope);
 	}
@@ -163,7 +168,11 @@ export class RoutingRuleReleaseResource {
 		const envelope = await this.transport.request<ListRuleReleasesResult>(
 			"GET",
 			path,
-			{ query },
+			{
+				query,
+				decode: (data) =>
+					z.array(zRuleRelease).parse(data) as ListRuleReleasesResult,
+			},
 		);
 		return unwrap(envelope);
 	}

package/src/routingRules/types.ts

@@ -1,118 +1,22 @@
-// ---------------------------------------------------------------------------
-// Routing Rule Versions + Env Pointers wire types (TO11-795 / llm-routing §S17).
-// ---------------------------------------------------------------------------
-// Spec: docs/product-specs/2026-05-14-llm-routing-env-pointers.md
-// Plan: docs/exec-plans/active/2026-05-14-llm-routing-env-pointers-plan.md §S17
-//
-// Hand-rolled TS mirrors of the Effect Schema types defined in
-// `apps/api/src/domains/llm-routing/model/rule-version.ts` and the wire
-// schemas exported from `apps/api/src/infrastructure/http/routes/rule-versions.ts`.
-// The published `@to11ai/sdk` package intentionally does NOT depend on the
-// internal `@to11/api` workspace package — keep these in lockstep with the
-// API model when adding fields.
-//
-// Credential invariant (per spec §"Data model"): `snapshotJson` MUST NOT
-// carry plaintext credentials. The wire shape declares it as `unknown` to
-// mirror the domain — provider references live inside `modelBindings[]` and
-// the gateway resolves credentials lazily at request time.
-// ---------------------------------------------------------------------------
-
-// ─── Snapshot shape ────────────────────────────────────────────────────────
-
-/**
- * Reference to a provider config bound to a specific environment. Mirrors
- * `RuleProviderRef` in the API domain model. `envSlug` is optional — when
- * omitted, the gateway falls back to the project's `is_gateway_fallback`
- * environment.
- */
-export interface RuleProviderRef {
-	providerId: string;
-	envSlug?: string;
-}
+import type {
+	RuleModelBinding as GenRuleModelBinding,
+	RuleProviderRef as GenRuleProviderRef,
+	RuleRelease as GenRuleRelease,
+	RuleReleaseWeight as GenRuleReleaseWeight,
+	RuleSnapshot as GenRuleSnapshot,
+	RuleVersion as GenRuleVersion,
+} from "../generated/types.gen";
 
-/**
- * Per-variant model binding inside a rule snapshot. Identifies which
- * `(provider, model)` pair serves a strategy variant; the gateway resolves
- * the actual credential at request time. `weight` is intentionally
- * permissive (0..100 in v1) so weighted/experimental strategies can evolve
- * without a SDK churn.
- */
-export interface RuleModelBinding {
-	modelId: string;
-	provider: RuleProviderRef;
-	weight?: number;
-}
+export type RuleProviderRef = GenRuleProviderRef;
 
-export type RuleStrategy = "single" | "weighted" | "fallback" | "experiment";
-
-/**
- * Frozen rule snapshot — the JSONB payload stored in
- * `rule_versions.snapshot_json`. Mirrors the API domain `RuleSnapshot`:
- *
- *   * `alias`        — optional `function::<alias>` indirection (S1).
- *   * `strategy`     — `single`, `weighted`, `fallback`, `experiment`.
- *   * `endpoint`     — `chat`, `embeddings`, …
- *   * `variants[]` | `steps[]` | `chain[]` — strategy-shape arrays.
- *   * `when`         — optional condition AST that gates the rule.
- *   * `retry`        — optional `{ maxRetries?, backoffBaseMs?, retryableStatusCodes? }`.
- *   * `modelBindings[]` — which `(providerId, modelId, envSlug)` serves each variant.
- *   * `providerRefs[]` — flat denormalized list of referenced providers.
- *
- * No credential field exists; the gateway resolves credentials lazily from
- * the per-env `routing_snapshots` ciphertext.
- */
-export interface RuleSnapshot {
-	alias?: string;
-	strategy: RuleStrategy | string;
-	endpoint: string;
-	variants?: unknown[];
-	steps?: unknown[];
-	chain?: unknown[];
-	when?: unknown;
-	retry?: {
-		maxRetries?: number;
-		backoffBaseMs?: number;
-		retryableStatusCodes?: number[];
-	};
-	modelBindings?: RuleModelBinding[];
-	providerRefs?: RuleProviderRef[];
-}
+export type RuleModelBinding = GenRuleModelBinding;
 
-// ─── Persisted shapes ──────────────────────────────────────────────────────
-
-/**
- * The persisted form of a rule version row as returned by
- * `GET /v1/projects/:projectId/routing/rules/:ruleId/versions/:versionId`.
- *
- * `version` is monotonic per `ruleId` — the server allocates it inside a
- * `SELECT MAX … FOR UPDATE` transaction. `snapshotJson` is typed as
- * `unknown` to mirror the API contract (the storage path persists JSONB
- * verbatim); callers that need the typed shape should cast through
- * `RuleSnapshot`.
- */
-export interface RuleVersion {
-	id: string;
-	ruleId: string;
-	version: number;
-	snapshotJson: unknown;
-	description: string | null;
-	createdBy: string;
-	/** ISO-8601 timestamp. */
-	createdAt: string;
-}
+export type RuleStrategy = GenRuleSnapshot["strategy"];
+
+export type RuleSnapshot = GenRuleSnapshot;
+
+export type RuleVersion = GenRuleVersion;
 
-// ─── Inputs ─────────────────────────────────────────────────────────────────
-
-/**
- * Wire input accepted by
- * `POST /v1/projects/:p/routing/rules/:ruleId/versions`. Requires the
- * `routing:write` capability.
- *
- * `snapshot` is the cleartext snapshot JSON the gateway uses to resolve
- * runtime traffic — stored verbatim in `rule_versions.snapshot_json`.
- * `description` is an optional commit message; the API surfaces it on the
- * audit timeline.
- */
 export interface CreateRuleVersionInput {
 	projectId: string;
 	ruleId: string;
@@ -122,22 +26,10 @@ export interface CreateRuleVersionInput {
 
 export type CreateRuleVersionResult = RuleVersion;
 
-/**
- * Cursor-paginated list input. `cursor` is the `version` number BELOW which
- * to fetch (keyset pagination — pass the last item's `version` to continue).
- * `limit` is clamped server-side to `MAX_LIST_LIMIT` (200 at the time of
- * writing); default is 50.
- */
 export interface ListRuleVersionsInput {
 	projectId: string;
 	ruleId: string;
-	/**
-	 * The `version` number BELOW which to fetch (the route uses a keyset
-	 * `WHERE version < cursor` clause and returns versions in `version DESC`
-	 * order). Omit for the first page.
-	 */
 	cursor?: number;
-	/** Page size. Server clamps to `[1, MAX_LIST_LIMIT]`. */
 	limit?: number;
 }
 
@@ -151,43 +43,17 @@ export interface GetRuleVersionInput {
 
 export type GetRuleVersionResult = RuleVersion;
 
-// ─── Releases (S2 / TO11-1009) ──────────────────────────────────────────────
+export type RuleReleaseStrategy = GenRuleRelease["strategy"];
 
-export type RuleReleaseStrategy = "single" | "weighted";
+export type RuleReleaseChangeKind = GenRuleRelease["changeKind"];
 
-export type RuleReleaseChangeKind =
-	| "release_initial"
-	| "release_promoted"
-	| "release_rolled_back"
-	| "release_weight_changed";
+export type RuleReleaseApprovalStatus = GenRuleRelease["approvalStatus"];
 
-export type RuleReleaseApprovalStatus = "committed" | "pending" | "rejected";
+export type RuleReleaseActorType = GenRuleRelease["actorType"];
 
-export type RuleReleaseActorType = "user" | "api_key" | "worker";
+export type RuleReleaseWeight = GenRuleReleaseWeight;
 
-export interface RuleReleaseWeight {
-	versionId: string;
-	weight: number;
-}
-
-export interface RuleRelease {
-	id: string;
-	ruleId: string;
-	environmentId: string;
-	envSlug: string;
-	strategy: RuleReleaseStrategy;
-	versionId: string | null;
-	weights: RuleReleaseWeight[] | null;
-	changeKind: RuleReleaseChangeKind;
-	priorReleaseId: string | null;
-	actorId: string;
-	actorType: RuleReleaseActorType;
-	reason: string | null;
-	approvalStatus: RuleReleaseApprovalStatus;
-	activeFrom: string | null;
-	activeTo: string | null;
-	createdAt: string;
-}
+export type RuleRelease = GenRuleRelease;
 
 export interface SetRuleReleaseInput {
 	projectId: string;