@buildwithtrace/sdk 0.1.0

package/README.md

@@ -0,0 +1,42 @@
+# @buildwithtrace/sdk
+
+TypeScript SDK for [Trace](https://buildwithtrace.com) — AI-powered PCB & schematic design.
+
+```bash
+npm install @buildwithtrace/sdk
+```
+
+```ts
+import { Trace } from '@buildwithtrace/sdk';
+
+const trace = new Trace({ apiKey: process.env.TRACE_API_KEY });
+
+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: `buildwithtrace auth token` (CLI) or buildwithtrace.com/dashboard/settings → Developer.
+
+## 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 supported via `chat(..., { llmProvider, llmApiKey, llmModelId })`.

package/dist/index.d.mts

@@ -0,0 +1,171 @@
+/**
+ * @buildwithtrace/sdk — TypeScript SDK for Trace AI-powered EDA tools.
+ *
+ * @example
+ * ```typescript
+ * import { Trace } from '@buildwithtrace/sdk';
+ *
+ * const trace = new Trace({ apiKey: 'your-api-key' });
+ *
+ * const symbol = await trace.generateSymbol('LM7805 5V voltage regulator');
+ * console.log(symbol.name);      // "LM7805"
+ * console.log(symbol.pinCount);  // 3
+ * symbol.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 results = await trace.search('voltage regulator', { type: 'symbol' });
+ * 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);
+}
+/**
+ * Thrown when an agent turn requests a tool the SDK does NOT execute locally.
+ *
+ * The SDK runs a client-side tool loop for FILE tools (`read_file`, `write`,
+ * `search_replace`, `list_dir`, `grep`, `delete_trace_file`). Engine/GUI tools
+ * — ERC/DRC, gerber/drill/position export, `take_snapshot`, `run_*`, `autoroute`,
+ * etc. — are out of scope and raise this error pointing you at the
+ * `buildwithtrace` CLI or the desktop app.
+ */
+declare class TraceToolExecutionError extends TraceError {
+    constructor(message: string);
+}
+interface TraceConfig {
+    apiKey: string;
+    baseUrl?: string;
+    timeout?: number;
+}
+interface GenerateResult {
+    name: string;
+    type: 'symbol' | 'footprint';
+    description: string;
+    pinCount: number;
+    padCount: number;
+    kicadSym: string | null;
+    kicadMod: string | null;
+    traceJson: Record<string, unknown> | null;
+    warning: string | null;
+    steps: Array<Record<string, unknown>>;
+    save(directory?: string): string;
+}
+interface SearchResult {
+    name: string;
+    library: string;
+    description: string;
+    pinCount: number;
+    padCount: number;
+    category: string;
+    source: string;
+    score: number;
+}
+interface TextResult {
+    text: string;
+    conversationId: string | null;
+    usage: Record<string, unknown> | null;
+}
+interface SearchOptions {
+    type?: 'symbol' | 'footprint';
+    limit?: number;
+}
+interface AskOptions {
+    projectDir?: string;
+    fileContent?: string;
+    appType?: 'eeschema' | 'pcbnew';
+    filePath?: string;
+    conversationId?: string;
+}
+interface ChatOptions {
+    mode?: 'ask' | 'agent' | 'plan';
+    appType?: 'eeschema' | 'pcbnew';
+    projectDir?: string;
+    filePath?: string;
+    fileContent?: string;
+    conversationId?: string;
+    teamId?: string;
+    attachments?: Array<Record<string, unknown>>;
+    /** BYOK: route this turn to your own provider (you pay the provider directly). */
+    llmProvider?: string;
+    llmApiKey?: string;
+    llmModelId?: string;
+}
+declare class Trace {
+    private apiKey;
+    private baseUrl;
+    private timeout;
+    constructor(config: TraceConfig);
+    generateSymbol(description: string, options?: {
+        datasheetUrl?: string;
+        additionalInstructions?: string;
+    }): Promise<GenerateResult>;
+    generateFootprint(description: string, options?: {
+        packageType?: string;
+        datasheetUrl?: string;
+    }): Promise<GenerateResult>;
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    ask(question: string, options?: AskOptions): Promise<TextResult>;
+    review(options?: {
+        projectDir?: string;
+        focus?: string;
+        appType?: 'eeschema' | 'pcbnew';
+        fileContent?: string;
+        filePath?: string;
+    }): Promise<TextResult>;
+    /**
+     * Stream a chat turn and collect the full response. Exposes the full backend
+     * chat contract: pcbnew vs eeschema (`appType`), multi-turn (`conversationId` —
+     * read it back off the result), team workspaces (`teamId`), multimodal
+     * `attachments`, `filePath` + `fileContent`, and BYOK
+     * (`llmProvider`/`llmApiKey`/`llmModelId`).
+     *
+     * NOTE: mode 'agent'/'plan' produce tool calls that run on the caller's
+     * machine. The SDK runs a client-side tool loop for FILE tools (read_file,
+     * write, search_replace, list_dir, grep, delete_trace_file), executing them
+     * under `projectDir` (defaults to process.cwd()) with the same path +
+     * extension allowlist as the CLI/desktop, and POSTing each result back to the
+     * backend so multi-step agent runs continue. Engine/GUI tools (ERC/DRC,
+     * gerber/export, take_snapshot, run_*, autoroute) are out of scope and throw
+     * TraceToolExecutionError — use the `buildwithtrace` CLI for those.
+     */
+    chat(message: string, options?: ChatOptions): Promise<TextResult>;
+    private _post;
+    private static _httpError;
+    private _get;
+    /**
+     * Single source of truth for the /chat/stream request body. Mirrors the
+     * backend ChatRequest contract so the SDK stays in lockstep with the
+     * CLI/desktop instead of sending a stale minimal payload.
+     */
+    private _buildChatBody;
+    /**
+     * Stream /chat/stream and drive a client-side tool loop.
+     *
+     * The backend pauses the SSE stream at each `tool_call` until the client POSTs
+     * the result to /tools/result, so we MUST read the body incrementally (not
+     * buffer it whole — that would dead-lock waiting for `done`). FILE tools are
+     * executed locally under `projectDir`; their result is posted back and the
+     * SAME stream keeps yielding events (the backend drives the multi-step loop)
+     * until `done`. Engine/GUI tools are out of scope and throw.
+     */
+    private _streamChat;
+    private static _parseSSELine;
+    /**
+     * Execute one tool call. FILE tools run locally (sandboxed to projectDir) and
+     * their result is POSTed to /tools/result so the backend continues the stream.
+     * Engine/GUI tools are out of scope and throw TraceToolExecutionError.
+     */
+    private _handleToolCall;
+    /**
+     * POST a tool result back to /api/<version>/tools/result (same base URL +
+     * version as /chat/stream). Non-fatal on failure — like the CLI, we warn and
+     * move on rather than crashing the loop (the backend turn will time out).
+     */
+    private _postToolResult;
+    private _makeGenerateResult;
+}
+
+export { type AskOptions, type ChatOptions, type GenerateResult, type SearchOptions, type SearchResult, type TextResult, Trace, type TraceConfig, TraceError, TraceToolExecutionError, Trace as default };

package/dist/index.d.ts

@@ -0,0 +1,171 @@
+/**
+ * @buildwithtrace/sdk — TypeScript SDK for Trace AI-powered EDA tools.
+ *
+ * @example
+ * ```typescript
+ * import { Trace } from '@buildwithtrace/sdk';
+ *
+ * const trace = new Trace({ apiKey: 'your-api-key' });
+ *
+ * const symbol = await trace.generateSymbol('LM7805 5V voltage regulator');
+ * console.log(symbol.name);      // "LM7805"
+ * console.log(symbol.pinCount);  // 3
+ * symbol.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 results = await trace.search('voltage regulator', { type: 'symbol' });
+ * 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);
+}
+/**
+ * Thrown when an agent turn requests a tool the SDK does NOT execute locally.
+ *
+ * The SDK runs a client-side tool loop for FILE tools (`read_file`, `write`,
+ * `search_replace`, `list_dir`, `grep`, `delete_trace_file`). Engine/GUI tools
+ * — ERC/DRC, gerber/drill/position export, `take_snapshot`, `run_*`, `autoroute`,
+ * etc. — are out of scope and raise this error pointing you at the
+ * `buildwithtrace` CLI or the desktop app.
+ */
+declare class TraceToolExecutionError extends TraceError {
+    constructor(message: string);
+}
+interface TraceConfig {
+    apiKey: string;
+    baseUrl?: string;
+    timeout?: number;
+}
+interface GenerateResult {
+    name: string;
+    type: 'symbol' | 'footprint';
+    description: string;
+    pinCount: number;
+    padCount: number;
+    kicadSym: string | null;
+    kicadMod: string | null;
+    traceJson: Record<string, unknown> | null;
+    warning: string | null;
+    steps: Array<Record<string, unknown>>;
+    save(directory?: string): string;
+}
+interface SearchResult {
+    name: string;
+    library: string;
+    description: string;
+    pinCount: number;
+    padCount: number;
+    category: string;
+    source: string;
+    score: number;
+}
+interface TextResult {
+    text: string;
+    conversationId: string | null;
+    usage: Record<string, unknown> | null;
+}
+interface SearchOptions {
+    type?: 'symbol' | 'footprint';
+    limit?: number;
+}
+interface AskOptions {
+    projectDir?: string;
+    fileContent?: string;
+    appType?: 'eeschema' | 'pcbnew';
+    filePath?: string;
+    conversationId?: string;
+}
+interface ChatOptions {
+    mode?: 'ask' | 'agent' | 'plan';
+    appType?: 'eeschema' | 'pcbnew';
+    projectDir?: string;
+    filePath?: string;
+    fileContent?: string;
+    conversationId?: string;
+    teamId?: string;
+    attachments?: Array<Record<string, unknown>>;
+    /** BYOK: route this turn to your own provider (you pay the provider directly). */
+    llmProvider?: string;
+    llmApiKey?: string;
+    llmModelId?: string;
+}
+declare class Trace {
+    private apiKey;
+    private baseUrl;
+    private timeout;
+    constructor(config: TraceConfig);
+    generateSymbol(description: string, options?: {
+        datasheetUrl?: string;
+        additionalInstructions?: string;
+    }): Promise<GenerateResult>;
+    generateFootprint(description: string, options?: {
+        packageType?: string;
+        datasheetUrl?: string;
+    }): Promise<GenerateResult>;
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    ask(question: string, options?: AskOptions): Promise<TextResult>;
+    review(options?: {
+        projectDir?: string;
+        focus?: string;
+        appType?: 'eeschema' | 'pcbnew';
+        fileContent?: string;
+        filePath?: string;
+    }): Promise<TextResult>;
+    /**
+     * Stream a chat turn and collect the full response. Exposes the full backend
+     * chat contract: pcbnew vs eeschema (`appType`), multi-turn (`conversationId` —
+     * read it back off the result), team workspaces (`teamId`), multimodal
+     * `attachments`, `filePath` + `fileContent`, and BYOK
+     * (`llmProvider`/`llmApiKey`/`llmModelId`).
+     *
+     * NOTE: mode 'agent'/'plan' produce tool calls that run on the caller's
+     * machine. The SDK runs a client-side tool loop for FILE tools (read_file,
+     * write, search_replace, list_dir, grep, delete_trace_file), executing them
+     * under `projectDir` (defaults to process.cwd()) with the same path +
+     * extension allowlist as the CLI/desktop, and POSTing each result back to the
+     * backend so multi-step agent runs continue. Engine/GUI tools (ERC/DRC,
+     * gerber/export, take_snapshot, run_*, autoroute) are out of scope and throw
+     * TraceToolExecutionError — use the `buildwithtrace` CLI for those.
+     */
+    chat(message: string, options?: ChatOptions): Promise<TextResult>;
+    private _post;
+    private static _httpError;
+    private _get;
+    /**
+     * Single source of truth for the /chat/stream request body. Mirrors the
+     * backend ChatRequest contract so the SDK stays in lockstep with the
+     * CLI/desktop instead of sending a stale minimal payload.
+     */
+    private _buildChatBody;
+    /**
+     * Stream /chat/stream and drive a client-side tool loop.
+     *
+     * The backend pauses the SSE stream at each `tool_call` until the client POSTs
+     * the result to /tools/result, so we MUST read the body incrementally (not
+     * buffer it whole — that would dead-lock waiting for `done`). FILE tools are
+     * executed locally under `projectDir`; their result is posted back and the
+     * SAME stream keeps yielding events (the backend drives the multi-step loop)
+     * until `done`. Engine/GUI tools are out of scope and throw.
+     */
+    private _streamChat;
+    private static _parseSSELine;
+    /**
+     * Execute one tool call. FILE tools run locally (sandboxed to projectDir) and
+     * their result is POSTed to /tools/result so the backend continues the stream.
+     * Engine/GUI tools are out of scope and throw TraceToolExecutionError.
+     */
+    private _handleToolCall;
+    /**
+     * POST a tool result back to /api/<version>/tools/result (same base URL +
+     * version as /chat/stream). Non-fatal on failure — like the CLI, we warn and
+     * move on rather than crashing the loop (the backend turn will time out).
+     */
+    private _postToolResult;
+    private _makeGenerateResult;
+}
+
+export { type AskOptions, type ChatOptions, type GenerateResult, type SearchOptions, type SearchResult, type TextResult, Trace, type TraceConfig, TraceError, TraceToolExecutionError, Trace as default };