@revenium/openai 1.0.13 → 1.0.15

package/src/types/index.ts

@@ -1,310 +0,0 @@
-/**
- * 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,  // 0.0-1.0 scale per API spec
- *   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;
-  /** Distributed tracing identifier for request tracking across services */
-  traceId?: string;
-
-  /** Quality score for response evaluation (0.0-1.0 scale per API spec) */
-  responseQualityScore?: number;
-
-  /** Agent or model variant identifier for A/B testing and performance tracking */
-  agent?: string;
-}
-
-/**
- * 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.ai',
- *   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.ai) */
-  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' | 'GENERATE' | 'EMBED' | 'CLASSIFY' | 'SUMMARIZE' | 'TRANSLATE' | 'OTHER';
-  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;
-  // API Spec: https://revenium.readme.io/reference/meter_ai_completion
-  // "Leave null for models without reasoning capabilities" - NOT in required fields
-  reasoningTokenCount: number | undefined;
-  cacheCreationTokenCount: number | undefined;  // Undefined when provider doesn't report
-  cacheReadTokenCount: number | undefined;      // Undefined when provider doesn't report
-
-  // Chat-specific fields
-  stopReason: string;
-  isStreamed: boolean;
-  timeToFirstToken?: number | undefined;  // Undefined when not tracking TTFB
-
-  // 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

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