@revenium/openai 1.0.10 → 1.0.12

package/src/types/index.ts

@@ -0,0 +1,313 @@
+/**
+ * Core Types Module
+ *
+ * Central type definitions for the Revenium OpenAI middleware.
+ * This module exports all core types used throughout the application.
+ */
+
+// Re-export function parameter types
+export * from './function-parameters.js';
+
+// Re-export Responses API types
+export * from './responses-api.js';
+
+/**
+ * Credential information for subscriber authentication
+ *
+ * Represents authentication credentials that can be attached to subscriber information
+ * for enhanced security and tracking capabilities.
+ *
+ * @public
+ * @example
+ * ```typescript
+ * const credential: Credential = {
+ *   name: 'api_token',
+ *   value: 'user_token_abc123'
+ * };
+ * ```
+ */
+export interface Credential {
+  /** The name/type of the credential (e.g., 'api_token', 'session_id') */
+  name: string;
+  /** The credential value (should be handled securely) */
+  value: string;
+}
+
+/**
+ * Subscriber information for Revenium API
+ *
+ * Represents end-user information for tracking and billing purposes.
+ * All fields are optional to provide maximum flexibility in implementation.
+ *
+ * @public
+ * @example
+ * ```typescript
+ * const subscriber: Subscriber = {
+ *   id: 'user-12345',
+ *   email: 'john.doe@company.com',
+ *   credential: {
+ *     name: 'session_token',
+ *     value: 'abc123xyz'
+ *   }
+ * };
+ * ```
+ */
+export interface Subscriber {
+  /** Unique identifier for the subscriber/user */
+  id?: string;
+  /** Email address of the subscriber */
+  email?: string;
+  /** Optional authentication credential for the subscriber */
+  credential?: Credential;
+}
+
+/**
+ * Usage metadata interface for tracking additional context
+ *
+ * Comprehensive metadata structure that enables detailed tracking of AI API usage
+ * for analytics, billing, and business intelligence purposes. All fields are optional
+ * to provide maximum flexibility while maintaining consistency across language implementations.
+ *
+ * @public
+ * @example
+ * ```typescript
+ * const metadata: UsageMetadata = {
+ *   subscriber: {
+ *     id: 'user-123',
+ *     email: 'user@company.com'
+ *   },
+ *   organizationId: 'org-456',
+ *   productId: 'chat-assistant',
+ *   taskType: 'customer-support',
+ *   traceId: 'trace-789',
+ *   responseQualityScore: 0.95,
+ *   agent: 'support-bot-v2'
+ * };
+ * ```
+ */
+export interface UsageMetadata {
+  /** User identification information (nested structure for detailed tracking) */
+  subscriber?: Subscriber;
+
+  /** Organization or company identifier for multi-tenant applications */
+  organizationId?: string;
+  /** Product or application identifier for usage segmentation */
+  productId?: string;
+  /** Subscription identifier for billing and plan management */
+  subscriptionId?: string;
+
+  /** Task type classification (e.g., 'chat', 'summarization', 'translation') */
+  taskType?: string;
+  /** Unique task identifier for request correlation */
+  taskId?: string;
+  /** Distributed tracing identifier for request tracking across services */
+  traceId?: string;
+
+  /** Quality score for response evaluation (0.0 to 1.0) */
+  responseQualityScore?: number;
+
+  /** Agent or model variant identifier for A/B testing and performance tracking */
+  agent?: string;
+
+  /** Allow additional custom fields for extensibility */
+  [key: string]: unknown;
+}
+
+/**
+ * Provider information for tracking API source
+ *
+ * Detailed information about the detected AI provider, including configuration
+ * details and Azure-specific settings when applicable. Used internally for
+ * provider-specific handling and metrics collection.
+ *
+ * @public
+ * @example
+ * ```typescript
+ * const providerInfo: ProviderInfo = {
+ *   provider: Provider.AZURE_OPENAI,
+ *   isAzure: true,
+ *   endpoint: 'https://my-resource.openai.azure.com',
+ *   apiVersion: '2024-02-01',
+ *   deployment: 'gpt-4-turbo'
+ * };
+ * ```
+ */
+export interface ProviderInfo {
+  /** The detected AI provider type */
+  provider: Provider;
+  /** Whether this is an Azure OpenAI instance */
+  isAzure: boolean;
+  /** API endpoint URL (for Azure OpenAI) */
+  endpoint?: string;
+  /** API version (for Azure OpenAI) */
+  apiVersion?: string;
+  /** Deployment name (for Azure OpenAI) */
+  deployment?: string;
+  /** Complete Azure configuration when available */
+  azureConfig?: AzureConfig;
+}
+
+/**
+ * Supported AI providers
+ *
+ * Enumeration of AI providers supported by the Revenium middleware.
+ * Used for automatic detection, routing, and provider-specific handling.
+ *
+ * @public
+ * @example
+ * ```typescript
+ * if (providerInfo.provider === Provider.AZURE_OPENAI) {
+ *   console.log('Using Azure OpenAI');
+ * }
+ * ```
+ */
+export enum Provider {
+  /** Standard OpenAI API */
+  OPENAI = 'OPENAI',
+  /** Azure OpenAI Service */
+  AZURE_OPENAI = 'AZURE_OPENAI',
+}
+
+/**
+ * Azure OpenAI configuration
+ *
+ * Configuration interface for Azure OpenAI Service integration.
+ * Provides all necessary settings for connecting to Azure OpenAI endpoints
+ * with proper authentication and resource identification.
+ *
+ * @public
+ * @example
+ * ```typescript
+ * const azureConfig: AzureConfig = {
+ *   endpoint: 'https://my-resource.openai.azure.com',
+ *   apiKey: process.env.AZURE_OPENAI_API_KEY,
+ *   apiVersion: '2024-02-01',
+ *   deployment: 'gpt-4-turbo',
+ *   tenantId: 'your-tenant-id'
+ * };
+ * ```
+ */
+export interface AzureConfig {
+  /** Azure OpenAI endpoint URL */
+  endpoint?: string;
+  /** Azure OpenAI API key */
+  apiKey?: string;
+  /** Azure OpenAI API version */
+  apiVersion?: string;
+  /** Azure OpenAI deployment name */
+  deployment?: string;
+  /** Azure tenant ID for authentication */
+  tenantId?: string;
+  /** Azure resource group name */
+  resourceGroup?: string;
+}
+
+/**
+ * Revenium configuration interface
+ *
+ * Main configuration interface for initializing the Revenium middleware.
+ * Defines all required and optional settings for connecting to Revenium's
+ * metering API and configuring middleware behavior.
+ *
+ * @public
+ * @example
+ * ```typescript
+ * const config: ReveniumConfig = {
+ *   reveniumApiKey: 'hak_your_revenium_api_key',
+ *   reveniumBaseUrl: 'https://api.revenium.io',
+ *   debug: true,
+ *   openaiApiKey: process.env.OPENAI_API_KEY
+ * };
+ * ```
+ */
+export interface ReveniumConfig {
+  /** Revenium API key for authentication (required) */
+  reveniumApiKey: string;
+  /** Revenium API base URL (optional, defaults to https://api.revenium.io) */
+  reveniumBaseUrl?: string;
+  /** Enable debug logging (optional, defaults to false) */
+  debug?: boolean;
+  /** Azure OpenAI configuration (optional, for Azure OpenAI usage) */
+  azure?: AzureConfig;
+  /** OpenAI API key (optional, can be set via environment variable) */
+  openaiApiKey?: string;
+}
+
+/**
+ * Logger interface for consistent logging
+ *
+ * Standardized logging interface that allows custom logger integration
+ * while maintaining consistent log levels and metadata support throughout
+ * the middleware. Supports both structured and string metadata.
+ *
+ * @public
+ * @example
+ * ```typescript
+ * const customLogger: Logger = {
+ *   debug: (msg, meta) => console.debug(`[DEBUG] ${msg}`, meta),
+ *   info: (msg, meta) => console.info(`[INFO] ${msg}`, meta),
+ *   warn: (msg, meta) => console.warn(`[WARN] ${msg}`, meta),
+ *   error: (msg, meta) => console.error(`[ERROR] ${msg}`, meta)
+ * };
+ * ```
+ */
+export interface Logger {
+  /** Log debug-level messages with optional metadata */
+  debug(message: string, meta?: Record<string, unknown> | string): void;
+  /** Log info-level messages with optional metadata */
+  info(message: string, meta?: Record<string, unknown> | string): void;
+  /** Log warning-level messages with optional metadata */
+  warn(message: string, meta?: Record<string, unknown> | string): void;
+  /** Log error-level messages with optional metadata */
+  error(message: string, meta?: Record<string, unknown> | string | unknown): void;
+}
+
+/**
+ * Revenium API payload structure
+ */
+export interface ReveniumPayload {
+  // Core identification
+  transactionId: string;
+  operationType: 'CHAT' | 'EMBED';
+  costType: 'AI';
+
+  // Model and provider info
+  model: string;
+  provider: string;
+  modelSource?: string;
+  middlewareSource: string;
+
+  // Timing information
+  requestTime: string;
+  responseTime: string;
+  requestDuration: number;
+  completionStartTime: string;
+
+  // Token counts
+  inputTokenCount: number;
+  outputTokenCount: number;
+  totalTokenCount: number;
+  reasoningTokenCount: number;
+  cacheCreationTokenCount: number;
+  cacheReadTokenCount: number;
+
+  // Chat-specific fields
+  stopReason: string;
+  isStreamed: boolean;
+  timeToFirstToken?: number;
+
+  // Cost information (calculated by backend)
+  inputTokenCost?: number;
+  outputTokenCost?: number;
+  totalCost?: number;
+
+  // Metadata fields (optional)
+  traceId?: string;
+  taskType?: string;
+  agent?: string;
+  organizationId?: string;
+  productId?: string;
+  subscriber?: Subscriber;
+  subscriptionId?: string;
+  responseQualityScore?: number;
+}

package/src/types/openai-augmentation.ts

@@ -0,0 +1,233 @@
+/**
+ * TypeScript module augmentation for OpenAI SDK
+ *
+ * This file extends OpenAI's existing types to include the usageMetadata field
+ * through TypeScript's declaration merging feature. This provides seamless
+ * integration with the OpenAI SDK, allowing developers to use usageMetadata
+ * directly in OpenAI API calls without type casting or additional imports.
+ *
+ * The augmentation covers all major OpenAI API endpoints including:
+ * - Chat completions (streaming and non-streaming)
+ * - Embeddings
+ * - Future API endpoints as they become available
+ *
+ * @fileoverview OpenAI SDK type augmentation for Revenium middleware
+ * @author Revenium
+ * @since 1.0.0
+ *
+ * @example Basic usage with chat completions
+ * ```typescript
+ * import '@revenium/openai';
+ * import OpenAI from 'openai';
+ *
+ * const openai = new OpenAI();
+ *
+ * const response = await openai.chat.completions.create({
+ *   model: 'gpt-4o-mini',
+ *   messages: [{ role: 'user', content: 'Hello!' }],
+ *   usageMetadata: {  // TypeScript recognizes this natively
+ *     subscriber: {
+ *       id: 'user-123',
+ *       email: 'user@my-company.com'
+ *     },
+ *     organizationId: 'my-company',
+ *     productId: 'chat-app',
+ *     taskType: 'customer-support'
+ *   }
+ * });
+ * ```
+ *
+ * @example Usage with embeddings
+ * ```typescript
+ * const embedding = await openai.embeddings.create({
+ *   model: 'text-embedding-ada-002',
+ *   input: 'Text to embed',
+ *   usageMetadata: {
+ *     subscriber: { id: 'user-456' },
+ *     productId: 'search-engine',
+ *     taskType: 'document-indexing'
+ *   }
+ * });
+ * ```
+ */
+
+import { UsageMetadata } from './index.js';
+
+// Export something to make this a module (required for TypeScript compilation)
+export {};
+
+/**
+ * OpenAI Chat Completions API augmentation
+ *
+ * Extends the OpenAI chat completions interfaces to include usageMetadata
+ * for all completion types (base, streaming, and non-streaming).
+ */
+declare module 'openai/resources/chat/completions/completions' {
+  interface ChatCompletionCreateParamsBase {
+    /**
+     * Optional metadata for enhanced tracking and analytics.
+     *
+     * Provides rich context for business analytics, user tracking, and billing purposes.
+     * All fields are optional to maintain backward compatibility and provide maximum flexibility.
+     *
+     * This metadata is automatically captured by the Revenium middleware and sent to
+     * the Revenium API for detailed usage analytics and billing calculations.
+     *
+     * @since 1.0.0
+     * @example Basic user tracking
+     * ```typescript
+     * usageMetadata: {
+     *   subscriber: {
+     *     id: 'user-123',
+     *     email: 'user@my-company.com'
+     *   },
+     *   organizationId: 'my-company',
+     *   productId: 'support-app'
+     * }
+     * ```
+     *
+     * @example Advanced tracking with quality metrics
+     * ```typescript
+     * usageMetadata: {
+     *   subscriber: { id: 'user-456' },
+     *   organizationId: 'enterprise-corp',
+     *   productId: 'ai-assistant',
+     *   taskType: 'customer-support',
+     *   traceId: 'session-abc-123',
+     *   responseQualityScore: 0.95,
+     *   agent: 'support-bot-v2'
+     * }
+     * ```
+     */
+    usageMetadata?: UsageMetadata;
+  }
+
+  interface ChatCompletionCreateParamsNonStreaming {
+    /**
+     * Optional metadata for enhanced tracking and analytics.
+     *
+     * Provides rich context for business analytics, user tracking, and billing purposes.
+     * Specifically for non-streaming chat completions where the full response is returned at once.
+     *
+     * @see {@link UsageMetadata} for detailed field descriptions
+     */
+    usageMetadata?: UsageMetadata;
+  }
+
+  interface ChatCompletionCreateParamsStreaming {
+    /**
+     * Optional metadata for enhanced tracking and analytics.
+     *
+     * Provides rich context for business analytics, user tracking, and billing purposes.
+     * Specifically for streaming chat completions where the response is delivered incrementally.
+     *
+     * @see {@link UsageMetadata} for detailed field descriptions
+     */
+    usageMetadata?: UsageMetadata;
+  }
+}
+
+/**
+ * OpenAI Embeddings API augmentation
+ *
+ * Extends the OpenAI embeddings interface to include usageMetadata
+ * for comprehensive tracking of embedding generation requests.
+ */
+declare module 'openai/resources/embeddings' {
+  interface EmbeddingCreateParams {
+    /**
+     * Optional metadata for enhanced tracking and analytics.
+     *
+     * Provides rich context for business analytics, user tracking, and billing purposes
+     * specifically for embedding generation requests. Particularly useful for tracking
+     * vector database operations, search functionality, and document processing workflows.
+     *
+     * All fields are optional to maintain backward compatibility and provide maximum flexibility.
+     *
+     * @since 1.0.0
+     * @example Document indexing workflow
+     * ```typescript
+     * usageMetadata: {
+     *   subscriber: {
+     *     id: 'user-123',
+     *     email: 'user@my-company.com'
+     *   },
+     *   organizationId: 'my-company',
+     *   productId: 'vector-search',
+     *   taskType: 'document-indexing',
+     *   taskId: 'batch-index-2024-01'
+     * }
+     * ```
+     *
+     * @example Semantic search application
+     * ```typescript
+     * usageMetadata: {
+     *   subscriber: { id: 'user-456' },
+     *   organizationId: 'enterprise-corp',
+     *   productId: 'knowledge-base',
+     *   taskType: 'semantic-search',
+     *   traceId: 'search-session-789'
+     * }
+     * ```
+     *
+     * @see {@link UsageMetadata} for detailed field descriptions
+     */
+    usageMetadata?: UsageMetadata;
+  }
+}
+
+/**
+ * OpenAI Responses API augmentation
+ *
+ * Extends the new Responses API to support usageMetadata for comprehensive tracking.
+ * The Responses API is OpenAI's new unified interface for agent-like applications.
+ */
+declare module 'openai' {
+  namespace Responses {
+    interface ResponseCreateParams {
+      /**
+       * Custom usage metadata for Revenium tracking
+       *
+       * Enables comprehensive tracking and analytics for Responses API calls.
+       * All fields are optional and can be customized based on your application needs.
+       *
+       * @example Basic Responses API usage with metadata
+       * ```typescript
+       * const response = await openai.responses.create({
+       *   model: 'gpt-4.1',
+       *   input: 'Analyze this data and provide insights',
+       *   usageMetadata: {
+       *     subscriber: {
+       *       id: 'analyst-123',
+       *       email: 'analyst@company.com'
+       *     },
+       *     organizationId: 'data-corp',
+       *     productId: 'analytics-platform',
+       *     taskType: 'data-analysis',
+       *     agent: 'responses-api-v1'
+       *   }
+       * });
+       * ```
+       *
+       * @example Streaming Responses API with metadata
+       * ```typescript
+       * const stream = await openai.responses.create({
+       *   model: 'gpt-4.1',
+       *   input: [
+       *     { role: 'user', content: 'Generate a detailed report' }
+       *   ],
+       *   stream: true,
+       *   usageMetadata: {
+       *     subscriber: { id: 'user-456' },
+       *     taskType: 'report-generation',
+       *     traceId: 'session-789'
+       *   }
+       * });
+       * ```
+       *
+       * @see {@link UsageMetadata} for detailed field descriptions
+       */
+      usageMetadata?: UsageMetadata;
+    }
+  }
+}