@to11ai/sdk 0.1.2 → 0.3.0

package/src/traceparent.ts

@@ -19,6 +19,16 @@
  * @see docs/product-specs/2026-05-20-to11-1016-sdk-traceparent-propagation.md
  */
 
+// NOTE: deliberately NO top-level `import ... from "node:module"`. With the
+// SDK's `--external '*'` build that import is emitted verbatim into the ESM
+// `dist/client.js`, and a static `node:module` import is resolved at module
+// initialization — *before* any try/catch in `resolveRequire()` can run. In
+// edge runtimes that lack `node:module` (Cloudflare Workers without
+// `nodejs_compat`, bare Service Workers) that is a hard module-load failure,
+// not the spec-R2 graceful no-op. We instead reach `node:module` lazily and
+// optionally via `process.getBuiltinModule`, which is absent (not throwing) in
+// those runtimes.
+
 // Minimal structural typing of the OTel API surface we actually use. Keeping
 // this local — rather than importing types from `@opentelemetry/api` — is
 // what keeps the SDK zero-dep at the TypeScript layer too. Source types:
@@ -52,16 +62,71 @@ let loader: OtelLoader = defaultLoader;
 
 function defaultLoader(): OtelApi | null {
 	try {
-		// biome-ignore lint/suspicious/noExplicitAny: dynamic require shim — see header comment
-		const g = globalThis as any;
-		// biome-ignore lint/security/noGlobalEval: runtime-detected optional peer dep; bundlers cannot statically resolve
-		const r = (g.require ?? eval("require")) as (id: string) => unknown;
+		const r = resolveRequire();
+		if (r === null) return null;
 		return r("@opentelemetry/api") as OtelApi;
 	} catch {
 		return null;
 	}
 }
 
+/**
+ * Resolve a CommonJS `require` usable for optionally loading `@opentelemetry/api`,
+ * across every runtime this package ships to. Order matters — it is the whole
+ * point of the TO11-1380 fix:
+ *
+ *   1. `globalThis.require` — present in some bundled / global contexts.
+ *   2. `eval("require")` — resolves the module-local `require` in the
+ *      `dist/client.cjs` (CommonJS) build. In a native Node ESM module this
+ *      throws `ReferenceError: require is not defined`, so we fall through.
+ *   3. `process.getBuiltinModule("node:module").createRequire(import.meta.url)`
+ *      — the ESM-correct path. The published `dist/client.js` is loaded by Node
+ *      via `import`, where `require` is not defined and not on `globalThis`. The
+ *      previous loader stopped at step 2, cached `null` forever, and made
+ *      `activeTraceContext()` a permanent no-op for the primary import build
+ *      (TO11-1380). `import.meta` is only referenced here, in the ESM branch, so
+ *      the CJS build never evaluates it.
+ *
+ * `node:module` is reached lazily via `process.getBuiltinModule` (not a static
+ * `import`) precisely so non-Node runtimes never resolve the builtin at module
+ * load. In a browser / edge runtime (Cloudflare Workers, Vercel Edge)
+ * `globalThis.require` is absent, `eval("require")` throws, and
+ * `process.getBuiltinModule` is absent — every step degrades to a strict no-op,
+ * preserving the zero-dep edge behavior (spec R2). `process.getBuiltinModule`
+ * is available on Node ≥ 20.16 / ≥ 22.3; older Node ESM (no global `require`,
+ * no `getBuiltinModule`) degrades to no-op rather than crashing.
+ */
+function resolveRequire(): ((id: string) => unknown) | null {
+	// biome-ignore lint/suspicious/noExplicitAny: dynamic require shim — see header comment
+	const g = globalThis as any;
+	if (typeof g.require === "function") {
+		return g.require as (id: string) => unknown;
+	}
+	try {
+		// biome-ignore lint/security/noGlobalEval: CJS build only; throws in native ESM and we fall through.
+		const cjsRequire = eval("require") as (id: string) => unknown;
+		if (typeof cjsRequire === "function") return cjsRequire;
+	} catch {
+		// Not a CommonJS context (native ESM or edge runtime). Try ESM next.
+	}
+	try {
+		// `getBuiltinModule` is optional: absent (returns undefined / not a
+		// function) in edge runtimes, so this never throws at module load.
+		const getBuiltinModule = g.process?.getBuiltinModule as
+			| ((id: string) => unknown)
+			| undefined;
+		if (typeof getBuiltinModule !== "function") return null;
+		const nodeModule = getBuiltinModule("node:module") as {
+			createRequire?: (path: string | URL) => (id: string) => unknown;
+		};
+		if (typeof nodeModule?.createRequire !== "function") return null;
+		return nodeModule.createRequire(import.meta.url);
+	} catch {
+		// No usable `node:module` (edge runtime) — strict no-op.
+		return null;
+	}
+}
+
 /**
  * Return the W3C `traceparent` (and optional `tracestate`) string pair for
  * the currently active OpenTelemetry span in the host process, or `null` if

package/src/transport.ts

@@ -1,13 +1,20 @@
+import type { BehaviorStore } from "./behaviors/store";
 import {
+	AmbiguousEnvLabelsError,
 	EnvNotEnabledForProviderError,
+	EnvNotFoundError,
+	NoActiveReleaseError,
 	NoApplicableRouteError,
 	PromptLabelNotRegisteredError,
+	PromptNotFoundError,
+	PromptPolicyViolationError,
 	RuleNotFoundError,
 	RuleVersionInvalidSnapshotError,
 	To11aiApiError,
 	To11aiAuthError,
 	To11aiNetworkError,
 	To11aiRateLimitError,
+	To11aiResponseValidationError,
 	To11aiValidationError,
 } from "./errors";
 import { activeTraceContext } from "./traceparent";
@@ -28,6 +35,111 @@ const RULE_NOT_FOUND_DETAILS_ERRORS = new Set([
 	"rule_not_found_in_env",
 ]);
 
+/**
+ * TO11-980 (S9) prompt-resolution canonical error codes.
+ *
+ * WIRE NOTE: the server (TO11-1925/1926) emits the generic HTTP class
+ * (`not_found` / `conflict` / `unprocessable_entity`) at the envelope's
+ * top-level `error.code`, and the canonical SCREAMING_SNAKE code below in
+ * `error.details.code` (matching the existing `PROMPT_NOT_FOUND` convention).
+ * The four prompt-resolve branches in `mapHttpError` therefore read
+ * `details.code`, NOT top-level `errorCode`.
+ *
+ * Two codes fold into `PromptNotFoundError`: `PROMPT_NOT_FOUND` (no prompt)
+ * and `PROMPT_LABELS_NOT_FOUND` (no version matched the env-label).
+ */
+const PROMPT_NOT_FOUND_DETAILS_CODES = new Set([
+	"PROMPT_NOT_FOUND",
+	"PROMPT_LABELS_NOT_FOUND",
+]);
+
+/**
+ * Prompt-resolution policy violation codes (S5 / TO11-976). The generic
+ * `POLICY_VIOLATION` plus the concrete `ENV_POLICY_*` family the server
+ * emits. Any of these maps to `PromptPolicyViolationError`. This set is
+ * matched on `details.code` BEFORE the generic `401 || 403 → auth` guard so a
+ * 403 policy violation is not swallowed as an auth error (D3, AC6).
+ */
+const PROMPT_POLICY_VIOLATION_DETAILS_CODES = new Set([
+	"POLICY_VIOLATION",
+	"ENV_POLICY_REQUIRED_SOURCE_ENV",
+	"ENV_POLICY_MINIMUM_DWELL_TIME",
+	"ENV_POLICY_NO_ROLLBACK_IN_SOURCE",
+	"ENV_POLICY_REQUIRES_APPROVAL",
+	"ENV_POLICY_SEPARATION_OF_DUTIES",
+	"ENV_POLICY_SOURCE_ENV_UNAVAILABLE",
+	"ENV_POLICY_ENV_NOT_FOUND",
+	"ENV_POLICY_INVALID_CONFIG",
+]);
+
+/**
+ * Map a prompt-resolution envelope (keyed on `details.code`) to a typed S9
+ * subclass, or `undefined` when the code is not one of the four S9 families.
+ *
+ * Returning `undefined` lets the caller fall through to the existing
+ * status-keyed dispatch (so unmapped codes stay base `To11aiApiError`, per
+ * D3). This function reads ONLY `details.code` — never top-level `error.code`
+ * — because the server puts the canonical code in `details.code` (see above).
+ */
+function mapPromptResolveError(
+	status: number,
+	message: string,
+	details: unknown,
+): To11aiApiError | undefined {
+	const d = (details && typeof details === "object" ? details : {}) as Record<
+		string,
+		unknown
+	>;
+	const detailsCode = typeof d.code === "string" ? d.code : undefined;
+	if (detailsCode === undefined) return undefined;
+
+	const slug = typeof d.slug === "string" ? d.slug : undefined;
+	const projectId = typeof d.projectId === "string" ? d.projectId : undefined;
+	const env = typeof d.env === "string" ? d.env : undefined;
+	const promptId = typeof d.promptId === "string" ? d.promptId : undefined;
+
+	if (PROMPT_NOT_FOUND_DETAILS_CODES.has(detailsCode)) {
+		return new PromptNotFoundError(
+			message,
+			detailsCode,
+			{ slug, projectId },
+			details,
+			status,
+		);
+	}
+	if (detailsCode === "ENV_NOT_FOUND") {
+		// Server-side unknown-env. (The client-eager "missing" variant is
+		// raised in resource.ts before any request — never here.)
+		return new EnvNotFoundError(
+			message,
+			{ env, source: "unknown" },
+			details,
+			status,
+		);
+	}
+	if (detailsCode === "NO_ACTIVE_RELEASE") {
+		return new NoActiveReleaseError(
+			message,
+			{ slug, promptId, env },
+			details,
+			status,
+		);
+	}
+	if (detailsCode === "AMBIGUOUS_ENV_LABELS") {
+		return new AmbiguousEnvLabelsError(message, { env, slug }, details, status);
+	}
+	if (PROMPT_POLICY_VIOLATION_DETAILS_CODES.has(detailsCode)) {
+		const policy = typeof d.policy === "string" ? d.policy : undefined;
+		return new PromptPolicyViolationError(
+			message,
+			{ code: detailsCode, policy, detail: d.detail },
+			details,
+			status,
+		);
+	}
+	return undefined;
+}
+
 export type AuthConfig =
 	| { readonly apiKey: string; readonly getAccessToken?: never }
 	| { readonly getAccessToken: () => Promise<string>; readonly apiKey?: never };
@@ -44,6 +156,12 @@ export interface TransportConfig {
 	 * attempt. Default: 3
 	 */
 	readonly maxRetries?: number;
+	/**
+	 * Optional behavior store updated from each successful response's
+	 * `sdkBehavior` field (TO11-2100). When omitted, server-delivered behavior
+	 * values are simply not captured.
+	 */
+	readonly behaviorStore?: BehaviorStore;
 }
 
 /** Standard API envelope returned by the to11ai server. */
@@ -58,6 +176,15 @@ export interface ApiEnvelope<T = unknown> {
 		readonly total: number;
 		readonly totalPages: number;
 	} | null;
+	/**
+	 * Optional, additively-versioned server-evaluated SDK-behavior values
+	 * (TO11-2100). Present only when the server has behavior flags to deliver;
+	 * an unknown `v` is ignored by the SDK. See `behaviors/store.ts`.
+	 */
+	readonly sdkBehavior?: {
+		readonly v: number;
+		readonly flags: Record<string, unknown>;
+	};
 }
 
 const DEFAULT_TIMEOUT_MS = 30_000;
@@ -99,6 +226,18 @@ function mapHttpError(
 	const errorCode = envelope?.code;
 	const details = envelope?.details;
 
+	// TO11-980 (S9): prompt-resolution typed errors are keyed on
+	// `details.code` (the canonical SCREAMING_SNAKE code), NOT top-level
+	// `error.code`. This MUST run BEFORE the generic `401 || 403 → auth`
+	// guard below so a 403 `POLICY_VIOLATION` is mapped to
+	// `PromptPolicyViolationError` rather than swallowed as `To11aiAuthError`
+	// (D3 branch-ordering, AC6). Unmapped `details.code` values return
+	// `undefined` and fall through to the existing status-keyed dispatch.
+	const promptResolveError = mapPromptResolveError(status, message, details);
+	if (promptResolveError) {
+		return promptResolveError;
+	}
+
 	if (status === 401 || status === 403) {
 		return new To11aiAuthError(
 			message,
@@ -253,12 +392,14 @@ export class Transport {
 	private readonly auth: AuthConfig;
 	private readonly timeoutMs: number;
 	private readonly maxRetries: number;
+	private readonly behaviorStore: BehaviorStore | undefined;
 
 	constructor(config: TransportConfig) {
 		this.baseUrl = config.baseUrl.replace(/\/$/, "");
 		this.auth = config.auth;
 		this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
 		this.maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
+		this.behaviorStore = config.behaviorStore;
 	}
 
 	private async buildHeaders(): Promise<Record<string, string>> {
@@ -289,6 +430,12 @@ export class Transport {
 		options?: {
 			query?: Record<string, string | number | boolean | undefined>;
 			body?: unknown;
+			/**
+			 * Runtime validator for the envelope `data` on a 2xx response. When
+			 * supplied, the decoded value replaces `data`; a thrown decoder error
+			 * surfaces as `To11aiResponseValidationError`.
+			 */
+			decode?: (data: unknown) => T;
 		},
 	): Promise<ApiEnvelope<T>> {
 		const url = new URL(this.baseUrl + path);
@@ -320,7 +467,15 @@ export class Transport {
 					signal: controller.signal,
 				});
 
-				clearTimeout(timeoutId);
+				// NOTE: the timeout is intentionally NOT cleared here. A server can
+				// send headers promptly (resolving `fetch`) but then stall the
+				// response body forever. The timeout must stay armed across
+				// `response.text()` and JSON parsing so a stalled body still aborts
+				// after `timeoutMs`; an abort mid-body surfaces as an AbortError that
+				// the catch block maps to `To11aiNetworkError`. Cleanup lives in the
+				// `finally` below so every exit path (success, retry `continue`,
+				// throw) clears the timer exactly once before the next attempt. See
+				// TO11-1402.
 
 				// 5xx — retry only if the method is idempotent (RFC 9110 §9.2.2).
 				// POST/PATCH may have already committed server-side, so replaying
@@ -361,10 +516,32 @@ export class Transport {
 					);
 				}
 
+				// Capture any server-delivered SDK-behavior values from the
+				// success envelope (TO11-2100). Behavior is delivered on success
+				// responses only — gate on the envelope's `success` flag, not just
+				// the 2xx status, so an unusual 2xx-with-`success:false` body does
+				// not update the store. An absent field leaves prior values intact.
+				// Done before any caller-supplied decode so the store reflects the
+				// raw envelope regardless of how the data is post-processed.
+				if (json.success === true) {
+					this.behaviorStore?.updateFromEnvelope(json.sdkBehavior);
+				}
+
+				if (options?.decode && json.data !== null && json.data !== undefined) {
+					try {
+						const decoded = options.decode(json.data);
+						return { ...json, data: decoded };
+					} catch (validationErr) {
+						throw new To11aiResponseValidationError(
+							path,
+							validationErr,
+							validationErr,
+						);
+					}
+				}
+
 				return json;
 			} catch (err) {
-				clearTimeout(timeoutId);
-
 				// Re-throw typed SDK errors immediately (no retry)
 				if (err instanceof To11aiApiError) {
 					throw err;
@@ -403,6 +580,14 @@ export class Transport {
 
 				// Re-throw unexpected errors (e.g. auth callback failures) as-is
 				throw err;
+			} finally {
+				// Clear the per-attempt timeout exactly once on every exit path:
+				// success (`return`), retry (`continue`), or throw. Running here —
+				// rather than after `fetch` resolves — keeps the timer armed across
+				// the response-body read so a stalled body still aborts (TO11-1402),
+				// while still freeing the timer before the loop starts a fresh
+				// attempt with a new AbortController.
+				clearTimeout(timeoutId);
 			}
 		}
 	}