@boostecom/provider 0.0.1

package/docs/src/claude-code-provider.test.ts

@@ -0,0 +1,97 @@
+import { describe, it, expect } from 'vitest';
+import { createClaudeCode } from './claude-code-provider.js';
+import { ClaudeCodeLanguageModel } from './claude-code-language-model.js';
+
+describe('createClaudeCode', () => {
+  it('should create a provider with default settings', () => {
+    const provider = createClaudeCode();
+    expect(provider).toBeDefined();
+    expect(typeof provider).toBe('function');
+  });
+
+  it('should create a provider with custom settings', () => {
+    const customSettings = {
+      pathToClaudeCodeExecutable: '/custom/path/claude',
+      customSystemPrompt: 'Custom prompt',
+      maxTurns: 10,
+    };
+
+    const provider = createClaudeCode({ defaultSettings: customSettings });
+    expect(provider).toBeDefined();
+  });
+
+  it('should return a language model when called with opus', () => {
+    const provider = createClaudeCode();
+    const model = provider('opus');
+
+    expect(model).toBeInstanceOf(ClaudeCodeLanguageModel);
+    expect(model.modelId).toBe('opus');
+  });
+
+  it('should return a language model when called with sonnet', () => {
+    const provider = createClaudeCode();
+    const model = provider('sonnet');
+
+    expect(model).toBeInstanceOf(ClaudeCodeLanguageModel);
+    expect(model.modelId).toBe('sonnet');
+  });
+
+  it('should allow custom model IDs', () => {
+    const provider = createClaudeCode();
+    const model = provider('custom-model-id');
+
+    expect(model).toBeInstanceOf(ClaudeCodeLanguageModel);
+    expect(model.modelId).toBe('custom-model-id');
+  });
+
+  it('should merge provider settings with model settings', () => {
+    const providerSettings = {
+      pathToClaudeCodeExecutable: '/provider/path',
+      maxTurns: 5,
+    };
+
+    const modelSettings = {
+      maxTurns: 10,
+      customSystemPrompt: 'Model prompt',
+    };
+
+    const provider = createClaudeCode({ defaultSettings: providerSettings });
+    const model = provider('opus', modelSettings);
+
+    expect(model).toBeInstanceOf(ClaudeCodeLanguageModel);
+    // Model settings should override provider settings
+    expect((model as ClaudeCodeLanguageModel).settings.maxTurns).toBe(10);
+    expect((model as ClaudeCodeLanguageModel).settings.customSystemPrompt).toBe('Model prompt');
+    expect((model as ClaudeCodeLanguageModel).settings.pathToClaudeCodeExecutable).toBe(
+      '/provider/path'
+    );
+  });
+
+  it('should create model with custom settings', () => {
+    const provider = createClaudeCode();
+    const model = provider('sonnet', { resume: 'test-session-123' });
+
+    expect(model).toBeInstanceOf(ClaudeCodeLanguageModel);
+    expect((model as ClaudeCodeLanguageModel).settings.resume).toBe('test-session-123');
+  });
+
+  it('should work with destructured usage', () => {
+    const { claudeCode } = { claudeCode: createClaudeCode() };
+    const model = claudeCode('opus');
+
+    expect(model).toBeInstanceOf(ClaudeCodeLanguageModel);
+    expect(model.modelId).toBe('opus');
+  });
+});
+
+describe('claudeCode export', () => {
+  it('should export a default provider instance', async () => {
+    const { claudeCode } = await import('./claude-code-provider.js');
+
+    expect(claudeCode).toBeDefined();
+    expect(typeof claudeCode).toBe('function');
+
+    const model = claudeCode('sonnet');
+    expect(model).toBeInstanceOf(ClaudeCodeLanguageModel);
+  });
+});

package/docs/src/claude-code-provider.ts

@@ -0,0 +1,179 @@
+import type { LanguageModelV3, ProviderV3 } from '@ai-sdk/provider';
+import { NoSuchModelError } from '@ai-sdk/provider';
+import { ClaudeCodeLanguageModel, type ClaudeCodeModelId } from './claude-code-language-model.js';
+import type { ClaudeCodeSettings } from './types.js';
+import { validateSettings } from './validation.js';
+import { getLogger } from './logger.js';
+
+/**
+ * Claude Code provider interface that extends the AI SDK's ProviderV3.
+ * Provides methods to create language models for interacting with Claude via the CLI.
+ *
+ * @example
+ * ```typescript
+ * import { claudeCode } from '@boostecom/provider';
+ *
+ * // Create a model instance
+ * const model = claudeCode('opus');
+ *
+ * // Or use the explicit methods
+ * const chatModel = claudeCode.chat('sonnet');
+ * const languageModel = claudeCode.languageModel('opus', { maxTurns: 10 });
+ * ```
+ */
+export interface ClaudeCodeProvider extends ProviderV3 {
+  /**
+   * Creates a language model instance for the specified model ID.
+   * This is a shorthand for calling `languageModel()`.
+   *
+   * @param modelId - The Claude model to use ('opus' or 'sonnet')
+   * @param settings - Optional settings to configure the model
+   * @returns A language model instance
+   */
+  (modelId: ClaudeCodeModelId, settings?: ClaudeCodeSettings): LanguageModelV3;
+
+  /**
+   * Creates a language model instance for text generation.
+   *
+   * @param modelId - The Claude model to use ('opus' or 'sonnet')
+   * @param settings - Optional settings to configure the model
+   * @returns A language model instance
+   */
+  languageModel(modelId: ClaudeCodeModelId, settings?: ClaudeCodeSettings): LanguageModelV3;
+
+  /**
+   * Alias for `languageModel()` to maintain compatibility with AI SDK patterns.
+   *
+   * @param modelId - The Claude model to use ('opus' or 'sonnet')
+   * @param settings - Optional settings to configure the model
+   * @returns A language model instance
+   */
+  chat(modelId: ClaudeCodeModelId, settings?: ClaudeCodeSettings): LanguageModelV3;
+
+  imageModel(modelId: string): never;
+}
+
+/**
+ * Configuration options for creating a Claude Code provider instance.
+ * These settings will be applied as defaults to all models created by the provider.
+ *
+ * @example
+ * ```typescript
+ * const provider = createClaudeCode({
+ *   defaultSettings: {
+ *     maxTurns: 5,
+ *     cwd: '/path/to/project'
+ *   }
+ * });
+ * ```
+ */
+export interface ClaudeCodeProviderSettings {
+  /**
+   * Default settings to use for all models created by this provider.
+   * Individual model settings will override these defaults.
+   */
+  defaultSettings?: ClaudeCodeSettings;
+}
+
+/**
+ * Creates a Claude Code provider instance with the specified configuration.
+ * The provider can be used to create language models for interacting with Claude 4 models.
+ *
+ * @param options - Provider configuration options
+ * @returns Claude Code provider instance
+ *
+ * @example
+ * ```typescript
+ * const provider = createClaudeCode({
+ *   defaultSettings: {
+ *     permissionMode: 'bypassPermissions',
+ *     maxTurns: 10
+ *   }
+ * });
+ *
+ * const model = provider('opus');
+ * ```
+ */
+export function createClaudeCode(options: ClaudeCodeProviderSettings = {}): ClaudeCodeProvider {
+  // Get logger from default settings if provided
+  const logger = getLogger(options.defaultSettings?.logger);
+
+  // Validate default settings if provided
+  if (options.defaultSettings) {
+    const validation = validateSettings(options.defaultSettings);
+    if (!validation.valid) {
+      throw new Error(`Invalid default settings: ${validation.errors.join(', ')}`);
+    }
+    if (validation.warnings.length > 0) {
+      validation.warnings.forEach((warning) => logger.warn(`Claude Code Provider: ${warning}`));
+    }
+  }
+
+  const createModel = (
+    modelId: ClaudeCodeModelId,
+    settings: ClaudeCodeSettings = {}
+  ): LanguageModelV3 => {
+    const mergedSettings = {
+      ...options.defaultSettings,
+      ...settings,
+    };
+
+    // Validate merged settings
+    const validation = validateSettings(mergedSettings);
+    if (!validation.valid) {
+      throw new Error(`Invalid settings: ${validation.errors.join(', ')}`);
+    }
+
+    return new ClaudeCodeLanguageModel({
+      id: modelId,
+      settings: mergedSettings,
+      settingsValidationWarnings: validation.warnings,
+    });
+  };
+
+  const provider = function (modelId: ClaudeCodeModelId, settings?: ClaudeCodeSettings) {
+    if (new.target) {
+      throw new Error('The Claude Code model function cannot be called with the new keyword.');
+    }
+
+    return createModel(modelId, settings);
+  };
+
+  provider.languageModel = createModel;
+  provider.chat = createModel; // Alias for languageModel
+  provider.specificationVersion = 'v3' as const;
+
+  // Add embeddingModel method that throws NoSuchModelError
+  provider.embeddingModel = (modelId: string) => {
+    throw new NoSuchModelError({
+      modelId,
+      modelType: 'embeddingModel',
+    });
+  };
+
+  provider.imageModel = (modelId: string) => {
+    throw new NoSuchModelError({
+      modelId,
+      modelType: 'imageModel',
+    });
+  };
+
+  return provider as ClaudeCodeProvider;
+}
+
+/**
+ * Default Claude Code provider instance.
+ * Pre-configured provider for quick usage without custom settings.
+ *
+ * @example
+ * ```typescript
+ * import { claudeCode } from '@boostecom/provider';
+ * import { generateText } from 'ai';
+ *
+ * const { text } = await generateText({
+ *   model: claudeCode('sonnet'),
+ *   prompt: 'Hello, Claude!'
+ * });
+ * ```
+ */
+export const claudeCode = createClaudeCode();

package/docs/src/convert-to-claude-code-messages.images.test.ts

@@ -0,0 +1,104 @@
+import { describe, it, expect } from 'vitest';
+import type { ModelMessage } from 'ai';
+import { convertToClaudeCodeMessages } from './convert-to-claude-code-messages.js';
+
+describe('convertToClaudeCodeMessages (images)', () => {
+  it('includes data URL images in streaming content', () => {
+    const prompt = [
+      {
+        role: 'user',
+        content: [
+          { type: 'text', text: 'Here is a sample image.' },
+          { type: 'image', image: 'data:image/png;base64,aGVsbG8=' },
+        ],
+      },
+    ] as ModelMessage[];
+
+    const result = convertToClaudeCodeMessages(prompt);
+
+    expect(result.warnings).toBeUndefined();
+    expect(result.hasImageParts).toBe(true);
+    expect(result.streamingContentParts).toHaveLength(2);
+    expect(result.streamingContentParts[0]).toEqual({
+      type: 'text',
+      text: 'Human: Here is a sample image.',
+    });
+    expect(result.streamingContentParts[1]).toEqual({
+      type: 'image',
+      source: {
+        type: 'base64',
+        media_type: 'image/png',
+        data: 'aGVsbG8=',
+      },
+    });
+  });
+
+  it('includes base64 images when mimeType is provided', () => {
+    const prompt = [
+      {
+        role: 'user',
+        content: [
+          { type: 'text', text: 'Inline base64 image.' },
+          { type: 'image', image: { data: 'AQID', mimeType: 'image/jpeg' } },
+        ],
+      },
+    ] as ModelMessage[];
+
+    const result = convertToClaudeCodeMessages(prompt);
+
+    expect(result.warnings).toBeUndefined();
+    expect(result.hasImageParts).toBe(true);
+    expect(result.streamingContentParts[1]).toEqual({
+      type: 'image',
+      source: {
+        type: 'base64',
+        media_type: 'image/jpeg',
+        data: 'AQID',
+      },
+    });
+  });
+
+  it('warns and skips HTTP image URLs', () => {
+    const prompt = [
+      {
+        role: 'user',
+        content: [
+          { type: 'text', text: 'Remote image' },
+          { type: 'image', image: 'https://example.com/image.png' },
+        ],
+      },
+    ] as ModelMessage[];
+
+    const result = convertToClaudeCodeMessages(prompt);
+
+    expect(result.hasImageParts).toBe(false);
+    expect(result.warnings).toContain(
+      'Image URLs are not supported by this provider; supply base64/data URLs.'
+    );
+    expect(result.streamingContentParts).toHaveLength(1);
+  });
+
+  it('accepts file parts with image media type', () => {
+    const prompt = [
+      {
+        role: 'user',
+        content: [
+          { type: 'text', text: 'File part image.' },
+          { type: 'file', mediaType: 'image/png', data: 'aGVsbG8=' },
+        ],
+      },
+    ] as ModelMessage[];
+
+    const result = convertToClaudeCodeMessages(prompt);
+
+    expect(result.hasImageParts).toBe(true);
+    expect(result.streamingContentParts[1]).toEqual({
+      type: 'image',
+      source: {
+        type: 'base64',
+        media_type: 'image/png',
+        data: 'aGVsbG8=',
+      },
+    });
+  });
+});

package/docs/src/convert-to-claude-code-messages.test.ts

@@ -0,0 +1,193 @@
+import { describe, it, expect } from 'vitest';
+import { convertToClaudeCodeMessages } from './convert-to-claude-code-messages.js';
+import type { ModelMessage } from 'ai';
+
+describe('convertToClaudeCodeMessages', () => {
+  it('should convert a simple user message', () => {
+    const result = convertToClaudeCodeMessages([
+      { role: 'user', content: 'Hello, Claude!' },
+    ] as ModelMessage[]);
+
+    expect(result.messagesPrompt).toBe('Human: Hello, Claude!');
+    expect(result.systemPrompt).toBeUndefined();
+  });
+
+  it('should convert a simple assistant message', () => {
+    const result = convertToClaudeCodeMessages([
+      { role: 'assistant', content: 'Hello! How can I help you?' },
+    ] as ModelMessage[]);
+
+    expect(result.messagesPrompt).toBe('Assistant: Hello! How can I help you?');
+    expect(result.systemPrompt).toBeUndefined();
+  });
+
+  it('should handle system message', () => {
+    const result = convertToClaudeCodeMessages([
+      { role: 'system', content: 'You are a helpful assistant.' },
+    ] as ModelMessage[]);
+
+    expect(result.messagesPrompt).toBe('You are a helpful assistant.');
+    expect(result.systemPrompt).toBe('You are a helpful assistant.');
+  });
+
+  it('should handle a conversation with multiple messages', () => {
+    const result = convertToClaudeCodeMessages([
+      { role: 'system', content: 'Be helpful.' },
+      { role: 'user', content: 'What is 2+2?' },
+      { role: 'assistant', content: '2+2 equals 4.' },
+      { role: 'user', content: 'Thanks!' },
+    ] as ModelMessage[]);
+
+    expect(result.systemPrompt).toBe('Be helpful.');
+    expect(result.messagesPrompt).toBe(
+      'Be helpful.\n\nHuman: What is 2+2?\n\nAssistant: 2+2 equals 4.\n\nHuman: Thanks!'
+    );
+  });
+
+  it('should handle multi-part text messages', () => {
+    const result = convertToClaudeCodeMessages([
+      {
+        role: 'user',
+        content: [
+          { type: 'text', text: 'Hello' },
+          { type: 'text', text: ', ' },
+          { type: 'text', text: 'world!' },
+        ],
+      },
+    ] as ModelMessage[]);
+
+    expect(result.messagesPrompt).toBe('Human: Hello\n, \nworld!');
+  });
+
+  it('should return warning when image content cannot be converted', () => {
+    const result = convertToClaudeCodeMessages([
+      {
+        role: 'user',
+        content: [
+          { type: 'text', text: 'Look at this:' },
+          { type: 'image', image: new Uint8Array([1, 2, 3]) },
+        ],
+      },
+    ] as ModelMessage[]);
+
+    expect(result.warnings).toBeDefined();
+    expect(result.warnings).toContain('Unable to convert image content; supply base64/data URLs.');
+    expect(result.messagesPrompt).toBe('Human: Look at this:');
+    expect(result.hasImageParts).toBe(false);
+  });
+
+  it('should handle unknown content types gracefully', () => {
+    const result = convertToClaudeCodeMessages([
+      {
+        role: 'user',
+        content: [
+          { type: 'text', text: 'Check this file:' },
+          { type: 'file', data: 'data:text/plain;base64,AQID', mimeType: 'text/plain' },
+        ],
+      },
+    ] as any);
+
+    // Unknown content types are filtered out
+    expect(result.messagesPrompt).toBe('Human: Check this file:');
+  });
+
+  it('should convert tool messages', () => {
+    const result = convertToClaudeCodeMessages([
+      {
+        role: 'tool',
+        content: [
+          {
+            type: 'tool-result',
+            toolCallId: 'call-123',
+            toolName: 'calculator',
+            output: { type: 'json', value: { answer: 42 } },
+          },
+        ],
+      },
+    ] as any);
+
+    expect(result.messagesPrompt).toBe('Tool Result (calculator): {"answer":42}');
+  });
+
+  it('should handle tool error messages', () => {
+    const result = convertToClaudeCodeMessages([
+      {
+        role: 'tool',
+        content: [
+          {
+            type: 'tool-result',
+            toolCallId: 'call-456',
+            toolName: 'search',
+            output: { type: 'text', value: 'Network error' },
+          },
+        ],
+      },
+    ] as any);
+
+    expect(result.messagesPrompt).toBe('Tool Result (search): Network error');
+  });
+
+  it('should handle empty content array', () => {
+    const result = convertToClaudeCodeMessages([
+      {
+        role: 'user',
+        content: [],
+      },
+    ] as ModelMessage[]);
+
+    expect(result.messagesPrompt).toBe('');
+  });
+
+  it('should handle undefined content gracefully', () => {
+    const result = convertToClaudeCodeMessages([
+      {
+        role: 'user',
+        content: [{ type: 'text', text: undefined as any }],
+      },
+    ] as ModelMessage[]);
+
+    expect(result.messagesPrompt).toBe('');
+  });
+
+  it('should handle complex tool results', () => {
+    const result = convertToClaudeCodeMessages([
+      {
+        role: 'tool',
+        content: [
+          {
+            type: 'tool-result',
+            toolCallId: 'call-789',
+            toolName: 'database',
+            output: {
+              type: 'json',
+              value: {
+                users: [
+                  { id: 1, name: 'Alice' },
+                  { id: 2, name: 'Bob' },
+                ],
+                count: 2,
+              },
+            },
+          },
+        ],
+      },
+    ] as any);
+
+    expect(result.messagesPrompt).toBe(
+      'Tool Result (database): {"users":[{"id":1,"name":"Alice"},{"id":2,"name":"Bob"}],"count":2}'
+    );
+  });
+
+  it('should handle consecutive messages properly', () => {
+    const result = convertToClaudeCodeMessages([
+      { role: 'user', content: 'First message' },
+      { role: 'user', content: 'Second message' },
+      { role: 'assistant', content: 'Response' },
+      { role: 'user', content: 'Third message' },
+    ] as ModelMessage[]);
+
+    expect(result.messagesPrompt).toBe(
+      'Human: First message\n\nHuman: Second message\n\nAssistant: Response\n\nHuman: Third message'
+    );
+  });
+});