@revenium/openai 1.0.11 → 1.0.12

package/src/core/wrapper/stream-wrapper.ts

@@ -0,0 +1,100 @@
+/**
+ * Stream Wrapper Module
+ *
+ * Handles wrapping of streaming responses for usage tracking.
+ * Extracted from wrapper.ts for better organization.
+ */
+
+import { UsageMetadata } from '../../types/index.js';
+import {
+  OpenAIClientInstance,
+  StreamChunk,
+  ExtendedUsage,
+} from '../../types/function-parameters.js';
+import { isStreamChunk } from '../../utils/type-guards.js';
+import { trackUsageAsync } from '../tracking/index.js';
+import { getLogger } from '../config/index.js';
+import { instanceProviders } from './instance-patcher.js';
+
+// Global logger
+const logger = getLogger();
+
+/**
+ * Create a simple stream wrapper that tracks usage when complete
+ */
+export function createTrackingStreamWrapper(
+  originalStream: AsyncIterable<unknown>,
+  usageMetadata: UsageMetadata | undefined,
+  requestStartTime: number,
+  instance: OpenAIClientInstance
+): AsyncIterable<unknown> {
+  // For streaming, we need to collect the final response data
+  let accumulatedResponse: StreamChunk | null = null;
+
+  // Create async iterator
+  const wrappedIterator = {
+    async *[Symbol.asyncIterator]() {
+      try {
+        for await (const chunk of originalStream) {
+          // Validate and accumulate response data for tracking
+          if (isStreamChunk(chunk)) {
+            if (!accumulatedResponse) {
+              accumulatedResponse = {
+                id: chunk.id,
+                model: chunk.model,
+                usage: { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 },
+              };
+            }
+
+            // Update usage if available in chunk
+            if (chunk.usage) {
+              accumulatedResponse.usage = chunk.usage;
+            }
+          }
+
+          // Forward the chunk to the client
+          yield chunk;
+        }
+
+        // Stream completed - track usage
+        if (accumulatedResponse && accumulatedResponse.usage) {
+          const duration = Date.now() - requestStartTime;
+
+          // Get provider info for this instance
+          const providerInfo = instanceProviders.get(instance);
+
+          // Safely access extended usage fields
+          const usage = accumulatedResponse.usage as ExtendedUsage;
+
+          trackUsageAsync({
+            requestId: accumulatedResponse.id,
+            model: accumulatedResponse.model,
+            promptTokens: usage.prompt_tokens,
+            completionTokens: usage.completion_tokens || 0,
+            totalTokens: usage.total_tokens,
+            reasoningTokens: usage.reasoning_tokens,
+            cachedTokens: usage.cached_tokens,
+            duration,
+            finishReason: null, // Will be determined from final chunk
+            usageMetadata,
+            isStreamed: true,
+            providerInfo,
+          });
+
+          logger.debug('Chat completion streaming completed', {
+            model: accumulatedResponse.model,
+            duration,
+            totalTokens: accumulatedResponse.usage.total_tokens,
+          });
+        }
+      } catch (error) {
+        logger.error('Chat completion streaming error', {
+          error: error instanceof Error ? error.message : String(error),
+        });
+        throw error;
+      }
+    },
+  };
+
+  return wrappedIterator;
+}

package/src/index.ts

@@ -0,0 +1,336 @@
+/**
+ * Revenium OpenAI Middleware for TypeScript
+ *
+ * This middleware tracks OpenAI usage and sends metrics to Revenium.
+ * Uses hybrid initialization: auto-initializes on import with graceful fallback to manual init.
+ *
+ * Environment Variables:
+ * REVENIUM_METERING_API_KEY=hak_your_api_key
+ * REVENIUM_METERING_BASE_URL=https://api.revenium.io (optional)
+ * OPENAI_API_KEY=sk_your_openai_key
+ *
+ * Simple Usage (auto-initialization):
+ * import { patchOpenAIInstance } from '@revenium/openai';
+ * import OpenAI from 'openai';
+ *
+ * const openai = patchOpenAIInstance(new OpenAI());
+ * // Auto-initializes from environment variables
+ *
+ * Advanced Usage (explicit initialization):
+ * import { initializeReveniumFromEnv, patchOpenAIInstance } from '@revenium/openai';
+ * import OpenAI from 'openai';
+ *
+ * const result = initializeReveniumFromEnv();
+ * if (!result.success) {
+ *   throw new Error(result.message);
+ * }
+ * const openai = patchOpenAIInstance(new OpenAI());
+ *
+ * const response = await openai.chat.completions.create({
+ *   model: 'gpt-4',
+ *   messages: [{ role: 'user', content: 'Hello!' }],
+ *   usageMetadata: {
+ *     subscriber: {
+ *       id: 'user-123',
+ *       email: 'user@my-org.com'
+ *     },
+ *     organizationId: 'my-org',
+ *     productId: 'my-app'
+ *   }
+ * });
+ */
+
+// Import type augmentations to extend OpenAI types with usageMetadata
+import './types/openai-augmentation.js';
+
+// Import from new modular structure
+import {
+  setConfig,
+  validateConfig,
+  initializeConfig,
+  getConfig,
+  getLogger,
+} from './core/config/index.js';
+import { patchOpenAI, patchOpenAIInstance } from './core/wrapper/index.js';
+import type { ReveniumConfig } from './types/index.js';
+
+// Track initialization state
+let isInitialized = false;
+let autoInitAttempted = false;
+
+/**
+ * Core types for TypeScript developers using Revenium middleware
+ *
+ * These types provide comprehensive TypeScript support for the Revenium OpenAI middleware,
+ * enabling type-safe configuration, usage tracking, and integration with OpenAI APIs.
+ *
+ * @public
+ */
+export type {
+  /**
+   * Configuration interface for Revenium middleware initialization
+   *
+   * Defines all required and optional settings for connecting to Revenium's
+   * metering API and configuring middleware behavior.
+   *
+   * @example
+   * ```typescript
+   * const config: ReveniumConfig = {
+   *   reveniumApiKey: 'hak_your_api_key',
+   *   reveniumBaseUrl: 'https://api.revenium.io',
+   *   debug: true
+   * };
+   * ```
+   */
+  ReveniumConfig,
+
+  /**
+   * Usage metadata structure for tracking AI API calls
+   *
+   * Comprehensive metadata interface that allows tracking of user context,
+   * business information, and custom fields for detailed analytics and billing.
+   * All fields are optional to provide maximum flexibility.
+   *
+   * @example
+   * ```typescript
+   * const metadata: UsageMetadata = {
+   *   subscriber: { id: 'user-123', email: 'user@company.com' },
+   *   organizationId: 'company-456',
+   *   productId: 'chat-app',
+   *   taskType: 'customer-support'
+   * };
+   * ```
+   */
+  UsageMetadata,
+
+  /**
+   * Logger interface for custom logging implementations
+   *
+   * Standardized logging interface that allows custom logger integration
+   * while maintaining consistent log levels and metadata support.
+   *
+   * @example
+   * ```typescript
+   * const customLogger: Logger = {
+   *   debug: (msg, meta) => console.debug(msg, meta),
+   *   info: (msg, meta) => console.info(msg, meta),
+   *   warn: (msg, meta) => console.warn(msg, meta),
+   *   error: (msg, meta) => console.error(msg, meta)
+   * };
+   * ```
+   */
+  Logger,
+
+  /**
+   * Azure OpenAI configuration interface
+   *
+   * Specific configuration options for Azure OpenAI integration,
+   * including endpoint, API version, and deployment settings.
+   *
+   * @example
+   * ```typescript
+   * const azureConfig: AzureConfig = {
+   *   endpoint: 'https://your-resource.openai.azure.com',
+   *   apiVersion: '2024-02-01',
+   *   deployment: 'gpt-4'
+   * };
+   * ```
+   */
+  AzureConfig,
+
+  /**
+   * AI provider enumeration
+   *
+   * Supported AI providers for automatic detection and routing.
+   * Used internally for provider-specific handling and metrics.
+   */
+  Provider,
+
+  /**
+   * Provider information structure
+   *
+   * Detailed information about the detected AI provider, including
+   * configuration details and Azure-specific settings when applicable.
+   *
+   * @example
+   * ```typescript
+   * const providerInfo: ProviderInfo = {
+   *   provider: Provider.AZURE_OPENAI,
+   *   isAzure: true,
+   *   endpoint: 'https://your-resource.openai.azure.com',
+   *   deployment: 'gpt-4'
+   * };
+   * ```
+   */
+  ProviderInfo,
+} from './types';
+
+// Note: ExtendedChatCompletionCreateParams and ExtendedEmbeddingCreateParams are no longer exported
+// as they have been replaced with seamless TypeScript module augmentation. The usageMetadata field
+// is now natively available on OpenAI's types without requiring additional imports.
+
+// Export tracking functions
+export { trackUsageAsync, trackEmbeddingsUsageAsync } from './core/tracking/index.js';
+
+// Export provider detection functions
+export {
+  detectProvider,
+  hasAzureConfig,
+  validateAzureConfig,
+  getProviderMetadata,
+} from './core/providers/index.js';
+export { getProviderInfo } from './core/wrapper/index.js';
+
+// Export Azure model resolution functions
+export {
+  resolveAzureModelName,
+  clearModelNameCache,
+  getModelNameCacheStats,
+  batchResolveModelNames,
+  wouldTransformDeploymentName,
+} from './utils/azure-model-resolver.js';
+
+// Global logger
+const logger = getLogger();
+
+/**
+ * Initialize Revenium middleware with configuration
+ */
+export function initializeRevenium(config: ReveniumConfig): {
+  success: boolean;
+  message: string;
+} {
+  // Check if already initialized to prevent duplicate initialization
+  if (isInitialized) {
+    return {
+      success: true,
+      message: 'Revenium middleware already initialized',
+    };
+  }
+
+  try {
+    // Apply default base URL if not provided
+    const configWithDefaults = {
+      ...config,
+      reveniumBaseUrl: config.reveniumBaseUrl || 'https://api.revenium.io',
+    };
+
+    validateConfig(configWithDefaults);
+    setConfig(configWithDefaults);
+
+    // Mark as initialized
+    isInitialized = true;
+
+    // Patch OpenAI prototype methods
+    patchOpenAI();
+
+    return {
+      success: true,
+      message: 'Revenium middleware initialized successfully',
+    };
+  } catch (error) {
+    isInitialized = false;
+    return {
+      success: false,
+      message: error instanceof Error ? error.message : 'Unknown initialization error',
+    };
+  }
+}
+
+/**
+ * Initialize Revenium middleware from environment variables
+ */
+export function initializeReveniumFromEnv(): {
+  success: boolean;
+  message: string;
+} {
+  // Check if already initialized to prevent duplicate initialization
+  if (isInitialized) {
+    return {
+      success: true,
+      message: 'Revenium middleware already initialized',
+    };
+  }
+
+  const envSuccess = initializeConfig();
+
+  if (!envSuccess) {
+    isInitialized = false;
+    return {
+      success: false,
+      message:
+        'Failed to load configuration from environment variables. Check REVENIUM_METERING_API_KEY and REVENIUM_METERING_BASE_URL.',
+    };
+  }
+
+  // Mark as initialized
+  isInitialized = true;
+
+  // Patch OpenAI prototype methods
+  patchOpenAI();
+
+  return {
+    success: true,
+    message: 'Revenium middleware initialized from environment',
+  };
+}
+
+/**
+ * Manually patch an OpenAI instance (for advanced use cases)
+ */
+export { patchOpenAIInstance } from './core/wrapper/index.js';
+
+/**
+ * Auto-initialization with graceful fallback
+ * Attempts to initialize from environment variables on module load.
+ * If it fails, logs a debug message but doesn't throw - allows manual configuration later.
+ */
+function attemptAutoInitialization(): void {
+  if (autoInitAttempted || isInitialized) return;
+
+  autoInitAttempted = true;
+  try {
+    const result = initializeReveniumFromEnv();
+    if (result.success) {
+      // Auto-init succeeded - log debug message
+      logger.debug('Revenium middleware auto-initialized from environment variables');
+    } else {
+      // Auto-init failed - log debug message but don't throw
+      logger.debug('Auto-initialization failed, manual initialization required:', result.message);
+    }
+  } catch (error) {
+    // Unexpected error during auto-init - log but don't throw
+    logger.debug(
+      'Auto-initialization encountered error:',
+      error instanceof Error ? error.message : String(error)
+    );
+  }
+}
+
+/**
+ * Check if middleware has been initialized
+ */
+export function isReveniumInitialized(): boolean {
+  return isInitialized;
+}
+
+/**
+ * Get detailed initialization status
+ */
+export function getInitializationStatus(): {
+  initialized: boolean;
+  hasConfig: boolean;
+  hasApiKey: boolean;
+  autoInitAttempted: boolean;
+} {
+  const config = getConfig();
+  return {
+    initialized: isInitialized,
+    hasConfig: !!config,
+    hasApiKey: !!config?.reveniumApiKey,
+    autoInitAttempted,
+  };
+}
+
+// Perform auto-initialization when module is imported
+attemptAutoInitialization();

package/src/types/function-parameters.ts

@@ -0,0 +1,251 @@
+/**
+ * Function Parameter Types
+ *
+ * Comprehensive type definitions for function parameters throughout the middleware.
+ * These interfaces provide type safety by replacing 'any' types with proper,
+ * well-documented interfaces that match OpenAI API structures and internal requirements.
+ *
+ * @fileoverview Type-safe function parameter definitions
+ * @author Revenium
+ * @since 1.0.0
+ */
+
+import { UsageMetadata, ProviderInfo } from './index';
+import { OpenAIResponsesRequest } from './responses-api';
+
+/**
+ * OpenAI API response structure for chat completions
+ *
+ * Represents the complete response structure returned by OpenAI's chat completions API.
+ * Includes usage statistics, response choices, and metadata. Used internally for
+ * processing responses and extracting usage metrics.
+ *
+ * @public
+ * @example
+ * ```typescript
+ * const response: OpenAIChatResponse = {
+ *   id: 'chatcmpl-123',
+ *   model: 'gpt-4o-mini',
+ *   usage: {
+ *     prompt_tokens: 10,
+ *     completion_tokens: 20,
+ *     total_tokens: 30
+ *   },
+ *   choices: [{
+ *     finish_reason: 'stop',
+ *     message: {
+ *       content: 'Hello! How can I help you?',
+ *       role: 'assistant'
+ *     }
+ *   }]
+ * };
+ * ```
+ */
+export interface OpenAIChatResponse {
+  /** Unique identifier for the chat completion */
+  id: string;
+  /** Model used for the completion */
+  model: string;
+  /** Token usage statistics */
+  usage: {
+    /** Number of tokens in the prompt */
+    prompt_tokens: number;
+    /** Number of tokens in the completion */
+    completion_tokens: number;
+    /** Total tokens used (prompt + completion) */
+    total_tokens: number;
+    /** Number of reasoning tokens (for reasoning models) */
+    reasoning_tokens?: number;
+    /** Number of cached tokens used */
+    cached_tokens?: number;
+  };
+  /** Array of completion choices */
+  choices: Array<{
+    /** Reason why the completion finished */
+    finish_reason: string | null;
+    /** Complete message (for non-streaming responses) */
+    message?: {
+      /** Message content */
+      content: string;
+      /** Message role (assistant, user, system) */
+      role: string;
+    };
+    /** Delta message (for streaming responses) */
+    delta?: {
+      /** Incremental content */
+      content?: string;
+      /** Message role */
+      role?: string;
+    };
+  }>;
+  /** Unix timestamp of when the completion was created */
+  created?: number;
+  /** Object type identifier */
+  object?: string;
+}
+
+/**
+ * OpenAI API response structure for embeddings
+ */
+export interface OpenAIEmbeddingResponse {
+  model: string;
+  usage: {
+    prompt_tokens: number;
+    total_tokens: number;
+  };
+  data: Array<{
+    embedding: number[];
+    index: number;
+    object: string;
+  }>;
+  object: string;
+}
+
+/**
+ * OpenAI chat completion request parameters
+ */
+export interface OpenAIChatRequest {
+  model: string;
+  messages: Array<{
+    role: string;
+    content: string;
+  }>;
+  stream?: boolean;
+  usageMetadata?: UsageMetadata;
+  max_tokens?: number;
+  temperature?: number;
+  top_p?: number;
+  frequency_penalty?: number;
+  presence_penalty?: number;
+  stop?: string | string[];
+  [key: string]: unknown;
+}
+
+/**
+ * OpenAI embeddings request parameters
+ */
+export interface OpenAIEmbeddingRequest {
+  model: string;
+  input: string | string[];
+  usageMetadata?: UsageMetadata;
+  encoding_format?: string;
+  dimensions?: number;
+  user?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * OpenAI client instance interface
+ */
+export interface OpenAIClientInstance {
+  baseURL?: string | URL;
+  constructor?: {
+    name: string;
+  };
+  chat?: {
+    completions?: {
+      create: any;
+    };
+  };
+  embeddings?: {
+    create: any;
+  };
+  // Allow additional properties for flexibility with proper typing
+  [key: string]: unknown;
+}
+
+/**
+ * OpenAI request options
+ */
+export interface OpenAIRequestOptions {
+  headers?: Record<string, string>;
+  timeout?: number;
+  signal?: AbortSignal;
+  [key: string]: unknown;
+}
+
+/**
+ * Azure model resolver function parameters
+ */
+export interface AzureModelResolverParams {
+  deploymentName: string;
+  useCache?: boolean;
+}
+
+/**
+ * Provider detection function parameters
+ */
+export interface ProviderDetectionParams {
+  client: OpenAIClientInstance;
+}
+
+/**
+ * Azure configuration validation result
+ */
+export interface AzureConfigValidationResult {
+  isValid: boolean;
+  missingFields: string[];
+  warnings: string[];
+}
+
+/**
+ * Lazy loading function type for Azure modules
+ */
+export interface LazyLoadedModule {
+  [key: string]: any;
+}
+
+/**
+ * Console logger arguments type
+ */
+export type LoggerArgs = unknown[];
+
+/**
+ * Generic function type for original OpenAI methods
+ */
+export type OpenAIOriginalFunction = (
+  params: OpenAIChatRequest | OpenAIEmbeddingRequest,
+  options?: OpenAIRequestOptions
+) => Promise<OpenAIChatResponse | OpenAIEmbeddingResponse>;
+
+/**
+ * Function type for original OpenAI Responses API methods
+ */
+export type OpenAIResponsesOriginalFunction = (
+  params: OpenAIResponsesRequest,
+  options?: OpenAIRequestOptions
+) => Promise<unknown>;
+
+/**
+ * Stream chunk interface for streaming responses
+ */
+export interface StreamChunk {
+  id: string;
+  model: string;
+  usage?: {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    reasoning_tokens?: number;
+    cached_tokens?: number;
+  };
+  choices?: Array<{
+    delta?: {
+      content?: string;
+      role?: string;
+    };
+    finish_reason?: string | null;
+  }>;
+  [key: string]: unknown;
+}
+
+/**
+ * Extended usage interface that includes optional reasoning and cached tokens
+ */
+export interface ExtendedUsage {
+  prompt_tokens: number;
+  completion_tokens: number;
+  total_tokens: number;
+  reasoning_tokens?: number;
+  cached_tokens?: number;
+}