@revenium/openai 1.0.10 → 1.0.12

package/src/utils/provider-detection.ts

@@ -0,0 +1,257 @@
+/**
+ * Provider Detection Utilities
+ *
+ * Simplifies complex provider detection logic using strategy pattern
+ * instead of nested conditionals.
+ */
+
+import { Provider, ProviderInfo, AzureConfig } from '../types/index.js';
+import { OpenAIClientInstance } from '../types/function-parameters.js';
+import { Logger } from '../types/index.js';
+
+/**
+ * Provider detection strategy interface
+ */
+interface ProviderDetectionStrategy {
+  /** Strategy name for logging */
+  name: string;
+  /** Priority (higher = checked first) */
+  priority: number;
+  /** Detection function */
+  detect: (client: OpenAIClientInstance) => boolean;
+  /** Additional context for logging */
+  getContext?: (client: OpenAIClientInstance) => Record<string, unknown>;
+}
+
+/**
+ * Provider detection strategies in priority order
+ */
+const DETECTION_STRATEGIES: ProviderDetectionStrategy[] = [
+  {
+    name: 'Constructor Name',
+    priority: 100,
+    detect: client => {
+      return client?.constructor?.name?.includes('Azure') || false;
+    },
+    getContext: client => ({
+      constructorName: client?.constructor?.name,
+    }),
+  },
+  {
+    name: 'Base URL',
+    priority: 90,
+    detect: client => {
+      const baseUrl = getBaseUrlString(client);
+      return baseUrl?.toLowerCase().includes('azure') || false;
+    },
+    getContext: client => ({
+      baseURL: getBaseUrlString(client),
+    }),
+  },
+  {
+    name: 'Environment Variables',
+    priority: 80,
+    detect: client => {
+      // Only use env vars if not explicitly OpenAI
+      const baseUrl = getBaseUrlString(client);
+      const isExplicitlyOpenAI =
+        baseUrl?.includes('api.openai.com') ||
+        (client?.constructor?.name?.toLowerCase().includes('openai') &&
+          !client?.constructor?.name?.toLowerCase().includes('azure'));
+
+      return !isExplicitlyOpenAI && !!process.env.AZURE_OPENAI_ENDPOINT;
+    },
+    getContext: () => ({
+      hasAzureEndpoint: !!process.env.AZURE_OPENAI_ENDPOINT,
+      hasAzureDeployment: !!process.env.AZURE_OPENAI_DEPLOYMENT,
+      hasAzureApiKey: !!process.env.AZURE_OPENAI_API_KEY,
+    }),
+  },
+];
+
+/**
+ * Extract base URL as string from client
+ */
+function getBaseUrlString(client: OpenAIClientInstance): string | undefined {
+  if (!client?.baseURL) return undefined;
+
+  return typeof client.baseURL === 'string' ? client.baseURL : client.baseURL.toString();
+}
+
+/**
+ * Detect provider using strategy pattern
+ *
+ * This replaces the complex nested conditional logic with a clean,
+ * testable strategy pattern.
+ *
+ * @param client - OpenAI client instance
+ * @param logger - Logger for debugging
+ * @returns Provider detection result
+ */
+export function detectProviderStrategy(
+  client: OpenAIClientInstance,
+  logger?: Logger
+): { provider: Provider; strategy?: string; context?: Record<string, unknown> } {
+  // Sort strategies by priority (highest first)
+  const sortedStrategies = [...DETECTION_STRATEGIES].sort((a, b) => b.priority - a.priority);
+
+  for (const strategy of sortedStrategies) {
+    try {
+      if (strategy.detect(client)) {
+        const context = strategy.getContext?.(client) || {};
+
+        if (logger) {
+          logger.debug(`Azure provider detected via ${strategy.name}`, context);
+        }
+
+        return {
+          provider: Provider.AZURE_OPENAI,
+          strategy: strategy.name,
+          context,
+        };
+      }
+    } catch (error) {
+      if (logger) {
+        logger.warn(`Provider detection strategy '${strategy.name}' failed`, {
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+    }
+  }
+
+  // Default to OpenAI
+  if (logger) {
+    logger.debug('Standard OpenAI provider detected (no Azure indicators found)');
+  }
+
+  return { provider: Provider.OPENAI };
+}
+
+/**
+ * Azure configuration gathering strategies
+ */
+interface AzureConfigStrategy {
+  name: string;
+  gather: (client: OpenAIClientInstance) => Partial<AzureConfig>;
+}
+
+const AZURE_CONFIG_STRATEGIES: AzureConfigStrategy[] = [
+  {
+    name: 'Client BaseURL',
+    gather: client => {
+      const baseUrl = getBaseUrlString(client);
+      return baseUrl ? { endpoint: baseUrl } : {};
+    },
+  },
+  {
+    name: 'Environment Variables',
+    gather: () => ({
+      endpoint: process.env.AZURE_OPENAI_ENDPOINT,
+      deployment: process.env.AZURE_OPENAI_DEPLOYMENT,
+      apiVersion: process.env.AZURE_OPENAI_API_VERSION || '2024-12-01-preview',
+      apiKey: process.env.AZURE_OPENAI_API_KEY,
+      tenantId: process.env.AZURE_OPENAI_TENANT_ID,
+      resourceGroup: process.env.AZURE_OPENAI_RESOURCE_GROUP,
+    }),
+  },
+];
+
+/**
+ * Gather Azure configuration using strategy pattern
+ *
+ * @param client - OpenAI client instance
+ * @param logger - Logger for debugging
+ * @returns Merged Azure configuration
+ */
+export function gatherAzureConfigStrategy(
+  client: OpenAIClientInstance,
+  logger?: Logger
+): AzureConfig {
+  const config: AzureConfig = {};
+  for (const strategy of AZURE_CONFIG_STRATEGIES) {
+    try {
+      const strategyConfig = strategy.gather(client);
+
+      // Merge non-undefined values
+      Object.entries(strategyConfig).forEach(([key, value]) => {
+        if (value !== undefined && !(key in config)) {
+          (config as any)[key] = value;
+        }
+      });
+    } catch (error) {
+      if (logger) {
+        logger.warn(`Azure config strategy '${strategy.name}' failed`, {
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+    }
+  }
+
+  if (logger) {
+    logger.debug('Azure configuration gathered', {
+      hasEndpoint: !!config.endpoint,
+      hasDeployment: !!config.deployment,
+      hasApiKey: !!config.apiKey,
+      apiVersion: config.apiVersion,
+    });
+  }
+
+  return config;
+}
+
+/**
+ * Create complete provider info using strategies
+ *
+ * @param client - OpenAI client instance
+ * @param logger - Logger for debugging
+ * @returns Complete provider information
+ */
+export function createProviderInfo(client: OpenAIClientInstance, logger?: Logger): ProviderInfo {
+  const detection = detectProviderStrategy(client, logger);
+
+  if (detection.provider === Provider.AZURE_OPENAI) {
+    const azureConfig = gatherAzureConfigStrategy(client, logger);
+
+    return {
+      provider: detection.provider,
+      isAzure: true,
+      azureConfig,
+    };
+  }
+
+  return {
+    provider: detection.provider,
+    isAzure: false,
+    azureConfig: undefined,
+  };
+}
+
+/**
+ * Validate provider detection result
+ *
+ * @param providerInfo - Provider info to validate
+ * @returns Validation result
+ */
+export function validateProviderInfo(providerInfo: ProviderInfo): {
+  isValid: boolean;
+  warnings: string[];
+} {
+  const warnings: string[] = [];
+  if (providerInfo.isAzure) {
+    if (!providerInfo.azureConfig) {
+      warnings.push('Azure provider detected but no Azure configuration available');
+    } else {
+      if (!providerInfo.azureConfig.endpoint) {
+        warnings.push('Azure configuration missing endpoint');
+      }
+      if (!providerInfo.azureConfig.apiKey) {
+        warnings.push('Azure configuration missing API key');
+      }
+    }
+  }
+
+  return {
+    isValid: warnings.length === 0,
+    warnings,
+  };
+}

package/src/utils/request-handler-factory.ts

@@ -0,0 +1,285 @@
+/**
+ * Request Handler Factory
+ *
+ * Eliminates dynamic require() calls and provides a clean factory pattern
+ * for creating request handlers with proper dependency injection.
+ */
+
+import {
+  OpenAIChatRequest,
+  OpenAIEmbeddingRequest,
+  OpenAIRequestOptions,
+  OpenAIClientInstance,
+  OpenAIOriginalFunction,
+  OpenAIResponsesOriginalFunction,
+} from '../types/function-parameters.js';
+import { UsageMetadata, OpenAIResponsesRequest } from '../types/index.js';
+
+/**
+ * Request handler function signatures
+ */
+export type StreamingRequestHandler = (
+  originalCreate: OpenAIOriginalFunction,
+  params: Omit<OpenAIChatRequest, 'usageMetadata'>,
+  options: OpenAIRequestOptions | undefined,
+  usageMetadata: UsageMetadata | undefined,
+  requestStartTime: number,
+  instance: OpenAIClientInstance
+) => Promise<AsyncIterable<unknown>>;
+
+export type NonStreamingRequestHandler = (
+  originalCreate: OpenAIOriginalFunction,
+  params: Omit<OpenAIChatRequest, 'usageMetadata'> | Omit<OpenAIEmbeddingRequest, 'usageMetadata'>,
+  options: OpenAIRequestOptions | undefined,
+  usageMetadata: UsageMetadata | undefined,
+  requestStartTime: number,
+  instance: OpenAIClientInstance
+) => Promise<unknown>;
+
+export type EmbeddingsRequestHandler = (
+  originalCreate: OpenAIOriginalFunction,
+  params: Omit<OpenAIEmbeddingRequest, 'usageMetadata'>,
+  options: OpenAIRequestOptions | undefined,
+  usageMetadata: UsageMetadata | undefined,
+  requestStartTime: number,
+  instance: OpenAIClientInstance
+) => Promise<unknown>;
+
+export type ResponsesStreamingRequestHandler = (
+  originalCreate: OpenAIResponsesOriginalFunction,
+  params: Omit<OpenAIResponsesRequest, 'usageMetadata'>,
+  options: OpenAIRequestOptions | undefined,
+  usageMetadata: UsageMetadata | undefined,
+  requestStartTime: number,
+  instance: OpenAIClientInstance
+) => Promise<AsyncIterable<unknown>>;
+
+export type ResponsesNonStreamingRequestHandler = (
+  originalCreate: OpenAIResponsesOriginalFunction,
+  params: Omit<OpenAIResponsesRequest, 'usageMetadata'>,
+  options: OpenAIRequestOptions | undefined,
+  usageMetadata: UsageMetadata | undefined,
+  requestStartTime: number,
+  instance: OpenAIClientInstance
+) => Promise<unknown>;
+
+/**
+ * Request handler dependencies
+ */
+export interface RequestHandlerDependencies {
+  handleStreamingRequest: StreamingRequestHandler;
+  handleNonStreamingRequest: NonStreamingRequestHandler;
+  handleEmbeddingsRequest: EmbeddingsRequestHandler;
+  handleResponsesStreamingRequest: ResponsesStreamingRequestHandler;
+  handleResponsesNonStreamingRequest: ResponsesNonStreamingRequestHandler;
+}
+
+/**
+ * Request handler factory class
+ *
+ * This eliminates the need for dynamic require() calls and provides
+ * a clean dependency injection pattern.
+ */
+export class RequestHandlerFactory {
+  private dependencies: RequestHandlerDependencies | null = null;
+
+  /**
+   * Initialize the factory with dependencies
+   */
+  initialize(dependencies: RequestHandlerDependencies): void {
+    this.dependencies = dependencies;
+  }
+
+  /**
+   * Get streaming request handler
+   */
+  getStreamingHandler(): StreamingRequestHandler {
+    if (!this.dependencies) {
+      throw new Error('RequestHandlerFactory not initialized. Call initialize() first.');
+    }
+    return this.dependencies.handleStreamingRequest;
+  }
+
+  /**
+   * Get non-streaming request handler
+   */
+  getNonStreamingHandler(): NonStreamingRequestHandler {
+    if (!this.dependencies) {
+      throw new Error('RequestHandlerFactory not initialized. Call initialize() first.');
+    }
+    return this.dependencies.handleNonStreamingRequest;
+  }
+
+  /**
+   * Get embeddings request handler
+   */
+  getEmbeddingsHandler(): EmbeddingsRequestHandler {
+    if (!this.dependencies) {
+      throw new Error('RequestHandlerFactory not initialized. Call initialize() first.');
+    }
+    return this.dependencies.handleEmbeddingsRequest;
+  }
+
+  /**
+   * Route chat request to appropriate handler
+   */
+  routeChatRequest(
+    originalCreate: OpenAIOriginalFunction,
+    params: Omit<OpenAIChatRequest, 'usageMetadata'>,
+    options: OpenAIRequestOptions | undefined,
+    usageMetadata: UsageMetadata | undefined,
+    requestStartTime: number,
+    instance: OpenAIClientInstance
+  ): Promise<unknown> {
+    if (!this.dependencies) {
+      throw new Error('RequestHandlerFactory not initialized. Call initialize() first.');
+    }
+
+    // Pass clean params (without usageMetadata) to handlers
+    // The handlers will receive usageMetadata separately
+    if (params.stream) {
+      return this.dependencies.handleStreamingRequest(
+        originalCreate,
+        params,
+        options,
+        usageMetadata,
+        requestStartTime,
+        instance
+      );
+    } else {
+      return this.dependencies.handleNonStreamingRequest(
+        originalCreate,
+        params,
+        options,
+        usageMetadata,
+        requestStartTime,
+        instance
+      );
+    }
+  }
+
+  /**
+   * Route embeddings request to appropriate handler
+   */
+  routeEmbeddingsRequest(
+    originalCreate: OpenAIOriginalFunction,
+    params: Omit<OpenAIEmbeddingRequest, 'usageMetadata'>,
+    options: OpenAIRequestOptions | undefined,
+    usageMetadata: UsageMetadata | undefined,
+    requestStartTime: number,
+    instance: OpenAIClientInstance
+  ): Promise<unknown> {
+    if (!this.dependencies) {
+      throw new Error('RequestHandlerFactory not initialized. Call initialize() first.');
+    }
+
+    // Pass clean params (without usageMetadata) to handler
+    // The handler will receive usageMetadata separately
+    return this.dependencies.handleEmbeddingsRequest(
+      originalCreate,
+      params,
+      options,
+      usageMetadata,
+      requestStartTime,
+      instance
+    );
+  }
+
+  /**
+   * Route responses request to appropriate handler (new OpenAI Responses API)
+   */
+  routeResponsesRequest(
+    originalCreate: OpenAIResponsesOriginalFunction,
+    params: Omit<OpenAIResponsesRequest, 'usageMetadata'>,
+    options: OpenAIRequestOptions | undefined,
+    usageMetadata: UsageMetadata | undefined,
+    requestStartTime: number,
+    instance: OpenAIClientInstance
+  ): Promise<unknown> {
+    if (!this.dependencies) {
+      throw new Error('RequestHandlerFactory not initialized. Call initialize() first.');
+    }
+
+    // Route to appropriate handler based on streaming
+    if (params.stream) {
+      return this.dependencies.handleResponsesStreamingRequest(
+        originalCreate,
+        params,
+        options,
+        usageMetadata,
+        requestStartTime,
+        instance
+      );
+    } else {
+      return this.dependencies.handleResponsesNonStreamingRequest(
+        originalCreate,
+        params,
+        options,
+        usageMetadata,
+        requestStartTime,
+        instance
+      );
+    }
+  }
+
+  /**
+   * Check if factory is initialized
+   */
+  isInitialized(): boolean {
+    return this.dependencies !== null;
+  }
+}
+
+/**
+ * Global factory instance
+ */
+export const requestHandlerFactory = new RequestHandlerFactory();
+
+/**
+ * Initialize the global factory (called once during module setup)
+ * Uses dynamic import to avoid circular dependencies
+ */
+export async function initializeRequestHandlerFactory(): Promise<void> {
+  // Use dynamic import instead of require for better TypeScript support
+  const handlerModule = await import('../core/wrapper/request-handler.js');
+
+  requestHandlerFactory.initialize({
+    handleStreamingRequest: handlerModule.handleStreamingRequest,
+    handleNonStreamingRequest: handlerModule.handleNonStreamingRequest,
+    handleEmbeddingsRequest: handlerModule.handleEmbeddingsRequest,
+    handleResponsesStreamingRequest: handlerModule.handleResponsesStreamingRequest,
+    handleResponsesNonStreamingRequest: handlerModule.handleResponsesNonStreamingRequest,
+  });
+}
+
+// Promise cache to prevent race conditions during initialization
+let initializationPromise: Promise<void> | null = null;
+
+/**
+ * Utility function to ensure factory is initialized
+ */
+export async function ensureFactoryInitialized(): Promise<void> {
+  if (!requestHandlerFactory.isInitialized()) {
+    if (!initializationPromise) {
+      initializationPromise = initializeRequestHandlerFactoryAsync();
+    }
+    await initializationPromise;
+  }
+}
+
+/**
+ * Async initialization for ES Module compatibility
+ * Uses dynamic import for ES Module compatibility
+ */
+async function initializeRequestHandlerFactoryAsync(): Promise<void> {
+  // Use dynamic import for ES Module compatibility
+  const handlerModule = await import('../core/wrapper/request-handler.js');
+
+  requestHandlerFactory.initialize({
+    handleStreamingRequest: handlerModule.handleStreamingRequest,
+    handleNonStreamingRequest: handlerModule.handleNonStreamingRequest,
+    handleEmbeddingsRequest: handlerModule.handleEmbeddingsRequest,
+    handleResponsesStreamingRequest: handlerModule.handleResponsesStreamingRequest,
+    handleResponsesNonStreamingRequest: handlerModule.handleResponsesNonStreamingRequest,
+  });
+}

package/src/utils/stop-reason-mapper.ts

@@ -0,0 +1,74 @@
+/**
+ * Stop Reason Mapper Utilities
+ *
+ * Centralized stop reason mapping logic using lookup tables
+ * instead of nested conditionals. Based on the good example
+ * from the anthropic-node middleware.
+ */
+
+/**
+ * Stop reason mapping configuration
+ * Maps provider-specific stop reasons to Revenium's standardized set
+ */
+const STOP_REASON_MAP: Record<string, string> = {
+  // OpenAI/Azure OpenAI stop reasons
+  stop: 'END',
+  function_call: 'END_SEQUENCE',
+  tool_calls: 'END_SEQUENCE',
+  timeout: 'TIMEOUT',
+  length: 'TOKEN_LIMIT',
+  max_tokens: 'TOKEN_LIMIT',
+  content_filter: 'ERROR',
+  error: 'ERROR',
+
+  // Anthropic stop reasons (for consistency across middleware)
+  end_turn: 'END',
+  stop_sequence: 'END_SEQUENCE',
+  tool_use: 'END_SEQUENCE',
+};
+
+/**
+ * Default stop reason when mapping fails
+ */
+const DEFAULT_STOP_REASON = 'END';
+
+/**
+ * Map provider stop reasons to Revenium stop reasons
+ *
+ * This replaces the nested if/switch logic with a clean lookup table approach.
+ * Based on the good example from the anthropic-node middleware.
+ *
+ * @param providerStopReason - Stop reason from the AI provider
+ * @param logger - Optional logger for warnings about unknown reasons
+ * @returns Standardized Revenium stop reason
+ */
+export function mapStopReason(
+  providerStopReason: string | null | undefined,
+  logger?: { warn: (message: string, ...args: any[]) => void }
+): string {
+  if (!providerStopReason) return DEFAULT_STOP_REASON;
+  const normalizedReason = providerStopReason.toLowerCase();
+  const mappedReason = STOP_REASON_MAP[normalizedReason];
+
+  if (!mappedReason) {
+    // Log warning for unknown stop reasons to help with future mapping
+    logger?.warn(`Unknown stop reason: ${providerStopReason}, mapping to ${DEFAULT_STOP_REASON}`);
+    return DEFAULT_STOP_REASON;
+  }
+
+  return mappedReason;
+}
+
+/**
+ * Get all supported stop reasons for documentation/testing
+ */
+export function getSupportedStopReasons(): string[] {
+  return Object.keys(STOP_REASON_MAP);
+}
+
+/**
+ * Check if a stop reason is supported
+ */
+export function isStopReasonSupported(reason: string): boolean {
+  return reason.toLowerCase() in STOP_REASON_MAP;
+}