@boostecom/provider 0.0.1

package/docs/src/errors.ts

@@ -0,0 +1,216 @@
+import { APICallError, LoadAPIKeyError } from '@ai-sdk/provider';
+
+/**
+ * Metadata associated with Claude Code SDK errors.
+ * Provides additional context about command execution failures.
+ */
+export interface ClaudeCodeErrorMetadata {
+  /**
+   * Error code from the CLI process (e.g., 'ENOENT', 'ETIMEDOUT').
+   */
+  code?: string;
+
+  /**
+   * Exit code from the Claude Code SDK process.
+   * Common codes:
+   * - 401: Authentication error
+   * - 1: General error
+   */
+  exitCode?: number;
+
+  /**
+   * Standard error output from the CLI process.
+   */
+  stderr?: string;
+
+  /**
+   * Excerpt from the prompt that caused the error.
+   * Limited to first 200 characters for debugging.
+   */
+  promptExcerpt?: string;
+}
+
+/**
+ * Creates an APICallError with Claude Code specific metadata.
+ * Used for general CLI execution errors.
+ *
+ * @param options - Error details and metadata
+ * @param options.message - Human-readable error message
+ * @param options.code - Error code from the CLI process
+ * @param options.exitCode - Exit code from the CLI
+ * @param options.stderr - Standard error output
+ * @param options.promptExcerpt - Excerpt of the prompt that caused the error
+ * @param options.isRetryable - Whether the error is potentially retryable
+ * @returns An APICallError instance with Claude Code metadata
+ *
+ * @example
+ * ```typescript
+ * throw createAPICallError({
+ *   message: 'Claude Code SDK failed',
+ *   code: 'ENOENT',
+ *   isRetryable: true
+ * });
+ * ```
+ */
+export function createAPICallError({
+  message,
+  code,
+  exitCode,
+  stderr,
+  promptExcerpt,
+  isRetryable = false,
+}: ClaudeCodeErrorMetadata & {
+  message: string;
+  isRetryable?: boolean;
+}): APICallError {
+  const metadata: ClaudeCodeErrorMetadata = {
+    code,
+    exitCode,
+    stderr,
+    promptExcerpt,
+  };
+
+  return new APICallError({
+    message,
+    isRetryable,
+    url: 'claude-code-cli://command',
+    requestBodyValues: promptExcerpt ? { prompt: promptExcerpt } : undefined,
+    data: metadata,
+  });
+}
+
+/**
+ * Creates an authentication error for Claude Code SDK login failures.
+ *
+ * @param options - Error configuration
+ * @param options.message - Error message describing the authentication failure
+ * @returns A LoadAPIKeyError instance
+ *
+ * @example
+ * ```typescript
+ * throw createAuthenticationError({
+ *   message: 'Please run "claude login" to authenticate'
+ * });
+ * ```
+ */
+export function createAuthenticationError({ message }: { message: string }): LoadAPIKeyError {
+  return new LoadAPIKeyError({
+    message:
+      message || 'Authentication failed. Please ensure Claude Code SDK is properly authenticated.',
+  });
+}
+
+/**
+ * Creates a timeout error for Claude Code SDK operations.
+ *
+ * @param options - Timeout error details
+ * @param options.message - Error message describing the timeout
+ * @param options.promptExcerpt - Excerpt of the prompt that timed out
+ * @param options.timeoutMs - Timeout duration in milliseconds
+ * @returns An APICallError instance configured as a timeout error
+ *
+ * @example
+ * ```typescript
+ * throw createTimeoutError({
+ *   message: 'Request timed out after 2 minutes',
+ *   timeoutMs: 120000
+ * });
+ * ```
+ */
+export function createTimeoutError({
+  message,
+  promptExcerpt,
+  timeoutMs,
+}: {
+  message: string;
+  promptExcerpt?: string;
+  timeoutMs?: number;
+}): APICallError {
+  // Store timeoutMs in metadata for potential use by error handlers
+  const metadata: ClaudeCodeErrorMetadata = {
+    code: 'TIMEOUT',
+    promptExcerpt,
+  };
+
+  return new APICallError({
+    message,
+    isRetryable: true,
+    url: 'claude-code-cli://command',
+    requestBodyValues: promptExcerpt ? { prompt: promptExcerpt } : undefined,
+    data: timeoutMs !== undefined ? { ...metadata, timeoutMs } : metadata,
+  });
+}
+
+/**
+ * Checks if an error is an authentication error.
+ * Returns true for LoadAPIKeyError instances or APICallError with exit code 401.
+ *
+ * @param error - The error to check
+ * @returns True if the error is an authentication error
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await model.generate(...);
+ * } catch (error) {
+ *   if (isAuthenticationError(error)) {
+ *     console.log('Please authenticate with Claude Code SDK');
+ *   }
+ * }
+ * ```
+ */
+export function isAuthenticationError(error: unknown): boolean {
+  if (error instanceof LoadAPIKeyError) return true;
+  if (error instanceof APICallError && (error.data as ClaudeCodeErrorMetadata)?.exitCode === 401)
+    return true;
+  return false;
+}
+
+/**
+ * Checks if an error is a timeout error.
+ * Returns true for APICallError instances with code 'TIMEOUT'.
+ *
+ * @param error - The error to check
+ * @returns True if the error is a timeout error
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await model.generate(...);
+ * } catch (error) {
+ *   if (isTimeoutError(error)) {
+ *     console.log('Request timed out, consider retrying');
+ *   }
+ * }
+ * ```
+ */
+export function isTimeoutError(error: unknown): boolean {
+  if (error instanceof APICallError && (error.data as ClaudeCodeErrorMetadata)?.code === 'TIMEOUT')
+    return true;
+  return false;
+}
+
+/**
+ * Extracts Claude Code error metadata from an error object.
+ *
+ * @param error - The error to extract metadata from
+ * @returns The error metadata if available, undefined otherwise
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await model.generate(...);
+ * } catch (error) {
+ *   const metadata = getErrorMetadata(error);
+ *   if (metadata?.exitCode === 401) {
+ *     console.log('Authentication required');
+ *   }
+ * }
+ * ```
+ */
+export function getErrorMetadata(error: unknown): ClaudeCodeErrorMetadata | undefined {
+  if (error instanceof APICallError && error.data) {
+    return error.data as ClaudeCodeErrorMetadata;
+  }
+  return undefined;
+}

package/docs/src/index.test.ts

@@ -0,0 +1,49 @@
+import { describe, it, expect } from 'vitest';
+
+describe('index exports', () => {
+  it('should export all expected functions and types', async () => {
+    const exports = await import('./index.js');
+
+    // Provider exports
+    expect(exports.createClaudeCode).toBeDefined();
+    expect(typeof exports.createClaudeCode).toBe('function');
+    expect(exports.claudeCode).toBeDefined();
+    expect(typeof exports.claudeCode).toBe('function');
+
+    // Language model exports
+    expect(exports.ClaudeCodeLanguageModel).toBeDefined();
+    expect(typeof exports.ClaudeCodeLanguageModel).toBe('function');
+
+    // Error handling exports
+    expect(exports.isAuthenticationError).toBeDefined();
+    expect(typeof exports.isAuthenticationError).toBe('function');
+    expect(exports.isTimeoutError).toBeDefined();
+    expect(typeof exports.isTimeoutError).toBe('function');
+    expect(exports.getErrorMetadata).toBeDefined();
+    expect(typeof exports.getErrorMetadata).toBe('function');
+    expect(exports.createAPICallError).toBeDefined();
+    expect(typeof exports.createAPICallError).toBe('function');
+    expect(exports.createAuthenticationError).toBeDefined();
+    expect(typeof exports.createAuthenticationError).toBe('function');
+    expect(exports.createTimeoutError).toBeDefined();
+    expect(typeof exports.createTimeoutError).toBe('function');
+
+    // SDK passthroughs
+    expect(exports.createSdkMcpServer).toBeDefined();
+    expect(typeof exports.createSdkMcpServer).toBe('function');
+    expect(exports.tool).toBeDefined();
+    expect(typeof exports.tool).toBe('function');
+  });
+
+  it('should export correct modules', async () => {
+    const indexExports = await import('./index.js');
+    const providerExports = await import('./claude-code-provider.js');
+    const errorExports = await import('./errors.js');
+
+    // Check that exported functions are the same references
+    expect(indexExports.createClaudeCode).toBe(providerExports.createClaudeCode);
+    expect(indexExports.claudeCode).toBe(providerExports.claudeCode);
+    expect(indexExports.isAuthenticationError).toBe(errorExports.isAuthenticationError);
+    expect(indexExports.isTimeoutError).toBe(errorExports.isTimeoutError);
+  });
+});

package/docs/src/index.ts

@@ -0,0 +1,98 @@
+/**
+ * Provider exports for creating and configuring Claude Code instances.
+ * @module claude-code
+ */
+
+/**
+ * Creates a new Claude Code provider instance and the default provider instance.
+ * @see {@link createClaudeCode} for creating custom provider instances
+ * @see {@link claudeCode} for the default provider instance
+ */
+export { createClaudeCode, claudeCode } from './claude-code-provider.js';
+
+/**
+ * Type definitions for the Claude Code provider.
+ * @see {@link ClaudeCodeProvider} for the provider interface
+ * @see {@link ClaudeCodeProviderSettings} for provider configuration options
+ */
+export type { ClaudeCodeProvider, ClaudeCodeProviderSettings } from './claude-code-provider.js';
+
+/**
+ * Language model implementation for Claude Code.
+ * This class implements the AI SDK's LanguageModelV3 interface.
+ */
+export { ClaudeCodeLanguageModel } from './claude-code-language-model.js';
+
+/**
+ * Type definitions for Claude Code language models.
+ * @see {@link ClaudeCodeModelId} for supported model identifiers
+ * @see {@link ClaudeCodeLanguageModelOptions} for model configuration options
+ */
+export type {
+  ClaudeCodeModelId,
+  ClaudeCodeLanguageModelOptions,
+} from './claude-code-language-model.js';
+
+/**
+ * Settings for configuring Claude Code behavior.
+ * Includes options for customizing the CLI execution, permissions, and tool usage.
+ */
+export type { ClaudeCodeSettings, Logger, MessageInjector } from './types.js';
+
+// Convenience re-exports from the SDK for custom tools and hooks
+export { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk';
+export { createCustomMcpServer } from './mcp-helpers.js';
+export type { ToolAnnotations, MinimalCallToolResult } from './mcp-helpers.js';
+export type {
+  HookEvent,
+  HookCallback,
+  HookCallbackMatcher,
+  HookInput,
+  HookJSONOutput,
+  PreToolUseHookInput,
+  PostToolUseHookInput,
+  UserPromptSubmitHookInput,
+  SessionStartHookInput,
+  SessionEndHookInput,
+  TeammateIdleHookInput,
+  TaskCompletedHookInput,
+  CanUseTool,
+  PermissionResult,
+  PermissionUpdate,
+  PermissionBehavior,
+  PermissionRuleValue,
+  McpServerConfig,
+  McpSdkServerConfigWithInstance,
+  OutputFormat,
+  SpawnedProcess,
+  SpawnOptions,
+  AgentMcpServerSpec,
+  // Query interface for mid-stream message injection via streamInput()
+  Query,
+} from '@anthropic-ai/claude-agent-sdk';
+
+/**
+ * Error handling utilities for Claude Code.
+ * These functions help create and identify specific error types.
+ *
+ * @see {@link isAuthenticationError} to check for authentication failures
+ * @see {@link isTimeoutError} to check for timeout errors
+ * @see {@link getErrorMetadata} to extract error metadata
+ * @see {@link createAPICallError} to create general API errors
+ * @see {@link createAuthenticationError} to create authentication errors
+ * @see {@link createTimeoutError} to create timeout errors
+ */
+export {
+  isAuthenticationError,
+  isTimeoutError,
+  getErrorMetadata,
+  createAPICallError,
+  createAuthenticationError,
+  createTimeoutError,
+} from './errors.js';
+
+/**
+ * Metadata associated with Claude Code errors.
+ * Contains additional context about CLI execution failures.
+ */
+export type { ClaudeCodeErrorMetadata } from './errors.js';

package/docs/src/logger.integration.test.ts

@@ -0,0 +1,164 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { createClaudeCode } from '../src/index.js';
+import type { Logger } from '../src/types.js';
+
+describe('logger integration', () => {
+  let originalConsoleWarn: typeof console.warn;
+  let originalConsoleError: typeof console.error;
+  let consoleWarnSpy: any;
+  let consoleErrorSpy: any;
+
+  beforeEach(() => {
+    originalConsoleWarn = console.warn;
+    originalConsoleError = console.error;
+    consoleWarnSpy = vi.fn();
+    consoleErrorSpy = vi.fn();
+    console.warn = consoleWarnSpy;
+    console.error = consoleErrorSpy;
+  });
+
+  afterEach(() => {
+    console.warn = originalConsoleWarn;
+    console.error = originalConsoleError;
+  });
+
+  describe('createClaudeCode with logger settings', () => {
+    it('should use console logger by default', () => {
+      createClaudeCode({
+        defaultSettings: {
+          maxTurns: 99, // High value to trigger warning
+        },
+      });
+
+      expect(consoleWarnSpy).toHaveBeenCalledWith(expect.stringContaining('High maxTurns value'));
+    });
+
+    it('should respect logger: false setting', () => {
+      createClaudeCode({
+        defaultSettings: {
+          logger: false,
+          maxTurns: 99, // High value that would normally trigger warning
+        },
+      });
+
+      expect(consoleWarnSpy).not.toHaveBeenCalled();
+    });
+
+    it('should use custom logger when provided', () => {
+      const customLogger: Logger = {
+        debug: vi.fn(),
+        info: vi.fn(),
+        warn: vi.fn(),
+        error: vi.fn(),
+      };
+
+      createClaudeCode({
+        defaultSettings: {
+          logger: customLogger,
+          maxTurns: 99, // High value to trigger warning
+        },
+      });
+
+      expect(customLogger.warn).toHaveBeenCalledWith(
+        expect.stringContaining('High maxTurns value')
+      );
+      expect(consoleWarnSpy).not.toHaveBeenCalled();
+    });
+
+    it('should pass logger to created models', () => {
+      const customLogger: Logger = {
+        debug: vi.fn(),
+        info: vi.fn(),
+        warn: vi.fn(),
+        error: vi.fn(),
+      };
+
+      const provider = createClaudeCode({
+        defaultSettings: {
+          logger: customLogger,
+        },
+      });
+
+      // Create a model with an unknown ID to trigger warning
+      provider('unknown-model-id');
+
+      expect(customLogger.warn).toHaveBeenCalledWith(expect.stringContaining('Unknown model ID'));
+    });
+
+    it('should allow model-specific logger override', () => {
+      const providerLogger: Logger = {
+        debug: vi.fn(),
+        info: vi.fn(),
+        warn: vi.fn(),
+        error: vi.fn(),
+      };
+
+      const modelLogger: Logger = {
+        debug: vi.fn(),
+        info: vi.fn(),
+        warn: vi.fn(),
+        error: vi.fn(),
+      };
+
+      const provider = createClaudeCode({
+        defaultSettings: {
+          logger: providerLogger,
+        },
+      });
+
+      // Create a model with its own logger
+      provider('unknown-model', {
+        logger: modelLogger,
+      });
+
+      expect(modelLogger.warn).toHaveBeenCalledWith(expect.stringContaining('Unknown model ID'));
+      expect(providerLogger.warn).not.toHaveBeenCalled();
+    });
+
+    it('should handle image input warnings', async () => {
+      const customLogger: Logger = {
+        debug: vi.fn(),
+        info: vi.fn(),
+        warn: vi.fn(),
+        error: vi.fn(),
+      };
+
+      const provider = createClaudeCode({
+        defaultSettings: {
+          logger: customLogger,
+        },
+      });
+
+      provider('opus');
+
+      // Mock the query function to prevent actual API calls
+      const { ClaudeCodeLanguageModel } = await import('../src/claude-code-language-model.js');
+      const proto = ClaudeCodeLanguageModel.prototype as any;
+
+      // Access the private method through prototype
+      const result = proto.generateAllWarnings.call(
+        {
+          modelValidationWarning: undefined,
+          settingsValidationWarnings: [],
+          logger: customLogger,
+        },
+        {
+          prompt: [
+            {
+              role: 'user',
+              content: [
+                { type: 'text', text: 'Hello' },
+                { type: 'image', image: new Uint8Array([]) },
+              ],
+            },
+          ],
+        },
+        'test prompt'
+      );
+
+      // The warning should be in the warnings array, not logged directly
+      expect(customLogger.warn).not.toHaveBeenCalled();
+      expect(result.some((w: any) => w.message?.includes('image inputs'))).toBe(false);
+    });
+  });
+});

package/docs/src/logger.test.ts

@@ -0,0 +1,184 @@
+import { describe, it, expect, vi } from 'vitest';
+import { getLogger, createVerboseLogger } from './logger.js';
+import type { Logger } from './types.js';
+
+describe('logger', () => {
+  describe('getLogger', () => {
+    it('should return default logger when undefined', () => {
+      const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const logger = getLogger(undefined);
+
+      logger.warn('test warning');
+
+      expect(consoleSpy).toHaveBeenCalledWith('[WARN] test warning');
+      consoleSpy.mockRestore();
+    });
+
+    it('should support all log levels with default logger', () => {
+      const debugSpy = vi.spyOn(console, 'debug').mockImplementation(() => {});
+      const infoSpy = vi.spyOn(console, 'info').mockImplementation(() => {});
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+      const logger = getLogger(undefined);
+
+      logger.debug('test debug');
+      logger.info('test info');
+      logger.warn('test warning');
+      logger.error('test error');
+
+      expect(debugSpy).toHaveBeenCalledWith('[DEBUG] test debug');
+      expect(infoSpy).toHaveBeenCalledWith('[INFO] test info');
+      expect(warnSpy).toHaveBeenCalledWith('[WARN] test warning');
+      expect(errorSpy).toHaveBeenCalledWith('[ERROR] test error');
+
+      debugSpy.mockRestore();
+      infoSpy.mockRestore();
+      warnSpy.mockRestore();
+      errorSpy.mockRestore();
+    });
+
+    it('should return noop logger when false', () => {
+      const logger = getLogger(false);
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+      logger.debug('test debug');
+      logger.info('test info');
+      logger.warn('test warning');
+      logger.error('test error');
+
+      expect(warnSpy).not.toHaveBeenCalled();
+      expect(errorSpy).not.toHaveBeenCalled();
+      warnSpy.mockRestore();
+      errorSpy.mockRestore();
+    });
+
+    it('should return custom logger when provided', () => {
+      const customLogger: Logger = {
+        debug: vi.fn(),
+        info: vi.fn(),
+        warn: vi.fn(),
+        error: vi.fn(),
+      };
+
+      const logger = getLogger(customLogger);
+
+      expect(logger).toBe(customLogger);
+
+      logger.debug('custom debug');
+      logger.info('custom info');
+      logger.warn('custom warning');
+      logger.error('custom error');
+
+      expect(customLogger.debug).toHaveBeenCalledWith('custom debug');
+      expect(customLogger.info).toHaveBeenCalledWith('custom info');
+      expect(customLogger.warn).toHaveBeenCalledWith('custom warning');
+      expect(customLogger.error).toHaveBeenCalledWith('custom error');
+    });
+
+    it('should handle error logging with default logger', () => {
+      const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+      const logger = getLogger(undefined);
+
+      logger.error('test error');
+
+      expect(consoleSpy).toHaveBeenCalledWith('[ERROR] test error');
+      consoleSpy.mockRestore();
+    });
+  });
+
+  describe('createVerboseLogger', () => {
+    it('should allow all log levels when verbose is true', () => {
+      const mockLogger: Logger = {
+        debug: vi.fn(),
+        info: vi.fn(),
+        warn: vi.fn(),
+        error: vi.fn(),
+      };
+
+      const logger = createVerboseLogger(mockLogger, true);
+
+      logger.debug('test debug');
+      logger.info('test info');
+      logger.warn('test warning');
+      logger.error('test error');
+
+      expect(mockLogger.debug).toHaveBeenCalledWith('test debug');
+      expect(mockLogger.info).toHaveBeenCalledWith('test info');
+      expect(mockLogger.warn).toHaveBeenCalledWith('test warning');
+      expect(mockLogger.error).toHaveBeenCalledWith('test error');
+    });
+
+    it('should suppress debug and info when verbose is false', () => {
+      const mockLogger: Logger = {
+        debug: vi.fn(),
+        info: vi.fn(),
+        warn: vi.fn(),
+        error: vi.fn(),
+      };
+
+      const logger = createVerboseLogger(mockLogger, false);
+
+      logger.debug('test debug');
+      logger.info('test info');
+      logger.warn('test warning');
+      logger.error('test error');
+
+      expect(mockLogger.debug).not.toHaveBeenCalled();
+      expect(mockLogger.info).not.toHaveBeenCalled();
+      expect(mockLogger.warn).toHaveBeenCalledWith('test warning');
+      expect(mockLogger.error).toHaveBeenCalledWith('test error');
+    });
+
+    it('should default to verbose false when not specified', () => {
+      const mockLogger: Logger = {
+        debug: vi.fn(),
+        info: vi.fn(),
+        warn: vi.fn(),
+        error: vi.fn(),
+      };
+
+      const logger = createVerboseLogger(mockLogger);
+
+      logger.debug('test debug');
+      logger.info('test info');
+
+      expect(mockLogger.debug).not.toHaveBeenCalled();
+      expect(mockLogger.info).not.toHaveBeenCalled();
+    });
+
+    it('should preserve this binding for custom logger instances', () => {
+      // Create a logger that relies on instance state
+      class CustomLogger implements Logger {
+        private prefix = '[CUSTOM]';
+
+        debug(message: string) {
+          return `${this.prefix} DEBUG: ${message}`;
+        }
+
+        info(message: string) {
+          return `${this.prefix} INFO: ${message}`;
+        }
+
+        warn(message: string) {
+          return `${this.prefix} WARN: ${message}`;
+        }
+
+        error(message: string) {
+          return `${this.prefix} ERROR: ${message}`;
+        }
+      }
+
+      const customLogger = new CustomLogger();
+      const logger = createVerboseLogger(customLogger, false);
+
+      // These should not throw and should preserve 'this' binding
+      const warnResult = logger.warn('test warning');
+      const errorResult = logger.error('test error');
+
+      expect(warnResult).toBe('[CUSTOM] WARN: test warning');
+      expect(errorResult).toBe('[CUSTOM] ERROR: test error');
+    });
+  });
+});