@to11ai/sdk 0.1.2 → 0.2.0

package/src/projectEnvironments/resource.ts

@@ -9,6 +9,8 @@
 // envelope, and returns the resource shape verbatim.
 // ---------------------------------------------------------------------------
 
+import { z } from "zod";
+import { zProjectEnvironment } from "../generated/zod.gen";
 import type { ApiEnvelope, Transport } from "../transport";
 import type {
 	ArchiveProjectEnvironmentInput,
@@ -87,6 +89,10 @@ export class ProjectEnvironmentResource {
 					query: input.includeArchived
 						? { includeArchived: "true" }
 						: undefined,
+					decode: (data) =>
+						z
+							.array(zProjectEnvironment)
+							.parse(data) as ListProjectEnvironmentsResult,
 				},
 			);
 		return unwrap(envelope);
@@ -100,6 +106,10 @@ export class ProjectEnvironmentResource {
 		const envelope = await this.transport.request<GetProjectEnvironmentResult>(
 			"GET",
 			projectEnvironmentPath(input.projectId, input.slug),
+			{
+				decode: (data) =>
+					zProjectEnvironment.parse(data) as GetProjectEnvironmentResult,
+			},
 		);
 		return unwrap(envelope);
 	}

package/src/projectEnvironments/types.ts

@@ -1,82 +1,18 @@
-// ---------------------------------------------------------------------------
-// Project Environments wire types (TO11-793 / env-registry §S21).
-// ---------------------------------------------------------------------------
-// Spec: docs/product-specs/2026-05-14-environments-registry.md
-// Plan: docs/exec-plans/active/2026-05-14-env-registry-plan.md §S21
-//
-// Hand-rolled TS mirrors of the Effect Schema types defined in
-// `apps/api/src/domains/tenancy/projects/model/project-environment.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.
-// ---------------------------------------------------------------------------
+import type {
+	ArchiveProjectEnvironmentResult as GenArchiveProjectEnvironmentResult,
+	LivePointerCounts as GenLivePointerCounts,
+	ProjectEnvironment as GenProjectEnvironment,
+} from "../generated/types.gen";
 
-// ─── Wire shape ─────────────────────────────────────────────────────────────
+export type ProjectEnvironment = GenProjectEnvironment;
 
-/**
- * Project-scoped environment row as returned by
- * `GET /v1/projects/:projectId/environments/:slug`.
- *
- * Notes:
- *  - `isSystem: true` for the seeded `prod` / `staging` rows. Those rows
- *    cannot be renamed, archived, or have their `slug`/`isSystem` mutated.
- *  - `isGatewayFallback: true` marks the env the gateway routes to when no
- *    `x-to11-env` header is supplied. At most one env per project may carry
- *    this flag; clearing the only fallback is rejected with 409
- *    `CANNOT_CLEAR_ONLY_GATEWAY_FALLBACK`.
- *  - `archivedAt` is `null` for live envs and an ISO-8601 timestamp for
- *    soft-archived ones.
- */
-export interface ProjectEnvironment {
-	id: string;
-	projectId: string;
-	slug: string;
-	name: string;
-	color: string | null;
-	description: string | null;
-	isPointer: boolean;
-	requiresApproval: boolean;
-	isDefault: boolean;
-	isGatewayFallback: boolean;
-	sortOrder: number;
-	isSystem: boolean;
-	archivedAt: string | null;
-	createdBy: string;
-	updatedBy: string;
-	createdAt: string;
-	updatedAt: string;
-}
-
-/**
- * Pointer-count payload attached to archive responses. `prompts` is real
- * today; `rules` / `providers` are 0 in v1 (reserved for Wave 6+ specs to
- * keep the response shape stable when those domains land).
- */
-export interface LivePointerCounts {
-	prompts: number;
-	rules: number;
-	providers: number;
-}
-
-/**
- * Response body for `POST /v1/projects/:projectId/environments/:slug/archive`.
- * Carries the soft-archived environment plus the count of live pointers
- * cascade-cleared by the archive operation (informational, for the
- * confirmation modal in the web UI).
- */
-export interface ArchiveProjectEnvironmentResult {
-	environment: ProjectEnvironment;
-	livePointerCounts: LivePointerCounts;
-}
+export type LivePointerCounts = GenLivePointerCounts;
 
-// ─── Inputs ─────────────────────────────────────────────────────────────────
+export type ArchiveProjectEnvironmentResult =
+	GenArchiveProjectEnvironmentResult;
 
 export interface ListProjectEnvironmentsInput {
 	projectId: string;
-	/**
-	 * When `true`, the response includes archived envs (those with a
-	 * non-null `archivedAt`). Default behavior excludes them.
-	 */
 	includeArchived?: boolean;
 }
 
@@ -89,15 +25,6 @@ export interface GetProjectEnvironmentInput {
 
 export type GetProjectEnvironmentResult = ProjectEnvironment;
 
-/**
- * Create input — must specify a unique `slug` matching lowercase-kebab
- * (a-z, 0-9, hyphen, 1..63 chars). Reserved system slugs (`prod`,
- * `staging`) are rejected by the API with `ENVIRONMENT_SLUG_TAKEN`.
- *
- * Setting `isGatewayFallback: true` here additionally requires the
- * `project:manage_default_environment` capability; the create use case
- * atomically clears the flag on any other env in the same project.
- */
 export interface CreateProjectEnvironmentInput {
 	projectId: string;
 	slug: string;
@@ -113,15 +40,6 @@ export interface CreateProjectEnvironmentInput {
 
 export type CreateProjectEnvironmentResult = ProjectEnvironment;
 
-/**
- * PATCH input — every field is optional. `slug` rename triggers a 7-day
- * alias row server-side. System envs (`isSystem: true`) reject `slug`,
- * `isSystem`, and other immutable-field mutations with
- * `SYSTEM_ENV_IMMUTABLE`.
- *
- * As with `create`, mutating `isGatewayFallback` requires the additional
- * `project:manage_default_environment` capability.
- */
 export interface UpdateProjectEnvironmentInput {
 	projectId: string;
 	slug: string;

package/src/prompts/cache.ts

@@ -1,4 +1,4 @@
-import type { ResolvedPrompt } from "./types";
+import type { FetchedPrompt, PromptContext, ResolvedPrompt } from "./types";
 
 export interface CacheConfig {
 	/** Time-to-live in seconds. Default: 300 (5 minutes) */
@@ -7,8 +7,14 @@ export interface CacheConfig {
 	maxEntries?: number;
 }
 
+/**
+ * The cache stores either a legacy `resolve()` result or an enriched
+ * `fetch()` result. Both are JSON-cloneable; the cache is shape-agnostic.
+ */
+export type CacheableResolved = ResolvedPrompt | FetchedPrompt;
+
 interface CacheEntry {
-	value: ResolvedPrompt;
+	value: CacheableResolved;
 	expiresAt: number;
 }
 
@@ -37,6 +43,35 @@ export function buildCacheKey(
 	return `${JSON.stringify(projectId)}|${JSON.stringify(slug)}|${JSON.stringify(sortedLabels)}|${JSON.stringify(varsPart)}`;
 }
 
+/**
+ * Build a cache key for an env-aware `fetch()` call.
+ *
+ * Folds in `env`, `context`, and `subject` ON TOP of the base
+ * project/slug/labels/variables key so two calls that differ only by
+ * env/context/subject do not return a stale cross-env / cross-cohort hit
+ * (spec §3 "Caching key changes"). The env slug is also forwarded as the
+ * single resolution label (env→label mapping, correction #3), so it appears
+ * in the `labels` segment too; including it explicitly here keeps the key
+ * unambiguous and self-documenting.
+ *
+ * `subject` participates in the key so a `subject`-keyed weighted assignment
+ * caches as the same deterministic variant on repeat (D8); the
+ * weighted-no-subject bypass is handled in the resource, not here.
+ */
+export function buildFetchCacheKey(
+	projectId: string,
+	slug: string,
+	env: string,
+	context?: PromptContext,
+	subject?: string,
+	variables?: Record<string, unknown>,
+): string {
+	const base = buildCacheKey(projectId, slug, [env], variables);
+	const ctxPart =
+		context !== undefined ? JSON.stringify(sortObjectKeys(context)) : null;
+	return `fetch|${base}|${JSON.stringify(env)}|${JSON.stringify(ctxPart)}|${JSON.stringify(subject ?? null)}`;
+}
+
 function sortObjectKeys(obj: unknown): unknown {
 	if (obj === null || typeof obj !== "object") return obj;
 	if (Array.isArray(obj)) return obj.map(sortObjectKeys);
@@ -65,7 +100,7 @@ export class PromptCache {
 		this.store = new Map();
 	}
 
-	get(key: string): ResolvedPrompt | undefined {
+	get(key: string): CacheableResolved | undefined {
 		const entry = this.store.get(key);
 		if (!entry) return undefined;
 
@@ -81,7 +116,7 @@ export class PromptCache {
 		return entry.value;
 	}
 
-	set(key: string, value: ResolvedPrompt): void {
+	set(key: string, value: CacheableResolved): void {
 		// maxEntries: 0 (or negative) means caching is disabled — drop the entry.
 		if (this.maxEntries <= 0) {
 			return;

package/src/prompts/resource.ts

@@ -1,7 +1,9 @@
-import { To11aiNetworkError } from "../errors";
+import { z } from "zod";
+import { EnvNotFoundError, To11aiNetworkError } from "../errors";
+import { zResolvedPrompt } from "../generated/zod.gen";
 import type { ApiEnvelope, Transport } from "../transport";
 import type { CacheConfig } from "./cache";
-import { buildCacheKey, PromptCache } from "./cache";
+import { buildCacheKey, buildFetchCacheKey, PromptCache } from "./cache";
 import type {
 	ArchivePromptInput,
 	ArchivePromptResult,
@@ -13,6 +15,8 @@ import type {
 	CreatePromptVersionResult,
 	DeleteProjectPromptLabelInput,
 	DeleteProjectPromptLabelResult,
+	FetchedPrompt,
+	FetchPromptOptions,
 	GetProjectPromptLabelInput,
 	GetProjectPromptLabelResult,
 	GetPromptInput,
@@ -34,6 +38,10 @@ import type {
 	MovePromptLabelInput,
 	MovePromptLabelResult,
 	PaginatedResult,
+	RenderedChatMessage,
+	RenderedPrompt,
+	ResolvedPrompt,
+	ResolvedPromptEnvelope,
 	ResolvePromptInput,
 	ResolvePromptResult,
 	UpdateProjectPromptLabelInput,
@@ -41,12 +49,14 @@ import type {
 	UpdatePromptInput,
 	UpdatePromptResult,
 } from "./types";
+import { ENV_SLUG_REGEX } from "./types";
 
 // Re-export CacheConfig so callers can import from this module
 export type { CacheConfig } from "./cache";
 export type {
 	ArchivePromptInput,
 	ArchivePromptResult,
+	BlockRenderRecord,
 	ChatMessage,
 	CreateProjectPromptLabelInput,
 	CreateProjectPromptLabelResult,
@@ -56,6 +66,8 @@ export type {
 	CreatePromptVersionResult,
 	DeleteProjectPromptLabelInput,
 	DeleteProjectPromptLabelResult,
+	FetchedPrompt,
+	FetchPromptOptions,
 	GetProjectPromptLabelInput,
 	GetProjectPromptLabelResult,
 	GetPromptInput,
@@ -82,6 +94,7 @@ export type {
 	ProjectPromptLabel,
 	ProjectPromptLabelUsage,
 	Prompt,
+	PromptContext,
 	PromptFormat,
 	PromptLabelEvent,
 	PromptLabelPointer,
@@ -90,6 +103,7 @@ export type {
 	RenderedChatMessage,
 	RenderedPrompt,
 	ResolvedPrompt,
+	ResolvedPromptEnvelope,
 	ResolvePromptInput,
 	ResolvePromptResult,
 	RowError,
@@ -102,6 +116,19 @@ export type {
 	UpdatePromptResult,
 } from "./types";
 
+const zResolvedPromptLegacy = zResolvedPrompt.pick({
+	promptId: true,
+	versionId: true,
+	version: true,
+	labels: true,
+	contentHash: true,
+	rendered: true,
+});
+
+const zResolvedPromptEnvelope = zResolvedPrompt
+	.partial({ releaseId: true })
+	.extend({ strategy: z.enum(["single", "weighted"]).optional() });
+
 function unwrap<T>(envelope: ApiEnvelope<T>): T {
 	if (envelope.data === null || envelope.data === undefined) {
 		throw new Error("API returned success but data is null");
@@ -113,6 +140,75 @@ function getProjectPromptsPath(projectId: string): string {
 	return `/v1/projects/${encodeURIComponent(projectId)}/prompts`;
 }
 
+/**
+ * Project a server `rendered` payload into the `messages` array of the R5
+ * `FetchedPrompt` (D5):
+ *   - `format: "chat"` → the message array directly.
+ *   - `format: "text"` → a single synthesized `{ role: "user", content }`.
+ */
+function renderedToMessages(rendered: RenderedPrompt): RenderedChatMessage[] {
+	if (rendered.format === "chat") {
+		return rendered.messages;
+	}
+	return [{ role: "user", content: rendered.text }];
+}
+
+/**
+ * Normalize the server resolve envelope into the enriched R5 `FetchedPrompt`.
+ *
+ * - `messages` is synthesized from `rendered` via the D5 projection.
+ * - `releaseId` is ALWAYS a key: a string when the server sends one, else
+ *   explicit `null` (R5 `string | null`).
+ * - `variantName` is present IFF the server sent one (i.e. weighted release);
+ *   absent for `single` — never `null`/`""`.
+ * - `blockRenderRecord` defaults to `{}` when the server omitted it.
+ */
+function normalizeResolvedEnvelope(
+	raw: ResolvedPrompt | ResolvedPromptEnvelope,
+): FetchedPrompt {
+	const provenance = raw as ResolvedPromptEnvelope;
+	const result: FetchedPrompt = {
+		messages: renderedToMessages(raw.rendered),
+		version: raw.version,
+		releaseId: provenance.releaseId ?? null,
+		blockRenderRecord: provenance.blockRenderRecord ?? {},
+		promptId: raw.promptId,
+		versionId: raw.versionId,
+		contentHash: raw.contentHash,
+		labels: raw.labels,
+		rendered: raw.rendered,
+	};
+	// Set `variantName` only when it is a non-empty string, so the key is
+	// genuinely absent for `single`-strategy releases (R5: present IFF weighted —
+	// never `null`, never `""`). A `null`/`""` from the wire is normalized to
+	// absent, which also keeps the D8 `variantName !== undefined` weighted
+	// inference honest (Cursor).
+	if (
+		typeof provenance.variantName === "string" &&
+		provenance.variantName.length > 0
+	) {
+		result.variantName = provenance.variantName;
+	}
+	return result;
+}
+
+/**
+ * Lift a caller-supplied offline `fallback` into the enriched `FetchedPrompt`
+ * shape (D7), so `fetch()` returns an identical shape on the online and
+ * offline paths. An already-enriched `FetchedPrompt` is returned as-is; a
+ * legacy `ResolvedPrompt` is lifted (messages synthesized; `releaseId` → its
+ * own value or explicit `null`; `blockRenderRecord` → `{}`; `variantName`
+ * stays absent).
+ */
+function liftFallbackToFetched(
+	fallback: ResolvedPrompt | FetchedPrompt,
+): FetchedPrompt {
+	if ("messages" in fallback) {
+		return structuredClone(fallback);
+	}
+	return normalizeResolvedEnvelope(fallback);
+}
+
 function getProjectPromptPath(projectId: string, promptId: string): string {
 	return `${getProjectPromptsPath(projectId)}/${encodeURIComponent(promptId)}`;
 }
@@ -149,13 +245,35 @@ function buildLabelEventsQuery(input: ListLabelEventsInput): string {
 	return params.toString();
 }
 
+/**
+ * Init-time config for the env-aware `fetch()` surface (TO11-980 / S9).
+ *
+ * `projectId` and `env` come from `createClient`. `projectId` is required for
+ * `fetch()` (it builds the project-scoped resolve path); `env` is the default
+ * serving environment inherited by every `fetch(slug)` call.
+ */
+export interface PromptResourceConfig {
+	/** Project the client is bound to. Required for `fetch()`; validated at createClient. */
+	projectId?: string;
+	/** Default serving env for `fetch()`. Validated against ENV_SLUG_REGEX at createClient. */
+	env?: string;
+}
+
 export class PromptResource {
 	private readonly transport: Transport;
 	private readonly cache: PromptCache;
-
-	constructor(transport: Transport, cacheConfig?: CacheConfig) {
+	private readonly projectId: string | undefined;
+	private readonly env: string | undefined;
+
+	constructor(
+		transport: Transport,
+		cacheConfig?: CacheConfig,
+		config?: PromptResourceConfig,
+	) {
 		this.transport = transport;
 		this.cache = new PromptCache(cacheConfig);
+		this.projectId = config?.projectId;
+		this.env = config?.env;
 	}
 
 	// ─── Create ──────────────────────────────────────────────────────────────
@@ -303,8 +421,138 @@ export class PromptResource {
 		return unwrap(envelope);
 	}
 
+	// ─── Fetch (env-aware resolution, TO11-980 / S9) ──────────────────────────
+
+	/**
+	 * Resolve a prompt for the client's configured `projectId` + `env`
+	 * (Style-A). The ergonomic slug-first surface: env is configured once at
+	 * `createClient` and inherited here, with an optional per-call override.
+	 *
+	 * - **env→label wire mapping (correction #3):** the resolve route is
+	 *   label-based (`/v1/projects/:projectId/prompts:resolve`, body
+	 *   `labels[]`); it does NOT accept a top-level `env` field. The resolved
+	 *   env slug (lowercase-kebab — a valid label name) is therefore sent as
+	 *   the single resolution label: body `{ slug, labels: [env], context?,
+	 *   subject?, variables? }`.
+	 * - **No silent fallback (R4):** if no env is resolvable (none at init AND
+	 *   none per call) this throws `EnvNotFoundError` (`reason.source =
+	 *   "missing"`) CLIENT-side, eagerly, before any transport call.
+	 * - **Cache (D8):** caches `single`-strategy releases and weighted releases
+	 *   WITH a `subject`; BYPASSES the cache for weighted releases with NO
+	 *   `subject` (a uniform-random assignment must not be pinned for the TTL).
+	 *
+	 * Prefer this over the deprecated `resolve()`.
+	 */
+	async fetch(
+		slug: string,
+		options: FetchPromptOptions = {},
+	): Promise<FetchedPrompt> {
+		if (this.projectId === undefined || this.projectId.trim() === "") {
+			throw new Error(
+				"[to11ai/sdk] `prompts.fetch()` requires a `projectId` on the client — pass it to createClient({ projectId, ... }).",
+			);
+		}
+
+		// R2 precedence: per-call env > init-time env. No third source.
+		const env = options.env ?? this.env;
+
+		// R4 / AC4: no env resolvable → throw eagerly, ZERO transport calls.
+		if (env === undefined) {
+			throw EnvNotFoundError.missing();
+		}
+
+		// Validate the RESOLVED env (per-call OR init). createClient validates the
+		// init-time env, but PromptResource has a public constructor that can
+		// bypass createClient, so re-validate here so a malformed env (e.g.
+		// "Prod") never reaches the wire as a resolution label (CodeRabbit).
+		if (!ENV_SLUG_REGEX.test(env)) {
+			throw new Error(
+				`[to11ai/sdk] \`env\` must match ${ENV_SLUG_REGEX} (lowercase-kebab, 1-63 chars). Received: ${JSON.stringify(env)}`,
+			);
+		}
+
+		const {
+			context,
+			subject,
+			variables,
+			cache: useCache = true,
+			fallback,
+		} = options;
+
+		const cacheKey = buildFetchCacheKey(
+			this.projectId,
+			slug,
+			env,
+			context,
+			subject,
+			variables,
+		);
+
+		if (useCache) {
+			const cached = this.cache.get(cacheKey);
+			// Only enriched (fetch) entries are valid hits here; the fetch key
+			// namespace ("fetch|…") never collides with the legacy resolve key.
+			if (cached && "messages" in cached) return structuredClone(cached);
+		}
+
+		// env→label mapping: the env slug is the single resolution label.
+		const body: Record<string, unknown> = { slug, labels: [env] };
+		if (context !== undefined) body.context = context;
+		if (subject !== undefined) body.subject = subject;
+		if (variables !== undefined) body.variables = variables;
+
+		try {
+			const envelope = await this.transport.request<ResolvedPromptEnvelope>(
+				"POST",
+				`${getProjectPromptsPath(this.projectId)}:resolve`,
+				{
+					body,
+					decode: (data) =>
+						zResolvedPromptEnvelope.parse(data) as ResolvedPromptEnvelope,
+				},
+			);
+			const raw = unwrap(envelope);
+			const result = normalizeResolvedEnvelope(raw);
+
+			// D8: bypass the cache for a weighted release with NO subject —
+			// caching a uniform-random assignment would pin one variant for the
+			// whole TTL. Cache `single` releases and `subject`-keyed weighted
+			// releases (deterministic, safe to cache). Weighted-ness is inferred
+			// from `strategy === "weighted"` OR the presence of `variantName`
+			// (which the server stamps iff weighted) — so a result that carries a
+			// variant but omits `strategy` is still correctly bypassed rather than
+			// pinning one random variant for the TTL (Cursor / Greptile).
+			const isWeighted =
+				raw.strategy === "weighted" || result.variantName !== undefined;
+			const cacheable = !(isWeighted && subject === undefined);
+			if (useCache && cacheable) {
+				this.cache.set(cacheKey, structuredClone(result));
+			}
+
+			return result;
+		} catch (err) {
+			// D7: offline fallback is consulted ONLY on a network outage with an
+			// empty cache. A server `ENV_NOT_FOUND` is a typed application error
+			// (not a To11aiNetworkError), so it bypasses this branch. R4's
+			// client-eager throw already happened above the try, so there is no
+			// network error to trigger it on the env-missing path.
+			if (err instanceof To11aiNetworkError && fallback !== undefined) {
+				return liftFallbackToFetched(fallback);
+			}
+			throw err;
+		}
+	}
+
 	// ─── Resolve ──────────────────────────────────────────────────────────────
 
+	/**
+	 * @deprecated Use {@link PromptResource.fetch | `prompts.fetch(slug,
+	 * options?)`} instead. `resolve()` is env-agnostic (no `env` / `context` /
+	 * `subject`, no enriched release/variant provenance, no typed-env errors)
+	 * and is retained only for back-compat. It is NOT subject to the R4
+	 * no-silent-fallback env gate (it has no env concept). New code should
+	 * configure `projectId` + `env` at `createClient` and call `fetch()`.
+	 */
 	async resolve(input: ResolvePromptInput): Promise<ResolvePromptResult> {
 		const {
 			projectId,
@@ -319,7 +567,10 @@ export class PromptResource {
 
 		if (useCache) {
 			const cached = this.cache.get(cacheKey);
-			if (cached) return structuredClone(cached);
+			// The legacy resolve key namespace only ever stores ResolvedPrompt
+			// entries (the fetch namespace is "fetch|…"); the `messages` guard
+			// keeps the static return type as ResolvedPrompt.
+			if (cached && !("messages" in cached)) return structuredClone(cached);
 		}
 
 		try {
@@ -328,6 +579,8 @@ export class PromptResource {
 				`${getProjectPromptsPath(projectId)}:resolve`,
 				{
 					body: { slug, labels, variables },
+					decode: (data) =>
+						zResolvedPromptLegacy.parse(data) as ResolvePromptResult,
 				},
 			);
 			const result = unwrap(envelope);