@to11ai/sdk 1.1.0 → 2.0.0-rc.2

package/dist/client.cjs

@@ -39,16 +39,19 @@ var __export = (target, all) => {
 // src/client.ts
 var exports_client = {};
 __export(exports_client, {
-  gatewayPromptHeaders: () => import_gateway.gatewayPromptHeaders,
-  gatewayAuthHeaders: () => import_gateway.gatewayAuthHeaders,
+  gatewayPromptHeaders: () => import_gateway2.gatewayPromptHeaders,
+  gatewayAuthHeaders: () => import_gateway2.gatewayAuthHeaders,
   envVarNameForKey: () => import_store2.envVarNameForKey,
   createClient: () => createClient,
+  UnknownRoleError: () => import_errors.UnknownRoleError,
+  Turn: () => import_context2.Turn,
   To11aiValidationError: () => import_errors.To11aiValidationError,
   To11aiRateLimitError: () => import_errors.To11aiRateLimitError,
   To11aiNetworkError: () => import_errors.To11aiNetworkError,
   To11aiError: () => import_errors.To11aiError,
   To11aiAuthError: () => import_errors.To11aiAuthError,
   To11aiApiError: () => import_errors.To11aiApiError,
+  Session: () => import_context2.Session,
   RuleVersionInvalidSnapshotError: () => import_errors.RuleVersionInvalidSnapshotError,
   RuleNotFoundError: () => import_errors.RuleNotFoundError,
   RoutingRulesResource: () => import_resource6.RoutingRulesResource,
@@ -64,29 +67,50 @@ __export(exports_client, {
   EnvNotFoundError: () => import_errors.EnvNotFoundError,
   EnvNotEnabledForProviderError: () => import_errors.EnvNotEnabledForProviderError,
   ENV_SLUG_REGEX: () => import_types2.ENV_SLUG_REGEX,
+  Conversation: () => import_context2.Conversation,
   BehaviorStore: () => import_store2.BehaviorStore,
   AmbiguousEnvLabelsError: () => import_errors.AmbiguousEnvLabelsError
 });
 module.exports = __toCommonJS(exports_client);
 var import_store = require("./behaviors/store");
+var import_config = require("./config");
+var import_context = require("./context");
+var import_gateway = require("./gateway");
 var import_resource = require("./projectEnvironments/resource");
 var import_resource2 = require("./prompts/resource");
 var import_types = require("./prompts/types");
 var import_resource3 = require("./routingRules/resource");
 var import_transport = require("./transport");
 var import_store2 = require("./behaviors/store");
+var import_context2 = require("./context");
 var import_errors = require("./errors");
-var import_gateway = require("./gateway");
+var import_gateway2 = require("./gateway");
 var import_resource4 = require("./projectEnvironments/resource");
 var import_resource5 = require("./prompts/resource");
 var import_types2 = require("./prompts/types");
 var import_resource6 = require("./routingRules/resource");
-function createClient(options) {
+function createClient(options = {}) {
   const isDomBrowser = typeof globalThis === "object" && typeof globalThis.document !== "undefined";
   const workerLikeGlobal = globalThis;
   const isBunMainThread = workerLikeGlobal.Bun?.isMainThread === true;
   const isWorkerBrowser = typeof globalThis === "object" && (typeof workerLikeGlobal.importScripts === "function" || !isBunMainThread && typeof workerLikeGlobal.postMessage === "function" && typeof workerLikeGlobal.onmessage !== "undefined");
-  if ((isDomBrowser || isWorkerBrowser) && options.apiKey !== undefined) {
+  const isBrowser = isDomBrowser || isWorkerBrowser;
+  const processEnv = !isBrowser && typeof process !== "undefined" && typeof process.env === "object" ? process.env : undefined;
+  const pick = (opt, envKey) => {
+    const fromOpt = opt?.trim();
+    if (fromOpt)
+      return fromOpt;
+    const fromEnv = processEnv?.[envKey]?.trim();
+    return fromEnv ? fromEnv : undefined;
+  };
+  const baseUrl = pick(options.baseUrl, "TO11_API_URL") ?? import_config.DEFAULT_API_URL;
+  const gatewayUrl = (pick(options.gatewayUrl, "TO11_GATEWAY_URL") ?? import_config.DEFAULT_GATEWAY_URL).replace(/\/+$/, "").replace(/\/v1$/, "");
+  const getAccessToken = options.getAccessToken;
+  const apiKey = getAccessToken !== undefined ? options.apiKey : pick(options.apiKey, "TO11_API_KEY");
+  const projectId = pick(options.projectId, "TO11_PROJECT_ID");
+  const env = pick(options.env, "TO11_ENV");
+  const providerApiKey = options.providerApiKey?.trim() || undefined;
+  if (isBrowser && options.apiKey !== undefined) {
     throw new Error("[to11ai/sdk] Do not use `apiKey` in browser contexts — use `getAccessToken` instead.");
   }
   if (options.apiKey !== undefined && options.apiKey.trim() === "") {
@@ -95,39 +119,85 @@ function createClient(options) {
   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.");
   }
-  if (options.env !== undefined && !import_types.ENV_SLUG_REGEX.test(options.env)) {
-    throw new Error(`[to11ai/sdk] \`env\` must match ${import_types.ENV_SLUG_REGEX} (lowercase-kebab, 1-63 chars). Received: ${JSON.stringify(options.env)}`);
+  if (options.env !== undefined && options.env.trim() === "") {
+    throw new Error("[to11ai/sdk] `env` must not be an empty string — omit it or pass a valid env slug.");
   }
-  const hasApiKey = options.apiKey !== undefined;
-  const hasGetAccessToken = options.getAccessToken !== undefined;
-  const getAccessToken = options.getAccessToken;
+  if (env !== undefined && !import_types.ENV_SLUG_REGEX.test(env)) {
+    throw new Error(`[to11ai/sdk] \`env\` must match ${import_types.ENV_SLUG_REGEX} (lowercase-kebab, 1-63 chars). Received: ${JSON.stringify(env)}`);
+  }
+  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).");
+    throw new Error("[to11ai/sdk] Provide exactly one of `apiKey` (or `TO11_API_KEY`) or `getAccessToken`.");
   }
-  const auth = options.apiKey !== undefined ? { apiKey: options.apiKey } : { getAccessToken };
-  const isBrowser = isDomBrowser || isWorkerBrowser;
-  const processEnv = !isBrowser && typeof process !== "undefined" && typeof process.env === "object" ? process.env : undefined;
+  const auth = hasApiKey ? { apiKey } : { getAccessToken };
   const behaviorStore = new import_store.BehaviorStore({
     initOverrides: options.behaviorOverrides,
     env: processEnv
   });
   const transport = new import_transport.Transport({
-    baseUrl: options.baseUrl,
+    baseUrl,
     auth,
     timeoutMs: options.timeoutMs,
     maxRetries: options.maxRetries,
     behaviorStore
   });
   const prompts = new import_resource2.PromptResource(transport, options.cache, {
-    projectId: options.projectId,
-    env: options.env
+    projectId,
+    env,
+    format: options.format,
+    onUnknownRole: options.onUnknownRole
   });
   const projectEnvironments = new import_resource.ProjectEnvironmentResource(transport);
   const routingRules = new import_resource3.RoutingRulesResource(transport);
+  const gatewayAuthContext = () => {
+    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;
+  const clientDefaultSession = () => {
+    if (defaultSession === undefined) {
+      defaultSession = new import_context.Session(gatewayAuthContext());
+    }
+    return defaultSession;
+  };
+  const gatewayClientOptions = (defaultBaseURL, overrides) => {
+    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`.");
+    }
+    const authHeaders = import_gateway.gatewayAuthHeaders(env !== undefined ? { apiKey, projectId, env } : { apiKey, projectId });
+    const {
+      apiKey: overrideApiKey,
+      baseURL: overrideBaseURL,
+      defaultHeaders: overrideHeaders,
+      ...passthrough
+    } = overrides ?? {};
+    return {
+      ...passthrough,
+      baseURL: overrideBaseURL ?? defaultBaseURL,
+      apiKey: overrideApiKey ?? providerApiKey ?? apiKey,
+      defaultHeaders: { ...authHeaders, ...overrideHeaders }
+    };
+  };
   return {
     prompts,
     projectEnvironments,
     routingRules,
-    resolveBehavior: (key, codedDefault) => behaviorStore.resolve(key, codedDefault)
+    resolveBehavior: (key, codedDefault) => behaviorStore.resolve(key, codedDefault),
+    apiKey,
+    gatewayUrl,
+    session: (id) => new import_context.Session(gatewayAuthContext(), id),
+    conversation: (id) => clientDefaultSession().conversation(id),
+    turn: () => clientDefaultSession().turn(),
+    openaiOptions: (overrides) => gatewayClientOptions(`${gatewayUrl}/v1`, overrides),
+    anthropicOptions: (overrides) => gatewayClientOptions(gatewayUrl, overrides)
   };
 }

package/dist/client.d.ts

@@ -1,69 +1,116 @@
+import { type Conversation, Session, type Turn } from "./context";
 import { ProjectEnvironmentResource } from "./projectEnvironments/resource";
 import type { CacheConfig } from "./prompts/cache";
 import { PromptResource } from "./prompts/resource";
+import { type RenderFormat, type UnknownRoleMode } from "./prompts/types";
 import { RoutingRulesResource } from "./routingRules/resource";
 export { BehaviorStore, type BehaviorStoreOptions, envVarNameForKey, type SdkBehaviorEnvelope, } from "./behaviors/store";
+export type { TurnAuthContext } from "./context";
+export { Conversation, Session, Turn } from "./context";
 export type { AmbiguousEnvLabelsReason, EnvNotFoundReason, NoActiveReleaseReason, NoApplicableRouteReason, PromptNotFoundReason, PromptPolicyViolationReason, } from "./errors";
-export { AmbiguousEnvLabelsError, EnvNotEnabledForProviderError, EnvNotFoundError, NoActiveReleaseError, NoApplicableRouteError, PromptLabelNotRegisteredError, PromptNotFoundError, PromptPolicyViolationError, RuleNotFoundError, RuleVersionInvalidSnapshotError, To11aiApiError, To11aiAuthError, To11aiError, To11aiNetworkError, To11aiRateLimitError, To11aiValidationError, } from "./errors";
-export type { GatewayAuthOptions } from "./gateway";
+export { AmbiguousEnvLabelsError, EnvNotEnabledForProviderError, EnvNotFoundError, NoActiveReleaseError, NoApplicableRouteError, PromptLabelNotRegisteredError, PromptNotFoundError, PromptPolicyViolationError, RuleNotFoundError, RuleVersionInvalidSnapshotError, To11aiApiError, To11aiAuthError, To11aiError, To11aiNetworkError, To11aiRateLimitError, To11aiValidationError, UnknownRoleError, } from "./errors";
+export type { ConvertMessagesOptions, GatewayAuthOptions } from "./gateway";
 export { gatewayAuthHeaders, gatewayPromptHeaders } from "./gateway";
 export type { ArchiveProjectEnvironmentInput, ArchiveProjectEnvironmentResult, CreateProjectEnvironmentInput, CreateProjectEnvironmentResult, GetProjectEnvironmentInput, GetProjectEnvironmentResult, ListProjectEnvironmentsInput, ListProjectEnvironmentsResult, LivePointerCounts, ProjectEnvironment, RestoreProjectEnvironmentInput, RestoreProjectEnvironmentResult, UpdateProjectEnvironmentInput, UpdateProjectEnvironmentResult, } from "./projectEnvironments/resource";
 export { ProjectEnvironmentResource } from "./projectEnvironments/resource";
 export type { CacheConfig } from "./prompts/cache";
 export type { PromptResourceConfig } from "./prompts/resource";
 export { PromptResource } from "./prompts/resource";
-export type { BlockRenderRecord, DeveloperRole, FetchedPrompt, FetchPromptOptions, RenderedChatMessage, RenderedPrompt, ResolvedPrompt, ResolvedPromptEnvelope, } from "./prompts/types";
+export type { AnthropicRenderedPrompt, OpenAiRenderedPrompt, PromptConfig, PromptMetadata, RenderResult, } from "./prompts/shape";
+export type { BlockRenderRecord, RenderedChatMessage, RenderedPrompt, RenderFormat, RenderOptions, ResolvedPrompt, ResolvedPromptEnvelope, UnknownRoleMode, } from "./prompts/types";
 export { ENV_SLUG_REGEX } from "./prompts/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 "./routingRules/resource";
 export { RoutingRuleReleaseResource, RoutingRulesResource, RoutingRuleVersionResource, } from "./routingRules/resource";
 export type { Transport } from "./transport";
-interface ServerAuthOptions {
-    /** API key for server-side use. Must not be used in browser contexts. */
-    apiKey: string;
-    getAccessToken?: never;
-}
-interface BrowserAuthOptions {
+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>;
-    apiKey?: never;
-}
-type AuthOptions = ServerAuthOptions | BrowserAuthOptions;
-export type ClientOptions = AuthOptions & {
-    baseUrl: string;
+    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>;
+}
+/**
+ * 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>;
 };
-export interface To11aiClient {
-    readonly prompts: PromptResource;
+export interface To11aiClient<F extends RenderFormat | undefined = undefined> {
+    readonly prompts: PromptResource<F>;
     readonly projectEnvironments: ProjectEnvironmentResource;
     readonly routingRules: RoutingRulesResource;
     /**
@@ -76,12 +123,67 @@ 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>;
 }
 /**
- * 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.
+ *
+ * @example Minimal setup (single call)
+ * import { createClient } from "@to11ai/sdk";
+ * import OpenAI from "openai";
  *
- * Auth mode is inferred from options:
- *  - `apiKey`          → server-side; rejected in browser contexts.
- *  - `getAccessToken`  → browser-safe; token fetched per request.
+ * 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 declare function createClient(options: ClientOptions): To11aiClient;
+export declare function createClient<const F extends RenderFormat | undefined = undefined>(options?: Omit<ClientOptions, "format"> & {
+    format?: F;
+}): To11aiClient<F>;

package/dist/client.js

@@ -1,14 +1,22 @@
 // src/client.ts
 import { BehaviorStore } from "./behaviors/store";
+import { DEFAULT_API_URL, DEFAULT_GATEWAY_URL } from "./config";
+import {
+  Session
+} from "./context";
+import { gatewayAuthHeaders } from "./gateway";
 import { ProjectEnvironmentResource } from "./projectEnvironments/resource";
 import { PromptResource } from "./prompts/resource";
-import { ENV_SLUG_REGEX } from "./prompts/types";
+import {
+  ENV_SLUG_REGEX
+} from "./prompts/types";
 import { RoutingRulesResource } from "./routingRules/resource";
 import { Transport } from "./transport";
 import {
   BehaviorStore as BehaviorStore2,
   envVarNameForKey
 } from "./behaviors/store";
+import { Conversation, Session as Session2, Turn } from "./context";
 import {
   AmbiguousEnvLabelsError,
   EnvNotEnabledForProviderError,
@@ -25,9 +33,10 @@ import {
   To11aiError,
   To11aiNetworkError,
   To11aiRateLimitError,
-  To11aiValidationError
+  To11aiValidationError,
+  UnknownRoleError
 } from "./errors";
-import { gatewayAuthHeaders, gatewayPromptHeaders } from "./gateway";
+import { gatewayAuthHeaders as gatewayAuthHeaders2, gatewayPromptHeaders } from "./gateway";
 import { ProjectEnvironmentResource as ProjectEnvironmentResource2 } from "./projectEnvironments/resource";
 import { PromptResource as PromptResource2 } from "./prompts/resource";
 import { ENV_SLUG_REGEX as ENV_SLUG_REGEX2 } from "./prompts/types";
@@ -36,12 +45,28 @@ import {
   RoutingRulesResource as RoutingRulesResource2,
   RoutingRuleVersionResource
 } from "./routingRules/resource";
-function createClient(options) {
+function createClient(options = {}) {
   const isDomBrowser = typeof globalThis === "object" && typeof globalThis.document !== "undefined";
   const workerLikeGlobal = globalThis;
   const isBunMainThread = workerLikeGlobal.Bun?.isMainThread === true;
   const isWorkerBrowser = typeof globalThis === "object" && (typeof workerLikeGlobal.importScripts === "function" || !isBunMainThread && typeof workerLikeGlobal.postMessage === "function" && typeof workerLikeGlobal.onmessage !== "undefined");
-  if ((isDomBrowser || isWorkerBrowser) && options.apiKey !== undefined) {
+  const isBrowser = isDomBrowser || isWorkerBrowser;
+  const processEnv = !isBrowser && typeof process !== "undefined" && typeof process.env === "object" ? process.env : undefined;
+  const pick = (opt, envKey) => {
+    const fromOpt = opt?.trim();
+    if (fromOpt)
+      return fromOpt;
+    const fromEnv = processEnv?.[envKey]?.trim();
+    return fromEnv ? fromEnv : undefined;
+  };
+  const baseUrl = pick(options.baseUrl, "TO11_API_URL") ?? DEFAULT_API_URL;
+  const gatewayUrl = (pick(options.gatewayUrl, "TO11_GATEWAY_URL") ?? DEFAULT_GATEWAY_URL).replace(/\/+$/, "").replace(/\/v1$/, "");
+  const getAccessToken = options.getAccessToken;
+  const apiKey = getAccessToken !== undefined ? options.apiKey : pick(options.apiKey, "TO11_API_KEY");
+  const projectId = pick(options.projectId, "TO11_PROJECT_ID");
+  const env = pick(options.env, "TO11_ENV");
+  const providerApiKey = options.providerApiKey?.trim() || undefined;
+  if (isBrowser && options.apiKey !== undefined) {
     throw new Error("[to11ai/sdk] Do not use `apiKey` in browser contexts — use `getAccessToken` instead.");
   }
   if (options.apiKey !== undefined && options.apiKey.trim() === "") {
@@ -50,53 +75,102 @@ function createClient(options) {
   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.");
   }
-  if (options.env !== undefined && !ENV_SLUG_REGEX.test(options.env)) {
-    throw new Error(`[to11ai/sdk] \`env\` must match ${ENV_SLUG_REGEX} (lowercase-kebab, 1-63 chars). Received: ${JSON.stringify(options.env)}`);
+  if (options.env !== undefined && options.env.trim() === "") {
+    throw new Error("[to11ai/sdk] `env` must not be an empty string — omit it or pass a valid env slug.");
   }
-  const hasApiKey = options.apiKey !== undefined;
-  const hasGetAccessToken = options.getAccessToken !== undefined;
-  const getAccessToken = options.getAccessToken;
+  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)}`);
+  }
+  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).");
+    throw new Error("[to11ai/sdk] Provide exactly one of `apiKey` (or `TO11_API_KEY`) or `getAccessToken`.");
   }
-  const auth = options.apiKey !== undefined ? { apiKey: options.apiKey } : { getAccessToken };
-  const isBrowser = isDomBrowser || isWorkerBrowser;
-  const processEnv = !isBrowser && typeof process !== "undefined" && typeof process.env === "object" ? process.env : undefined;
+  const auth = hasApiKey ? { apiKey } : { getAccessToken };
   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
+    projectId,
+    env,
+    format: options.format,
+    onUnknownRole: options.onUnknownRole
   });
   const projectEnvironments = new ProjectEnvironmentResource(transport);
   const routingRules = new RoutingRulesResource(transport);
+  const gatewayAuthContext = () => {
+    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;
+  const clientDefaultSession = () => {
+    if (defaultSession === undefined) {
+      defaultSession = new Session(gatewayAuthContext());
+    }
+    return defaultSession;
+  };
+  const gatewayClientOptions = (defaultBaseURL, overrides) => {
+    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`.");
+    }
+    const authHeaders = gatewayAuthHeaders(env !== undefined ? { apiKey, projectId, env } : { apiKey, projectId });
+    const {
+      apiKey: overrideApiKey,
+      baseURL: overrideBaseURL,
+      defaultHeaders: overrideHeaders,
+      ...passthrough
+    } = overrides ?? {};
+    return {
+      ...passthrough,
+      baseURL: overrideBaseURL ?? defaultBaseURL,
+      apiKey: overrideApiKey ?? providerApiKey ?? apiKey,
+      defaultHeaders: { ...authHeaders, ...overrideHeaders }
+    };
+  };
   return {
     prompts,
     projectEnvironments,
     routingRules,
-    resolveBehavior: (key, codedDefault) => behaviorStore.resolve(key, codedDefault)
+    resolveBehavior: (key, codedDefault) => behaviorStore.resolve(key, codedDefault),
+    apiKey,
+    gatewayUrl,
+    session: (id) => new Session(gatewayAuthContext(), id),
+    conversation: (id) => clientDefaultSession().conversation(id),
+    turn: () => clientDefaultSession().turn(),
+    openaiOptions: (overrides) => gatewayClientOptions(`${gatewayUrl}/v1`, overrides),
+    anthropicOptions: (overrides) => gatewayClientOptions(gatewayUrl, overrides)
   };
 }
 export {
   gatewayPromptHeaders,
-  gatewayAuthHeaders,
+  gatewayAuthHeaders2 as gatewayAuthHeaders,
   envVarNameForKey,
   createClient,
+  UnknownRoleError,
+  Turn,
   To11aiValidationError,
   To11aiRateLimitError,
   To11aiNetworkError,
   To11aiError,
   To11aiAuthError,
   To11aiApiError,
+  Session2 as Session,
   RuleVersionInvalidSnapshotError,
   RuleNotFoundError,
   RoutingRulesResource2 as RoutingRulesResource,
@@ -112,6 +186,7 @@ export {
   EnvNotFoundError,
   EnvNotEnabledForProviderError,
   ENV_SLUG_REGEX2 as ENV_SLUG_REGEX,
+  Conversation,
   BehaviorStore2 as BehaviorStore,
   AmbiguousEnvLabelsError
 };

package/dist/config.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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 declare const DEFAULT_API_URL = "https://api.to11.ai";
+export declare const DEFAULT_GATEWAY_URL = "https://gw.to11.ai";