@buildwithtrace/sdk 0.1.0 → 0.1.1

package/README.md

@@ -9,7 +9,13 @@ npm install @buildwithtrace/sdk
 ```ts
 import { Trace } from '@buildwithtrace/sdk';
 
-const trace = new Trace({ apiKey: process.env.TRACE_API_KEY });
+// Sign in once via the browser (opens the Trace login page, captcha solved there);
+// credentials persist so a bare `new Trace()` reuses them. `Trace.logout()` clears them.
+const trace = await Trace.login();
+
+// Or construct directly — token precedence: apiKey > TRACE_API_KEY env > stored credentials:
+// const trace = new Trace({ apiKey: process.env.TRACE_API_KEY });
+// const trace = new Trace();  // uses credentials stored by Trace.login()/the CLI
 
 const sym = await trace.generateSymbol('LM7805 5V voltage regulator');
 sym.save('./symbols/');                       // writes LM7805.kicad_sym
@@ -29,7 +35,12 @@ const res = await trace.chat('Add a 100nF decoupling cap on U1', {
 });
 ```
 
-Get an API key: `buildwithtrace auth token` (CLI) or buildwithtrace.com/dashboard/settings → Developer.
+Get an API key (CI): mint a long-lived Personal Access Token with `buildwithtrace auth token --create --name ci-bot` (`trace_pat_...`, shown once), or in the dashboard (Settings → Developer).
+
+Env overrides: `TRACE_API_KEY` (token), `TRACE_BASE_URL` (API base), `TRACE_FRONTEND_URL`
+(login page origin), `TRACE_CONFIG_DIR` (credential store), `TRACE_LLM_PROVIDER` /
+`TRACE_LLM_API_KEY` / `TRACE_LLM_MODEL` (BYOK), `TRACE_NO_ANALYTICS` / `DO_NOT_TRACK`
+(opt out of anonymous usage analytics; also auto-off in CI).
 
 ## Notes
 
@@ -39,4 +50,9 @@ Get an API key: `buildwithtrace auth token` (CLI) or buildwithtrace.com/dashboar
   are not yet ported — those throw `TraceToolExecutionError`; use the `buildwithtrace` CLI for them.
 - `.trace_*` writes succeed, but the matching `.kicad_*` isn't regenerated client-side yet
   (the converter isn't bundled in the Node SDK) — the result says so.
-- BYOK supported via `chat(..., { llmProvider, llmApiKey, llmModelId })`.
+- BYOK via per-call `chat(..., { llmProvider, llmApiKey, llmModelId })`, the constructor
+  (`new Trace({ llmProvider, llmApiKey, llmModelId })`), or the
+  `TRACE_LLM_PROVIDER`/`TRACE_LLM_API_KEY`/`TRACE_LLM_MODEL` env (precedence: per-call >
+  constructor > env). BYOK skips Trace's cost cap but NOT the plan gate — `agent`/`plan`
+  still require a trial/paid plan even with your own key (`ask` is free); a free account gets
+  a `TracePlanRestrictedError`.

package/dist/index.d.mts

@@ -1,3 +1,90 @@
+/**
+ * Browser "deeplink" login + file-based credential storage for the Trace SDK.
+ *
+ * Mirrors the Python SDK (`buildwithtrace_sdk`) so the two tools interoperate:
+ * the loopback callback contract is identical and credentials persist to the
+ * same `credentials.json` filename under an OS config dir.
+ *
+ * Login flow:
+ *   1. Start a loopback HTTP server on 127.0.0.1 on a free port.
+ *   2. Open `{FRONTEND}/login?callback=http://localhost:PORT/callback` in the
+ *      user's browser. The user authenticates in-browser (captcha solved there).
+ *   3. The browser redirects to
+ *      `http://localhost:PORT/callback?token=<ACCESS_JWT>&refresh_token=<RT>&user=<urlencoded JSON>`.
+ *      The access-token query param is named `token` (NOT `access_token`).
+ *   4. We parse the tokens, respond with a "you can close this window" page,
+ *      close the server, and resolve.
+ *
+ * Uses only Node built-ins (http, child_process, os, fs, path) — no runtime deps.
+ */
+/** Subset of the Supabase user object the callback URL-encodes into `user`. */
+interface TraceUser {
+    id?: string;
+    email?: string;
+    full_name?: string;
+    avatar_url?: string;
+    [key: string]: unknown;
+}
+/** Shape persisted to credentials.json (field names mirror the Python SDK). */
+interface StoredCredentials {
+    access_token: string;
+    refresh_token: string;
+    user_data?: TraceUser | null;
+}
+/** Result of a successful browser login. */
+interface BrowserLoginResult {
+    accessToken: string;
+    refreshToken: string;
+    user: TraceUser | null;
+}
+interface BrowserLoginOptions {
+    /** API base URL — used to derive the FRONTEND login host. */
+    baseUrl?: string;
+    /** Explicit frontend origin (e.g. `https://buildwithtrace.com`). Overrides derivation. */
+    frontendUrl?: string;
+    /** How long to wait for the browser round-trip before rejecting. Default 120s. */
+    timeoutMs?: number;
+    /** Inject a custom browser-opener (used in tests). Defaults to the OS opener. */
+    open?: (url: string) => void;
+}
+/**
+ * The login page lives on the FRONTEND host, not the API host. Derive it:
+ *   - `TRACE_FRONTEND_URL` env always wins.
+ *   - `api.<domain>` -> `https://<domain>`  (e.g. api.buildwithtrace.com -> buildwithtrace.com)
+ *   - localhost / 127.0.0.1 -> `http://localhost:3000` (dev frontend default)
+ *   - anything else (staging IPs, unknown hosts) -> the production frontend.
+ */
+declare function deriveFrontendUrl(baseUrl?: string): string;
+/**
+ * OS config directory for Trace, best-effort matching the Python SDK's
+ * `platformdirs.user_config_dir("trace", "buildwithtrace")`:
+ *   - `TRACE_CONFIG_DIR` env always wins.
+ *   - macOS:   ~/Library/Application Support/trace
+ *   - Windows: %APPDATA%\buildwithtrace\trace
+ *   - Linux:   $XDG_CONFIG_HOME/trace  (else ~/.config/trace)
+ */
+declare function getConfigDir(): string;
+/** Persist tokens to a 0600 credentials.json. Creates the config dir if needed. */
+declare function storeCredentials(creds: StoredCredentials): string;
+/** Read stored credentials, or null if absent/corrupt. */
+declare function readCredentials(): StoredCredentials | null;
+/** The stored access token (a Supabase JWT), or null if not logged in. */
+declare function getStoredAccessToken(): string | null;
+/** Remove stored credentials. No-op if there are none. */
+declare function clearCredentials(): void;
+/**
+ * Open a URL in the user's default browser. Cross-platform via the OS opener
+ * (macOS `open`, Windows `start`, Linux `xdg-open`). Best-effort: if the spawn
+ * fails the caller still prints the URL as a manual fallback.
+ */
+declare function openBrowser(url: string): void;
+/**
+ * Run the browser deeplink login. Starts a loopback server, opens the frontend
+ * login page, and resolves with the tokens parsed from the callback redirect.
+ * Rejects cleanly on timeout. Does NOT persist anything — see `Trace.login`.
+ */
+declare function browserLogin(opts?: BrowserLoginOptions): Promise<BrowserLoginResult>;
+
 /**
  * @buildwithtrace/sdk — TypeScript SDK for Trace AI-powered EDA tools.
  *
@@ -19,6 +106,7 @@
  * const answer = await trace.ask('What ERC violations exist?', { projectDir: './my-board/' });
  * ```
  */
+
 /** Base error for SDK-surfaced backend failures (e.g. an SSE `error` event). */
 declare class TraceError extends Error {
     constructor(message: string);
@@ -35,9 +123,48 @@ declare class TraceError extends Error {
 declare class TraceToolExecutionError extends TraceError {
     constructor(message: string);
 }
+/**
+ * Thrown when the backend rejects a mode the user's plan doesn't allow (HTTP
+ * 403). Free users can only use `ask`; `agent`/`plan` require a paid plan (BYOK
+ * does NOT bypass this gate). The backend body is
+ * `{"detail": {"error": "plan_restricted", "message": ..., "current_plan_id": ...}}`
+ * (see backend `app/auth/quota.py::PlanRestricted`). Callers (the CLI) can catch
+ * this and print a clean upgrade CTA instead of a raw error.
+ */
+declare class TracePlanRestrictedError extends TraceError {
+    /** Always true — lets callers branch on a flag, mirroring the backend `code`. */
+    readonly planRestricted = true;
+    /** The chat mode that was rejected (`"agent"`/`"plan"`), if known. */
+    readonly mode?: string;
+    /** The user's current plan id (`"free"`), if the backend reported it. */
+    readonly plan?: string;
+    constructor(message: string, opts?: {
+        mode?: string;
+        plan?: string;
+    });
+}
 interface TraceConfig {
-    apiKey: string;
+    /**
+     * Bearer token for the API. Optional: if omitted, the SDK falls back to the
+     * `TRACE_API_KEY` env var, then to credentials stored by `Trace.login()`.
+     */
+    apiKey?: string;
+    baseUrl?: string;
+    timeout?: number;
+    /**
+     * BYOK defaults for every call on this client (route turns to your own
+     * provider; you pay the provider directly, so Trace's cost cap is skipped).
+     * Per-call `chat(...)` options override these; both override the env vars.
+     */
+    llmProvider?: string;
+    llmApiKey?: string;
+    llmModelId?: string;
+}
+/** Options for the browser deeplink login (`Trace.login`). */
+interface LoginOptions extends BrowserLoginOptions {
+    /** API base URL the returned `Trace` instance will use (also seeds frontend derivation). */
     baseUrl?: string;
+    /** Request timeout (ms) for the returned `Trace` instance. */
     timeout?: number;
 }
 interface GenerateResult {
@@ -97,7 +224,37 @@ declare class Trace {
     private apiKey;
     private baseUrl;
     private timeout;
-    constructor(config: TraceConfig);
+    /** Constructor-level BYOK defaults (overridden per-call; both override env). */
+    private byokProvider?;
+    private byokApiKey?;
+    private byokModelId?;
+    /** Whether this instance holds a token (always true post-construction; sent as an analytics super-prop). */
+    private authed;
+    constructor(config?: TraceConfig);
+    /**
+     * 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.
+     */
+    private _instrument;
+    /**
+     * 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 login(opts?: LoginOptions): Promise<Trace>;
+    /** Clear stored credentials (sign out). Subsequent `new Trace()` will need a token again. */
+    static logout(): void;
     generateSymbol(description: string, options?: {
         datasheetUrl?: string;
         additionalInstructions?: string;
@@ -140,6 +297,16 @@ declare 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.
+     */
+    private _resolveByok;
     private _buildChatBody;
     /**
      * Stream /chat/stream and drive a client-side tool loop.
@@ -168,4 +335,4 @@ declare class Trace {
     private _makeGenerateResult;
 }
 
-export { type AskOptions, type ChatOptions, type GenerateResult, type SearchOptions, type SearchResult, type TextResult, Trace, type TraceConfig, TraceError, TraceToolExecutionError, Trace as default };
+export { type AskOptions, type BrowserLoginOptions, type BrowserLoginResult, type ChatOptions, type GenerateResult, type LoginOptions, type SearchOptions, type SearchResult, type StoredCredentials, type TextResult, Trace, type TraceConfig, TraceError, TracePlanRestrictedError, TraceToolExecutionError, type TraceUser, browserLogin, clearCredentials, Trace as default, deriveFrontendUrl, getConfigDir, getStoredAccessToken, openBrowser, readCredentials, storeCredentials };

package/dist/index.d.ts

@@ -1,3 +1,90 @@
+/**
+ * Browser "deeplink" login + file-based credential storage for the Trace SDK.
+ *
+ * Mirrors the Python SDK (`buildwithtrace_sdk`) so the two tools interoperate:
+ * the loopback callback contract is identical and credentials persist to the
+ * same `credentials.json` filename under an OS config dir.
+ *
+ * Login flow:
+ *   1. Start a loopback HTTP server on 127.0.0.1 on a free port.
+ *   2. Open `{FRONTEND}/login?callback=http://localhost:PORT/callback` in the
+ *      user's browser. The user authenticates in-browser (captcha solved there).
+ *   3. The browser redirects to
+ *      `http://localhost:PORT/callback?token=<ACCESS_JWT>&refresh_token=<RT>&user=<urlencoded JSON>`.
+ *      The access-token query param is named `token` (NOT `access_token`).
+ *   4. We parse the tokens, respond with a "you can close this window" page,
+ *      close the server, and resolve.
+ *
+ * Uses only Node built-ins (http, child_process, os, fs, path) — no runtime deps.
+ */
+/** Subset of the Supabase user object the callback URL-encodes into `user`. */
+interface TraceUser {
+    id?: string;
+    email?: string;
+    full_name?: string;
+    avatar_url?: string;
+    [key: string]: unknown;
+}
+/** Shape persisted to credentials.json (field names mirror the Python SDK). */
+interface StoredCredentials {
+    access_token: string;
+    refresh_token: string;
+    user_data?: TraceUser | null;
+}
+/** Result of a successful browser login. */
+interface BrowserLoginResult {
+    accessToken: string;
+    refreshToken: string;
+    user: TraceUser | null;
+}
+interface BrowserLoginOptions {
+    /** API base URL — used to derive the FRONTEND login host. */
+    baseUrl?: string;
+    /** Explicit frontend origin (e.g. `https://buildwithtrace.com`). Overrides derivation. */
+    frontendUrl?: string;
+    /** How long to wait for the browser round-trip before rejecting. Default 120s. */
+    timeoutMs?: number;
+    /** Inject a custom browser-opener (used in tests). Defaults to the OS opener. */
+    open?: (url: string) => void;
+}
+/**
+ * The login page lives on the FRONTEND host, not the API host. Derive it:
+ *   - `TRACE_FRONTEND_URL` env always wins.
+ *   - `api.<domain>` -> `https://<domain>`  (e.g. api.buildwithtrace.com -> buildwithtrace.com)
+ *   - localhost / 127.0.0.1 -> `http://localhost:3000` (dev frontend default)
+ *   - anything else (staging IPs, unknown hosts) -> the production frontend.
+ */
+declare function deriveFrontendUrl(baseUrl?: string): string;
+/**
+ * OS config directory for Trace, best-effort matching the Python SDK's
+ * `platformdirs.user_config_dir("trace", "buildwithtrace")`:
+ *   - `TRACE_CONFIG_DIR` env always wins.
+ *   - macOS:   ~/Library/Application Support/trace
+ *   - Windows: %APPDATA%\buildwithtrace\trace
+ *   - Linux:   $XDG_CONFIG_HOME/trace  (else ~/.config/trace)
+ */
+declare function getConfigDir(): string;
+/** Persist tokens to a 0600 credentials.json. Creates the config dir if needed. */
+declare function storeCredentials(creds: StoredCredentials): string;
+/** Read stored credentials, or null if absent/corrupt. */
+declare function readCredentials(): StoredCredentials | null;
+/** The stored access token (a Supabase JWT), or null if not logged in. */
+declare function getStoredAccessToken(): string | null;
+/** Remove stored credentials. No-op if there are none. */
+declare function clearCredentials(): void;
+/**
+ * Open a URL in the user's default browser. Cross-platform via the OS opener
+ * (macOS `open`, Windows `start`, Linux `xdg-open`). Best-effort: if the spawn
+ * fails the caller still prints the URL as a manual fallback.
+ */
+declare function openBrowser(url: string): void;
+/**
+ * Run the browser deeplink login. Starts a loopback server, opens the frontend
+ * login page, and resolves with the tokens parsed from the callback redirect.
+ * Rejects cleanly on timeout. Does NOT persist anything — see `Trace.login`.
+ */
+declare function browserLogin(opts?: BrowserLoginOptions): Promise<BrowserLoginResult>;
+
 /**
  * @buildwithtrace/sdk — TypeScript SDK for Trace AI-powered EDA tools.
  *
@@ -19,6 +106,7 @@
  * const answer = await trace.ask('What ERC violations exist?', { projectDir: './my-board/' });
  * ```
  */
+
 /** Base error for SDK-surfaced backend failures (e.g. an SSE `error` event). */
 declare class TraceError extends Error {
     constructor(message: string);
@@ -35,9 +123,48 @@ declare class TraceError extends Error {
 declare class TraceToolExecutionError extends TraceError {
     constructor(message: string);
 }
+/**
+ * Thrown when the backend rejects a mode the user's plan doesn't allow (HTTP
+ * 403). Free users can only use `ask`; `agent`/`plan` require a paid plan (BYOK
+ * does NOT bypass this gate). The backend body is
+ * `{"detail": {"error": "plan_restricted", "message": ..., "current_plan_id": ...}}`
+ * (see backend `app/auth/quota.py::PlanRestricted`). Callers (the CLI) can catch
+ * this and print a clean upgrade CTA instead of a raw error.
+ */
+declare class TracePlanRestrictedError extends TraceError {
+    /** Always true — lets callers branch on a flag, mirroring the backend `code`. */
+    readonly planRestricted = true;
+    /** The chat mode that was rejected (`"agent"`/`"plan"`), if known. */
+    readonly mode?: string;
+    /** The user's current plan id (`"free"`), if the backend reported it. */
+    readonly plan?: string;
+    constructor(message: string, opts?: {
+        mode?: string;
+        plan?: string;
+    });
+}
 interface TraceConfig {
-    apiKey: string;
+    /**
+     * Bearer token for the API. Optional: if omitted, the SDK falls back to the
+     * `TRACE_API_KEY` env var, then to credentials stored by `Trace.login()`.
+     */
+    apiKey?: string;
+    baseUrl?: string;
+    timeout?: number;
+    /**
+     * BYOK defaults for every call on this client (route turns to your own
+     * provider; you pay the provider directly, so Trace's cost cap is skipped).
+     * Per-call `chat(...)` options override these; both override the env vars.
+     */
+    llmProvider?: string;
+    llmApiKey?: string;
+    llmModelId?: string;
+}
+/** Options for the browser deeplink login (`Trace.login`). */
+interface LoginOptions extends BrowserLoginOptions {
+    /** API base URL the returned `Trace` instance will use (also seeds frontend derivation). */
     baseUrl?: string;
+    /** Request timeout (ms) for the returned `Trace` instance. */
     timeout?: number;
 }
 interface GenerateResult {
@@ -97,7 +224,37 @@ declare class Trace {
     private apiKey;
     private baseUrl;
     private timeout;
-    constructor(config: TraceConfig);
+    /** Constructor-level BYOK defaults (overridden per-call; both override env). */
+    private byokProvider?;
+    private byokApiKey?;
+    private byokModelId?;
+    /** Whether this instance holds a token (always true post-construction; sent as an analytics super-prop). */
+    private authed;
+    constructor(config?: TraceConfig);
+    /**
+     * 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.
+     */
+    private _instrument;
+    /**
+     * 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 login(opts?: LoginOptions): Promise<Trace>;
+    /** Clear stored credentials (sign out). Subsequent `new Trace()` will need a token again. */
+    static logout(): void;
     generateSymbol(description: string, options?: {
         datasheetUrl?: string;
         additionalInstructions?: string;
@@ -140,6 +297,16 @@ declare 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.
+     */
+    private _resolveByok;
     private _buildChatBody;
     /**
      * Stream /chat/stream and drive a client-side tool loop.
@@ -168,4 +335,4 @@ declare class Trace {
     private _makeGenerateResult;
 }
 
-export { type AskOptions, type ChatOptions, type GenerateResult, type SearchOptions, type SearchResult, type TextResult, Trace, type TraceConfig, TraceError, TraceToolExecutionError, Trace as default };
+export { type AskOptions, type BrowserLoginOptions, type BrowserLoginResult, type ChatOptions, type GenerateResult, type LoginOptions, type SearchOptions, type SearchResult, type StoredCredentials, type TextResult, Trace, type TraceConfig, TraceError, TracePlanRestrictedError, TraceToolExecutionError, type TraceUser, browserLogin, clearCredentials, Trace as default, deriveFrontendUrl, getConfigDir, getStoredAccessToken, openBrowser, readCredentials, storeCredentials };