feat: Task 04.1: OpenAI Model Core Structure and Configuration Implementation (#54)

* feat: implement OpenAI model core structure and configuration

- Add openai package dependency (v4.77.3)
- Implement OpenAIModelConfig interface with OpenAI-specific options
- Implement OpenAIModelOptions interface with apiKey, baseUrl, and clientConfig
- Create OpenAIModel class with constructor, updateConfig, getConfig methods
- Add stream method stub (to be implemented in Task 04.2)
- Implement comprehensive unit tests with 100% coverage
- Export OpenAI types and class in src/index.ts

Resolves: #47

---------

Co-authored-by: Strands Agent <[email protected]>

Author: afarntrog

package.json

@@ -66,5 +66,8 @@
   "homepage": "https://github.com/strands-agents/sdk-typescript#readme",
   "dependencies": {
     "@aws-sdk/client-bedrock-runtime": "^3.911.0"
+  },
+  "optionalDependencies": {
+    "openai": "^4.77.3"
   }
 }

src/models/__tests__/openai.test.ts

@@ -0,0 +1,174 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import OpenAI from 'openai'
+import { OpenAIModel } from '../openai'
+import type { Message } from '../../types/messages'
+
+// Mock the OpenAI SDK
+vi.mock('openai', () => {
+  const mockConstructor = vi.fn().mockImplementation(() => ({}))
+  return {
+    default: mockConstructor,
+  }
+})
+
+describe('OpenAIModel', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    // Set default env var for most tests using Vitest's stubEnv
+    vi.stubEnv('OPENAI_API_KEY', 'sk-test-env')
+  })
+
+  afterEach(() => {
+    vi.clearAllMocks()
+    // Restore all environment variables to their original state
+    vi.unstubAllEnvs()
+  })
+
+  describe('constructor', () => {
+    it('creates an instance with required modelId', () => {
+      const provider = new OpenAIModel({ modelId: 'gpt-4o', apiKey: 'sk-test' })
+      const config = provider.getConfig()
+      expect(config.modelId).toBe('gpt-4o')
+    })
+
+    it('uses custom model ID', () => {
+      const customModelId = 'gpt-3.5-turbo'
+      const provider = new OpenAIModel({ modelId: customModelId, apiKey: 'sk-test' })
+      expect(provider.getConfig()).toStrictEqual({
+        modelId: customModelId,
+      })
+    })
+
+    it('uses API key from constructor parameter', () => {
+      const apiKey = 'sk-explicit'
+      new OpenAIModel({ modelId: 'gpt-4o', apiKey })
+      expect(OpenAI).toHaveBeenCalledWith(
+        expect.objectContaining({
+          apiKey: apiKey,
+        })
+      )
+    })
+
+    it('uses API key from environment variable', () => {
+      vi.stubEnv('OPENAI_API_KEY', 'sk-from-env')
+      new OpenAIModel({ modelId: 'gpt-4o' })
+      // OpenAI client should be called without explicit apiKey (uses env var internally)
+      expect(OpenAI).toHaveBeenCalled()
+    })
+
+    it('explicit API key takes precedence over environment variable', () => {
+      vi.stubEnv('OPENAI_API_KEY', 'sk-from-env')
+      const explicitKey = 'sk-explicit'
+      new OpenAIModel({ modelId: 'gpt-4o', apiKey: explicitKey })
+      expect(OpenAI).toHaveBeenCalledWith(
+        expect.objectContaining({
+          apiKey: explicitKey,
+        })
+      )
+    })
+
+    it('throws error when no API key is available', () => {
+      vi.stubEnv('OPENAI_API_KEY', '')
+      expect(() => new OpenAIModel({ modelId: 'gpt-4o' })).toThrow(
+        "OpenAI API key is required. Provide it via the 'apiKey' option or set the OPENAI_API_KEY environment variable."
+      )
+    })
+
+    it('uses custom client configuration', () => {
+      const timeout = 30000
+      new OpenAIModel({ modelId: 'gpt-4o', apiKey: 'sk-test', clientConfig: { timeout } })
+      expect(OpenAI).toHaveBeenCalledWith(
+        expect.objectContaining({
+          timeout: timeout,
+        })
+      )
+    })
+
+    it('uses provided client instance', () => {
+      vi.clearAllMocks()
+      const mockClient = {} as OpenAI
+      const provider = new OpenAIModel({ modelId: 'gpt-4o', client: mockClient })
+      // Should not create a new OpenAI client
+      expect(OpenAI).not.toHaveBeenCalled()
+      expect(provider).toBeDefined()
+    })
+
+    it('provided client takes precedence over apiKey and clientConfig', () => {
+      vi.clearAllMocks()
+      const mockClient = {} as OpenAI
+      new OpenAIModel({
+        modelId: 'gpt-4o',
+        apiKey: 'sk-test',
+        client: mockClient,
+        clientConfig: { timeout: 30000 },
+      })
+      // Should not create a new OpenAI client when client is provided
+      expect(OpenAI).not.toHaveBeenCalled()
+    })
+
+    it('does not require API key when client is provided', () => {
+      vi.clearAllMocks()
+      vi.stubEnv('OPENAI_API_KEY', '')
+      const mockClient = {} as OpenAI
+      expect(() => new OpenAIModel({ modelId: 'gpt-4o', client: mockClient })).not.toThrow()
+    })
+  })
+
+  describe('updateConfig', () => {
+    it('merges new config with existing config', () => {
+      const provider = new OpenAIModel({ modelId: 'gpt-4o', apiKey: 'sk-test', temperature: 0.5 })
+      provider.updateConfig({ modelId: 'gpt-4o', temperature: 0.8, maxTokens: 2048 })
+      expect(provider.getConfig()).toStrictEqual({
+        modelId: 'gpt-4o',
+        temperature: 0.8,
+        maxTokens: 2048,
+      })
+    })
+
+    it('preserves fields not included in the update', () => {
+      const provider = new OpenAIModel({
+        apiKey: 'sk-test',
+        modelId: 'gpt-3.5-turbo',
+        temperature: 0.5,
+        maxTokens: 1024,
+      })
+      provider.updateConfig({ modelId: 'gpt-3.5-turbo', temperature: 0.8 })
+      expect(provider.getConfig()).toStrictEqual({
+        modelId: 'gpt-3.5-turbo',
+        temperature: 0.8,
+        maxTokens: 1024,
+      })
+    })
+  })
+
+  describe('getConfig', () => {
+    it('returns the current configuration', () => {
+      const provider = new OpenAIModel({
+        modelId: 'gpt-4o',
+        apiKey: 'sk-test',
+        maxTokens: 1024,
+        temperature: 0.7,
+      })
+      expect(provider.getConfig()).toStrictEqual({
+        modelId: 'gpt-4o',
+        maxTokens: 1024,
+        temperature: 0.7,
+      })
+    })
+  })
+
+  describe('stream', () => {
+    it('throws not yet implemented error', async () => {
+      const provider = new OpenAIModel({ modelId: 'gpt-4o' })
+      const messages: Message[] = [{ role: 'user', content: [{ type: 'textBlock', text: 'Hello' }] }]
+
+      await expect(async () => {
+        // Try to consume the async generator
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        for await (const _event of provider.stream(messages)) {
+          // Should not reach here
+        }
+      }).rejects.toThrow('Not yet implemented - will be completed in Task 04.2')
+    })
+  })
+})