ai-providers 0.2.0 → 0.3.0

package/src/index.test.ts

@@ -0,0 +1,341 @@
+/**
+ * Tests for the public API surface
+ *
+ * Covers:
+ * - Exported functions and types
+ * - Module re-exports
+ * - API consistency
+ */
+
+import { describe, it, expect } from 'vitest'
+import * as aiProviders from './index.js'
+
+describe('public API exports', () => {
+  describe('registry functions', () => {
+    it('exports createRegistry', () => {
+      expect(aiProviders.createRegistry).toBeDefined()
+      expect(typeof aiProviders.createRegistry).toBe('function')
+    })
+
+    it('exports getRegistry', () => {
+      expect(aiProviders.getRegistry).toBeDefined()
+      expect(typeof aiProviders.getRegistry).toBe('function')
+    })
+
+    it('exports configureRegistry', () => {
+      expect(aiProviders.configureRegistry).toBeDefined()
+      expect(typeof aiProviders.configureRegistry).toBe('function')
+    })
+  })
+
+  describe('model functions', () => {
+    it('exports model', () => {
+      expect(aiProviders.model).toBeDefined()
+      expect(typeof aiProviders.model).toBe('function')
+    })
+
+    it('exports embeddingModel', () => {
+      expect(aiProviders.embeddingModel).toBeDefined()
+      expect(typeof aiProviders.embeddingModel).toBe('function')
+    })
+  })
+
+  describe('constants', () => {
+    it('exports DIRECT_PROVIDERS', () => {
+      expect(aiProviders.DIRECT_PROVIDERS).toBeDefined()
+      expect(Array.isArray(aiProviders.DIRECT_PROVIDERS)).toBe(true)
+    })
+  })
+
+  describe('types', () => {
+    it('exports ProviderId type', () => {
+      // Type-only export, check in type context
+      const typeCheck: aiProviders.ProviderId = 'openai'
+      expect(typeCheck).toBe('openai')
+    })
+
+    it('exports DirectProvider type', () => {
+      // Type-only export, check in type context
+      const typeCheck: aiProviders.DirectProvider = 'anthropic'
+      expect(typeCheck).toBe('anthropic')
+    })
+
+    it('exports ProviderConfig type', () => {
+      // Type-only export, check in type context
+      const typeCheck: aiProviders.ProviderConfig = {
+        gatewayUrl: 'test',
+      }
+      expect(typeCheck).toBeDefined()
+    })
+
+    it('exports Provider type from AI SDK', () => {
+      // Re-exported from 'ai' package
+      // Type-only export for convenience
+      expect(true).toBe(true)
+    })
+
+    it('exports ProviderRegistryProvider type from AI SDK', () => {
+      // Re-exported from 'ai' package
+      // Type-only export for convenience
+      expect(true).toBe(true)
+    })
+  })
+
+  describe('API completeness', () => {
+    it('exports all documented functions', () => {
+      const expectedExports = [
+        'createRegistry',
+        'getRegistry',
+        'configureRegistry',
+        'model',
+        'embeddingModel',
+        'DIRECT_PROVIDERS',
+      ]
+
+      for (const exportName of expectedExports) {
+        expect(aiProviders).toHaveProperty(exportName)
+      }
+    })
+
+    it('does not export internal implementation details', () => {
+      // Should not export internal functions like getEnvConfig, getBaseUrl, etc.
+      const internalFunctions = [
+        'getEnvConfig',
+        'getBaseUrl',
+        'createGatewayFetch',
+        'useGatewaySecrets',
+        'getApiKey',
+        'createOpenAIProvider',
+        'createAnthropicProvider',
+        'createGoogleProvider',
+        'createOpenRouterProvider',
+        'createCloudflareProvider',
+        'parseModelId',
+        'providerFactories',
+      ]
+
+      for (const internalName of internalFunctions) {
+        expect(aiProviders).not.toHaveProperty(internalName)
+      }
+    })
+  })
+
+  describe('module structure', () => {
+    it('has expected module exports', () => {
+      const exports = Object.keys(aiProviders)
+      expect(exports.length).toBeGreaterThan(0)
+    })
+
+    it('all exported functions are callable', () => {
+      const functions = [
+        'createRegistry',
+        'getRegistry',
+        'configureRegistry',
+        'model',
+        'embeddingModel',
+      ]
+
+      for (const fnName of functions) {
+        const fn = (aiProviders as any)[fnName]
+        expect(typeof fn).toBe('function')
+      }
+    })
+
+    it('all exported constants are defined', () => {
+      expect(aiProviders.DIRECT_PROVIDERS).toBeDefined()
+    })
+  })
+})
+
+describe('API usage patterns', () => {
+  it('allows importing all exports', () => {
+    const {
+      createRegistry,
+      getRegistry,
+      configureRegistry,
+      model,
+      embeddingModel,
+      DIRECT_PROVIDERS,
+    } = aiProviders
+
+    expect(createRegistry).toBeDefined()
+    expect(getRegistry).toBeDefined()
+    expect(configureRegistry).toBeDefined()
+    expect(model).toBeDefined()
+    expect(embeddingModel).toBeDefined()
+    expect(DIRECT_PROVIDERS).toBeDefined()
+  })
+
+  it('allows importing specific exports', async () => {
+    const { model } = await import('./index.js')
+    expect(model).toBeDefined()
+  })
+
+  it('supports default import pattern', async () => {
+    const module = await import('./index.js')
+    expect(module.model).toBeDefined()
+  })
+})
+
+describe('type exports', () => {
+  it('ProviderId accepts valid provider names', () => {
+    const providers: aiProviders.ProviderId[] = [
+      'openai',
+      'anthropic',
+      'google',
+      'openrouter',
+      'cloudflare',
+    ]
+    expect(providers).toHaveLength(5)
+  })
+
+  it('ProviderConfig has optional fields', () => {
+    const configs: aiProviders.ProviderConfig[] = [
+      {},
+      { gatewayUrl: 'test' },
+      { gatewayToken: 'test' },
+      { openaiApiKey: 'test' },
+      {
+        gatewayUrl: 'test',
+        gatewayToken: 'test',
+        openaiApiKey: 'test',
+        anthropicApiKey: 'test',
+        googleApiKey: 'test',
+        openrouterApiKey: 'test',
+        cloudflareAccountId: 'test',
+        cloudflareApiToken: 'test',
+      },
+    ]
+    expect(configs).toHaveLength(5)
+  })
+
+  it('DirectProvider is a subset of ProviderId', () => {
+    // DirectProvider should be 'openai' | 'anthropic' | 'google'
+    const direct: aiProviders.DirectProvider[] = ['openai', 'anthropic', 'google']
+    expect(direct).toHaveLength(3)
+  })
+})
+
+describe('package documentation', () => {
+  it('has JSDoc package documentation', () => {
+    // Main module should have @packageDocumentation
+    expect(true).toBe(true)
+  })
+
+  it('exports match README examples', () => {
+    // README shows these imports:
+    // import { model } from 'ai-providers'
+    // import { embeddingModel } from 'ai-providers'
+    // import { createRegistry } from 'ai-providers'
+    // import { getRegistry } from 'ai-providers'
+
+    expect(aiProviders.model).toBeDefined()
+    expect(aiProviders.embeddingModel).toBeDefined()
+    expect(aiProviders.createRegistry).toBeDefined()
+    expect(aiProviders.getRegistry).toBeDefined()
+  })
+})
+
+describe('convenience re-exports', () => {
+  it('re-exports AI SDK types for convenience', () => {
+    // Provider and ProviderRegistryProvider are re-exported from 'ai'
+    // This allows users to import types from ai-providers instead of ai
+    expect(true).toBe(true)
+  })
+
+  it('re-exports DIRECT_PROVIDERS from language-models', () => {
+    // DIRECT_PROVIDERS is re-exported from language-models for consistency
+    expect(aiProviders.DIRECT_PROVIDERS).toBeDefined()
+  })
+})
+
+describe('integration with subpackages', () => {
+  it('main package exports registry functions', () => {
+    // Main package exports registry.ts
+    expect(aiProviders.createRegistry).toBeDefined()
+  })
+
+  it('cloudflare provider is in separate export', async () => {
+    // Cloudflare provider should be importable from 'ai-providers/cloudflare'
+    // Not from the main 'ai-providers' export
+    expect(aiProviders).not.toHaveProperty('cloudflareEmbedding')
+    expect(aiProviders).not.toHaveProperty('cloudflare')
+  })
+})
+
+describe('backward compatibility', () => {
+  it('maintains stable public API', () => {
+    // These exports should remain stable across versions
+    const stableExports = [
+      'createRegistry',
+      'getRegistry',
+      'model',
+      'embeddingModel',
+      'DIRECT_PROVIDERS',
+    ]
+
+    for (const exportName of stableExports) {
+      expect(aiProviders).toHaveProperty(exportName)
+    }
+  })
+
+  it('types are backward compatible', () => {
+    // Type structure should be stable
+    const config: aiProviders.ProviderConfig = {
+      gatewayUrl: 'test',
+    }
+    expect(config).toBeDefined()
+  })
+})
+
+describe('error messages', () => {
+  it('provides helpful error for missing credentials', async () => {
+    // When creating a model without credentials, should have clear error
+    expect(true).toBe(true)
+  })
+
+  it('provides helpful error for invalid model ID', async () => {
+    // When providing invalid model ID, should have clear error
+    expect(true).toBe(true)
+  })
+})
+
+describe('async API behavior', () => {
+  it('createRegistry returns a Promise', async () => {
+    const result = aiProviders.createRegistry()
+    expect(result).toBeInstanceOf(Promise)
+    await result // Wait for it to complete
+  })
+
+  it('getRegistry returns a Promise', async () => {
+    const result = aiProviders.getRegistry()
+    expect(result).toBeInstanceOf(Promise)
+    await result
+  })
+
+  it('configureRegistry returns a Promise', async () => {
+    const result = aiProviders.configureRegistry({})
+    expect(result).toBeInstanceOf(Promise)
+    await result
+  })
+
+  it('model returns a Promise', async () => {
+    try {
+      const result = aiProviders.model('test')
+      expect(result).toBeInstanceOf(Promise)
+      await result
+    } catch {
+      // May fail without proper config
+    }
+  })
+
+  it('embeddingModel returns a Promise', async () => {
+    try {
+      const result = aiProviders.embeddingModel('openai:test')
+      expect(result).toBeInstanceOf(Promise)
+      await result
+    } catch {
+      // May fail without proper config
+    }
+  })
+})

package/src/index.ts

@@ -0,0 +1,37 @@
+/**
+ * ai-providers - Unified AI Provider Registry
+ *
+ * Access multiple AI providers via simple string identifiers.
+ * Supports Cloudflare AI Gateway for unified routing and auth.
+ *
+ * @packageDocumentation
+ */
+
+export {
+  createRegistry,
+  getRegistry,
+  configureRegistry,
+  model,
+  embeddingModel,
+  DIRECT_PROVIDERS,
+  type ProviderId,
+  type DirectProvider,
+  type ProviderConfig
+} from './registry.js'
+
+// Export llm.do WebSocket transport
+export {
+  LLM,
+  getLLM,
+  createLLMFetch,
+  type LLMConfig,
+  type UniversalRequest,
+  type UniversalCreated,
+  type UniversalStream,
+  type UniversalDone,
+  type UniversalError,
+  type GatewayMessage
+} from './llm.do.js'
+
+// Re-export AI SDK types for convenience
+export type { Provider, ProviderRegistryProvider } from 'ai'

package/src/integration.test.ts

@@ -0,0 +1,317 @@
+/**
+ * Integration tests for ai-providers
+ *
+ * These tests make real API calls and are skipped if credentials are not available.
+ * Set AI_GATEWAY_URL and AI_GATEWAY_TOKEN (or individual provider keys) to run these tests.
+ *
+ * Tests cover:
+ * - End-to-end provider usage
+ * - Gateway integration
+ * - Model generation
+ * - Embedding generation
+ */
+
+import { describe, it, expect } from 'vitest'
+import { model, embeddingModel, createRegistry } from './index.js'
+
+// Skip tests if no credentials configured
+const hasGateway = !!(
+  process.env.AI_GATEWAY_URL ||
+  process.env.ANTHROPIC_API_KEY ||
+  process.env.OPENAI_API_KEY ||
+  process.env.OPENROUTER_API_KEY
+)
+
+const hasCloudflare = !!(
+  process.env.CLOUDFLARE_ACCOUNT_ID &&
+  process.env.CLOUDFLARE_API_TOKEN
+)
+
+describe.skipIf(!hasGateway)('model() integration', () => {
+  it('gets a language model from registry', async () => {
+    const m = await model('sonnet')
+    expect(m).toBeDefined()
+  })
+
+  it('resolves aliases to full model IDs', async () => {
+    const m = await model('opus')
+    expect(m).toBeDefined()
+  })
+
+  it('works with full model IDs', async () => {
+    const m = await model('anthropic/claude-sonnet-4.5')
+    expect(m).toBeDefined()
+  })
+
+  it('routes OpenAI models to OpenAI SDK', async () => {
+    try {
+      const m = await model('openai/gpt-4o')
+      expect(m).toBeDefined()
+    } catch (error) {
+      // May not be configured
+      expect(error).toBeDefined()
+    }
+  })
+
+  it('routes Anthropic models to Anthropic SDK', async () => {
+    try {
+      const m = await model('anthropic/claude-sonnet-4.5')
+      expect(m).toBeDefined()
+    } catch (error) {
+      // May not be configured
+      expect(error).toBeDefined()
+    }
+  })
+
+  it('routes Google models to Google SDK', async () => {
+    try {
+      const m = await model('google/gemini-2.5-flash')
+      expect(m).toBeDefined()
+    } catch (error) {
+      // May not be configured
+      expect(error).toBeDefined()
+    }
+  })
+
+  it('routes other models through OpenRouter', async () => {
+    try {
+      const m = await model('meta-llama/llama-3.3-70b-instruct')
+      expect(m).toBeDefined()
+    } catch (error) {
+      // May not be configured
+      expect(error).toBeDefined()
+    }
+  })
+})
+
+describe.skipIf(!hasGateway)('embeddingModel() integration', () => {
+  it('gets an OpenAI embedding model', async () => {
+    try {
+      const em = await embeddingModel('openai:text-embedding-3-small')
+      expect(em).toBeDefined()
+      expect(em.provider).toBe('openai')
+    } catch (error) {
+      // May not be configured
+      expect(error).toBeDefined()
+    }
+  })
+
+  it.skipIf(!hasCloudflare)('gets a Cloudflare embedding model', async () => {
+    const em = await embeddingModel('cloudflare:@cf/baai/bge-m3')
+    expect(em).toBeDefined()
+    expect(em.provider).toBe('cloudflare')
+  })
+})
+
+describe.skipIf(!hasGateway)('createRegistry() integration', () => {
+  it('creates registry with gateway config', async () => {
+    const registry = await createRegistry({
+      gatewayUrl: process.env.AI_GATEWAY_URL,
+      gatewayToken: process.env.AI_GATEWAY_TOKEN,
+    })
+
+    expect(registry).toBeDefined()
+    expect(typeof registry.languageModel).toBe('function')
+    expect(typeof registry.textEmbeddingModel).toBe('function')
+  })
+
+  it('creates registry with direct API keys', async () => {
+    const registry = await createRegistry({
+      openaiApiKey: process.env.OPENAI_API_KEY,
+      anthropicApiKey: process.env.ANTHROPIC_API_KEY,
+      openrouterApiKey: process.env.OPENROUTER_API_KEY,
+    })
+
+    expect(registry).toBeDefined()
+  })
+
+  it('can use registry to get models', async () => {
+    const registry = await createRegistry()
+
+    try {
+      const m = registry.languageModel('openrouter:anthropic/claude-sonnet-4.5')
+      expect(m).toBeDefined()
+    } catch (error) {
+      // May not be configured
+      expect(error).toBeDefined()
+    }
+  })
+})
+
+describe.skipIf(!hasGateway)('gateway authentication', () => {
+  it('works with gateway stored secrets', async () => {
+    if (!process.env.AI_GATEWAY_URL || !process.env.AI_GATEWAY_TOKEN) {
+      return
+    }
+
+    const registry = await createRegistry({
+      gatewayUrl: process.env.AI_GATEWAY_URL,
+      gatewayToken: process.env.AI_GATEWAY_TOKEN,
+      // No individual API keys needed
+    })
+
+    expect(registry).toBeDefined()
+  })
+
+  it('custom fetch adds cf-aig-authorization header', async () => {
+    // This is tested indirectly through successful API calls with gateway
+    expect(true).toBe(true)
+  })
+})
+
+describe.skipIf(!hasCloudflare)('Cloudflare embeddings integration', () => {
+  it('generates embeddings via REST API', async () => {
+    const { cloudflareEmbedding } = await import('./providers/cloudflare.js')
+    const model = cloudflareEmbedding('@cf/baai/bge-m3', {
+      accountId: process.env.CLOUDFLARE_ACCOUNT_ID,
+      apiToken: process.env.CLOUDFLARE_API_TOKEN,
+    })
+
+    const result = await model.doEmbed({
+      values: ['hello world', 'test embedding'],
+    })
+
+    expect(result.embeddings).toHaveLength(2)
+    expect(result.embeddings[0].length).toBeGreaterThan(0)
+    expect(Array.isArray(result.embeddings[0])).toBe(true)
+  })
+
+  it('supports different embedding models', async () => {
+    const { cloudflareEmbedding } = await import('./providers/cloudflare.js')
+    const models = [
+      '@cf/baai/bge-small-en-v1.5',
+      '@cf/baai/bge-base-en-v1.5',
+      '@cf/baai/bge-m3',
+    ]
+
+    for (const modelId of models) {
+      const model = cloudflareEmbedding(modelId, {
+        accountId: process.env.CLOUDFLARE_ACCOUNT_ID,
+        apiToken: process.env.CLOUDFLARE_API_TOKEN,
+      })
+
+      const result = await model.doEmbed({
+        values: ['test'],
+      })
+
+      expect(result.embeddings).toHaveLength(1)
+    }
+  }, 30000) // Allow extra time for multiple API calls
+})
+
+describe.skipIf(!hasGateway)('provider-specific features', () => {
+  it.skip('supports Anthropic MCP with direct routing', async () => {
+    // Test MCP features when using direct Anthropic SDK routing
+    // Requires actual MCP implementation
+    expect(true).toBe(true)
+  })
+
+  it.skip('supports OpenAI function calling with direct routing', async () => {
+    // Test function calling when using direct OpenAI SDK routing
+    expect(true).toBe(true)
+  })
+
+  it.skip('supports Google grounding with direct routing', async () => {
+    // Test grounding when using direct Google SDK routing
+    expect(true).toBe(true)
+  })
+})
+
+describe.skipIf(!hasGateway)('error handling', () => {
+  it('handles invalid model IDs gracefully', async () => {
+    try {
+      await model('invalid-model-that-does-not-exist-12345')
+    } catch (error) {
+      expect(error).toBeDefined()
+    }
+  })
+
+  it('handles network errors gracefully', async () => {
+    const registry = await createRegistry({
+      baseUrls: {
+        openrouter: 'https://invalid-url-that-does-not-exist.example.com',
+      },
+    })
+
+    try {
+      const m = registry.languageModel('openrouter:test')
+      // Attempting to use this model should fail
+      expect(m).toBeDefined()
+    } catch (error) {
+      expect(error).toBeDefined()
+    }
+  })
+
+  it('handles missing credentials gracefully', async () => {
+    const registry = await createRegistry({
+      // No credentials provided
+      gatewayUrl: undefined,
+      gatewayToken: undefined,
+      openaiApiKey: undefined,
+      anthropicApiKey: undefined,
+    })
+
+    // Registry should be created, but using models may fail
+    expect(registry).toBeDefined()
+  })
+})
+
+describe.skipIf(!hasGateway)('concurrent requests', () => {
+  it('handles multiple concurrent model resolutions', async () => {
+    const promises = [
+      model('sonnet'),
+      model('opus'),
+      model('gpt-4o'),
+    ]
+
+    try {
+      const models = await Promise.all(promises)
+      expect(models).toHaveLength(3)
+      models.forEach(m => expect(m).toBeDefined())
+    } catch (error) {
+      // Some models may not be configured
+      expect(error).toBeDefined()
+    }
+  })
+
+  it('caches registry to avoid duplicate initialization', async () => {
+    const { getRegistry } = await import('./index.js')
+
+    const promises = [
+      getRegistry(),
+      getRegistry(),
+      getRegistry(),
+    ]
+
+    const registries = await Promise.all(promises)
+
+    // All should be the same instance
+    expect(registries[0]).toBe(registries[1])
+    expect(registries[1]).toBe(registries[2])
+  })
+})
+
+describe.skipIf(!hasGateway)('performance', () => {
+  it('resolves models quickly after initial setup', async () => {
+    const start = Date.now()
+    await model('sonnet')
+    const duration = Date.now() - start
+
+    // After registry is initialized, should be fast
+    // Allow up to 1 second for initialization
+    expect(duration).toBeLessThan(1000)
+  })
+
+  it('caches registry for subsequent calls', async () => {
+    // First call initializes
+    await model('sonnet')
+
+    // Second call should use cached registry
+    const start = Date.now()
+    await model('opus')
+    const duration = Date.now() - start
+
+    // Should be very fast (< 100ms) when cached
+    expect(duration).toBeLessThan(100)
+  })
+})