@boostecom/provider 0.0.1

package/docs/examples/generate-object.ts

@@ -0,0 +1,211 @@
+#!/usr/bin/env tsx
+
+/**
+ * Object Generation Examples
+ *
+ * Demonstrates core generateObject patterns with the Claude Code provider,
+ * progressing from simple to complex.
+ *
+ * Topics covered:
+ * - Simple objects with primitives
+ * - Arrays and optional fields
+ * - Enums and nested objects
+ * - Arrays of objects
+ * - Deep nesting (3+ levels)
+ *
+ * NOTE: Avoid Zod methods that produce unsupported JSON Schema annotations:
+ * .email(), .url(), .uuid(), .datetime() all emit `format` constraints that
+ * cause the Claude Code CLI to silently fall back to prose. Use .describe()
+ * with format hints instead, then validate client-side if strict format
+ * compliance is needed. See JSON_FIX.md for details.
+ */
+
+import { createClaudeCode } from '../dist/index.js';
+import { generateObject } from 'ai';
+import { z } from 'zod';
+
+const claudeCode = createClaudeCode();
+
+console.log('=== Claude Code: Object Generation Examples ===\n');
+
+// ---------------------------------------------------------------------------
+// Example 1: Simple object with primitives
+// ---------------------------------------------------------------------------
+async function example1_simpleObject() {
+  console.log('1. Simple Object with Primitives\n');
+
+  const { object } = await generateObject({
+    model: claudeCode('opus'),
+    schema: z.object({
+      name: z.string().describe('Full name of the person'),
+      age: z.number().describe('Age in years'),
+      email: z.string().describe('Email address (e.g. user@example.com)'),
+      isActive: z.boolean().describe('Whether the account is active'),
+    }),
+    prompt: 'Generate a profile for a software developer named Sarah.',
+  });
+
+  console.log('Generated profile:');
+  console.log(JSON.stringify(object, null, 2));
+  console.log();
+}
+
+// ---------------------------------------------------------------------------
+// Example 2: Arrays and optional fields
+// ---------------------------------------------------------------------------
+async function example2_arraysAndOptional() {
+  console.log('2. Arrays and Optional Fields\n');
+
+  const { object } = await generateObject({
+    model: claudeCode('opus'),
+    schema: z.object({
+      productName: z.string().describe('Name of the product'),
+      price: z.number().describe('Price in USD'),
+      description: z.string().describe('Product description'),
+      discount: z.number().optional().describe('Discount percentage if applicable'),
+      tags: z.array(z.string()).optional().describe('Product tags for categorization'),
+      features: z.array(z.string()).describe('Key product features'),
+      inStock: z.boolean().describe('Whether the product is in stock'),
+    }),
+    prompt: 'Generate a product listing for a wireless mechanical keyboard.',
+  });
+
+  console.log('Generated product:');
+  console.log(JSON.stringify(object, null, 2));
+  console.log();
+}
+
+// ---------------------------------------------------------------------------
+// Example 3: Enums and nested objects
+// ---------------------------------------------------------------------------
+async function example3_enumsAndNested() {
+  console.log('3. Enums and Nested Objects\n');
+
+  const { object } = await generateObject({
+    model: claudeCode('opus'),
+    schema: z.object({
+      id: z.string().describe('Unique user ID'),
+      username: z.string(),
+      profile: z.object({
+        firstName: z.string(),
+        lastName: z.string(),
+        age: z.number().min(0).max(150),
+        email: z.string().describe('Email address (e.g. alex@example.com)'),
+        bio: z.string().describe('Short biography'),
+        interests: z.array(z.string()).describe('List of interests'),
+        location: z.object({
+          city: z.string(),
+          country: z.string(),
+          timezone: z.string(),
+        }),
+      }),
+      settings: z.object({
+        theme: z.enum(['light', 'dark', 'auto']),
+        notifications: z.boolean(),
+        language: z.string(),
+      }),
+    }),
+    prompt:
+      'Generate a complete user profile for a software developer named Alex who loves open source.',
+  });
+
+  console.log('Generated user profile:');
+  console.log(JSON.stringify(object, null, 2));
+  console.log();
+}
+
+// ---------------------------------------------------------------------------
+// Example 4: Arrays of objects
+// ---------------------------------------------------------------------------
+async function example4_arraysOfObjects() {
+  console.log('4. Arrays of Objects\n');
+
+  const { object } = await generateObject({
+    model: claudeCode('opus'),
+    schema: z.object({
+      name: z.string().describe('Name of the recipe'),
+      ingredients: z
+        .array(
+          z.object({
+            item: z.string(),
+            amount: z.string(),
+          })
+        )
+        .describe('List of ingredients with amounts'),
+      instructions: z.array(z.string()).describe('Step-by-step cooking instructions'),
+      prepTime: z.number().describe('Preparation time in minutes'),
+      cookTime: z.number().describe('Cooking time in minutes'),
+      servings: z.number().describe('Number of servings'),
+    }),
+    prompt: 'Generate a detailed recipe for chocolate chip cookies.',
+  });
+
+  console.log('Generated recipe:');
+  console.log(JSON.stringify(object, null, 2));
+  console.log();
+}
+
+// ---------------------------------------------------------------------------
+// Example 5: Deep nesting (3+ levels)
+// ---------------------------------------------------------------------------
+async function example5_deepNesting() {
+  console.log('5. Deep Nesting (3+ Levels)\n');
+
+  const { object } = await generateObject({
+    model: claudeCode('opus'),
+    schema: z.object({
+      company: z.object({
+        name: z.string().describe('Company name'),
+        founded: z.number().describe('Year founded'),
+        headquarters: z.object({
+          city: z.string(),
+          country: z.string(),
+          timezone: z.string(),
+        }),
+        departments: z
+          .array(
+            z.object({
+              name: z.string().describe('Department name'),
+              budget: z.number().describe('Annual budget in USD'),
+              headCount: z.number().describe('Number of employees'),
+              teams: z.array(
+                z.object({
+                  name: z.string(),
+                  lead: z.string().describe('Team lead name'),
+                  members: z.number().describe('Team size'),
+                  projects: z.array(z.string()).describe('Active project names'),
+                })
+              ),
+            })
+          )
+          .describe('Company departments'),
+      }),
+    }),
+    prompt:
+      'Generate a structure for a mid-sized software company with 3 departments: Engineering, Product, and Marketing. Each should have 2-3 teams.',
+  });
+
+  console.log('Generated company structure:');
+  console.log(JSON.stringify(object, null, 2));
+  console.log();
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+async function main() {
+  try {
+    await example1_simpleObject();
+    await example2_arraysAndOptional();
+    await example3_enumsAndNested();
+    await example4_arraysOfObjects();
+    await example5_deepNesting();
+
+    console.log('All examples completed!');
+  } catch (error) {
+    console.error('Error:', error);
+    console.log('\nTip: Make sure the Claude Code SDK is authenticated with: claude login');
+  }
+}
+
+main().catch(console.error);

package/docs/examples/hooks-callbacks.ts

@@ -0,0 +1,63 @@
+/**
+ * Example: Hooks and canUseTool
+ *
+ * Demonstrates lifecycle hooks and dynamic permission callback.
+ * Requires Claude Code CLI authentication and environment setup.
+ */
+
+import { streamText } from 'ai';
+import { createClaudeCode } from '../dist/index.js';
+// NOTE: Migrating to Claude Agent SDK:
+// - System prompt is not applied by default
+// - Filesystem settings (CLAUDE.md, settings.json) are not loaded by default
+// To restore old behavior, set when creating model instances, e.g.:
+//   systemPrompt: { type: 'preset', preset: 'claude_code' }
+//   settingSources: ['user', 'project', 'local']
+
+// PreToolUse hook: log and allow
+const preToolHook = async (input: any) => {
+  if (input.hook_event_name === 'PreToolUse') {
+    console.log(`🔧 About to run tool: ${input.tool_name}`);
+    return {
+      continue: true,
+      hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'allow' },
+    };
+  }
+  return { continue: true };
+};
+
+// PostToolUse hook: log after tool completes
+const postToolHook = async (input: any) => {
+  if (input.hook_event_name === 'PostToolUse') {
+    console.log(`✅ Tool completed: ${input.tool_name}`);
+  }
+  return { continue: true };
+};
+
+async function main() {
+  const provider = createClaudeCode({
+    defaultSettings: {
+      hooks: {
+        PreToolUse: [{ hooks: [preToolHook] }],
+        PostToolUse: [{ hooks: [postToolHook] }],
+      },
+    },
+  });
+
+  // Use a prompt that triggers tool use so the hooks actually fire
+  const result = streamText({
+    model: provider('sonnet'),
+    prompt: 'List the files in the current directory using the Bash tool.',
+  });
+
+  let text = '';
+  for await (const chunk of result.textStream) {
+    text += chunk;
+  }
+  console.log('Response:', text.trim());
+}
+
+main().catch((err) => {
+  console.error('Example failed:', err);
+  process.exit(1);
+});

package/docs/examples/images.ts

@@ -0,0 +1,76 @@
+import { readFileSync } from 'node:fs';
+import { extname, basename, join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { streamText } from 'ai';
+import { claudeCode } from '../dist/index.js';
+
+const SUPPORTED_EXTENSIONS: Record<string, string> = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+};
+
+function toDataUrl(filePath: string): string {
+  const ext = extname(filePath).toLowerCase();
+  const mediaType = SUPPORTED_EXTENSIONS[ext];
+  if (!mediaType) {
+    throw new Error(
+      `Unsupported image extension "${ext}". Supported: ${Object.keys(SUPPORTED_EXTENSIONS).join(', ')}`
+    );
+  }
+
+  const contents = readFileSync(filePath);
+  const base64 = contents.toString('base64');
+  return `data:${mediaType};base64,${base64}`;
+}
+
+async function main() {
+  // Use bundled bull.webp as default if no path provided
+  const __dirname = dirname(fileURLToPath(import.meta.url));
+  const defaultImagePath = join(__dirname, 'bull.webp');
+
+  const filePath = process.argv[2] || defaultImagePath;
+  if (!process.argv[2]) {
+    console.log(`Using default image: ${defaultImagePath}`);
+    console.log(
+      'Tip: Pass a custom image path as argument: npx tsx examples/images.ts /path/to/image.png\n'
+    );
+  }
+
+  const dataUrl = toDataUrl(filePath);
+
+  const result = streamText({
+    model: claudeCode('opus', { streamingInput: 'always' }),
+    messages: [
+      {
+        role: 'user',
+        content: [
+          {
+            type: 'text',
+            text: `Describe the mood conveyed by "${basename(filePath)}" in one sentence.`,
+          },
+          { type: 'image', image: dataUrl },
+        ],
+      },
+    ],
+  });
+
+  process.stdout.write('Assistant: ');
+  for await (const chunk of result.textStream) {
+    process.stdout.write(chunk);
+  }
+  process.stdout.write('\n');
+}
+
+main().catch((error) => {
+  console.error('Error while streaming image prompt:', error);
+  process.exitCode = 1;
+});
+// NOTE: Migrating to Claude Agent SDK:
+// - System prompt is not applied by default
+// - Filesystem settings (CLAUDE.md, settings.json) are not loaded by default
+// To restore old behavior, set:
+//   systemPrompt: { type: 'preset', preset: 'claude_code' }
+//   settingSources: ['user', 'project', 'local']

package/docs/examples/integration-test.ts

@@ -0,0 +1,241 @@
+/**
+ * Integration tests for the Claude Code AI SDK Provider
+ *
+ * These tests verify core functionality of the provider
+ * including text generation, conversations, and error handling.
+ */
+
+import { generateText } from 'ai';
+import { claudeCode, isAuthenticationError } from '../dist/index.js';
+// NOTE: Migrating to Claude Agent SDK:
+// - System prompt is not applied by default
+// - Filesystem settings (CLAUDE.md, settings.json) are not loaded by default
+// To restore old behavior, set:
+//   systemPrompt: { type: 'preset', preset: 'claude_code' }
+//   settingSources: ['user', 'project', 'local']
+
+async function testBasicGeneration() {
+  console.log('🧪 Test 1: Basic text generation with Haiku...');
+  try {
+    const { text } = await generateText({
+      model: claudeCode('opus'),
+      prompt: 'Say "Hello from Claude Code Provider!" and nothing else.',
+    });
+
+    if (text.includes('Hello from Claude Code Provider')) {
+      console.log('✅ Success:', text);
+    } else {
+      console.error('❌ Unexpected response:', text);
+      throw new Error('Basic generation test failed');
+    }
+  } catch (error) {
+    console.error('❌ Failed:', error);
+    throw error;
+  }
+}
+
+async function testWithSystemMessage() {
+  console.log('\n🧪 Test 2: Generation with system message...');
+  try {
+    const { text } = await generateText({
+      model: claudeCode('opus'),
+      messages: [
+        {
+          role: 'system',
+          content: 'You are a helpful assistant. Answer with just the number, no explanation.',
+        },
+        { role: 'user', content: 'What is 2+2?' },
+      ],
+    });
+
+    const cleanText = text.trim();
+    if (cleanText === '4' || cleanText.includes('4')) {
+      console.log('✅ Success:', text);
+    } else {
+      console.error('❌ Unexpected response:', text);
+      throw new Error('System message test failed');
+    }
+  } catch (error) {
+    console.error('❌ Failed:', error);
+    throw error;
+  }
+}
+
+async function testConversation() {
+  console.log('\n🧪 Test 3: Multi-turn conversation with message history...');
+  try {
+    // First turn: establish context
+    const { text: response1 } = await generateText({
+      model: claudeCode('opus'),
+      messages: [
+        {
+          role: 'user',
+          content:
+            'My favorite color is purple and I live in Seattle. Just acknowledge this information.',
+        },
+      ],
+    });
+    console.log('✅ First turn:', response1);
+
+    // Second turn: test memory with full history
+    const { text: response2 } = await generateText({
+      model: claudeCode('opus'),
+      messages: [
+        {
+          role: 'user',
+          content:
+            'My favorite color is purple and I live in Seattle. Just acknowledge this information.',
+        },
+        { role: 'assistant', content: response1 },
+        { role: 'user', content: 'What is my favorite color?' },
+      ],
+    });
+
+    if (response2.toLowerCase().includes('purple')) {
+      console.log('✅ Second turn (remembered color):', response2);
+    } else {
+      console.error('❌ Failed to remember color:', response2);
+      throw new Error('Conversation memory test failed');
+    }
+
+    // Third turn: test deeper context
+    const { text: response3 } = await generateText({
+      model: claudeCode('opus'),
+      messages: [
+        {
+          role: 'user',
+          content:
+            'My favorite color is purple and I live in Seattle. Just acknowledge this information.',
+        },
+        { role: 'assistant', content: response1 },
+        { role: 'user', content: 'What is my favorite color?' },
+        { role: 'assistant', content: response2 },
+        { role: 'user', content: 'Where do I live?' },
+      ],
+    });
+
+    if (response3.toLowerCase().includes('seattle')) {
+      console.log('✅ Third turn (remembered location):', response3);
+      console.log('✅ Conversation context maintained successfully!');
+    } else {
+      console.error('❌ Failed to remember location:', response3);
+      throw new Error('Conversation memory test failed');
+    }
+  } catch (error) {
+    console.error('❌ Failed:', error);
+    throw error;
+  }
+}
+
+async function testErrorHandling() {
+  console.log('\n🧪 Test 4: Error handling with invalid executable path...');
+  try {
+    const badClaude = claudeCode('opus', {
+      pathToClaudeCodeExecutable: 'claude-nonexistent-binary-12345',
+    });
+
+    await generateText({
+      model: badClaude,
+      prompt: 'This should fail',
+    });
+
+    console.error('❌ Expected error but got success');
+    throw new Error('Error handling test failed - should have thrown an error');
+  } catch (error: any) {
+    if (error.message?.includes('not found') || error.message?.includes('ENOENT')) {
+      console.log('✅ Error handled correctly:', error.message);
+    } else if (error.message?.includes('Error handling test failed')) {
+      throw error; // Re-throw our test failure
+    } else {
+      console.log('✅ Got error (different than expected):', error.message);
+    }
+  }
+}
+
+async function testStreaming() {
+  console.log('\n🧪 Test 5: Basic streaming...');
+  try {
+    const { textStream } = streamText({
+      model: claudeCode('opus'),
+      prompt: 'Count from 1 to 5, one number per line.',
+    });
+
+    let fullText = '';
+    process.stdout.write('Streaming: ');
+    for await (const chunk of textStream) {
+      process.stdout.write(chunk);
+      fullText += chunk;
+    }
+    console.log('\n✅ Streaming completed');
+
+    // Verify we got numbers
+    const hasNumbers = ['1', '2', '3', '4', '5'].every((num) => fullText.includes(num));
+    if (!hasNumbers) {
+      throw new Error('Streaming test failed - missing expected numbers');
+    }
+  } catch (error) {
+    console.error('\n❌ Streaming failed:', error);
+    throw error;
+  }
+}
+
+// Import streamText for the streaming test
+import { streamText } from 'ai';
+
+async function runAllTests() {
+  console.log('🚀 Running Claude Code AI SDK Provider Integration Tests\n');
+
+  const startTime = Date.now();
+  let testsRun = 0;
+  let testsPassed = 0;
+
+  const tests = [
+    { name: 'Basic Generation', fn: testBasicGeneration },
+    { name: 'System Message', fn: testWithSystemMessage },
+    { name: 'Conversation', fn: testConversation },
+    { name: 'Error Handling', fn: testErrorHandling },
+    { name: 'Streaming', fn: testStreaming },
+  ];
+
+  for (const test of tests) {
+    testsRun++;
+    try {
+      await test.fn();
+      testsPassed++;
+    } catch (error) {
+      console.error(`\n❌ ${test.name} test failed`);
+      if (isAuthenticationError(error)) {
+        console.log('\n⚠️  Authentication required. Please run: claude login');
+        process.exit(1);
+      }
+    }
+  }
+
+  const duration = Date.now() - startTime;
+  console.log('\n' + '='.repeat(50));
+  console.log(`📊 Test Results: ${testsPassed}/${testsRun} passed (${duration}ms)`);
+
+  if (testsPassed === testsRun) {
+    console.log('✅ All tests passed!');
+    process.exit(0);
+  } else {
+    console.log(`❌ ${testsRun - testsPassed} tests failed`);
+    process.exit(1);
+  }
+}
+
+// Add configurable global timeout (default 3 minutes)
+const TIMEOUT_MS = Number(process.env.CLAUDE_IT_TIMEOUT_MS ?? '180000');
+const timeoutId = setTimeout(() => {
+  console.log(`\n⏱️ Tests timed out after ${TIMEOUT_MS / 1000} seconds`);
+  process.exit(1);
+}, TIMEOUT_MS);
+
+runAllTests()
+  .then(() => {
+    clearTimeout(timeoutId);
+  })
+  .catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+  });