@to11ai/sdk 1.1.0 → 2.0.0-rc.10

package/README.md

@@ -2,325 +2,166 @@
 
 JavaScript/TypeScript SDK for [to11ai](https://to11ai.com) — the AI engineering platform for prompt management, tracing, and evals.
 
+Use it to **render managed prompts** at runtime, **wire your own provider client** (OpenAI, Anthropic, …) to the to11 gateway with the right auth/trace headers, and group model calls into **sessions, conversations, and turns** for tracing.
+
 Ships ESM, CommonJS, and raw TypeScript source in the same package. Runtimes and bundlers pick the right variant automatically.
 
 ## Installation
 
 ```bash
 npm install @to11ai/sdk
-# or
-bun add @to11ai/sdk
-# or
-pnpm add @to11ai/sdk
-# or
-yarn add @to11ai/sdk
+# or: bun add @to11ai/sdk · pnpm add @to11ai/sdk · yarn add @to11ai/sdk
 ```
 
-## Runtime support
-
-| Runtime / loader            | Resolves to          | Notes                                         |
-| --------------------------- | -------------------- | --------------------------------------------- |
-| Node.js (ESM: `import`)     | `dist/*.js`          | Bundled ESM, Node-targeted                    |
-| Node.js (CJS: `require`)    | `dist/*.cjs`         | Bundled CommonJS                              |
-| TypeScript (type resolution)| `dist/*.d.ts`        | Declarations for editor + tsc                 |
-| Bun                         | `src/*.ts`           | Raw source — zero build overhead, full maps  |
-| Deno                        | `src/*.ts`           | Raw source                                    |
-| Browsers (via bundler)      | `dist/*.js`          | Tree-shakeable ESM                            |
-| Workers / edge runtimes     | `dist/*.js`          | ESM, Node-compatible                          |
+Runs anywhere Node, Bun, Deno, or edge runs — servers, CLIs, and backend jobs. Not for browsers: a to11 API key carries gateway access and must never ship in client-side code.
 
-Resolution is driven by the package's `exports` conditional map. The tarball ships both `dist/` (compiled) and `src/` (TypeScript) so runtimes that support raw `.ts` can skip the build step.
+## Quick start
 
-## Getting started
+Create a client, render a prompt for the current environment, and send it through the gateway with your normal provider client:
 
 ```typescript
 import { createClient } from "@to11ai/sdk";
-
-const client = createClient({
-  baseUrl: "https://api.to11ai.com",
-  apiKey: process.env.TO11AI_API_KEY!,
+import OpenAI from "openai";
+
+const to11 = createClient({
+  // `process.env` is the Node/Bun form; on Deno/edge use that runtime's env API —
+  // or omit these entirely, since the SDK reads the matching `TO11_*` vars itself.
+  baseUrl: process.env.TO11_API_URL,       // → https://api.to11.ai
+  apiKey: process.env.TO11_API_KEY,        // → TO11_API_KEY
+  projectId: process.env.TO11_PROJECT_ID,  // → TO11_PROJECT_ID
+  env: process.env.TO11_ENV,               // "prod", "staging", … → TO11_ENV
 });
 
-const result = await client.prompts.resolve({
-  projectId: "proj_abc123",
-  slug: "chat-system-prompt",
-  labels: ["production"],
-  variables: { userName: "Alice" },
+// Render a released prompt for the client's project + environment.
+const prompt = await to11.prompts.render("welcome-message", {
+  variables: { name: "Ada" },
+  format: "openai", // omit for the provider-neutral result
 });
 
-console.log(result.rendered); // { format: "text", text: "Hello, Alice!" }
+// Point your provider client at the gateway and send it.
+const openai = new OpenAI(to11.openaiOptions());
+const completion = await openai.chat.completions.create(
+  { ...prompt.config, messages: prompt.messages },
+  { headers: to11.turn().headers(prompt) }, // auth + trace id + prompt provenance
+);
 ```
 
-## Client construction
+`prompt.config` carries the model parameters, `prompt.messages` the rendered messages, and `turn().headers(prompt)` the headers that authenticate the gateway call and record which prompt produced the trace. You never assemble a `provider::model` string or merge auth headers by hand.
 
-### Server-side (API key)
+## Configuring the client
 
-Use an API key for server-side Node.js, Bun, Deno, or edge runtimes where a secret is safe:
+`createClient(options)` is a factory (call it directly, no `new`). Each URL/credential resolves **option → environment variable → built-in default**, so a server app can construct it from the environment alone.
 
-```typescript
-import { createClient } from "@to11ai/sdk";
+| Option | Resolves from | Default |
+| --- | --- | --- |
+| `baseUrl` | option → `TO11_API_URL` | `https://api.to11.ai` |
+| `gatewayUrl` | option → `TO11_GATEWAY_URL` | `https://gw.to11.ai` |
+| `apiKey` | option → `TO11_API_KEY` | — (throws if constructed in a browser) |
+| `projectId` | option → `TO11_PROJECT_ID` | — |
+| `env` | option → `TO11_ENV` | — (must match `^[a-z0-9-]{1,63}$`) |
+| `providerApiKey` | option | — (BYOK; carried by `openaiOptions()`/`anthropicOptions()`) |
+| `format` | option | — (`"openai"` \| `"anthropic"`; omit for the neutral result) |
+| `onUnknownRole` | option | `"drop"` |
+| `timeoutMs` / `maxRetries` | option | `30000` / `3` |
 
-const client = createClient({
-  baseUrl: "https://api.to11ai.com",
-  apiKey: process.env.TO11AI_API_KEY!,
-});
-```
+> **Keep credentials server-side.** A to11 API key carries gateway access, so it must never ship in browser code — the SDK throws if you construct a client with `apiKey` in a browser context (like OpenAI's `dangerouslyAllowBrowser`). The same goes for a `providerApiKey` (BYOK). Use the SDK from a server, CLI, or backend job.
 
-### Browser-side (access token callback)
+The client exposes read-only accessors for the resolved values — **`to11.baseUrl`**, **`to11.gatewayUrl`**, **`to11.apiKey`**, **`to11.projectId`**, and **`to11.env`**. Use the non-secret ones (`baseUrl`/`gatewayUrl`/`projectId`/`env`) for diagnostics; `apiKey` is exposed to build manual auth headers — treat it as a secret and never log it. `providerApiKey` (BYOK) is deliberately **not** exposed back off the client.
 
-Use a `getAccessToken` callback to avoid shipping a static secret to the browser:
+## Rendering prompts
 
-```typescript
-import { createClient } from "@to11ai/sdk";
+`prompts.render(slug, options?)` resolves the released prompt for the client's `projectId` + `env` in one request. Set `format` (on the client or per call) to get a result shaped for that provider; omit it for the provider-neutral result.
 
-const client = createClient({
-  baseUrl: "https://api.to11ai.com",
-  getAccessToken: async () => {
-    const res = await fetch("/api/auth/token");
-    const { token } = await res.json();
-    return token;
-  },
+```typescript
+const prompt = await to11.prompts.render("weather-concierge", {
+  variables: { city: "New York", units: "fahrenheit" },
+  // label?: label to resolve for this call (defaults to the client's env)
+  // subject?: a stable id so a weighted release pins the same caller to a variant
+  // fallback?: a previously-rendered RenderedPrompt served on a network error
+  // format?: "openai" | "anthropic"
 });
 ```
 
-Passing `apiKey` in a browser context throws immediately to prevent accidental secret exposure.
-
-## Prompt resolution
+- **With `format`** the result is spread-ready: `{ messages, config, metadata }` (`config` = the version's model params; `metadata` = prompt/version/release provenance).
+- **Without `format`** you get the neutral **`RenderedPrompt`**: `messages`, `tools`, `toolChoice`, `promptId`, `version`, `versionId`, `releaseId`, `variantName`, `contentHash`, `label`, `slug`, `blockRenderRecord`, and `modelConfig`. This is the path for providers the shaper doesn't cover (Vercel AI, LangChain) or for driving one prompt through more than one provider.
 
-`prompts.resolve()` is the primary use case — it fetches a prompt by slug, applies labels to select a version, renders Liquid template variables, and returns the final text or chat messages.
+Authored `developer` blocks come back as-is; the SDK maps them per provider (OpenAI keeps `developer`; Anthropic folds `system`/`developer` into the top-level `system`). `onUnknownRole` (`"drop"` default, `"warn"`, `"error"`) controls how an unrecognized role is handled during provider conversion.
 
-```typescript
-const result = await client.prompts.resolve({
-  projectId: "proj_abc123",
-  slug: "summarise-article",
-  labels: ["production", "en"],
-  variables: {
-    article: "OpenAI releases GPT-5...",
-    maxLength: 200,
-  },
-});
+> Prompts render as **chat blocks**. The pre-2.0 `resolve()` and the `text` render format have been removed — use `render()` with a `label` (the client's `env` is the default; env is just a label value).
 
-if (result.rendered.format === "text") {
-  console.log(result.rendered.text);
-} else {
-  // chat format
-  for (const msg of result.rendered.messages) {
-    console.log(`[${msg.role}] ${msg.content}`);
-  }
-}
-```
+## Sending through the gateway
 
-## All prompt methods
-
-| Method | Description |
-|---|---|
-| `prompts.resolve(input)` | Fetch a prompt by slug + labels, render variables, return rendered output. Cached by default. |
-| `prompts.create(input)` | Create a new prompt (name, slug, description, tags). |
-| `prompts.list(input)` | List prompts in a project with optional pagination. |
-| `prompts.get(input)` | Get a single prompt by ID. |
-| `prompts.update(input)` | Update prompt metadata (name, description, tags). |
-| `prompts.archive(input)` | Archive a prompt (soft delete). |
-| `prompts.createVersion(input)` | Create a new version for an existing prompt. |
-| `prompts.listVersions(input)` | List all versions of a prompt. |
-| `prompts.getVersion(input)` | Get a specific version by version number. |
-| `prompts.moveLabel(input)` | Point a label (e.g. `production`) at a specific version. |
-| `prompts.listLabels(input)` | List all label pointers for a prompt. |
-| `prompts.listProjectLabels(input)` | List the project-level label registry. Pass `includeArchived: true` for soft-deleted rows. |
-| `prompts.createProjectLabel(input)` | Create a new project label (requires `project:manage_labels`). |
-| `prompts.getProjectLabel(input)` | Get a single project label by name. |
-| `prompts.updateProjectLabel(input)` | Update a project label's `isDefault`, `description`, or `displayColor`. |
-| `prompts.deleteProjectLabel(input)` | Archive (soft-delete) a project label. Returns the archived row. |
-| `prompts.listProjectLabelUsages(input)` | List every prompt currently pointed at by a given project label. |
-| `prompts.listLabelEvents(input)` | List immutable label-movement events. Polymorphic by `scope`: `"label"`, `"prompt"`, or `"project"`. |
-
-All methods require at minimum `projectId` and the relevant resource identifier(s).
-
-## Project label registry
-
-The project label registry stores the canonical list of labels available in a project (e.g. `production`, `staging`, `experiment`). When strict-mode is enabled on a project, `prompts.moveLabel()` only accepts labels that exist in the registry.
+`openaiOptions()` / `anthropicOptions()` return spread-ready options (`{ baseURL, apiKey, defaultHeaders }`) for a provider client pointed at the gateway; `defaultHeaders` carries the static tenant auth. Add `turn().headers(prompt)` per call for the trace id and prompt provenance:
 
 ```typescript
-// Create a new project label
-const label = await client.prompts.createProjectLabel({
-  projectId: "proj_abc123",
-  label: "canary",
-  isDefault: false,
-  description: "5% traffic shadow",
-  displayColor: "amber",
-});
-
-// List the project's labels (excludes archived rows by default)
-const labels = await client.prompts.listProjectLabels({
-  projectId: "proj_abc123",
-});
-
-// Reverse-lookup: which prompts currently point at this label?
-const usages = await client.prompts.listProjectLabelUsages({
-  projectId: "proj_abc123",
-  label: "production",
-});
+import Anthropic from "@anthropic-ai/sdk";
+const anthropic = new Anthropic(to11.anthropicOptions());
+```
 
-// Event history — three scopes via one polymorphic method
-const allEvents = await client.prompts.listLabelEvents({
-  scope: "project",
-  projectId: "proj_abc123",
-  page: 1,
-  limit: 50,
-  since: "2024-01-01T00:00:00Z",
-});
+By default the gateway runs the call on the project's configured provider credential (managed). For **BYOK**, set `providerApiKey` on `createClient` (or pass `apiKey` to the helper per call). For Vercel AI / LangChain, build the base URL from `to11.gatewayUrl` and attach `turn().headers()` yourself.
 
-const promptEvents = await client.prompts.listLabelEvents({
-  scope: "prompt",
-  projectId: "proj_abc123",
-  promptId: "prompt_xyz789",
-  label: "production", // optional filter
-});
+## Sessions, conversations & turns
 
-const labelEvents = await client.prompts.listLabelEvents({
-  scope: "label",
-  projectId: "proj_abc123",
-  promptId: "prompt_xyz789",
-  label: "production",
-});
-```
+Group model calls for tracing. `to11.turn()` uses the client's default session; create explicit ones with `to11.session(id?)` / `to11.conversation(id?)`. `turn().headers(prompt?)` emits the session/conversation/`traceparent` headers (plus prompt provenance when a rendered prompt is passed).
 
-## Error handling
+## Managing prompts, versions & labels
 
-The SDK exports six typed error classes. Catch `To11aiError` as a base or catch specific subclasses:
+Beyond `render()`, the `prompts` namespace covers the control-plane lifecycle. **All of these default `projectId` from the client** — pass it per call only to override:
 
 ```typescript
-import {
-  To11aiError,
-  To11aiApiError,
-  To11aiAuthError,
-  To11aiRateLimitError,
-  To11aiValidationError,
-  To11aiNetworkError,
-  PromptLabelNotRegisteredError,
-} from "@to11ai/sdk";
+const to11 = createClient({ apiKey, projectId: "proj_abc123" });
 
-try {
-  const result = await client.prompts.resolve({ ... });
-} catch (err) {
-  if (err instanceof To11aiRateLimitError) {
-    const retryAfter = err.retryAfterSeconds ?? 60;
-    console.warn(`Rate limited — retry in ${retryAfter}s`);
-  } else if (err instanceof To11aiAuthError) {
-    console.error("Authentication failed:", err.statusCode, err.message);
-  } else if (err instanceof To11aiValidationError) {
-    console.error("Bad request:", err.message, err.details);
-  } else if (err instanceof To11aiNetworkError) {
-    console.error("Network failure:", err.message, err.cause);
-  } else if (err instanceof To11aiApiError) {
-    console.error(`API error ${err.statusCode} [${err.errorCode}]:`, err.message);
-  } else {
-    throw err;
-  }
-}
+await to11.prompts.list();                              // uses the bound projectId
+await to11.prompts.get({ promptId: "prompt_1" });
+await to11.prompts.getVersion({ promptId: "prompt_1", versionNumber: 3 });
+await to11.prompts.moveLabel({ promptId: "prompt_1", label: "production", versionId: "ver_9", reason: "promote" });
 ```
 
-### Strict-mode label rejection
+Full set: `create`, `list`, `get`, `update`, `archive`, `createVersion`, `listVersions`, `getVersion`, `moveLabel`, `listLabels`, and the project-label registry (`listProjectLabels`, `createProjectLabel`, `getProjectLabel`, `updateProjectLabel`, `deleteProjectLabel`, `listProjectLabelUsages`, `listLabelEvents`). `client.projectEnvironments` and `client.routingRules` expose the environment and routing-rule surfaces.
 
-When a project enables `enforce_label_registry`, calling `moveLabel` with a label that's not in the registry fails with a typed `PromptLabelNotRegisteredError`. Catch it explicitly to prompt the user to create the label first:
+## Error handling
+
+`To11aiError` is the base; catch it broadly or match a subclass:
 
 ```typescript
-import { PromptLabelNotRegisteredError } from "@to11ai/sdk";
+import { To11aiRateLimitError, PromptNotFoundError } from "@to11ai/sdk";
 
 try {
-  await client.prompts.moveLabel({
-    projectId: "proj_abc123",
-    promptId: "prompt_xyz789",
-    label: "canary",
-    versionId: "ver_42",
-    reason: "promote to canary",
-  });
+  const prompt = await to11.prompts.render("welcome-message");
 } catch (err) {
-  if (PromptLabelNotRegisteredError.is(err)) {
-    console.error(
-      `Label "${err.label}" is not registered in project ${err.projectId}.`,
-    );
-    // Offer to create it: client.prompts.createProjectLabel({ … })
-  } else {
-    throw err;
-  }
+  if (err instanceof To11aiRateLimitError) { /* err.retryAfterSeconds */ }
+  else if (err instanceof PromptNotFoundError) { /* … */ }
+  else throw err;
 }
 ```
 
-| Class | When thrown |
-|---|---|
-| `To11aiError` | Base class for all SDK errors |
-| `To11aiApiError` | Non-2xx API response with structured error envelope |
-| `To11aiValidationError` | 400 schema validation failure |
-| `To11aiAuthError` | 401 or 403 authentication/authorisation failure |
-| `To11aiRateLimitError` | 429 rate limit hit; includes `retryAfterSeconds` |
-| `To11aiNetworkError` | Network failure or request timeout |
-| `PromptLabelNotRegisteredError` | 422 strict-mode rejection — label not in the project registry |
-
-## Caching
-
-`prompts.resolve()` uses an in-memory LRU cache by default. Configure it at client construction time:
-
-```typescript
-const client = createClient({
-  baseUrl: "https://api.to11ai.com",
-  apiKey: process.env.TO11AI_API_KEY!,
-  cache: {
-    ttlSeconds: 600,   // default: 300 (5 minutes)
-    maxEntries: 500,   // default: 100
-  },
-});
-```
-
-**Per-call bypass:** pass `cache: false` to skip the cache for a single call:
+| Class | When |
+| --- | --- |
+| `To11aiApiError` | non-2xx API response (`statusCode`, `errorCode`, `details`) |
+| `To11aiAuthError` | 401/403 |
+| `To11aiRateLimitError` | 429 (`retryAfterSeconds`) |
+| `To11aiValidationError` | 400 |
+| `To11aiNetworkError` | network failure / timeout |
+| `PromptNotFoundError` · `LabelNotFoundError` · `MissingLabelError` · `NoActiveReleaseError` · `PromptPolicyViolationError` · `PromptLabelNotRegisteredError` | typed prompt-resolution errors |
+| `UnknownRoleError` | an unrecognized message role with `onUnknownRole: "error"` |
 
-```typescript
-const fresh = await client.prompts.resolve({
-  projectId: "proj_abc123",
-  slug: "chat-system-prompt",
-  labels: ["production"],
-  cache: false, // bypass cache, always fetch from API
-});
-```
+## TypeScript types
 
-**Fallback on network error:** pass `fallback` to return a pre-defined value if the network request fails (e.g. during a deployment):
+All inputs/outputs are typed; declarations ship as `dist/*.d.ts` (no separate `@types`). Import types from the entrypoint or the `@to11ai/sdk/prompts` subpath:
 
 ```typescript
-const result = await client.prompts.resolve({
-  projectId: "proj_abc123",
-  slug: "chat-system-prompt",
-  labels: ["production"],
-  fallback: {
-    promptId: "...",
-    versionId: "...",
-    version: 1,
-    rendered: { format: "text", text: "You are a helpful assistant." },
-  },
-});
+import type { ClientOptions, RenderOptions, RenderedPrompt } from "@to11ai/sdk";
 ```
 
-## TypeScript types
+## Runtime support
 
-All inputs and outputs are fully typed. Import types directly if needed:
+| Runtime / loader | Resolves to | Notes |
+| --- | --- | --- |
+| Node.js (ESM `import`) | `dist/*.js` | Bundled ESM |
+| Node.js (CJS `require`) | `dist/*.cjs` | Bundled CommonJS |
+| TypeScript | `dist/*.d.ts` | Declarations |
+| Bun / Deno | `src/*.ts` | Raw source — zero build overhead |
 
-```typescript
-import type {
-  ClientOptions,
-  CacheConfig,
-  To11aiClient,
-} from "@to11ai/sdk";
-
-import type {
-  ResolvePromptInput,
-  ResolvePromptResult,
-  ResolvedPrompt,
-  Prompt,
-  PromptVersion,
-  // Project label registry
-  ProjectPromptLabel,
-  ProjectPromptLabelUsage,
-  PromptLabelEvent,
-  PaletteToken,
-  ListLabelEventsInput,
-} from "@to11ai/sdk/prompts";
-```
+## Documentation
 
-Type declarations ship in the package as `dist/*.d.ts`. No separate `@types` package is required. Bun and Deno consumers additionally get the raw TypeScript source.
+Full reference: [TypeScript SDK docs](https://docs.to11.ai/reference/typescript-sdk) · [Rendering prompts](https://docs.to11.ai/platform/prompts/rendering). Licensed under MPL-2.0.

package/dist/client.cjs

@@ -39,55 +39,66 @@ var __export = (target, all) => {
 // src/client.ts
 var exports_client = {};
 __export(exports_client, {
-  gatewayPromptHeaders: () => import_gateway.gatewayPromptHeaders,
-  gatewayAuthHeaders: () => import_gateway.gatewayAuthHeaders,
-  envVarNameForKey: () => import_store2.envVarNameForKey,
+  gatewayPromptHeaders: () => import_gateway2.gatewayPromptHeaders,
+  gatewayAuthHeaders: () => import_gateway2.gatewayAuthHeaders,
   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,
-  RuleVersionInvalidSnapshotError: () => import_errors.RuleVersionInvalidSnapshotError,
-  RuleNotFoundError: () => import_errors.RuleNotFoundError,
-  RoutingRulesResource: () => import_resource6.RoutingRulesResource,
-  RoutingRuleVersionResource: () => import_resource6.RoutingRuleVersionResource,
-  RoutingRuleReleaseResource: () => import_resource6.RoutingRuleReleaseResource,
-  PromptResource: () => import_resource5.PromptResource,
+  Session: () => import_context2.Session,
+  PromptResource: () => import_resource4.PromptResource,
   PromptPolicyViolationError: () => import_errors.PromptPolicyViolationError,
   PromptNotFoundError: () => import_errors.PromptNotFoundError,
   PromptLabelNotRegisteredError: () => import_errors.PromptLabelNotRegisteredError,
-  ProjectEnvironmentResource: () => import_resource4.ProjectEnvironmentResource,
-  NoApplicableRouteError: () => import_errors.NoApplicableRouteError,
+  ProjectEnvironmentResource: () => import_resource3.ProjectEnvironmentResource,
   NoActiveReleaseError: () => import_errors.NoActiveReleaseError,
-  EnvNotFoundError: () => import_errors.EnvNotFoundError,
-  EnvNotEnabledForProviderError: () => import_errors.EnvNotEnabledForProviderError,
+  MissingLabelError: () => import_errors.MissingLabelError,
+  LabelNotFoundError: () => import_errors.LabelNotFoundError,
   ENV_SLUG_REGEX: () => import_types2.ENV_SLUG_REGEX,
-  BehaviorStore: () => import_store2.BehaviorStore,
-  AmbiguousEnvLabelsError: () => import_errors.AmbiguousEnvLabelsError
+  Conversation: () => import_context2.Conversation
 });
 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_resource4 = require("./projectEnvironments/resource");
-var import_resource5 = require("./prompts/resource");
+var import_gateway2 = require("./gateway");
+var import_resource3 = require("./projectEnvironments/resource");
+var import_resource4 = 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) {
-    throw new Error("[to11ai/sdk] Do not use `apiKey` in browser contexts — use `getAccessToken` instead.");
+  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 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 a browser — a to11 API key carries gateway access and must stay server-side (server, CLI, or backend job).");
   }
   if (options.apiKey !== undefined && options.apiKey.trim() === "") {
     throw new Error("[to11ai/sdk] `apiKey` must not be an empty string.");
@@ -95,39 +106,74 @@ 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 (hasApiKey === hasGetAccessToken) {
-    throw new Error("[to11ai/sdk] Provide exactly one of `apiKey` (server) or `getAccessToken` (browser).");
+  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 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 behaviorStore = new import_store.BehaviorStore({
-    initOverrides: options.behaviorOverrides,
-    env: processEnv
-  });
+  if (apiKey === undefined) {
+    throw new Error("[to11ai/sdk] An `apiKey` (or `TO11_API_KEY`) is required.");
+  }
+  const auth = { apiKey };
+  const behaviorStore = new import_store.BehaviorStore({ 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
+  const prompts = new import_resource2.PromptResource(transport, {
+    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 (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 (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)
+    apiKey,
+    baseUrl,
+    gatewayUrl,
+    projectId,
+    env,
+    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)
   };
 }