@to11ai/sdk 0.0.2 → 0.1.1

package/src/routingRules/resource.ts

@@ -0,0 +1,180 @@
+import type { ApiEnvelope, Transport } from "../transport";
+import type {
+	CreateRuleVersionInput,
+	CreateRuleVersionResult,
+	GetRuleVersionInput,
+	GetRuleVersionResult,
+	ListRuleReleasesInput,
+	ListRuleReleasesResult,
+	ListRuleVersionsInput,
+	ListRuleVersionsResult,
+	RollbackRuleReleaseInput,
+	RollbackRuleReleaseResult,
+	SetRuleReleaseInput,
+	SetRuleReleaseResult,
+} from "./types";
+
+export type {
+	CreateRuleVersionInput,
+	CreateRuleVersionResult,
+	GetRuleVersionInput,
+	GetRuleVersionResult,
+	ListRuleReleasesInput,
+	ListRuleReleasesResult,
+	ListRuleVersionsInput,
+	ListRuleVersionsResult,
+	RollbackRuleReleaseInput,
+	RollbackRuleReleaseResult,
+	RuleModelBinding,
+	RuleProviderRef,
+	RuleRelease,
+	RuleReleaseActorType,
+	RuleReleaseApprovalStatus,
+	RuleReleaseChangeKind,
+	RuleReleaseStrategy,
+	RuleReleaseWeight,
+	RuleSnapshot,
+	RuleStrategy,
+	RuleVersion,
+	SetRuleReleaseInput,
+	SetRuleReleaseResult,
+} 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 rulePath(projectId: string, ruleId: string): string {
+	return `/v1/projects/${encodeURIComponent(projectId)}/routing/rules/${encodeURIComponent(ruleId)}`;
+}
+
+function versionsPath(projectId: string, ruleId: string): string {
+	return `${rulePath(projectId, ruleId)}/versions`;
+}
+
+function versionPath(
+	projectId: string,
+	ruleId: string,
+	versionId: string,
+): string {
+	return `${versionsPath(projectId, ruleId)}/${encodeURIComponent(versionId)}`;
+}
+
+function releasesPath(projectId: string, ruleId: string): string {
+	return `${rulePath(projectId, ruleId)}/releases`;
+}
+
+function releasePath(
+	projectId: string,
+	ruleId: string,
+	envSlug: string,
+): string {
+	return `${releasesPath(projectId, ruleId)}/${encodeURIComponent(envSlug)}`;
+}
+
+function releaseRollbackPath(
+	projectId: string,
+	ruleId: string,
+	envSlug: string,
+): string {
+	return `${releasePath(projectId, ruleId, envSlug)}/rollback`;
+}
+
+export class RoutingRuleVersionResource {
+	private readonly transport: Transport;
+
+	constructor(transport: Transport) {
+		this.transport = transport;
+	}
+
+	async create(
+		input: CreateRuleVersionInput,
+	): Promise<CreateRuleVersionResult> {
+		const { projectId, ruleId, ...body } = input;
+		const envelope = await this.transport.request<CreateRuleVersionResult>(
+			"POST",
+			versionsPath(projectId, ruleId),
+			{ body },
+		);
+		return unwrap(envelope);
+	}
+
+	async list(input: ListRuleVersionsInput): Promise<ListRuleVersionsResult> {
+		const query: Record<string, string | number | undefined> = {};
+		if (input.cursor !== undefined) query.cursor = input.cursor;
+		if (input.limit !== undefined) query.limit = input.limit;
+		const envelope = await this.transport.request<ListRuleVersionsResult>(
+			"GET",
+			versionsPath(input.projectId, input.ruleId),
+			{ query },
+		);
+		return unwrap(envelope);
+	}
+
+	async get(input: GetRuleVersionInput): Promise<GetRuleVersionResult> {
+		const envelope = await this.transport.request<GetRuleVersionResult>(
+			"GET",
+			versionPath(input.projectId, input.ruleId, input.versionId),
+		);
+		return unwrap(envelope);
+	}
+}
+
+export class RoutingRuleReleaseResource {
+	private readonly transport: Transport;
+
+	constructor(transport: Transport) {
+		this.transport = transport;
+	}
+
+	async set(input: SetRuleReleaseInput): Promise<SetRuleReleaseResult> {
+		const { projectId, ruleId, envSlug, ...body } = input;
+		const envelope = await this.transport.request<SetRuleReleaseResult>(
+			"PUT",
+			releasePath(projectId, ruleId, envSlug),
+			{ body },
+		);
+		return unwrap(envelope);
+	}
+
+	async rollback(
+		input: RollbackRuleReleaseInput,
+	): Promise<RollbackRuleReleaseResult> {
+		const { projectId, ruleId, envSlug, ...body } = input;
+		const envelope = await this.transport.request<RollbackRuleReleaseResult>(
+			"POST",
+			releaseRollbackPath(projectId, ruleId, envSlug),
+			{ body },
+		);
+		return unwrap(envelope);
+	}
+
+	async list(input: ListRuleReleasesInput): Promise<ListRuleReleasesResult> {
+		const query: Record<string, string | number | undefined> = {};
+		if (input.cursor !== undefined) query.cursor = input.cursor;
+		if (input.limit !== undefined) query.limit = input.limit;
+		const path =
+			input.envSlug !== undefined
+				? releasePath(input.projectId, input.ruleId, input.envSlug)
+				: releasesPath(input.projectId, input.ruleId);
+		const envelope = await this.transport.request<ListRuleReleasesResult>(
+			"GET",
+			path,
+			{ query },
+		);
+		return unwrap(envelope);
+	}
+}
+
+export class RoutingRulesResource {
+	readonly versions: RoutingRuleVersionResource;
+	readonly releases: RoutingRuleReleaseResource;
+
+	constructor(transport: Transport) {
+		this.versions = new RoutingRuleVersionResource(transport);
+		this.releases = new RoutingRuleReleaseResource(transport);
+	}
+}

package/src/routingRules/types.ts

@@ -0,0 +1,222 @@
+// ---------------------------------------------------------------------------
+// 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;
+}
+
+/**
+ * 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 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[];
+}
+
+// ─── 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;
+}
+
+// ─── 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;
+	snapshot: RuleSnapshot | unknown;
+	description?: string;
+}
+
+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;
+}
+
+export type ListRuleVersionsResult = RuleVersion[];
+
+export interface GetRuleVersionInput {
+	projectId: string;
+	ruleId: string;
+	versionId: string;
+}
+
+export type GetRuleVersionResult = RuleVersion;
+
+// ─── Releases (S2 / TO11-1009) ──────────────────────────────────────────────
+
+export type RuleReleaseStrategy = "single" | "weighted";
+
+export type RuleReleaseChangeKind =
+	| "release_initial"
+	| "release_promoted"
+	| "release_rolled_back"
+	| "release_weight_changed";
+
+export type RuleReleaseApprovalStatus = "committed" | "pending" | "rejected";
+
+export type RuleReleaseActorType = "user" | "api_key" | "worker";
+
+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 interface SetRuleReleaseInput {
+	projectId: string;
+	ruleId: string;
+	envSlug: string;
+	strategy: RuleReleaseStrategy;
+	versionId?: string;
+	weights?: RuleReleaseWeight[];
+	reason?: string;
+}
+
+export type SetRuleReleaseResult = RuleRelease;
+
+export interface RollbackRuleReleaseInput {
+	projectId: string;
+	ruleId: string;
+	envSlug: string;
+	reason: string;
+	targetReleaseId?: string;
+}
+
+export type RollbackRuleReleaseResult = RuleRelease;
+
+export interface ListRuleReleasesInput {
+	projectId: string;
+	ruleId: string;
+	envSlug?: string;
+	cursor?: string;
+	limit?: number;
+}
+
+export type ListRuleReleasesResult = RuleRelease[];

package/src/traceparent.ts

@@ -0,0 +1,124 @@
+/**
+ * W3C Trace Context propagation for outbound SDK calls.
+ *
+ * Reads the host process's active OpenTelemetry span — if any — and formats a
+ * W3C `traceparent` (and optional `tracestate`) string for injection as
+ * outbound HTTP headers. Lets customers correlate their tracer's spans with
+ * the gateway-emitted span we record.
+ *
+ * Design constraints (from TO11-1016 / S8c spec):
+ *   1. NO runtime dependency on `@opentelemetry/api`. The package is detected
+ *      at runtime via a try/require shim; if it is not loadable, this module
+ *      is a strict no-op and `activeTraceContext()` returns `null`.
+ *   2. NO SDK config surface change. There is no constructor option or env
+ *      var; behavior is invisible if the host has no OTel installed.
+ *   3. Header omitted, not zero-filled — W3C §3.2.2.5 forbids all-zero
+ *      trace/span ids in `traceparent`. We return `null` (caller omits).
+ *
+ * @see https://www.w3.org/TR/trace-context/ for the wire format.
+ * @see docs/product-specs/2026-05-20-to11-1016-sdk-traceparent-propagation.md
+ */
+
+// 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:
+// https://github.com/open-telemetry/opentelemetry-js-api/
+interface OtelTraceState {
+	serialize(): string;
+}
+interface OtelSpanContext {
+	traceId: string;
+	spanId: string;
+	traceFlags: number;
+	traceState?: OtelTraceState;
+}
+interface OtelSpan {
+	spanContext(): OtelSpanContext;
+}
+interface OtelTrace {
+	getActiveSpan(): OtelSpan | undefined;
+}
+interface OtelApi {
+	trace: OtelTrace;
+}
+
+type OtelLoader = () => OtelApi | null;
+
+const ZERO_TRACE_ID = "0".repeat(32);
+const ZERO_SPAN_ID = "0".repeat(16);
+
+let cached: OtelApi | null | undefined; // undefined = not yet probed
+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;
+		return r("@opentelemetry/api") as OtelApi;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Return the W3C `traceparent` (and optional `tracestate`) string pair for
+ * the currently active OpenTelemetry span in the host process, or `null` if
+ * no active span exists or `@opentelemetry/api` is not installed.
+ *
+ * Idempotent and side-effect-free past the one-time module probe. Callers
+ * inject the returned strings as outbound HTTP headers when non-null.
+ */
+export function activeTraceContext(): {
+	traceparent: string;
+	tracestate?: string;
+} | null {
+	if (cached === undefined) cached = loader();
+	if (cached === null) return null;
+
+	let span: OtelSpan | undefined;
+	let ctx: OtelSpanContext;
+	try {
+		span = cached.trace.getActiveSpan();
+		if (!span) return null;
+		ctx = span.spanContext();
+	} catch {
+		// A broken / partially-installed OTel SDK must not break customer
+		// outbound calls. Degrade to no-op.
+		return null;
+	}
+
+	const { traceId, spanId } = ctx;
+	if (!traceId || !spanId) return null;
+	if (traceId === ZERO_TRACE_ID || spanId === ZERO_SPAN_ID) return null;
+
+	const flags = ((ctx.traceFlags ?? 0) & 0xff).toString(16).padStart(2, "0");
+	const traceparent = `00-${traceId}-${spanId}-${flags}`;
+
+	let tracestate: string | undefined;
+	try {
+		const raw = ctx.traceState?.serialize();
+		if (typeof raw === "string" && raw.length > 0) tracestate = raw;
+	} catch {
+		// Same defensive posture — never let a vendor tracestate bug
+		// surface as a request failure.
+	}
+
+	return tracestate === undefined
+		? { traceparent }
+		: { traceparent, tracestate };
+}
+
+/**
+ * Test-only seam: install a deterministic OTel loader and reset the
+ * module-level cache. Underscore-prefixed and intentionally NOT re-exported
+ * from the package entry-point.
+ *
+ * Production code never calls this. Tests call it to simulate
+ * "OTel installed" / "OTel absent" / "broken OTel install" cells.
+ */
+export function _loadOtelForTests(injected: OtelLoader | undefined): void {
+	loader = injected ?? defaultLoader;
+	cached = undefined;
+}