@revenium/openai 1.0.12 → 1.0.14

package/src/index.ts

@@ -1,336 +0,0 @@
-/**
- * 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

@@ -1,251 +0,0 @@
-/**
- * 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;
-}