@to11ai/sdk 1.1.0 → 2.0.0-rc.2

package/src/client.ts

@@ -1,8 +1,20 @@
 import { BehaviorStore } from "./behaviors/store";
+import { DEFAULT_API_URL, DEFAULT_GATEWAY_URL } from "./config";
+import {
+	type Conversation,
+	Session,
+	type Turn,
+	type TurnAuthContext,
+} from "./context";
+import { gatewayAuthHeaders } from "./gateway";
 import { ProjectEnvironmentResource } from "./projectEnvironments/resource";
 import type { CacheConfig } from "./prompts/cache";
 import { PromptResource } from "./prompts/resource";
-import { ENV_SLUG_REGEX } from "./prompts/types";
+import {
+	ENV_SLUG_REGEX,
+	type RenderFormat,
+	type UnknownRoleMode,
+} from "./prompts/types";
 import { RoutingRulesResource } from "./routingRules/resource";
 import { Transport } from "./transport";
 
@@ -13,6 +25,8 @@ export {
 	envVarNameForKey,
 	type SdkBehaviorEnvelope,
 } from "./behaviors/store";
+export type { TurnAuthContext } from "./context";
+export { Conversation, Session, Turn } from "./context";
 // Re-export all error types for convenience
 export type {
 	AmbiguousEnvLabelsReason,
@@ -40,8 +54,9 @@ export {
 	To11aiNetworkError,
 	To11aiRateLimitError,
 	To11aiValidationError,
+	UnknownRoleError,
 } from "./errors";
-export type { GatewayAuthOptions } from "./gateway";
+export type { ConvertMessagesOptions, GatewayAuthOptions } from "./gateway";
 export { gatewayAuthHeaders, gatewayPromptHeaders } from "./gateway";
 export type {
 	ArchiveProjectEnvironmentInput,
@@ -63,16 +78,23 @@ export { ProjectEnvironmentResource } from "./projectEnvironments/resource";
 export type { CacheConfig } from "./prompts/cache";
 export type { PromptResourceConfig } from "./prompts/resource";
 export { PromptResource } from "./prompts/resource";
-// TO11-980 (S9): env-aware fetch() surface types at the package entrypoint (AC9).
+export type {
+	AnthropicRenderedPrompt,
+	OpenAiRenderedPrompt,
+	PromptConfig,
+	PromptMetadata,
+	RenderResult,
+} from "./prompts/shape";
+// TO11-980 (S9): env-aware render() surface types at the package entrypoint (AC9).
 export type {
 	BlockRenderRecord,
-	DeveloperRole,
-	FetchedPrompt,
-	FetchPromptOptions,
 	RenderedChatMessage,
 	RenderedPrompt,
+	RenderFormat,
+	RenderOptions,
 	ResolvedPrompt,
 	ResolvedPromptEnvelope,
+	UnknownRoleMode,
 } from "./prompts/types";
 export { ENV_SLUG_REGEX } from "./prompts/types";
 export type {
@@ -107,63 +129,106 @@ export {
 } from "./routingRules/resource";
 export type { Transport } from "./transport";
 
-// ─── Auth option shapes ────────────────────────────────────────────────────
-
-interface ServerAuthOptions {
-	/** API key for server-side use. Must not be used in browser contexts. */
-	apiKey: string;
-	getAccessToken?: never;
-}
-
-interface BrowserAuthOptions {
-	/** Token callback for browser / edge contexts — avoids static secrets. */
-	getAccessToken: () => Promise<string>;
-	apiKey?: never;
-}
-
-type AuthOptions = ServerAuthOptions | BrowserAuthOptions;
-
 // ─── Client options ────────────────────────────────────────────────────────
 
-export type ClientOptions = AuthOptions & {
-	baseUrl: string;
+export interface ClientOptions {
+	/**
+	 * Control-plane base URL. Precedence: this option → `TO11_API_URL` env →
+	 * `https://api.to11.ai`.
+	 */
+	baseUrl?: string;
+	/**
+	 * Data-plane gateway URL (the app's provider-client `baseURL`). Precedence:
+	 * this option → `TO11_GATEWAY_URL` env → `https://gw.to11.ai`.
+	 */
+	gatewayUrl?: string;
+	/**
+	 * API key for server-side use. Precedence: this option → `TO11_API_KEY` env.
+	 * Rejected in browser contexts — use `getAccessToken` there.
+	 */
+	apiKey?: string;
+	/** Token callback for browser / edge contexts — avoids static secrets. */
+	getAccessToken?: () => Promise<string>;
+	/**
+	 * Provider API key (BYOK) carried by `openaiOptions()` / `anthropicOptions()`
+	 * as the provider client's `apiKey`, so a BYOK call is a single
+	 * `new OpenAI(to11.openaiOptions())`. When omitted, those helpers fall back to
+	 * the to11 `apiKey` as a placeholder (the managed / server-side-credential
+	 * path). Option only — no env fallback. Whether the gateway actually uses this
+	 * key depends on the provider's passthrough mode; otherwise the project's
+	 * stored credential wins.
+	 */
+	providerApiKey?: string;
 	/**
-	 * Project the client is bound to (TO11-980 / S9). Required for the
-	 * env-aware `prompts.fetch(slug, …)` surface, which builds the
-	 * project-scoped resolve path from it. Validated non-empty at
-	 * construction. The deprecated `prompts.resolve()` keeps its per-call
-	 * `projectId` and ignores this.
+	 * Project the client is bound to. Precedence: this option → `TO11_PROJECT_ID`
+	 * env. Required for `prompts.render()` and the gateway context helpers.
 	 */
 	projectId?: string;
 	/**
-	 * Default serving environment for `prompts.fetch(slug)` (TO11-980 / S9,
-	 * Style-A). When set, every `fetch()` call inherits it unless overridden
-	 * per call. Validated eagerly against the project-environments registry
-	 * rule (lowercase-kebab, `^[a-z0-9-]{1,63}$`): empty / whitespace-only /
-	 * uppercase / 64+-char values throw at construction with a loud
-	 * `[to11ai/sdk]` message before any request hits the wire.
+	 * Default serving environment for `prompts.render(slug)`, inherited by every
+	 * render unless overridden per call. Precedence: this option → `TO11_ENV`
+	 * env. Validated eagerly against the project-environments slug rule
+	 * (`^[a-z0-9-]{1,63}$`).
 	 */
 	env?: string;
-	/** LRU cache configuration for resolve(). Defaults: ttlSeconds=300, maxEntries=100 */
+	/**
+	 * Default provider shape for `prompts.render()` output (`"openai"` |
+	 * `"anthropic"`). Omit for the neutral result. Per-call override allowed.
+	 */
+	format?: RenderFormat;
+	/**
+	 * Default policy for a message with an unrecognized role while shaping
+	 * `render({ format })` output: `"drop"` (default, silent), `"warn"` (drop +
+	 * `console.warn`), or `"error"` (throw `UnknownRoleError`). Per-call override
+	 * via `render(slug, { onUnknownRole })`.
+	 */
+	onUnknownRole?: UnknownRoleMode;
+	/** LRU cache configuration for render(). Defaults: ttlSeconds=300, maxEntries=100 */
 	cache?: CacheConfig;
 	/** Request timeout in milliseconds. Default: 30_000 */
 	timeoutMs?: number;
 	/** Max retry attempts for network errors / 5xx. Default: 3 */
 	maxRetries?: number;
 	/**
-	 * Purely local overrides for server-evaluated SDK-behavior flags (TO11-2100),
-	 * keyed by namespaced flag key (e.g. `{ "sdk.retry-v2": true }`). These take
-	 * precedence over server-delivered values and the SDK's coded defaults. For
-	 * the same flag key, an init option here wins over a `TO11_SDK_BEHAVIOR_*`
-	 * environment variable. Published-SDK only — no LaunchDarkly involved.
+	 * Purely local overrides for server-evaluated SDK-behavior flags (TO11-2100).
+	 * An init option here wins over a `TO11_SDK_BEHAVIOR_*` env var. No LaunchDarkly.
 	 */
 	behaviorOverrides?: Record<string, unknown>;
+}
+
+// ─── Provider-client options (openaiOptions / anthropicOptions) ─────────────
+
+/**
+ * Overrides accepted by `openaiOptions()` / `anthropicOptions()`. The three
+ * known fields are merged (`apiKey` / `baseURL` override; `defaultHeaders`
+ * shallow-merges over the tenant-auth headers, caller wins); any other keys —
+ * `timeout`, `maxRetries`, `fetch`, … — pass through untouched to the provider
+ * client, so `new OpenAI(to11.openaiOptions({ apiKey, timeout }))` needs no
+ * outer spread.
+ */
+export interface ProviderClientOverrides {
+	apiKey?: string;
+	baseURL?: string;
+	defaultHeaders?: Record<string, string>;
+}
+
+/**
+ * The spread-ready result of `openaiOptions()` / `anthropicOptions()`: the three
+ * managed fields plus whatever passthrough keys the caller supplied (their types
+ * preserved), so it drops straight into `new OpenAI(...)` / `new Anthropic(...)`.
+ */
+export type ProviderClientOptions<
+	T extends ProviderClientOverrides = ProviderClientOverrides,
+> = Omit<T, "apiKey" | "baseURL" | "defaultHeaders"> & {
+	baseURL: string;
+	apiKey: string;
+	defaultHeaders: Record<string, string>;
 };
 
 // ─── Client interface ──────────────────────────────────────────────────────
 
-export interface To11aiClient {
-	readonly prompts: PromptResource;
+export interface To11aiClient<F extends RenderFormat | undefined = undefined> {
+	readonly prompts: PromptResource<F>;
 	readonly projectEnvironments: ProjectEnvironmentResource;
 	readonly routingRules: RoutingRulesResource;
 	/**
@@ -176,18 +241,79 @@ export interface To11aiClient {
 	 * delivered on the envelope.
 	 */
 	readonly resolveBehavior: <T>(key: string, codedDefault: T) => T;
+	/** Resolved API key (server mode); `undefined` in browser (`getAccessToken`) mode. */
+	readonly apiKey: string | undefined;
+	/** Resolved data-plane gateway URL (option → `TO11_GATEWAY_URL` → default). */
+	readonly gatewayUrl: string;
+	/** A new session (unit of work). Pass an id to group telemetry by your own id. */
+	session(id?: string): Session;
+	/**
+	 * A conversation in the client's default session (for side / parallel agents).
+	 *
+	 * @example Two agents under one session
+	 * const research = to11.conversation();   // a separate thread from to11.turn()'s default
+	 * const res = await openai.chat.completions.create(
+	 *   { ...researchPrompt.config, messages },
+	 *   { headers: research.turn().headers(researchPrompt) },
+	 * );
+	 */
+	conversation(id?: string): Conversation;
+	/** A turn in the client's default session + default conversation. */
+	turn(): Turn;
+	/**
+	 * Spread-ready options for `new OpenAI(...)` targeting the gateway:
+	 * `{ baseURL, apiKey, defaultHeaders }` (baseURL carries `/v1`). `defaultHeaders`
+	 * holds the static tenant auth, so the client authenticates on its own; add
+	 * `turn().headers(prompt)` per call for trace + prompt provenance. Pass
+	 * `overrides` to change `apiKey`/`baseURL`, merge extra `defaultHeaders`, or
+	 * forward any other provider-SDK option (`timeout`, …).
+	 *
+	 * @example
+	 * const openai = new OpenAI(to11.openaiOptions());
+	 * @example BYOK + a provider-SDK option, no outer spread
+	 * const openai = new OpenAI(to11.openaiOptions({ apiKey: MY_KEY, timeout: 60_000 }));
+	 */
+	openaiOptions<T extends ProviderClientOverrides = ProviderClientOverrides>(
+		overrides?: T,
+	): ProviderClientOptions<T>;
+	/**
+	 * Spread-ready options for `new Anthropic(...)` targeting the gateway root
+	 * (the Anthropic SDK appends `/v1/messages` itself). Same shape and merge
+	 * rules as {@link To11aiClient.openaiOptions}.
+	 */
+	anthropicOptions<T extends ProviderClientOverrides = ProviderClientOverrides>(
+		overrides?: T,
+	): ProviderClientOptions<T>;
 }
 
 // ─── Factory ───────────────────────────────────────────────────────────────
 
 /**
- * Create a to11ai SDK client.
+ * Create a to11ai SDK client. Resolution precedence differs per option:
+ *  - URLs (`baseUrl` / `gatewayUrl`) — option → env var → built-in default.
+ *  - `apiKey` / `projectId` — option → env var (no default).
+ *  - `env` / `format` — option only.
+ * Auth mode:
+ *  - `apiKey` (or `TO11_API_KEY`) → server-side; rejected in browser contexts.
+ *  - `getAccessToken`             → browser-safe; token fetched per request.
  *
- * Auth mode is inferred from options:
- *  - `apiKey`          → server-side; rejected in browser contexts.
- *  - `getAccessToken`  → browser-safe; token fetched per request.
+ * @example Minimal setup (single call)
+ * import { createClient } from "@to11ai/sdk";
+ * import OpenAI from "openai";
+ *
+ * const to11   = createClient({ env: "prod", format: "openai" });
+ * const openai = new OpenAI(to11.openaiOptions());
+ * const prompt = await to11.prompts.render("weather-concierge", { variables: { city: "NYC" } });
+ * const res = await openai.chat.completions.create(
+ *   { ...prompt.config, messages: prompt.messages },
+ *   { headers: to11.turn().headers(prompt) },
+ * );
  */
-export function createClient(options: ClientOptions): To11aiClient {
+export function createClient<
+	const F extends RenderFormat | undefined = undefined,
+>(
+	options: Omit<ClientOptions, "format"> & { format?: F } = {},
+): To11aiClient<F> {
 	const isDomBrowser =
 		typeof globalThis === "object" &&
 		typeof (globalThis as { document?: unknown }).document !== "undefined";
@@ -206,86 +332,215 @@ export function createClient(options: ClientOptions): To11aiClient {
 			(!isBunMainThread &&
 				typeof workerLikeGlobal.postMessage === "function" &&
 				typeof workerLikeGlobal.onmessage !== "undefined"));
+	const isBrowser = isDomBrowser || isWorkerBrowser;
+
+	// Env vars are read ONLY in a non-browser context, so the published browser
+	// bundle never touches `process.env`; explicit options apply everywhere.
+	const processEnv =
+		!isBrowser &&
+		typeof process !== "undefined" &&
+		typeof process.env === "object"
+			? process.env
+			: undefined;
+
+	// Resolve each value: explicit option → env var → default. `pick` trims and
+	// treats empty as absent, so an empty option or env value falls through.
+	const pick = (
+		opt: string | undefined,
+		envKey: string,
+	): string | undefined => {
+		const fromOpt = opt?.trim();
+		if (fromOpt) return fromOpt;
+		const fromEnv = processEnv?.[envKey]?.trim();
+		return fromEnv ? fromEnv : undefined;
+	};
 
-	if ((isDomBrowser || isWorkerBrowser) && options.apiKey !== undefined) {
+	const baseUrl = pick(options.baseUrl, "TO11_API_URL") ?? DEFAULT_API_URL;
+	// The gateway root (host, no version path). Normalize away a trailing slash
+	// and a trailing `/v1` so both the root form (`https://gw.to11.ai`) and the
+	// older `/v1` form resolve identically — the provider helpers add the path
+	// each SDK expects.
+	const gatewayUrl = (
+		pick(options.gatewayUrl, "TO11_GATEWAY_URL") ?? DEFAULT_GATEWAY_URL
+	)
+		.replace(/\/+$/, "")
+		.replace(/\/v1$/, "");
+	const getAccessToken = options.getAccessToken;
+	// Explicit token auth suppresses an ambient `TO11_API_KEY` so a shared env
+	// (SSR / CI / edge) can't defeat an explicit `getAccessToken`. Only an
+	// *explicit* `options.apiKey` alongside `getAccessToken` stays ambiguous and
+	// is rejected by the exactly-one check below.
+	const apiKey =
+		getAccessToken !== undefined
+			? options.apiKey
+			: pick(options.apiKey, "TO11_API_KEY");
+	const projectId = pick(options.projectId, "TO11_PROJECT_ID");
+	// Default serving env: explicit option → `TO11_ENV` env var — the same
+	// `pick(option, "TO11_*")` resolution `apiKey`/`projectId` use (empty option
+	// or empty env var trims to absent). An explicit empty option is rejected by
+	// the dedicated guard below (mirroring `apiKey`/`projectId`); a non-empty but
+	// malformed value fails the `ENV_SLUG_REGEX` check.
+	const env = pick(options.env, "TO11_ENV");
+	// Provider (BYOK) key — option only, no env fallback (which provider's env
+	// var is ambiguous). Empty trims to absent so it falls back to the placeholder.
+	const providerApiKey = options.providerApiKey?.trim() || undefined;
+
+	// A browser must never carry a static API key. `processEnv` is already
+	// undefined in the browser, so only the explicit option can reach here.
+	if (isBrowser && options.apiKey !== undefined) {
 		throw new Error(
 			"[to11ai/sdk] Do not use `apiKey` in browser contexts — use `getAccessToken` instead.",
 		);
 	}
 
+	// Explicit empty credentials are a misconfiguration — reject loudly.
 	if (options.apiKey !== undefined && options.apiKey.trim() === "") {
 		throw new Error("[to11ai/sdk] `apiKey` must not be an empty string.");
 	}
-
-	// R0: validate `projectId` eagerly when supplied (loud throw). An empty /
-	// whitespace-only value is a misconfiguration; reject before any request.
 	if (options.projectId !== undefined && options.projectId.trim() === "") {
 		throw new Error(
 			"[to11ai/sdk] `projectId` must not be an empty string — omit it or pass a valid project id.",
 		);
 	}
-
-	// R1: validate the init-time `env` against the project-environments
-	// registry rule (stricter than gatewayAuthHeaders' empty-only check) so a
-	// malformed env fails locally rather than round-tripping to ENV_NOT_FOUND.
-	if (options.env !== undefined && !ENV_SLUG_REGEX.test(options.env)) {
+	if (options.env !== undefined && options.env.trim() === "") {
 		throw new Error(
-			`[to11ai/sdk] \`env\` must match ${ENV_SLUG_REGEX} (lowercase-kebab, 1-63 chars). Received: ${JSON.stringify(options.env)}`,
+			"[to11ai/sdk] `env` must not be an empty string — omit it or pass a valid env slug.",
 		);
 	}
 
-	// TypeScript's union type prevents callers from providing both, but JS consumers can.
-	// Perform an explicit XOR check at runtime to catch the case where both are supplied.
-	const hasApiKey = options.apiKey !== undefined;
-	const hasGetAccessToken = options.getAccessToken !== undefined;
-	const getAccessToken = options.getAccessToken;
+	// Validate the init-time `env` against the project-environments slug rule so
+	// a malformed env fails locally rather than round-tripping to ENV_NOT_FOUND.
+	if (env !== undefined && !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)}`,
+		);
+	}
 
+	// Exactly one auth source after resolution.
+	const hasApiKey = apiKey !== undefined;
+	const hasGetAccessToken = getAccessToken !== undefined;
 	if (hasApiKey === hasGetAccessToken) {
 		throw new Error(
-			"[to11ai/sdk] Provide exactly one of `apiKey` (server) or `getAccessToken` (browser).",
+			"[to11ai/sdk] Provide exactly one of `apiKey` (or `TO11_API_KEY`) or `getAccessToken`.",
 		);
 	}
 
-	const auth =
-		options.apiKey !== undefined
-			? ({ apiKey: options.apiKey } as const)
-			: ({ getAccessToken: getAccessToken as () => Promise<string> } as const);
+	const auth = hasApiKey
+		? ({ apiKey: apiKey as string } as const)
+		: ({ getAccessToken: getAccessToken as () => Promise<string> } as const);
 
-	// SDK-behavior store (TO11-2100). Env-var overrides (`TO11_SDK_BEHAVIOR_*`)
-	// are read ONLY in a non-browser context so the published browser bundle
-	// never touches `process.env`; init-option overrides apply everywhere.
-	const isBrowser = isDomBrowser || isWorkerBrowser;
-	const processEnv =
-		!isBrowser &&
-		typeof process !== "undefined" &&
-		typeof process.env === "object"
-			? process.env
-			: undefined;
 	const behaviorStore = new BehaviorStore({
 		initOverrides: options.behaviorOverrides,
 		env: processEnv,
 	});
 
 	const transport = new Transport({
-		baseUrl: options.baseUrl,
+		baseUrl,
 		auth,
 		timeoutMs: options.timeoutMs,
 		maxRetries: options.maxRetries,
 		behaviorStore,
 	});
 
-	const prompts = new PromptResource(transport, options.cache, {
-		projectId: options.projectId,
-		env: options.env,
+	const prompts = new PromptResource<F>(transport, options.cache, {
+		projectId,
+		env,
+		format: options.format,
+		onUnknownRole: options.onUnknownRole,
 	});
 	const projectEnvironments = new ProjectEnvironmentResource(transport);
 	const routingRules = new RoutingRulesResource(transport);
 
+	// ── Gateway observability context (session → conversation → turn) ──
+	// These build gateway auth headers, so they require a server-side apiKey +
+	// projectId; fail loudly rather than emit a broken header bag.
+	const gatewayAuthContext = (): TurnAuthContext => {
+		if (apiKey === undefined) {
+			throw new Error(
+				"[to11ai/sdk] session()/turn()/openaiOptions() need an `apiKey` (or `TO11_API_KEY`) — gateway calls require a server-side key. In the browser use `getAccessToken` for control-plane calls only.",
+			);
+		}
+		if (projectId === undefined) {
+			throw new Error(
+				"[to11ai/sdk] session()/turn() need a `projectId` (or `TO11_PROJECT_ID`).",
+			);
+		}
+		return env !== undefined
+			? { apiKey, projectId, env }
+			: { apiKey, projectId };
+	};
+
+	let defaultSession: Session | undefined;
+	const clientDefaultSession = (): Session => {
+		if (defaultSession === undefined) {
+			defaultSession = new Session(gatewayAuthContext());
+		}
+		return defaultSession;
+	};
+
+	// OpenAI's SDK convention puts `/v1` in `baseURL`; the Anthropic SDK appends
+	// `/v1/messages` itself, so it takes the gateway root. Both point at the same
+	// gateway; only the base differs per provider convention. The result is a
+	// spread-ready provider-client options object: managed fields (baseURL/apiKey/
+	// defaultHeaders) are computed+merged, and any other override key passes
+	// through untouched to the provider SDK.
+	const gatewayClientOptions = <
+		T extends ProviderClientOverrides = ProviderClientOverrides,
+	>(
+		defaultBaseURL: string,
+		overrides?: T,
+	): ProviderClientOptions<T> => {
+		if (apiKey === undefined) {
+			throw new Error(
+				"[to11ai/sdk] openaiOptions()/anthropicOptions() need an `apiKey` (or `TO11_API_KEY`) — gateway calls require a server-side key. In the browser use `getAccessToken` for control-plane calls only.",
+			);
+		}
+		if (projectId === undefined) {
+			throw new Error(
+				"[to11ai/sdk] openaiOptions()/anthropicOptions() need a `projectId` (or `TO11_PROJECT_ID`) — it authenticates the gateway call via `x-to11-project-id`.",
+			);
+		}
+		// Static tenant auth for the provider client's defaultHeaders; per-call
+		// trace + prompt provenance still come from `turn().headers(prompt)`.
+		const authHeaders = gatewayAuthHeaders(
+			env !== undefined ? { apiKey, projectId, env } : { apiKey, projectId },
+		);
+		const {
+			apiKey: overrideApiKey,
+			baseURL: overrideBaseURL,
+			defaultHeaders: overrideHeaders,
+			...passthrough
+		} = overrides ?? ({} as T);
+		return {
+			...passthrough,
+			baseURL: overrideBaseURL ?? defaultBaseURL,
+			// Provider (BYOK) key when supplied, else the to11 key as a placeholder
+			// (the managed / server-side-credential path).
+			apiKey: overrideApiKey ?? providerApiKey ?? apiKey,
+			defaultHeaders: { ...authHeaders, ...overrideHeaders },
+		} as ProviderClientOptions<T>;
+	};
+
 	return {
 		prompts,
 		projectEnvironments,
 		routingRules,
 		resolveBehavior: (key, codedDefault) =>
 			behaviorStore.resolve(key, codedDefault),
+		apiKey,
+		gatewayUrl,
+		session: (id) => new Session(gatewayAuthContext(), id),
+		conversation: (id) => clientDefaultSession().conversation(id),
+		turn: () => clientDefaultSession().turn(),
+		openaiOptions: <
+			T extends ProviderClientOverrides = ProviderClientOverrides,
+		>(
+			overrides?: T,
+		) => gatewayClientOptions(`${gatewayUrl}/v1`, overrides),
+		anthropicOptions: <
+			T extends ProviderClientOverrides = ProviderClientOverrides,
+		>(
+			overrides?: T,
+		) => gatewayClientOptions(gatewayUrl, overrides),
 	};
 }

package/src/config.ts

@@ -0,0 +1,13 @@
+/**
+ * Internal default endpoints. Deliberately NOT re-exported from the package
+ * root: `createClient` resolves the URLs (option → env → default) and exposes
+ * the resolved data-plane URL as `to11.gatewayUrl`, so app code never imports a
+ * bare URL constant. Keeping these out of the public surface avoids a JS-only
+ * exported symbol that would need a Python-parity record.
+ */
+
+export const DEFAULT_API_URL = "https://api.to11.ai";
+// The gateway *root* — no `/v1` version path. Provider helpers add the path each
+// provider SDK expects (`openaiOptions()` appends `/v1`; the Anthropic SDK adds
+// `/v1/messages` itself), so users configure only the host.
+export const DEFAULT_GATEWAY_URL = "https://gw.to11.ai";