@buildwithtrace/sdk 0.1.0 → 0.1.2

package/dist/index.js

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
@@ -22,8 +32,17 @@ var index_exports = {};
 __export(index_exports, {
   Trace: () => Trace,
   TraceError: () => TraceError,
+  TracePlanRestrictedError: () => TracePlanRestrictedError,
   TraceToolExecutionError: () => TraceToolExecutionError,
-  default: () => index_default
+  browserLogin: () => browserLogin,
+  clearCredentials: () => clearCredentials,
+  default: () => index_default,
+  deriveFrontendUrl: () => deriveFrontendUrl,
+  getConfigDir: () => getConfigDir,
+  getStoredAccessToken: () => getStoredAccessToken,
+  openBrowser: () => openBrowser,
+  readCredentials: () => readCredentials,
+  storeCredentials: () => storeCredentials
 });
 module.exports = __toCommonJS(index_exports);
 var import_fs2 = require("fs");
@@ -439,8 +458,401 @@ function executeFileTool(toolName, toolArgs, projectDir, defaultFile = "") {
   }
 }
 
-// src/index.ts
+// src/auth.ts
+var childProcess = __toESM(require("child_process"));
+var import_node_http = require("http");
+var import_node_os = require("os");
+var import_node_path = require("path");
+var import_node_fs = require("fs");
+var import_node_url = require("url");
 var DEFAULT_API_URL = "https://api.buildwithtrace.com";
+var PRODUCTION_FRONTEND_URL = "https://buildwithtrace.com";
+var LOCAL_FRONTEND_URL = "http://localhost:3000";
+var DEFAULT_LOGIN_TIMEOUT_MS = 12e4;
+function deriveFrontendUrl(baseUrl) {
+  const envOverride = process.env.TRACE_FRONTEND_URL;
+  if (envOverride && envOverride.trim()) {
+    return envOverride.trim().replace(/\/$/, "");
+  }
+  const api = (baseUrl || process.env.TRACE_BASE_URL || DEFAULT_API_URL).trim();
+  try {
+    const u = new import_node_url.URL(api);
+    const host = u.hostname;
+    if (host === "localhost" || host === "127.0.0.1") {
+      return LOCAL_FRONTEND_URL;
+    }
+    if (host.startsWith("api.")) {
+      return `${u.protocol}//${host.slice("api.".length)}`;
+    }
+    return PRODUCTION_FRONTEND_URL;
+  } catch {
+    return PRODUCTION_FRONTEND_URL;
+  }
+}
+var CREDENTIALS_FILENAME = "credentials.json";
+function getConfigDir() {
+  const override = process.env.TRACE_CONFIG_DIR;
+  if (override && override.trim()) return override.trim();
+  const home = (0, import_node_os.homedir)();
+  switch ((0, import_node_os.platform)()) {
+    case "darwin":
+      return (0, import_node_path.join)(home, "Library", "Application Support", "trace");
+    case "win32": {
+      const appData = process.env.APPDATA || (0, import_node_path.join)(home, "AppData", "Roaming");
+      return (0, import_node_path.join)(appData, "buildwithtrace", "trace");
+    }
+    default: {
+      const xdg = process.env.XDG_CONFIG_HOME;
+      const base = xdg && xdg.trim() ? xdg.trim() : (0, import_node_path.join)(home, ".config");
+      return (0, import_node_path.join)(base, "trace");
+    }
+  }
+}
+function credentialsPath() {
+  return (0, import_node_path.join)(getConfigDir(), CREDENTIALS_FILENAME);
+}
+function storeCredentials(creds) {
+  const dir = getConfigDir();
+  (0, import_node_fs.mkdirSync)(dir, { recursive: true });
+  const path = credentialsPath();
+  const data = {
+    access_token: creds.access_token,
+    refresh_token: creds.refresh_token
+  };
+  if (creds.user_data) data.user_data = creds.user_data;
+  (0, import_node_fs.writeFileSync)(path, JSON.stringify(data, null, 2), { encoding: "utf-8", mode: 384 });
+  try {
+    (0, import_node_fs.chmodSync)(path, 384);
+  } catch {
+  }
+  return path;
+}
+function readCredentials() {
+  const path = credentialsPath();
+  if (!(0, import_node_fs.existsSync)(path)) return null;
+  try {
+    const parsed = JSON.parse((0, import_node_fs.readFileSync)(path, "utf-8"));
+    if (parsed && typeof parsed.access_token === "string" && parsed.access_token) {
+      return parsed;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+function getStoredAccessToken() {
+  return readCredentials()?.access_token ?? null;
+}
+function clearCredentials() {
+  const path = credentialsPath();
+  if ((0, import_node_fs.existsSync)(path)) {
+    (0, import_node_fs.rmSync)(path, { force: true });
+  }
+}
+function openBrowser(url) {
+  let command;
+  let args;
+  switch ((0, import_node_os.platform)()) {
+    case "darwin":
+      command = "open";
+      args = [url];
+      break;
+    case "win32":
+      command = "cmd";
+      args = ["/c", "start", "", url];
+      break;
+    default:
+      command = "xdg-open";
+      args = [url];
+      break;
+  }
+  try {
+    const child = childProcess.spawn(command, args, { stdio: "ignore", detached: true });
+    child.on("error", () => {
+    });
+    child.unref();
+  } catch {
+  }
+}
+var SUCCESS_HTML = `<!DOCTYPE html><html><head><meta charset="utf-8"><title>Trace</title></head>
+<body style="font-family:system-ui,-apple-system,sans-serif;text-align:center;padding:64px;color:#2a2119">
+<h1 style="font-weight:600">&#10003; Authentication successful</h1>
+<p>You can close this window and return to your terminal.</p>
+<script>setTimeout(function(){window.close();},500)</script>
+</body></html>`;
+var PENDING_HTML = `<!DOCTYPE html><html><head><meta charset="utf-8"><title>Trace</title></head>
+<body style="font-family:system-ui,-apple-system,sans-serif;text-align:center;padding:64px;color:#2a2119">
+<h1 style="font-weight:600">Waiting for authentication&#8230;</h1>
+<p>This page is the Trace login callback. Complete sign-in in the other tab.</p>
+</body></html>`;
+function parseCallback(query) {
+  const accessToken = query.get("token") || query.get("access_token");
+  if (!accessToken) return null;
+  const refreshToken = query.get("refresh_token") || "";
+  let user = null;
+  const userRaw = query.get("user");
+  if (userRaw) {
+    try {
+      user = JSON.parse(userRaw);
+    } catch {
+      user = null;
+    }
+  }
+  return { accessToken, refreshToken, user };
+}
+function browserLogin(opts = {}) {
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_LOGIN_TIMEOUT_MS;
+  const frontendUrl = opts.frontendUrl?.trim().replace(/\/$/, "") || deriveFrontendUrl(opts.baseUrl);
+  const openFn = opts.open ?? openBrowser;
+  return new Promise((resolve3, reject) => {
+    let settled = false;
+    let timer;
+    const shutdown = () => {
+      try {
+        server.closeAllConnections?.();
+      } catch {
+      }
+      server.close();
+    };
+    const settle = (run) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      run();
+    };
+    const server = (0, import_node_http.createServer)((req, res) => {
+      let url;
+      try {
+        url = new import_node_url.URL(req.url || "/", "http://127.0.0.1");
+      } catch {
+        res.writeHead(400).end();
+        return;
+      }
+      if (!url.pathname.startsWith("/callback")) {
+        res.writeHead(204).end();
+        return;
+      }
+      const result = parseCallback(url.searchParams);
+      if (!result) {
+        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" }).end(PENDING_HTML);
+        return;
+      }
+      res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" }).end(SUCCESS_HTML);
+      res.on("finish", shutdown);
+      res.on("close", shutdown);
+      settle(() => resolve3(result));
+    });
+    server.on("error", (err) => {
+      settle(() => {
+        shutdown();
+        reject(new Error(`Failed to start the local login callback server: ${err.message}`));
+      });
+    });
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      if (!address) {
+        settle(() => {
+          shutdown();
+          reject(new Error("Could not determine the local callback port."));
+        });
+        return;
+      }
+      const port = address.port;
+      const callbackUrl = `http://localhost:${port}/callback`;
+      const loginUrl = `${frontendUrl}/login?callback=${encodeURIComponent(callbackUrl)}`;
+      console.error(`Opening your browser to sign in to Trace...
+If it does not open, visit:
+  ${loginUrl}
+`);
+      openFn(loginUrl);
+      timer = setTimeout(() => {
+        settle(() => {
+          shutdown();
+          reject(
+            new Error(
+              `Login timed out after ${Math.round(timeoutMs / 1e3)}s. Re-run login, or open this URL manually:
+  ${loginUrl}`
+            )
+          );
+        });
+      }, timeoutMs);
+      if (typeof timer.unref === "function") timer.unref();
+    });
+  });
+}
+
+// src/analytics.ts
+var import_node_crypto = require("crypto");
+var import_node_os2 = require("os");
+var import_node_fs2 = require("fs");
+var import_node_path2 = require("path");
+var import_posthog_node = require("posthog-node");
+
+// src/_build_config.ts
+var BUILD_POSTHOG_KEY = "phc_YbXW9ynLyGf9qHVxOY87InoZNSRikTCQ14GDJOZtSxX";
+var BUILD_POSTHOG_HOST = "https://us.i.posthog.com";
+var BUILD_SDK_VERSION = "0.1.2";
+
+// src/analytics.ts
+var DEFAULT_HOST = "https://us.i.posthog.com";
+var INSTALL_ID_FILENAME = "install_id";
+var MAX_STRING_LEN = 80;
+var MAX_KEY_LEN = 64;
+function envSet(name) {
+  const v = process.env[name];
+  if (!v) return false;
+  const t = v.trim().toLowerCase();
+  return t !== "" && t !== "0" && t !== "false";
+}
+function isOptedOut() {
+  return envSet("DO_NOT_TRACK") || envSet("TRACE_NO_ANALYTICS");
+}
+function isCI() {
+  return envSet("CI") || envSet("CONTINUOUS_INTEGRATION") || envSet("GITHUB_ACTIONS");
+}
+function resolveKey() {
+  return (process.env.POSTHOG_API_KEY || BUILD_POSTHOG_KEY || "").trim();
+}
+function resolveHost() {
+  return (process.env.POSTHOG_HOST || BUILD_POSTHOG_HOST || DEFAULT_HOST).trim() || DEFAULT_HOST;
+}
+function isAnalyticsEnabled() {
+  try {
+    if (isOptedOut()) return false;
+    if (isCI()) return false;
+    return resolveKey().length > 0;
+  } catch {
+    return false;
+  }
+}
+var _installId;
+function getInstallId() {
+  if (_installId) return _installId;
+  try {
+    const dir = getConfigDir();
+    const path = (0, import_node_path2.join)(dir, INSTALL_ID_FILENAME);
+    if ((0, import_node_fs2.existsSync)(path)) {
+      const existing = (0, import_node_fs2.readFileSync)(path, "utf-8").trim();
+      if (existing) {
+        _installId = existing;
+        return existing;
+      }
+    }
+    const id = (0, import_node_crypto.randomUUID)();
+    (0, import_node_fs2.mkdirSync)(dir, { recursive: true });
+    (0, import_node_fs2.writeFileSync)(path, `${id}
+`, { encoding: "utf-8", mode: 384 });
+    _installId = id;
+    return id;
+  } catch {
+    if (!_installId) _installId = (0, import_node_crypto.randomUUID)();
+    return _installId;
+  }
+}
+function storedUserId() {
+  try {
+    const id = readCredentials()?.user_data?.id;
+    return typeof id === "string" && id ? id : null;
+  } catch {
+    return null;
+  }
+}
+function sanitizeProps(props) {
+  const out = {};
+  if (!props || typeof props !== "object") return out;
+  for (const [key, value] of Object.entries(props)) {
+    if (typeof key !== "string" || !key || key.length > MAX_KEY_LEN) continue;
+    if (typeof value === "boolean") {
+      out[key] = value;
+    } else if (typeof value === "number") {
+      if (Number.isFinite(value)) out[key] = value;
+    } else if (typeof value === "string") {
+      if (!value) continue;
+      if (value.length > MAX_STRING_LEN) continue;
+      if (/[\\/\n\r\t]/.test(value)) continue;
+      out[key] = value;
+    }
+  }
+  return out;
+}
+function superProps() {
+  return {
+    client: "sdk-node",
+    client_version: BUILD_SDK_VERSION || "0.0.0",
+    os: process.platform,
+    os_version: (0, import_node_os2.release)(),
+    node_version: process.version,
+    is_ci: isCI(),
+    install_id: getInstallId()
+  };
+}
+var _client;
+var _exitHookRegistered = false;
+function registerExitFlush() {
+  if (_exitHookRegistered) return;
+  _exitHookRegistered = true;
+  try {
+    process.once("beforeExit", () => {
+      try {
+        _client?.shutdown?.();
+      } catch {
+      }
+    });
+  } catch {
+  }
+}
+function getClient() {
+  if (_client !== void 0) return _client;
+  if (!isAnalyticsEnabled()) {
+    _client = null;
+    return null;
+  }
+  try {
+    _client = new import_posthog_node.PostHog(resolveKey(), {
+      host: resolveHost(),
+      flushAt: 1,
+      // short-lived SDK processes: send promptly
+      flushInterval: 1e4
+    });
+    registerExitFlush();
+    return _client;
+  } catch {
+    _client = null;
+    return null;
+  }
+}
+function track(event, props) {
+  try {
+    if (!event) return;
+    const client = getClient();
+    if (!client) return;
+    const distinctId = storedUserId() || getInstallId();
+    const properties = { ...sanitizeProps(props), ...superProps() };
+    client.capture({ distinctId, event, properties });
+  } catch {
+  }
+}
+function identify(distinctId, traits) {
+  try {
+    if (!distinctId) return;
+    const client = getClient();
+    if (!client) return;
+    client.identify({ distinctId, properties: { ...sanitizeProps(traits), ...superProps() } });
+  } catch {
+  }
+}
+function alias(distinctId, aliasId) {
+  try {
+    if (!distinctId || !aliasId || distinctId === aliasId) return;
+    const client = getClient();
+    if (!client) return;
+    client.alias?.({ distinctId, alias: aliasId });
+  } catch {
+  }
+}
+
+// src/index.ts
+var DEFAULT_API_URL2 = "https://api.buildwithtrace.com";
 var API_VERSION = "latest";
 var TraceError = class extends Error {
   constructor(message) {
@@ -454,66 +866,179 @@ var TraceToolExecutionError = class extends TraceError {
     this.name = "TraceToolExecutionError";
   }
 };
+var TracePlanRestrictedError = class extends TraceError {
+  constructor(message, opts) {
+    super(message);
+    /** Always true — lets callers branch on a flag, mirroring the backend `code`. */
+    this.planRestricted = true;
+    this.name = "TracePlanRestrictedError";
+    this.mode = opts?.mode;
+    this.plan = opts?.plan;
+  }
+};
+function parsePlanRestricted(text) {
+  if (!text) return null;
+  try {
+    const data = JSON.parse(text);
+    const detail = typeof data.detail === "object" && data.detail !== null ? data.detail : data;
+    if (detail.error === "plan_restricted" || detail.code === "plan_restricted") {
+      const message = detail.message || "This feature requires a paid plan.";
+      const plan = typeof detail.current_plan_id === "string" ? detail.current_plan_id : void 0;
+      return { message, plan };
+    }
+  } catch {
+  }
+  if (text.includes("plan_restricted")) {
+    return { message: "This feature requires a paid plan." };
+  }
+  return null;
+}
 var Trace = class _Trace {
-  constructor(config) {
-    this.apiKey = config.apiKey || process.env.TRACE_API_KEY || "";
+  constructor(config = {}) {
+    this.apiKey = config.apiKey || process.env.TRACE_API_KEY || getStoredAccessToken() || "";
     if (!this.apiKey) {
       throw new Error(
-        "API key required. Pass apiKey in config or set TRACE_API_KEY env var. Get your key at buildwithtrace.com/dashboard/settings > Developer, or via CLI: buildwithtrace auth token"
+        "API key required. Sign in with `await Trace.login()`, pass apiKey in config, or set TRACE_API_KEY env var. Get your key at buildwithtrace.com/dashboard/settings > Developer, or via CLI: buildwithtrace auth token"
       );
     }
-    this.baseUrl = (config.baseUrl || process.env.TRACE_BASE_URL || DEFAULT_API_URL).replace(/\/$/, "");
+    this.authed = true;
+    this.baseUrl = (config.baseUrl || process.env.TRACE_BASE_URL || DEFAULT_API_URL2).replace(/\/$/, "");
     this.timeout = config.timeout || 3e5;
+    this.byokProvider = config.llmProvider;
+    this.byokApiKey = config.llmApiKey;
+    this.byokModelId = config.llmModelId;
+    track("sdk_init", { authed: this.authed });
+  }
+  /**
+   * Wrap a public method call: emit `sdk_call` (with timing + outcome) on every
+   * call and `sdk_error` (with the error class) on failure. Analytics is
+   * fire-and-forget; it must never change behavior, so the underlying result /
+   * thrown error always propagates unchanged.
+   */
+  async _instrument(method, streaming, byok, fn) {
+    const start = Date.now();
+    try {
+      const result = await fn();
+      track("sdk_call", {
+        method,
+        api_version: API_VERSION,
+        streaming,
+        byok,
+        duration_ms: Date.now() - start,
+        ok: true,
+        authed: this.authed
+      });
+      return result;
+    } catch (err) {
+      track("sdk_call", {
+        method,
+        api_version: API_VERSION,
+        streaming,
+        byok,
+        duration_ms: Date.now() - start,
+        ok: false,
+        authed: this.authed
+      });
+      track("sdk_error", {
+        method,
+        error_type: err instanceof Error && err.name || "Error",
+        authed: this.authed
+      });
+      throw err;
+    }
+  }
+  /**
+   * Sign in via the browser deeplink flow, persist the returned tokens to a
+   * 0600 `credentials.json`, and return a ready-to-use `Trace` instance.
+   *
+   * Opens `{FRONTEND}/login?callback=http://localhost:PORT/callback` in the
+   * browser; the user authenticates there (captcha included) and the page
+   * redirects back to the loopback server with the final Supabase JWTs.
+   *
+   * @example
+   * ```typescript
+   * const trace = await Trace.login();
+   * const answer = await trace.ask('What ERC violations exist?');
+   * ```
+   */
+  static async login(opts = {}) {
+    const result = await browserLogin({
+      baseUrl: opts.baseUrl,
+      frontendUrl: opts.frontendUrl,
+      timeoutMs: opts.timeoutMs,
+      open: opts.open
+    });
+    storeCredentials({
+      access_token: result.accessToken,
+      refresh_token: result.refreshToken,
+      user_data: result.user
+    });
+    const userId = result.user?.id;
+    if (typeof userId === "string" && userId) {
+      identify(userId);
+      alias(userId, getInstallId());
+    }
+    return new _Trace({ apiKey: result.accessToken, baseUrl: opts.baseUrl, timeout: opts.timeout });
+  }
+  /** Clear stored credentials (sign out). Subsequent `new Trace()` will need a token again. */
+  static logout() {
+    clearCredentials();
   }
   async generateSymbol(description, options) {
-    const body = { description };
-    if (options?.datasheetUrl) body.datasheet_url = options.datasheetUrl;
-    if (options?.additionalInstructions) body.additional_instructions = options.additionalInstructions;
-    const data = await this._post(`/api/${API_VERSION}/components/generate/symbol`, body);
-    return this._makeGenerateResult(data, "symbol");
+    return this._instrument("generateSymbol", false, false, async () => {
+      const body = { description };
+      if (options?.datasheetUrl) body.datasheet_url = options.datasheetUrl;
+      if (options?.additionalInstructions) body.additional_instructions = options.additionalInstructions;
+      const data = await this._post(`/api/${API_VERSION}/components/generate/symbol`, body);
+      return this._makeGenerateResult(data, "symbol");
+    });
   }
   async generateFootprint(description, options) {
-    const body = { description };
-    if (options?.packageType) body.package_type = options.packageType;
-    if (options?.datasheetUrl) body.datasheet_url = options.datasheetUrl;
-    const data = await this._post(`/api/${API_VERSION}/components/generate/footprint`, body);
-    return this._makeGenerateResult(data, "footprint");
+    return this._instrument("generateFootprint", false, false, async () => {
+      const body = { description };
+      if (options?.packageType) body.package_type = options.packageType;
+      if (options?.datasheetUrl) body.datasheet_url = options.datasheetUrl;
+      const data = await this._post(`/api/${API_VERSION}/components/generate/footprint`, body);
+      return this._makeGenerateResult(data, "footprint");
+    });
   }
   async search(query, options) {
-    const params = new URLSearchParams({ q: query, limit: String(options?.limit || 20) });
-    if (options?.type) params.set("type", options.type);
-    const data = await this._get(`/api/${API_VERSION}/components/search?${params}`);
-    return (data.results || []).map((r) => ({
-      name: r.name || "",
-      library: r.library || "",
-      description: r.description || "",
-      pinCount: r.pin_count || 0,
-      padCount: r.pad_count || 0,
-      category: r.category || "",
-      source: r.source || "",
-      score: r.score || 0
-    }));
+    return this._instrument("search", false, false, async () => {
+      const params = new URLSearchParams({ q: query, limit: String(options?.limit || 20) });
+      if (options?.type) params.set("type", options.type);
+      const data = await this._get(`/api/${API_VERSION}/components/search?${params}`);
+      return (data.results || []).map((r) => ({
+        name: r.name || "",
+        library: r.library || "",
+        description: r.description || "",
+        pinCount: r.pin_count || 0,
+        padCount: r.pad_count || 0,
+        category: r.category || "",
+        source: r.source || "",
+        score: r.score || 0
+      }));
+    });
   }
   async ask(question, options) {
-    return this._streamChat(question, {
+    return this._instrument("ask", true, false, () => this._streamChat(question, {
       mode: "ask",
       appType: options?.appType,
       projectDir: options?.projectDir,
       fileContent: options?.fileContent,
       filePath: options?.filePath,
       conversationId: options?.conversationId
-    });
+    }));
   }
   async review(options) {
     let prompt = "Review this design for issues, best practices, and improvements.";
     if (options?.focus) prompt += ` Focus on: ${options.focus}`;
-    return this._streamChat(prompt, {
+    return this._instrument("review", true, false, () => this._streamChat(prompt, {
       mode: "ask",
       appType: options?.appType,
       projectDir: options?.projectDir,
       fileContent: options?.fileContent,
       filePath: options?.filePath
-    });
+    }));
   }
   /**
    * Stream a chat turn and collect the full response. Exposes the full backend
@@ -532,7 +1057,9 @@ var Trace = class _Trace {
    * TraceToolExecutionError — use the `buildwithtrace` CLI for those.
    */
   async chat(message, options) {
-    return this._streamChat(message, options || {});
+    const resolved = this._resolveByok(options || {});
+    const byok = !!(resolved.provider && resolved.apiKey);
+    return this._instrument("chat", true, byok, () => this._streamChat(message, options || {}));
   }
   async _post(path, body) {
     const controller = new AbortController();
@@ -557,10 +1084,14 @@ var Trace = class _Trace {
       clearTimeout(timeoutId);
     }
   }
-  static _httpError(status, text) {
+  static _httpError(status, text, mode) {
     if (status === 401) return new TraceError("Invalid or expired API key. Get a new one at buildwithtrace.com/dashboard/settings > Developer");
     if (status === 402) return new TraceError("Quota exceeded. Upgrade at buildwithtrace.com/dashboard/billing");
-    if (status === 403) return new TraceError("Access denied. This feature requires a paid plan.");
+    if (status === 403) {
+      const pr = parsePlanRestricted(text);
+      if (pr) return new TracePlanRestrictedError(pr.message, { mode, plan: pr.plan });
+      return new TraceError("Access denied. This feature requires a paid plan.");
+    }
     return new Error(`Trace API error ${status}: ${text.slice(0, 200)}`);
   }
   async _get(path) {
@@ -581,6 +1112,37 @@ var Trace = class _Trace {
    * backend ChatRequest contract so the SDK stays in lockstep with the
    * CLI/desktop instead of sending a stale minimal payload.
    */
+  /**
+   * Resolve BYOK routing with precedence: per-call options > constructor config >
+   * env (`TRACE_LLM_PROVIDER` / `TRACE_LLM_API_KEY` / `TRACE_LLM_MODEL`). Provider
+   * and key are resolved as a UNIT from the first source supplying BOTH (we never
+   * mix a per-call provider with an env key); the model id is layered (a more
+   * specific source's model wins). Node has no keyring `byok set` store, so env is
+   * the "persisted" mechanism. Returns `{}` when no complete config is found, so
+   * nothing is attached and the backend uses Trace-hosted Bedrock.
+   */
+  _resolveByok(opts) {
+    if (opts.llmProvider && opts.llmApiKey) {
+      return { provider: opts.llmProvider, apiKey: opts.llmApiKey, modelId: opts.llmModelId };
+    }
+    if (this.byokProvider && this.byokApiKey) {
+      return {
+        provider: this.byokProvider,
+        apiKey: this.byokApiKey,
+        modelId: opts.llmModelId || this.byokModelId
+      };
+    }
+    const envProvider = process.env.TRACE_LLM_PROVIDER;
+    const envKey = process.env.TRACE_LLM_API_KEY;
+    if (envProvider && envKey) {
+      return {
+        provider: envProvider,
+        apiKey: envKey,
+        modelId: opts.llmModelId || this.byokModelId || process.env.TRACE_LLM_MODEL
+      };
+    }
+    return {};
+  }
   _buildChatBody(message, opts, sessionId) {
     const appType = opts.appType || "eeschema";
     const body = {
@@ -601,10 +1163,11 @@ var Trace = class _Trace {
     if (opts.projectDir) body.project_dir = opts.projectDir;
     if (opts.teamId) body.team_id = opts.teamId;
     if (opts.attachments) body.attachments = opts.attachments;
-    if (opts.llmProvider && opts.llmApiKey) {
-      body.llm_provider = opts.llmProvider;
-      body.llm_api_key = opts.llmApiKey;
-      if (opts.llmModelId) body.llm_model_id = opts.llmModelId;
+    const byok = this._resolveByok(opts);
+    if (byok.provider && byok.apiKey) {
+      body.llm_provider = byok.provider;
+      body.llm_api_key = byok.apiKey;
+      if (byok.modelId) body.llm_model_id = byok.modelId;
     }
     return body;
   }
@@ -633,7 +1196,7 @@ var Trace = class _Trace {
     });
     if (!resp.ok) {
       const errText = await resp.text().catch(() => "");
-      throw _Trace._httpError(resp.status, errText);
+      throw _Trace._httpError(resp.status, errText, opts.mode);
     }
     if (!resp.body) {
       throw new TraceError("The backend returned an empty response stream.");
@@ -782,5 +1345,14 @@ var index_default = Trace;
 0 && (module.exports = {
   Trace,
   TraceError,
-  TraceToolExecutionError
+  TracePlanRestrictedError,
+  TraceToolExecutionError,
+  browserLogin,
+  clearCredentials,
+  deriveFrontendUrl,
+  getConfigDir,
+  getStoredAccessToken,
+  openBrowser,
+  readCredentials,
+  storeCredentials
 });