@buildwithtrace/sdk

What's new in v0.1.6

Added

• Browser-based deeplink login flow: calling the auth helper opens a browser tab and stores credentials in a local file for subsequent runs.
• File-based credential store: the SDK reads and writes credentials to disk so API keys persist across sessions.
• TRACE_API_KEY / BYOK env-var fallback: if a key is set in the environment it takes precedence over stored credentials.
• TRACE_BASE_URL environment variable to override the API base URL (useful for self-hosted or staging endpoints).
• Client-side file-tool execution loop enabling a standalone agent that reads/writes files without a separate process.
• Full chat contract support with fail-fast behaviour on unexpected agent tool calls.
• SDK defaults to the /api/latest backend API version automatically.
• Privacy-first PostHog telemetry (opt-out analytics, matching Python SDK behaviour).
• Typed PlanRestrictedError surface for quota/plan-limit responses.

Changed

• Quota and plan-limit error messages from the server are now surfaced verbatim to callers instead of being replaced with a generic string.
• Auth status display shows a human-readable percentage instead of a raw internal cost-cap value.

Fixed

• Server quota/plan messages were previously swallowed; they are now passed through unchanged so callers can display actionable upgrade copy.

Full history: release notes.

TypeScript SDK for Trace — AI-powered PCB & schematic design.

Changelog: see CHANGELOG.md in this package, or the suite-wide CLI & SDK Release Notes.

npm install @buildwithtrace/sdk

import { Trace } from '@buildwithtrace/sdk';

// 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

const fp = await trace.generateFootprint('SOIC-8 3.9x4.9mm');
fp.save('./footprints/');                      // writes SOIC-8.kicad_mod

const hits = await trace.search('3.3V LDO', { type: 'symbol' });

// Read-only Q&A:
const ans = await trace.ask('What ERC violations exist?', { projectDir: './my-board/' });

// Standalone agent (executes file tools locally + posts results):
const res = await trace.chat('Add a 100nF decoupling cap on U1', {
  mode: 'agent',
  projectDir: './my-board/',
});

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

• chat({ mode: 'agent' | 'plan' }) runs a client-side tool-execution loop for file tools (read_file, write, search_replace, list_dir, grep, delete_trace_file) with a path/extension allowlist + project-dir sandbox. Engine tools (ERC/DRC/gerbers/export) 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 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 paid plan or free agent credits even with your own key (ask is free); a free account gets a TracePlanRestrictedError.