@scottwalker/claude-connector 0.1.0

package/dist/builder/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/builder/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAwB,MAAM,mBAAmB,CAAC"}

package/dist/client/claude.d.ts

@@ -0,0 +1,120 @@
+import type { ClientOptions, QueryOptions, QueryResult, StreamEvent } from '../types/index.js';
+import type { SessionOptions } from '../types/session.js';
+import type { IExecutor } from '../executor/interface.js';
+import { type InitStage } from '../executor/sdk-executor.js';
+import { Session } from './session.js';
+import { type ScheduledJob } from '../scheduler/scheduler.js';
+/**
+ * Main entry point for claude-connector.
+ *
+ * `Claude` is a **facade** that orchestrates the executor, argument builder,
+ * and parsers behind a clean, minimal API.
+ *
+ * ## Execution modes
+ *
+ * - **CLI mode** (default): each query spawns a new `claude -p` process.
+ *   Simple, no warm-up needed, but slower for interactive use.
+ *
+ * - **SDK mode** (`useSdk: true`): creates a persistent session via the
+ *   Claude Agent SDK. First query requires warm-up (~5-10s), but subsequent
+ *   queries are near-instant. Best for interactive and high-throughput use.
+ *
+ * @example
+ * ```ts
+ * // CLI mode (default)
+ * const claude = new Claude({ model: 'sonnet' })
+ *
+ * // SDK mode (persistent session, fast queries)
+ * const claude = new Claude({ useSdk: true, model: 'sonnet' })
+ * claude.on('init:stage', (stage, msg) => console.log(`[${stage}] ${msg}`))
+ * await claude.init()  // warm up once
+ * const result = await claude.query('Fix bugs')  // fast!
+ * ```
+ */
+export declare class Claude {
+    /** Frozen client-level options. */
+    private readonly options;
+    /** Executor responsible for running CLI commands. */
+    private readonly executor;
+    /** SdkExecutor reference (only when useSdk: true) for lifecycle control. */
+    private readonly sdkExecutor;
+    constructor(options?: ClientOptions, executor?: IExecutor);
+    /**
+     * Initialize the SDK session (warm up).
+     *
+     * Only needed when `useSdk: true`. In CLI mode this is a no-op.
+     *
+     * Subscribe to initialization events before calling:
+     * ```ts
+     * claude.on('init:stage', (stage, message) => {
+     *   console.log(`[${stage}] ${message}`)
+     * })
+     * claude.on('init:ready', () => console.log('Ready!'))
+     * claude.on('init:error', (err) => console.error(err))
+     *
+     * await claude.init()
+     * ```
+     *
+     * Safe to call multiple times — only initializes once.
+     */
+    init(): Promise<void>;
+    /** Whether the SDK session is initialized and ready (always true for CLI mode). */
+    get ready(): boolean;
+    /**
+     * Subscribe to initialization events.
+     *
+     * Events:
+     * - `init:stage` `(stage: InitStage, message: string)` — progress updates
+     *    Stages: `'importing'` → `'creating'` → `'connecting'` → `'ready'`
+     * - `init:ready` — session is warm and queries will be fast
+     * - `init:error` `(error: Error)` — initialization failed
+     *
+     * Only meaningful when `useSdk: true`. In CLI mode, listeners are never called.
+     */
+    on(event: 'init:stage', listener: (stage: InitStage, message: string) => void): this;
+    on(event: 'init:ready', listener: () => void): this;
+    on(event: 'init:error', listener: (error: Error) => void): this;
+    on(event: string, listener: (...args: never[]) => void): this;
+    /**
+     * Execute a one-shot query and return the complete result.
+     *
+     * In SDK mode, auto-initializes if `init()` hasn't been called yet.
+     */
+    query(prompt: string, options?: QueryOptions): Promise<QueryResult>;
+    /**
+     * Execute a query with streaming response.
+     *
+     * Returns an async iterable that yields events as they arrive.
+     * The final event is always `type: 'result'` or `type: 'error'`.
+     */
+    stream(prompt: string, options?: QueryOptions): AsyncIterable<StreamEvent>;
+    /**
+     * Create a session for multi-turn conversation.
+     */
+    session(sessionOptions?: SessionOptions): Session;
+    /**
+     * Schedule a recurring query (equivalent of /loop).
+     */
+    loop(interval: string | number, prompt: string, options?: QueryOptions): ScheduledJob;
+    /**
+     * Run multiple queries in parallel.
+     */
+    parallel(queries: readonly {
+        prompt: string;
+        options?: QueryOptions;
+    }[]): Promise<QueryResult[]>;
+    /**
+     * Abort any running execution on the underlying executor.
+     */
+    abort(): void;
+    /**
+     * Close the SDK session and free resources.
+     * Only needed when `useSdk: true`. In CLI mode this is a no-op.
+     */
+    close(): void;
+    /**
+     * Access the underlying executor (for advanced use / testing).
+     */
+    getExecutor(): IExecutor;
+}
+//# sourceMappingURL=claude.d.ts.map

package/dist/client/claude.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../src/client/claude.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC/F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAE1D,OAAO,EAAe,KAAK,SAAS,EAA2B,MAAM,6BAA6B,CAAC;AAGnG,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAa,KAAK,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,MAAM;IACjB,mCAAmC;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;IAElD,qDAAqD;IACrD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAY;IAErC,4EAA4E;IAC5E,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA4B;gBAE5C,OAAO,GAAE,aAAkB,EAAE,QAAQ,CAAC,EAAE,SAAS;IAsB7D;;;;;;;;;;;;;;;;;OAiBG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAM3B,mFAAmF;IACnF,IAAI,KAAK,IAAI,OAAO,CAGnB;IAED;;;;;;;;;;OAUG;IACH,EAAE,CAAC,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI;IACpF,EAAE,CAAC,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI;IACnD,EAAE,CAAC,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI;IAC/D,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,IAAI,GAAG,IAAI;IAQ7D;;;;OAIG;IACG,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;IAkBzE;;;;;OAKG;IACI,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,aAAa,CAAC,WAAW,CAAC;IAkBjF;;OAEG;IACH,OAAO,CAAC,cAAc,CAAC,EAAE,cAAc,GAAG,OAAO;IAIjD;;OAEG;IACH,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,YAAY;IAKrF;;OAEG;IACG,QAAQ,CACZ,OAAO,EAAE,SAAS;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,YAAY,CAAA;KAAE,EAAE,GAC7D,OAAO,CAAC,WAAW,EAAE,CAAC;IAMzB;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;;OAGG;IACH,KAAK,IAAI,IAAI;IAMb;;OAEG;IACH,WAAW,IAAI,SAAS;CAGzB"}

package/dist/client/claude.js

@@ -0,0 +1,182 @@
+import { CliExecutor } from '../executor/cli-executor.js';
+import { SdkExecutor } from '../executor/sdk-executor.js';
+import { buildArgs, mergeOptions, resolveEnv } from '../builder/args-builder.js';
+import { validateClientOptions, validateQueryOptions, validatePrompt } from '../utils/validation.js';
+import { Session } from './session.js';
+import { Scheduler } from '../scheduler/scheduler.js';
+/**
+ * Main entry point for claude-connector.
+ *
+ * `Claude` is a **facade** that orchestrates the executor, argument builder,
+ * and parsers behind a clean, minimal API.
+ *
+ * ## Execution modes
+ *
+ * - **CLI mode** (default): each query spawns a new `claude -p` process.
+ *   Simple, no warm-up needed, but slower for interactive use.
+ *
+ * - **SDK mode** (`useSdk: true`): creates a persistent session via the
+ *   Claude Agent SDK. First query requires warm-up (~5-10s), but subsequent
+ *   queries are near-instant. Best for interactive and high-throughput use.
+ *
+ * @example
+ * ```ts
+ * // CLI mode (default)
+ * const claude = new Claude({ model: 'sonnet' })
+ *
+ * // SDK mode (persistent session, fast queries)
+ * const claude = new Claude({ useSdk: true, model: 'sonnet' })
+ * claude.on('init:stage', (stage, msg) => console.log(`[${stage}] ${msg}`))
+ * await claude.init()  // warm up once
+ * const result = await claude.query('Fix bugs')  // fast!
+ * ```
+ */
+export class Claude {
+    /** Frozen client-level options. */
+    options;
+    /** Executor responsible for running CLI commands. */
+    executor;
+    /** SdkExecutor reference (only when useSdk: true) for lifecycle control. */
+    sdkExecutor = null;
+    constructor(options = {}, executor) {
+        validateClientOptions(options);
+        this.options = Object.freeze({ ...options });
+        if (executor) {
+            this.executor = executor;
+        }
+        else if (options.useSdk) {
+            const sdkOpts = {
+                model: options.model,
+                pathToClaudeCodeExecutable: options.executable,
+                permissionMode: options.permissionMode,
+                allowedTools: options.allowedTools ? [...options.allowedTools] : undefined,
+                disallowedTools: options.disallowedTools ? [...options.disallowedTools] : undefined,
+                env: options.env,
+            };
+            this.sdkExecutor = new SdkExecutor(sdkOpts);
+            this.executor = this.sdkExecutor;
+        }
+        else {
+            this.executor = new CliExecutor(options.executable);
+        }
+    }
+    /**
+     * Initialize the SDK session (warm up).
+     *
+     * Only needed when `useSdk: true`. In CLI mode this is a no-op.
+     *
+     * Subscribe to initialization events before calling:
+     * ```ts
+     * claude.on('init:stage', (stage, message) => {
+     *   console.log(`[${stage}] ${message}`)
+     * })
+     * claude.on('init:ready', () => console.log('Ready!'))
+     * claude.on('init:error', (err) => console.error(err))
+     *
+     * await claude.init()
+     * ```
+     *
+     * Safe to call multiple times — only initializes once.
+     */
+    async init() {
+        if (this.sdkExecutor) {
+            await this.sdkExecutor.init();
+        }
+    }
+    /** Whether the SDK session is initialized and ready (always true for CLI mode). */
+    get ready() {
+        if (this.sdkExecutor)
+            return this.sdkExecutor.ready;
+        return true;
+    }
+    on(event, listener) {
+        if (this.sdkExecutor) {
+            this.sdkExecutor.on(event, listener);
+        }
+        return this;
+    }
+    /**
+     * Execute a one-shot query and return the complete result.
+     *
+     * In SDK mode, auto-initializes if `init()` hasn't been called yet.
+     */
+    async query(prompt, options) {
+        validatePrompt(prompt);
+        if (options)
+            validateQueryOptions(options);
+        const resolved = mergeOptions(this.options, options, {
+            prompt,
+            outputFormat: 'json',
+        });
+        const args = buildArgs(resolved);
+        const env = resolveEnv(this.options, options);
+        return this.executor.execute(args, {
+            cwd: resolved.cwd,
+            env,
+            input: options?.input,
+        });
+    }
+    /**
+     * Execute a query with streaming response.
+     *
+     * Returns an async iterable that yields events as they arrive.
+     * The final event is always `type: 'result'` or `type: 'error'`.
+     */
+    async *stream(prompt, options) {
+        validatePrompt(prompt);
+        if (options)
+            validateQueryOptions(options);
+        const resolved = mergeOptions(this.options, options, {
+            prompt,
+            outputFormat: 'stream-json',
+        });
+        const args = buildArgs(resolved);
+        const env = resolveEnv(this.options, options);
+        yield* this.executor.stream(args, {
+            cwd: resolved.cwd,
+            env,
+            input: options?.input,
+        });
+    }
+    /**
+     * Create a session for multi-turn conversation.
+     */
+    session(sessionOptions) {
+        return new Session(this.options, this.executor, sessionOptions);
+    }
+    /**
+     * Schedule a recurring query (equivalent of /loop).
+     */
+    loop(interval, prompt, options) {
+        const scheduler = new Scheduler(this);
+        return scheduler.schedule(interval, prompt, options);
+    }
+    /**
+     * Run multiple queries in parallel.
+     */
+    async parallel(queries) {
+        return Promise.all(queries.map(({ prompt, options }) => this.query(prompt, options)));
+    }
+    /**
+     * Abort any running execution on the underlying executor.
+     */
+    abort() {
+        this.executor.abort?.();
+    }
+    /**
+     * Close the SDK session and free resources.
+     * Only needed when `useSdk: true`. In CLI mode this is a no-op.
+     */
+    close() {
+        if (this.sdkExecutor) {
+            this.sdkExecutor.close();
+        }
+    }
+    /**
+     * Access the underlying executor (for advanced use / testing).
+     */
+    getExecutor() {
+        return this.executor;
+    }
+}
+//# sourceMappingURL=claude.js.map

package/dist/client/claude.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude.js","sourceRoot":"","sources":["../../src/client/claude.ts"],"names":[],"mappings":"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"}

package/dist/client/session.d.ts

@@ -0,0 +1,64 @@
+import type { ClientOptions, QueryOptions, QueryResult, StreamEvent } from '../types/index.js';
+import type { SessionOptions } from '../types/session.js';
+import type { IExecutor } from '../executor/interface.js';
+/**
+ * A stateful conversation session.
+ *
+ * Sessions wrap the Claude Code `--continue` / `--resume` mechanism to
+ * provide multi-turn conversations with persistent context.
+ *
+ * ## Lifecycle
+ *
+ * 1. **First query**: runs normally, captures the `sessionId` from the result.
+ * 2. **Subsequent queries**: automatically pass `--resume <sessionId>` to continue
+ *    the conversation with full context.
+ *
+ * ## Concurrency
+ *
+ * Sessions are NOT safe for concurrent queries. Each query must complete before
+ * the next one starts. For parallel work, use separate sessions or `claude.parallel()`.
+ *
+ * @example
+ * ```ts
+ * const session = claude.session()
+ *
+ * const r1 = await session.query('What files are in src/?')
+ * // Claude reads the directory
+ *
+ * const r2 = await session.query('Refactor the largest file')
+ * // Claude remembers the previous context
+ *
+ * console.log(session.sessionId) // 'abc-123-...'
+ * ```
+ */
+export declare class Session {
+    private readonly clientOptions;
+    private readonly executor;
+    private readonly sessionOptions;
+    /** Session ID, populated after the first query completes. */
+    private _sessionId;
+    /** Number of queries executed in this session. */
+    private _queryCount;
+    constructor(clientOptions: Readonly<ClientOptions>, executor: IExecutor, sessionOptions?: SessionOptions);
+    /** Current session ID (null until the first query completes). */
+    get sessionId(): string | null;
+    /** Number of queries executed so far. */
+    get queryCount(): number;
+    /**
+     * Send a query within this session.
+     *
+     * The first query creates the session; subsequent queries resume it.
+     */
+    query(prompt: string, options?: QueryOptions): Promise<QueryResult>;
+    /**
+     * Send a query with streaming response within this session.
+     */
+    stream(prompt: string, options?: QueryOptions): AsyncIterable<StreamEvent>;
+    /**
+     * Abort the current running query in this session.
+     */
+    abort(): void;
+    private buildSessionArgs;
+    private updateSessionState;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/client/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/client/session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC/F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAI1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,OAAO;IAClB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA0B;IACxD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAY;IACrC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAiB;IAEhD,6DAA6D;IAC7D,OAAO,CAAC,UAAU,CAAgB;IAElC,kDAAkD;IAClD,OAAO,CAAC,WAAW,CAAK;gBAGtB,aAAa,EAAE,QAAQ,CAAC,aAAa,CAAC,EACtC,QAAQ,EAAE,SAAS,EACnB,cAAc,GAAE,cAAmB;IAQrC,iEAAiE;IACjE,IAAI,SAAS,IAAI,MAAM,GAAG,IAAI,CAE7B;IAED,yCAAyC;IACzC,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED;;;;OAIG;IACG,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;IAqBzE;;OAEG;IACI,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,aAAa,CAAC,WAAW,CAAC;IAwBjF;;OAEG;IACH,KAAK,IAAI,IAAI;IAMb,OAAO,CAAC,gBAAgB;IAkBxB,OAAO,CAAC,kBAAkB;CAM3B"}

package/dist/client/session.js

@@ -0,0 +1,128 @@
+import { buildArgs, mergeOptions, resolveEnv } from '../builder/args-builder.js';
+import { validateQueryOptions, validatePrompt } from '../utils/validation.js';
+/**
+ * A stateful conversation session.
+ *
+ * Sessions wrap the Claude Code `--continue` / `--resume` mechanism to
+ * provide multi-turn conversations with persistent context.
+ *
+ * ## Lifecycle
+ *
+ * 1. **First query**: runs normally, captures the `sessionId` from the result.
+ * 2. **Subsequent queries**: automatically pass `--resume <sessionId>` to continue
+ *    the conversation with full context.
+ *
+ * ## Concurrency
+ *
+ * Sessions are NOT safe for concurrent queries. Each query must complete before
+ * the next one starts. For parallel work, use separate sessions or `claude.parallel()`.
+ *
+ * @example
+ * ```ts
+ * const session = claude.session()
+ *
+ * const r1 = await session.query('What files are in src/?')
+ * // Claude reads the directory
+ *
+ * const r2 = await session.query('Refactor the largest file')
+ * // Claude remembers the previous context
+ *
+ * console.log(session.sessionId) // 'abc-123-...'
+ * ```
+ */
+export class Session {
+    clientOptions;
+    executor;
+    sessionOptions;
+    /** Session ID, populated after the first query completes. */
+    _sessionId;
+    /** Number of queries executed in this session. */
+    _queryCount = 0;
+    constructor(clientOptions, executor, sessionOptions = {}) {
+        this.clientOptions = clientOptions;
+        this.executor = executor;
+        this.sessionOptions = sessionOptions;
+        this._sessionId = sessionOptions.resume ?? null;
+    }
+    /** Current session ID (null until the first query completes). */
+    get sessionId() {
+        return this._sessionId;
+    }
+    /** Number of queries executed so far. */
+    get queryCount() {
+        return this._queryCount;
+    }
+    /**
+     * Send a query within this session.
+     *
+     * The first query creates the session; subsequent queries resume it.
+     */
+    async query(prompt, options) {
+        validatePrompt(prompt);
+        if (options)
+            validateQueryOptions(options);
+        const args = this.buildSessionArgs(prompt, 'json', options);
+        const env = resolveEnv(this.clientOptions, options);
+        const resolved = mergeOptions(this.clientOptions, options, {
+            prompt,
+            outputFormat: 'json',
+        });
+        const result = await this.executor.execute(args, {
+            cwd: resolved.cwd,
+            env,
+            input: options?.input,
+        });
+        this.updateSessionState(result.sessionId);
+        return result;
+    }
+    /**
+     * Send a query with streaming response within this session.
+     */
+    async *stream(prompt, options) {
+        validatePrompt(prompt);
+        if (options)
+            validateQueryOptions(options);
+        const args = this.buildSessionArgs(prompt, 'stream-json', options);
+        const env = resolveEnv(this.clientOptions, options);
+        const resolved = mergeOptions(this.clientOptions, options, {
+            prompt,
+            outputFormat: 'stream-json',
+        });
+        for await (const event of this.executor.stream(args, {
+            cwd: resolved.cwd,
+            env,
+            input: options?.input,
+        })) {
+            // Capture session ID from result events
+            if (event.type === 'result' && event.sessionId) {
+                this.updateSessionState(event.sessionId);
+            }
+            yield event;
+        }
+    }
+    /**
+     * Abort the current running query in this session.
+     */
+    abort() {
+        this.executor.abort?.();
+    }
+    // ── Private helpers ───────────────────────────────────────────────
+    buildSessionArgs(prompt, outputFormat, queryOptions) {
+        const isFirstQuery = this._queryCount === 0;
+        const resolved = mergeOptions(this.clientOptions, queryOptions, {
+            prompt,
+            outputFormat,
+            sessionId: this._sessionId ?? undefined,
+            continueSession: isFirstQuery && this.sessionOptions.continue,
+            forkSession: isFirstQuery && this.sessionOptions.fork,
+        });
+        return buildArgs(resolved);
+    }
+    updateSessionState(sessionId) {
+        if (sessionId) {
+            this._sessionId = sessionId;
+        }
+        this._queryCount++;
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/client/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/client/session.ts"],"names":[],"mappings":"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"}

package/dist/errors/errors.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Base error class for all claude-connector errors.
+ *
+ * Consumers can catch this to handle any library error uniformly:
+ * ```ts
+ * try {
+ *   await claude.query('...')
+ * } catch (e) {
+ *   if (e instanceof ClaudeConnectorError) { ... }
+ * }
+ * ```
+ */
+export declare class ClaudeConnectorError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when the Claude Code CLI binary cannot be found at the specified path.
+ */
+export declare class CliNotFoundError extends ClaudeConnectorError {
+    readonly executable: string;
+    constructor(executable: string);
+}
+/**
+ * Thrown when the CLI process exits with a non-zero code.
+ */
+export declare class CliExecutionError extends ClaudeConnectorError {
+    readonly exitCode: number;
+    readonly stderr: string;
+    constructor(message: string, exitCode: number, stderr: string);
+}
+/**
+ * Thrown when the CLI process exceeds the configured timeout.
+ */
+export declare class CliTimeoutError extends ClaudeConnectorError {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+/**
+ * Thrown when CLI output cannot be parsed (unexpected format).
+ */
+export declare class ParseError extends ClaudeConnectorError {
+    readonly rawOutput: string;
+    constructor(message: string, rawOutput: string);
+}
+/**
+ * Thrown when invalid options are provided to the client.
+ */
+export declare class ValidationError extends ClaudeConnectorError {
+    readonly field: string;
+    constructor(field: string, message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,oBAAoB;IACxD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAEhB,UAAU,EAAE,MAAM;CAS/B;AAED;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,oBAAoB;IACzD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAM9D;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,oBAAoB;IACvD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,SAAS,EAAE,MAAM;CAK9B;AAED;;GAEG;AACH,qBAAa,UAAW,SAAQ,oBAAoB;IAClD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAK/C;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,oBAAoB;IACvD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBAEX,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK3C"}

package/dist/errors/errors.js

@@ -0,0 +1,78 @@
+/**
+ * Base error class for all claude-connector errors.
+ *
+ * Consumers can catch this to handle any library error uniformly:
+ * ```ts
+ * try {
+ *   await claude.query('...')
+ * } catch (e) {
+ *   if (e instanceof ClaudeConnectorError) { ... }
+ * }
+ * ```
+ */
+export class ClaudeConnectorError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ClaudeConnectorError';
+    }
+}
+/**
+ * Thrown when the Claude Code CLI binary cannot be found at the specified path.
+ */
+export class CliNotFoundError extends ClaudeConnectorError {
+    executable;
+    constructor(executable) {
+        super(`Claude Code CLI not found at '${executable}'. ` +
+            `Ensure it is installed and the path is correct. ` +
+            `Install: https://docs.anthropic.com/en/docs/claude-code/overview`);
+        this.name = 'CliNotFoundError';
+        this.executable = executable;
+    }
+}
+/**
+ * Thrown when the CLI process exits with a non-zero code.
+ */
+export class CliExecutionError extends ClaudeConnectorError {
+    exitCode;
+    stderr;
+    constructor(message, exitCode, stderr) {
+        super(message);
+        this.name = 'CliExecutionError';
+        this.exitCode = exitCode;
+        this.stderr = stderr;
+    }
+}
+/**
+ * Thrown when the CLI process exceeds the configured timeout.
+ */
+export class CliTimeoutError extends ClaudeConnectorError {
+    timeoutMs;
+    constructor(timeoutMs) {
+        super(`Claude Code CLI timed out after ${timeoutMs}ms`);
+        this.name = 'CliTimeoutError';
+        this.timeoutMs = timeoutMs;
+    }
+}
+/**
+ * Thrown when CLI output cannot be parsed (unexpected format).
+ */
+export class ParseError extends ClaudeConnectorError {
+    rawOutput;
+    constructor(message, rawOutput) {
+        super(message);
+        this.name = 'ParseError';
+        this.rawOutput = rawOutput;
+    }
+}
+/**
+ * Thrown when invalid options are provided to the client.
+ */
+export class ValidationError extends ClaudeConnectorError {
+    field;
+    constructor(field, message) {
+        super(`Invalid option '${field}': ${message}`);
+        this.name = 'ValidationError';
+        this.field = field;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC7C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,gBAAiB,SAAQ,oBAAoB;IAC/C,UAAU,CAAS;IAE5B,YAAY,UAAkB;QAC5B,KAAK,CACH,iCAAiC,UAAU,KAAK;YAChD,kDAAkD;YAClD,kEAAkE,CACnE,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,iBAAkB,SAAQ,oBAAoB;IAChD,QAAQ,CAAS;IACjB,MAAM,CAAS;IAExB,YAAY,OAAe,EAAE,QAAgB,EAAE,MAAc;QAC3D,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,eAAgB,SAAQ,oBAAoB;IAC9C,SAAS,CAAS;IAE3B,YAAY,SAAiB;QAC3B,KAAK,CAAC,mCAAmC,SAAS,IAAI,CAAC,CAAC;QACxD,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,UAAW,SAAQ,oBAAoB;IACzC,SAAS,CAAS;IAE3B,YAAY,OAAe,EAAE,SAAiB;QAC5C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;QACzB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,eAAgB,SAAQ,oBAAoB;IAC9C,KAAK,CAAS;IAEvB,YAAY,KAAa,EAAE,OAAe;QACxC,KAAK,CAAC,mBAAmB,KAAK,MAAM,OAAO,EAAE,CAAC,CAAC;QAC/C,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF"}

package/dist/errors/index.d.ts

@@ -0,0 +1,2 @@
+export { ClaudeConnectorError, CliNotFoundError, CliExecutionError, CliTimeoutError, ParseError, ValidationError, } from './errors.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/errors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,UAAU,EACV,eAAe,GAChB,MAAM,aAAa,CAAC"}

package/dist/errors/index.js

@@ -0,0 +1,2 @@
+export { ClaudeConnectorError, CliNotFoundError, CliExecutionError, CliTimeoutError, ParseError, ValidationError, } from './errors.js';
+//# sourceMappingURL=index.js.map