@to11ai/sdk 0.0.2 → 0.1.1

package/src/errors.ts

@@ -89,3 +89,175 @@ export class To11aiNetworkError extends To11aiError {
 		Object.setPrototypeOf(this, new.target.prototype);
 	}
 }
+
+/**
+ * Thrown when strict-mode rejects a label move for an unregistered label.
+ *
+ * The API returns 422 with `error.code === "PROMPT_LABEL_NOT_REGISTERED"`
+ * when `project.enforce_label_registry = true` and the caller tries to
+ * move a label that has no active entry in the project label registry.
+ * The transport surfaces these as this typed subclass; existing
+ * `instanceof To11aiApiError` blocks still match.
+ *
+ * Note: this extends `To11aiApiError` directly (not `To11aiValidationError`,
+ * which hardcodes status 400). The API returns 422 for this case.
+ */
+export class PromptLabelNotRegisteredError extends To11aiApiError {
+	readonly projectId: string;
+	readonly label: string;
+
+	constructor(
+		message: string,
+		projectId: string,
+		label: string,
+		details?: unknown,
+	) {
+		super(
+			message,
+			422,
+			"PROMPT_LABEL_NOT_REGISTERED",
+			details !== undefined ? details : { projectId, label },
+		);
+		this.name = "PromptLabelNotRegisteredError";
+		this.projectId = projectId;
+		this.label = label;
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+
+	/** Type guard helper — checks `instanceof` (not parent + errorCode string). */
+	static is(err: unknown): err is PromptLabelNotRegisteredError {
+		return err instanceof PromptLabelNotRegisteredError;
+	}
+}
+
+/**
+ * Thrown when a rule cannot be located. Covers two variants of the same
+ * named class (single class so existing `catch (err: RuleNotFoundError)`
+ * blocks match both):
+ *
+ *   * Control-plane variant (404 `RULE_NOT_FOUND`) — `ruleId` is the id
+ *     the caller supplied and that did not exist in the project.
+ *   * Gateway variant (404 `RULE_NOT_FOUND_IN_ENV`) — `model` is the
+ *     `function::<alias>` (or raw model id) the gateway tried to resolve
+ *     and `env` is the request env. `ruleId` is undefined because the
+ *     alias may not resolve to any rule in the env.
+ */
+export class RuleNotFoundError extends To11aiApiError {
+	readonly ruleId: string | undefined;
+	readonly model: string | undefined;
+	readonly env: string | undefined;
+
+	constructor(
+		message: string,
+		errorCode: string,
+		fields: { ruleId?: string; model?: string; env?: string },
+		details?: unknown,
+	) {
+		super(message, 404, errorCode, details);
+		this.name = "RuleNotFoundError";
+		this.ruleId = fields.ruleId;
+		this.model = fields.model;
+		this.env = fields.env;
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+
+	static is(err: unknown): err is RuleNotFoundError {
+		return err instanceof RuleNotFoundError;
+	}
+}
+
+export type NoApplicableRouteReason =
+	| "all_conditions_false"
+	| "all_variants_unreachable"
+	| "all_steps_non_routable";
+
+/**
+ * Thrown when the gateway resolved a rule + version but no variant /
+ * step / chain element was applicable to the request — every condition
+ * was false, every variant unreachable, or every fallback step
+ * non-routable. Surfaces as 422 `NO_APPLICABLE_ROUTE`.
+ */
+export class NoApplicableRouteError extends To11aiApiError {
+	readonly ruleId: string;
+	readonly versionId: string;
+	readonly reason: NoApplicableRouteReason | string;
+
+	constructor(
+		message: string,
+		fields: { ruleId: string; versionId: string; reason: string },
+		details?: unknown,
+	) {
+		super(message, 422, "NO_APPLICABLE_ROUTE", details);
+		this.name = "NoApplicableRouteError";
+		this.ruleId = fields.ruleId;
+		this.versionId = fields.versionId;
+		this.reason = fields.reason;
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+
+	static is(err: unknown): err is NoApplicableRouteError {
+		return err instanceof NoApplicableRouteError;
+	}
+}
+
+/**
+ * Thrown when a rule references a provider that has no activation in the
+ * requested env. Surfaces as 422 `ENV_NOT_ENABLED_FOR_PROVIDER`.
+ */
+export class EnvNotEnabledForProviderError extends To11aiApiError {
+	readonly ruleId: string;
+	readonly envSlug: string;
+	readonly providerId: string;
+
+	constructor(
+		message: string,
+		fields: { ruleId: string; envSlug: string; providerId: string },
+		details?: unknown,
+	) {
+		super(message, 422, "ENV_NOT_ENABLED_FOR_PROVIDER", details);
+		this.name = "EnvNotEnabledForProviderError";
+		this.ruleId = fields.ruleId;
+		this.envSlug = fields.envSlug;
+		this.providerId = fields.providerId;
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+
+	static is(err: unknown): err is EnvNotEnabledForProviderError {
+		return err instanceof EnvNotEnabledForProviderError;
+	}
+}
+
+/**
+ * Thrown when version create rejects the snapshot for a structural
+ * reason — invalid variant params, malformed `when` clause, illegal
+ * weight set, malformed retry policy, … Surfaces with one of the
+ * `INVALID_VARIANT_PARAMS` / `INVALID_VARIANT_WEIGHTS` /
+ * `INVALID_RULE_STRATEGY` / `INVALID_STEP_COUNT` /
+ * `RULE_ENDPOINT_MISMATCH` / `INVALID_WHEN_CLAUSE` /
+ * `INVALID_STRATEGY_VARIANTS` / `INVALID_RETRY_POLICY` error codes
+ * at HTTP status 400 or 422.
+ */
+export class RuleVersionInvalidSnapshotError extends To11aiApiError {
+	readonly field: string | undefined;
+	readonly reason: string | undefined;
+	readonly variantName: string | undefined;
+
+	constructor(
+		message: string,
+		errorCode: string,
+		fields: { field?: string; reason?: string; variantName?: string },
+		details?: unknown,
+		statusCode: number = 400,
+	) {
+		super(message, statusCode, errorCode, details);
+		this.name = "RuleVersionInvalidSnapshotError";
+		this.field = fields.field;
+		this.reason = fields.reason;
+		this.variantName = fields.variantName;
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+
+	static is(err: unknown): err is RuleVersionInvalidSnapshotError {
+		return err instanceof RuleVersionInvalidSnapshotError;
+	}
+}

package/src/gateway.ts

@@ -3,13 +3,32 @@ import type { ResolvedPrompt } from "./prompts/types";
 export interface GatewayAuthOptions {
 	apiKey: string;
 	projectId: string;
+	/**
+	 * Optional environment slug routed via the gateway's `x-to11-env`
+	 * header. When omitted, the gateway falls back to the project's
+	 * `is_gateway_fallback=true` environment; if no fallback exists, the
+	 * request fails with `400 missing_env_no_project_default`.
+	 *
+	 * Slug validation matches the project-environments registry:
+	 * lowercase-kebab (`a-z`, `0-9`, `-`, 1..63 chars). The SDK rejects
+	 * empty / whitespace-only values eagerly so misconfiguration surfaces
+	 * before the request hits the wire.
+	 */
+	env?: string;
 }
 
 /**
  * Build the auth headers required for every request through the to11 gateway.
  *
+ * Includes `x-to11-env: <slug>` when `options.env` is set — see the
+ * environments-registry spec for gateway routing semantics. Empty /
+ * whitespace-only env values throw immediately so caller misconfiguration
+ * is loud.
+ *
  * @example
  * const headers = gatewayAuthHeaders({ apiKey, projectId });
+ * @example
+ * const headers = gatewayAuthHeaders({ apiKey, projectId, env: "staging" });
  */
 export function gatewayAuthHeaders(
 	options: GatewayAuthOptions,
@@ -20,10 +39,19 @@ export function gatewayAuthHeaders(
 	if (options.projectId.trim().length === 0) {
 		throw new Error("[to11ai/sdk] `projectId` must not be empty.");
 	}
-	return {
+	const headers: Record<string, string> = {
 		"x-to11-authorization": `Bearer ${options.apiKey}`,
 		"x-to11-project-id": options.projectId,
 	};
+	if (options.env !== undefined) {
+		if (options.env.trim().length === 0) {
+			throw new Error(
+				"[to11ai/sdk] `env` must not be empty — omit the field to use the project's gateway-fallback environment.",
+			);
+		}
+		headers["x-to11-env"] = options.env;
+	}
+	return headers;
 }
 
 /**

package/src/projectEnvironments/resource.ts

@@ -0,0 +1,220 @@
+// ---------------------------------------------------------------------------
+// ProjectEnvironmentResource — fluent SDK surface for project environments.
+// ---------------------------------------------------------------------------
+// Spec: docs/product-specs/2026-05-14-environments-registry.md
+// Plan: docs/exec-plans/active/2026-05-14-env-registry-plan.md §S21
+//
+// Mirrors `PromptResource` in shape so existing call-site intuition
+// transfers: each method takes a flat input object, unwraps the API
+// envelope, and returns the resource shape verbatim.
+// ---------------------------------------------------------------------------
+
+import type { ApiEnvelope, Transport } from "../transport";
+import type {
+	ArchiveProjectEnvironmentInput,
+	ArchiveProjectEnvironmentResult,
+	CreateProjectEnvironmentInput,
+	CreateProjectEnvironmentResult,
+	GetProjectEnvironmentInput,
+	GetProjectEnvironmentResult,
+	ListProjectEnvironmentsInput,
+	ListProjectEnvironmentsResult,
+	RestoreProjectEnvironmentInput,
+	RestoreProjectEnvironmentResult,
+	UpdateProjectEnvironmentInput,
+	UpdateProjectEnvironmentResult,
+} from "./types";
+
+// Re-export wire types so callers can import from `@to11ai/sdk/projectEnvironments`.
+export type {
+	ArchiveProjectEnvironmentInput,
+	ArchiveProjectEnvironmentResult,
+	CreateProjectEnvironmentInput,
+	CreateProjectEnvironmentResult,
+	GetProjectEnvironmentInput,
+	GetProjectEnvironmentResult,
+	ListProjectEnvironmentsInput,
+	ListProjectEnvironmentsResult,
+	LivePointerCounts,
+	ProjectEnvironment,
+	RestoreProjectEnvironmentInput,
+	RestoreProjectEnvironmentResult,
+	UpdateProjectEnvironmentInput,
+	UpdateProjectEnvironmentResult,
+} from "./types";
+
+function unwrap<T>(envelope: ApiEnvelope<T>): T {
+	if (envelope.data === null || envelope.data === undefined) {
+		throw new Error("API returned success but data is null");
+	}
+	return envelope.data;
+}
+
+function projectEnvironmentsPath(projectId: string): string {
+	return `/v1/projects/${encodeURIComponent(projectId)}/environments`;
+}
+
+function projectEnvironmentPath(projectId: string, slug: string): string {
+	return `${projectEnvironmentsPath(projectId)}/${encodeURIComponent(slug)}`;
+}
+
+/**
+ * SDK resource for `/v1/projects/:projectId/environments`. Constructed by
+ * `createClient` and exposed as `client.projectEnvironments`.
+ */
+export class ProjectEnvironmentResource {
+	private readonly transport: Transport;
+
+	constructor(transport: Transport) {
+		this.transport = transport;
+	}
+
+	// ─── List ────────────────────────────────────────────────────────────────
+
+	/**
+	 * List the project's environments. Excludes archived rows by default —
+	 * pass `includeArchived: true` to include rows with a non-null
+	 * `archivedAt` (used by the admin / restore UI).
+	 */
+	async list(
+		input: ListProjectEnvironmentsInput,
+	): Promise<ListProjectEnvironmentsResult> {
+		const envelope =
+			await this.transport.request<ListProjectEnvironmentsResult>(
+				"GET",
+				projectEnvironmentsPath(input.projectId),
+				{
+					query: input.includeArchived
+						? { includeArchived: "true" }
+						: undefined,
+				},
+			);
+		return unwrap(envelope);
+	}
+
+	// ─── Get ─────────────────────────────────────────────────────────────────
+
+	async get(
+		input: GetProjectEnvironmentInput,
+	): Promise<GetProjectEnvironmentResult> {
+		const envelope = await this.transport.request<GetProjectEnvironmentResult>(
+			"GET",
+			projectEnvironmentPath(input.projectId, input.slug),
+		);
+		return unwrap(envelope);
+	}
+
+	// ─── Create ──────────────────────────────────────────────────────────────
+
+	/**
+	 * Create a new environment.
+	 *
+	 * `slug` must match lowercase-kebab (`a-z`, `0-9`, `-`, 1..63 chars).
+	 * Reserved system slugs (`prod`, `staging`) and any already-used slug
+	 * return 409 `ENVIRONMENT_SLUG_TAKEN`.
+	 *
+	 * Setting `isGatewayFallback: true` additionally requires the
+	 * `project:manage_default_environment` capability; the create use
+	 * case clears the flag on any other env in the same project.
+	 */
+	async create(
+		input: CreateProjectEnvironmentInput,
+	): Promise<CreateProjectEnvironmentResult> {
+		const { projectId, ...body } = input;
+		const envelope =
+			await this.transport.request<CreateProjectEnvironmentResult>(
+				"POST",
+				projectEnvironmentsPath(projectId),
+				{ body },
+			);
+		return unwrap(envelope);
+	}
+
+	// ─── Update ──────────────────────────────────────────────────────────────
+
+	/**
+	 * PATCH an environment.
+	 *
+	 * - System envs (`isSystem: true`) reject `slug`/`isSystem`/immutable-
+	 *   field mutations with 409 `SYSTEM_ENV_IMMUTABLE`.
+	 * - Renaming via `newSlug` triggers a 7-day alias row server-side so
+	 *   in-flight gateway requests carrying the old slug keep resolving.
+	 * - Mutating `isGatewayFallback` requires the
+	 *   `project:manage_default_environment` capability AND the target
+	 *   env must have at least one live snapshot (else 409
+	 *   `FALLBACK_ENV_NOT_READY`).
+	 *
+	 * The SDK marshals `newSlug` onto the wire as `slug` (the API accepts
+	 * `slug` on the PATCH body for a rename — the URL slug stays the
+	 * pre-rename identifier).
+	 */
+	async update(
+		input: UpdateProjectEnvironmentInput,
+	): Promise<UpdateProjectEnvironmentResult> {
+		const { projectId, slug, newSlug, ...rest } = input;
+		const body: Record<string, unknown> = {};
+		if (newSlug !== undefined) body.slug = newSlug;
+		if (rest.name !== undefined) body.name = rest.name;
+		if (rest.color !== undefined) body.color = rest.color;
+		if (rest.description !== undefined) body.description = rest.description;
+		if (rest.isPointer !== undefined) body.isPointer = rest.isPointer;
+		if (rest.requiresApproval !== undefined)
+			body.requiresApproval = rest.requiresApproval;
+		if (rest.isDefault !== undefined) body.isDefault = rest.isDefault;
+		if (rest.isGatewayFallback !== undefined)
+			body.isGatewayFallback = rest.isGatewayFallback;
+		if (rest.sortOrder !== undefined) body.sortOrder = rest.sortOrder;
+
+		const envelope =
+			await this.transport.request<UpdateProjectEnvironmentResult>(
+				"PATCH",
+				projectEnvironmentPath(projectId, slug),
+				{ body },
+			);
+		return unwrap(envelope);
+	}
+
+	// ─── Archive ─────────────────────────────────────────────────────────────
+
+	/**
+	 * Soft-archive an environment. The response carries the archived row
+	 * plus a `livePointerCounts` summary (informational — pointers are
+	 * cascade-cleared by the use case).
+	 *
+	 * System envs (`isSystem: true`) and the current gateway-fallback env
+	 * cannot be archived; the API returns 409 `SYSTEM_ENV_IMMUTABLE` or
+	 * `CANNOT_ARCHIVE_GATEWAY_FALLBACK` respectively.
+	 *
+	 * Uses `POST /:slug/archive` rather than `DELETE` so the server can
+	 * return a structured 200 with the archived row + counts.
+	 */
+	async archive(
+		input: ArchiveProjectEnvironmentInput,
+	): Promise<ArchiveProjectEnvironmentResult> {
+		const envelope =
+			await this.transport.request<ArchiveProjectEnvironmentResult>(
+				"POST",
+				`${projectEnvironmentPath(input.projectId, input.slug)}/archive`,
+			);
+		return unwrap(envelope);
+	}
+
+	// ─── Restore ─────────────────────────────────────────────────────────────
+
+	/**
+	 * Restore a previously-archived environment. The server resets
+	 * `archivedAt` to `null` and returns the live row. No-op if the env
+	 * is already live; returns 404 `ENVIRONMENT_NOT_FOUND` if the slug
+	 * has never existed.
+	 */
+	async restore(
+		input: RestoreProjectEnvironmentInput,
+	): Promise<RestoreProjectEnvironmentResult> {
+		const envelope =
+			await this.transport.request<RestoreProjectEnvironmentResult>(
+				"POST",
+				`${projectEnvironmentPath(input.projectId, input.slug)}/restore`,
+			);
+		return unwrap(envelope);
+	}
+}

package/src/projectEnvironments/types.ts

@@ -0,0 +1,151 @@
+// ---------------------------------------------------------------------------
+// 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.
+// ---------------------------------------------------------------------------
+
+// ─── Wire shape ─────────────────────────────────────────────────────────────
+
+/**
+ * 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;
+}
+
+// ─── Inputs ─────────────────────────────────────────────────────────────────
+
+export interface ListProjectEnvironmentsInput {
+	projectId: string;
+	/**
+	 * When `true`, the response includes archived envs (those with a
+	 * non-null `archivedAt`). Default behavior excludes them.
+	 */
+	includeArchived?: boolean;
+}
+
+export type ListProjectEnvironmentsResult = ProjectEnvironment[];
+
+export interface GetProjectEnvironmentInput {
+	projectId: string;
+	slug: string;
+}
+
+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;
+	name: string;
+	color?: string | null;
+	description?: string | null;
+	isPointer?: boolean;
+	requiresApproval?: boolean;
+	isDefault?: boolean;
+	isGatewayFallback?: boolean;
+	sortOrder?: number;
+}
+
+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;
+	newSlug?: string;
+	name?: string;
+	color?: string | null;
+	description?: string | null;
+	isPointer?: boolean;
+	requiresApproval?: boolean;
+	isDefault?: boolean;
+	isGatewayFallback?: boolean;
+	sortOrder?: number;
+}
+
+export type UpdateProjectEnvironmentResult = ProjectEnvironment;
+
+export interface ArchiveProjectEnvironmentInput {
+	projectId: string;
+	slug: string;
+}
+
+export interface RestoreProjectEnvironmentInput {
+	projectId: string;
+	slug: string;
+}
+
+export type RestoreProjectEnvironmentResult = ProjectEnvironment;