OpenAI can pass apiKey in clientConfig

[zastrowm]

OpenAI can pass apiKey in clientConfig

Original Request

Our OpenAI model can take in an apiKey as a member of clientConfig, but right now we throw an exception if we try to do this (because neither the environment variable nor the explicit apiKey at the top level config was passed in). However, the clientConfig.apiKey is useful because it can be a function instead of a string.

Update the OpenAI model config to allow the same type for apiKey as the client does, so that you can pass a function to the openAI model provider.

Implementation Requirements

Problem Analysis

The current OpenAIModelOptions interface (line 173 in src/models/openai.ts) defines apiKey as only accepting a string:

export interface OpenAIModelOptions extends OpenAIModelConfig {
  apiKey?: string  // ❌ Only accepts string
  // ...
}

However, the OpenAI SDK's ClientOptions interface supports apiKey as either a string OR an async function that returns a string:

export type ApiKeySetter = () => Promise<string>

export interface ClientOptions {
  apiKey?: string | ApiKeySetter | undefined
  // ...
}

This function-based API key is useful for:

• Dynamic API key rotation
• Runtime credential refresh
• Fetching keys from secret managers
• Per-request authentication logic

Technical Approach

File to Modify: src/models/openai.ts

Change 1: Import the ApiKeySetter Type

Location: Line 10 (import statement)

Current:

import OpenAI, { type ClientOptions } from 'openai'

Required:

import OpenAI, { type ClientOptions, type ApiKeySetter } from 'openai'

Change 2: Update Interface Type Definition

Location: Line 169-173 (OpenAIModelOptions interface)

Current:

export interface OpenAIModelOptions extends OpenAIModelConfig {
  /**
   * OpenAI API key (falls back to OPENAI_API_KEY environment variable).
   */
  apiKey?: string

Required:

export interface OpenAIModelOptions extends OpenAIModelConfig {
  /**
   * OpenAI API key (falls back to OPENAI_API_KEY environment variable).
   * 
   * Accepts either a static string or an async function that resolves to a string.
   * When a function is provided, it is invoked before each request, allowing for
   * dynamic API key rotation or runtime credential refresh.
   */
  apiKey?: string | ApiKeySetter

Change 3: Update Constructor Validation Logic

Location: Lines 265-272 (constructor validation)

Current:

const hasEnvKey =
  typeof process !== 'undefined' && typeof process.env !== 'undefined' && process.env.OPENAI_API_KEY
if (!apiKey && !hasEnvKey) {
  throw new Error(
    "OpenAI API key is required. Provide it via the 'apiKey' option or set the OPENAI_API_KEY environment variable."
  )
}

Required:

const hasEnvKey =
  typeof process !== 'undefined' && typeof process.env !== 'undefined' && process.env.OPENAI_API_KEY
// Check if apiKey is provided (string or function are both truthy)
if (!apiKey && !hasEnvKey) {
  throw new Error(
    "OpenAI API key is required. Provide it via the 'apiKey' option (string or function) or set the OPENAI_API_KEY environment variable."
  )
}

Note: No additional validation is needed for function-based keys - the OpenAI SDK will validate that the function returns a non-empty string and throw appropriate errors.

Change 4: Update Constructor TSDoc Examples

Location: Lines 218-250 (constructor documentation)

Add example demonstrating function-based API key usage:

/**
 * Creates a new OpenAIModel instance.
 *
 * @param options - Configuration for model and client
 *
 * @example
 * ```typescript
 * // Using static API key
 * const provider = new OpenAIModel({
 *   modelId: 'gpt-4o',
 *   apiKey: 'sk-...'
 * })
 *
 * // Using function-based API key for dynamic rotation
 * const provider = new OpenAIModel({
 *   modelId: 'gpt-4o',
 *   apiKey: async () => await getRotatingApiKey()
 * })
 *
 * // Using environment variable
 * const provider = new OpenAIModel({
 *   modelId: 'gpt-3.5-turbo'
 * })
 * ```
 */

Test Requirements

File to Modify: src/models/__tests__/openai.test.ts

Add test cases in the constructor describe block (after line 147):

Test 1: String-based API key (already exists)

Verify existing test at line 51 still passes.

Test 2: Function-based API key

it('accepts function-based API key', () => {
  const apiKeyFn = vi.fn(async () => 'sk-dynamic')
  new OpenAIModel({ 
    modelId: 'gpt-4o', 
    apiKey: apiKeyFn 
  })
  expect(OpenAI).toHaveBeenCalledWith(
    expect.objectContaining({
      apiKey: apiKeyFn
    })
  )
})

Test 3: Async function API key

it('accepts async function-based API key', async () => {
  const apiKeyFn = async () => {
    // Simulate async operation
    await new Promise(resolve => setTimeout(resolve, 10))
    return 'sk-async-key'
  }
  
  new OpenAIModel({ 
    modelId: 'gpt-4o', 
    apiKey: apiKeyFn 
  })
  
  expect(OpenAI).toHaveBeenCalledWith(
    expect.objectContaining({
      apiKey: apiKeyFn
    })
  )
})

Test 4: Function API key takes precedence over env var

if (isNode) {
  it('function-based API key takes precedence over environment variable', () => {
    vi.stubEnv('OPENAI_API_KEY', 'sk-from-env')
    const apiKeyFn = async () => 'sk-from-function'
    
    new OpenAIModel({ 
      modelId: 'gpt-4o', 
      apiKey: apiKeyFn 
    })
    
    expect(OpenAI).toHaveBeenCalledWith(
      expect.objectContaining({
        apiKey: apiKeyFn
      })
    )
  })
}

Test 5: Error when neither string nor function API key provided

it('throws error when no API key is available (no function or string)', () => {
  if (isNode) {
    vi.stubEnv('OPENAI_API_KEY', '')
  }
  expect(() => 
    new OpenAIModel({ modelId: 'gpt-4o' })
  ).toThrow(
    "OpenAI API key is required. Provide it via the 'apiKey' option (string or function) or set the OPENAI_API_KEY environment variable."
  )
})

Acceptance Criteria

• ApiKeySetter type is imported from 'openai' package
• OpenAIModelOptions.apiKey accepts string | ApiKeySetter
• Constructor accepts string-based apiKey without error (existing behavior)
• Constructor accepts function-based apiKey without error (new behavior)
• Constructor passes function-based apiKey directly to OpenAI client
• Validation logic treats function as valid (truthy check)
• Error message updated to mention "string or function"
• TSDoc comments document function-based API key capability
• TSDoc includes example of function-based usage
• All existing tests continue to pass
• New tests added for function-based apiKey scenarios
• Test coverage remains at 80%+
• Code passes linting and formatting checks
• No breaking changes to existing API

Estimated Scope

• Complexity: Low
• Files Modified: 2 files (openai.ts and openai.test.ts)
• Lines Changed:
  • Source: ~15 lines (import, type, validation, docs)
  • Tests: ~70 lines (5 new test cases)
• Implementation Time: 1-2 hours
• Testing Time: 1 hour

Additional Notes

• No breaking changes - This is purely additive functionality that expands the accepted type
• Backward compatible - All existing string-based usage patterns continue to work
• OpenAI SDK handles validation - No need to validate function return values; OpenAI SDK will throw appropriate errors
• Type safety - Using OpenAI's native ApiKeySetter type ensures compatibility
• Use case alignment - Matches real-world needs for credential rotation and dynamic key management

[zastrowm]

/strands review

[github-actions]

Task Review Complete ✅

I've completed the review and refinement of this issue. The task is ready for implementation.

Summary

This is a straightforward enhancement to the OpenAIModel constructor validation logic. The issue is well-scoped and implementable in a few hours.

What was accomplished:

• ✅ Analyzed the current implementation in src/models/openai.ts
• ✅ Identified the exact code change needed (3-line validation update)
• ✅ Designed comprehensive test coverage for the new functionality
• ✅ Defined clear acceptance criteria
• ✅ Updated issue description with detailed implementation requirements

Key Implementation Points

Core Change: Update the API key validation in the constructor to check three sources instead of two:

1. Top-level apiKey option
2. clientConfig.apiKey ← NEW
3. Environment variable fallback

Testing Strategy: Add 4 new test cases covering:

• String-based apiKey in clientConfig
• Function-based apiKey in clientConfig
• Precedence when multiple sources are provided
• Error handling when no key is available

Impact:

• Low complexity, no breaking changes
• Purely additive functionality
• Aligns with OpenAI SDK's native interface
• Estimated 2-3 hours total implementation time

Files to Modify

1. src/models/openai.ts - Constructor validation (~5 lines)
2. src/models/__tests__/openai.test.ts - New test cases (~60 lines)

The issue description has been updated with complete implementation details, code examples, and acceptance criteria. Ready for a developer to pick up and implement.

[zastrowm]

/strands review no the openai config should allow the top level API key Param to be the same type as the client config value.

Don't just check for the client config property

[github-actions]

Updated Understanding - Clarifying Questions

Thank you for the clarification! I now understand you want the top-level apiKey parameter to support the same type as ClientOptions.apiKey, not just check clientConfig as an additional source.

Current Situation

export interface OpenAIModelOptions extends OpenAIModelConfig {
  apiKey?: string  // ❌ Only accepts string
  // ...
}

OpenAI SDK Type

export type ApiKeySetter = () => Promise<string>

export interface ClientOptions {
  apiKey?: string | ApiKeySetter | undefined
  // ...
}

Proposed Solution

Change OpenAIModelOptions.apiKey to match OpenAI's type:

export interface OpenAIModelOptions extends OpenAIModelConfig {
  apiKey?: string | (() => Promise<string>)  // ✅ Accepts string OR async function
  // ...
}

This would allow:

// String (current)
const model = new OpenAIModel({
  modelId: 'gpt-4o',
  apiKey: 'sk-...'
})

// Function (new capability)
const model = new OpenAIModel({
  modelId: 'gpt-4o',
  apiKey: async () => await getRotatingApiKey()
})

Clarifying Questions

Q1: Type Import Strategy
Should we import OpenAI's ApiKeySetter type or define inline?

• Option A: import type { ClientOptions, ApiKeySetter } from 'openai' then use apiKey?: string | ApiKeySetter
• Option B: Define inline: apiKey?: string | (() => Promise<string>)

Option A is more consistent with OpenAI SDK; Option B is simpler with no additional import.

Q2: Validation
The OpenAI SDK validates that the function returns a non-empty string. Should we add our own validation or rely on OpenAI's?

• Option A: Add validation in our constructor (more explicit error messages)
• Option B: Let OpenAI SDK handle validation (simpler, less code duplication)

Q3: Type Export
Should we export a type alias for users? E.g., export type ApiKey = string | (() => Promise<string>)

Please let me know your preferences, or if you'd like me to proceed with reasonable defaults.

[zastrowm]

/strands

Updated Understanding - Clarifying Questions

Thank you for the clarification! I now understand you want the top-level apiKey parameter to support the same type as ClientOptions.apiKey, not just check clientConfig as an additional source.

Current Situation

export interface OpenAIModelOptions extends OpenAIModelConfig {
  apiKey?: string  // ❌ Only accepts string
  // ...
}

OpenAI SDK Type

export type ApiKeySetter = () => Promise<string>

export interface ClientOptions {
  apiKey?: string | ApiKeySetter | undefined
  // ...
}

Proposed Solution

Change OpenAIModelOptions.apiKey to match OpenAI's type:

export interface OpenAIModelOptions extends OpenAIModelConfig {
  apiKey?: string | (() => Promise<string>)  // ✅ Accepts string OR async function
  // ...
}

This would allow:

// String (current)
const model = new OpenAIModel({
  modelId: 'gpt-4o',
  apiKey: 'sk-...'
})

// Function (new capability)
const model = new OpenAIModel({
  modelId: 'gpt-4o',
  apiKey: async () => await getRotatingApiKey()
})

Clarifying Questions

Q1: Type Import Strategy
Should we import OpenAI's ApiKeySetter type or define inline?

• Option A: import type { ClientOptions, ApiKeySetter } from 'openai' then use apiKey?: string | ApiKeySetter
• Option B: Define inline: apiKey?: string | (() => Promise<string>)

Option A is more consistent with OpenAI SDK; Option B is simpler with no additional import.

Option A

Q2: Validation
The OpenAI SDK validates that the function returns a non-empty string. Should we add our own validation or rely on OpenAI's?

• Option A: Add validation in our constructor (more explicit error messages)
• Option B: Let OpenAI SDK handle validation (simpler, less code duplication)

B

Q3: Type Export
Should we export a type alias for users? E.g., export type ApiKey = string | (() => Promise<string>)

No type export

Please let me know your preferences, or if you'd like me to proceed with reasonable defaults.

[github-actions]

✅ Task Review Complete - Updated Implementation

Thank you for the clarification! I've updated the issue description with the corrected implementation requirements.

Summary of Changes

What was wrong: My initial approach was to check clientConfig.apiKey as an additional source.

What's correct: Change the TYPE of OpenAIModelOptions.apiKey to match OpenAI SDK's type, allowing it to accept a function.

Implementation Overview

Type Change:

// Before
apiKey?: string

// After
apiKey?: string | ApiKeySetter  // where ApiKeySetter = () => Promise<string>

Key Decisions (based on your feedback):

1. ✅ Import ApiKeySetter type from 'openai' package (Option A)
2. ✅ Let OpenAI SDK handle validation (Option B)
3. ✅ No type export needed

Files to Modify:

1. src/models/openai.ts
   • Import ApiKeySetter type
   • Change apiKey type definition
   • Update error message
   • Update TSDoc examples
2. src/models/__tests__/openai.test.ts
   • Add 5 test cases for function-based API key

Estimated Effort: 2-3 hours total

What This Enables

Users can now pass a function for dynamic API key management:

const model = new OpenAIModel({
  modelId: 'gpt-4o',
  apiKey: async () => await getRotatingApiKey()
})

This is useful for:

• API key rotation
• Runtime credential refresh
• Fetching keys from secret managers
• Per-request authentication logic

The issue description now has complete implementation details with code examples, test requirements, and acceptance criteria. Ready for implementation! 🚀

[zastrowm]

/strands implement