@revenium/openai 1.0.11 → 1.0.12

package/src/core/providers/detector.ts

@@ -0,0 +1,159 @@
+/**
+ * Provider Detection Module
+ *
+ * Handles detection of AI providers (OpenAI vs Azure OpenAI).
+ * Extracted from provider.ts for better organization.
+ */
+
+import { Provider, ProviderInfo, AzureConfig } from '../../types/index.js';
+import { OpenAIClientInstance } from '../../types/function-parameters.js';
+import { isOpenAIClientInstance } from '../../utils/type-guards.js';
+import { createProviderInfo, validateProviderInfo } from '../../utils/provider-detection.js';
+import { getLogger } from '../config/index.js';
+
+// Global logger
+const logger = getLogger();
+
+/**
+ * Detect Azure OpenAI provider from client instance
+ *
+ * @param client - OpenAI or AzureOpenAI client instance
+ * @returns ProviderInfo with detection results
+ */
+export function detectProvider(client: OpenAIClientInstance): ProviderInfo {
+  // Validate client instance
+  if (!isOpenAIClientInstance(client)) {
+    logger.warn('Invalid OpenAI client instance provided to detectProvider');
+    return {
+      provider: Provider.OPENAI,
+      isAzure: false,
+      azureConfig: undefined,
+    };
+  }
+
+  try {
+    // Use strategy pattern for clean provider detection
+    const providerInfo = createProviderInfo(client, logger);
+
+    // Validate the result
+    const validation = validateProviderInfo(providerInfo);
+    if (validation.warnings.length > 0) {
+      logger.warn('Provider detection completed with warnings', {
+        warnings: validation.warnings,
+      });
+    }
+
+    // Log final result
+    if (providerInfo.isAzure) {
+      logger.info('Azure OpenAI provider detected', {
+        provider: providerInfo.provider,
+        hasAzureConfig: !!providerInfo.azureConfig,
+        endpoint: providerInfo.azureConfig?.endpoint ? '[REDACTED]' : undefined,
+      });
+    } else {
+      logger.debug('Standard OpenAI provider detected');
+    }
+
+    return providerInfo;
+  } catch (error) {
+    logger.warn('Error during provider detection, defaulting to OpenAI', {
+      error: error instanceof Error ? error.message : String(error),
+    });
+
+    // Default to OpenAI on any error
+    return {
+      provider: Provider.OPENAI,
+      isAzure: false,
+      azureConfig: undefined,
+    };
+  }
+}
+
+/**
+ * Check if the current environment has Azure configuration
+ * This is a lightweight check for lazy loading decisions
+ *
+ * @returns boolean indicating if Azure config is present
+ */
+export function hasAzureConfig(): boolean {
+  return !!(
+    process.env.AZURE_OPENAI_ENDPOINT ||
+    process.env.AZURE_OPENAI_DEPLOYMENT ||
+    process.env.AZURE_OPENAI_API_KEY
+  );
+}
+
+/**
+ * Validate Azure configuration completeness
+ *
+ * @param config - Azure configuration to validate
+ * @returns validation result with missing fields
+ */
+export function validateAzureConfig(config: AzureConfig): {
+  isValid: boolean;
+  missingFields: string[];
+  warnings: string[];
+} {
+  const missingFields: string[] = [];
+  const warnings: string[] = [];
+
+  // Required fields for basic Azure OpenAI operation
+  if (!config.endpoint) {
+    missingFields.push('endpoint');
+  }
+
+  if (!config.apiKey) {
+    missingFields.push('apiKey');
+  }
+
+  // Optional but recommended fields
+  if (!config.deployment) {
+    warnings.push('deployment name not specified - may need to be included in model parameter');
+  }
+
+  if (!config.apiVersion) {
+    warnings.push('API version not specified - using default 2024-12-01-preview');
+  }
+
+  // Validate endpoint format
+  if (config.endpoint) {
+    try {
+      new URL(config.endpoint);
+      if (!config.endpoint.toLowerCase().includes('azure')) {
+        warnings.push(
+          'endpoint does not contain "azure" - please verify this is an Azure OpenAI endpoint'
+        );
+      }
+    } catch (error) {
+      missingFields.push('valid endpoint URL');
+    }
+  }
+
+  return {
+    isValid: missingFields.length === 0,
+    missingFields,
+    warnings,
+  };
+}
+
+/**
+ * Get provider metadata for Revenium payload
+ *
+ * @param providerInfo - Provider detection result
+ * @returns metadata object for Revenium
+ */
+export function getProviderMetadata(providerInfo: ProviderInfo): {
+  provider: string;
+  modelSource: string;
+} {
+  if (providerInfo.isAzure) {
+    return {
+      provider: 'Azure',
+      modelSource: 'OPENAI',
+    };
+  }
+  return {
+    provider: 'OPENAI',
+    modelSource: 'OPENAI',
+  };
+}

package/src/core/providers/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Providers module - Main exports
+ *
+ * This module provides a clean interface for provider detection and management,
+ * separating concerns into focused sub-modules.
+ */
+
+// Re-export all provider functionality
+export {
+  detectProvider,
+  hasAzureConfig,
+  validateAzureConfig,
+  getProviderMetadata,
+} from './detector.js';
+
+export { gatherAzureConfig } from '../config/azure-config.js';

package/src/core/tracking/api-client.ts

@@ -0,0 +1,78 @@
+/**
+ * Revenium API Client Module
+ *
+ * Handles HTTP communication with the Revenium API.
+ * Extracted from tracking.ts for single responsibility.
+ */
+
+import { ReveniumPayload } from '../../types/index.js';
+import { getConfig, getLogger } from '../config/index.js';
+import { buildReveniumUrl } from '../../utils/url-builder.js';
+
+// Global logger
+const logger = getLogger();
+
+/**
+ * Send payload to Revenium API
+ *
+ * This is the shared HTTP function that eliminates all duplication
+ * between chat completions and embeddings tracking.
+ *
+ * @param payload - The payload to send to Revenium
+ */
+export async function sendToRevenium(payload: ReveniumPayload): Promise<void> {
+  const config = getConfig();
+  if (!config) return logger.warn('Revenium configuration not found, skipping tracking');
+
+  // Use the new URL builder utility instead of nested conditionals
+  const url = buildReveniumUrl(
+    config.reveniumBaseUrl || 'https://api.revenium.io',
+    '/ai/completions'
+  );
+
+  logger.debug('Sending Revenium API request', {
+    url,
+    operationType: payload.operationType,
+    transactionId: payload.transactionId,
+    model: payload.model,
+    totalTokens: payload.totalTokenCount,
+  });
+
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Accept: 'application/json',
+      'x-api-key': config.reveniumApiKey,
+    },
+    body: JSON.stringify(payload),
+  });
+
+  logger.debug('Revenium API response', {
+    status: response.status,
+    statusText: response.statusText,
+    transactionId: payload.transactionId,
+    operationType: payload.operationType,
+  });
+
+  if (!response.ok) {
+    const responseText = await response.text();
+    logger.error('Revenium API error response', {
+      status: response.status,
+      statusText: response.statusText,
+      body: responseText,
+      transactionId: payload.transactionId,
+      operationType: payload.operationType,
+    });
+    throw new Error(
+      `Revenium API error: ${response.status} ${response.statusText} - ${responseText}`
+    );
+  }
+
+  const responseBody = await response.text();
+  logger.debug('Revenium tracking successful', {
+    transactionId: payload.transactionId,
+    operationType: payload.operationType,
+    response: responseBody,
+  });
+}

package/src/core/tracking/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Tracking module - Main exports
+ *
+ * This module provides a clean interface for usage tracking,
+ * separating concerns into focused sub-modules.
+ */
+
+// Re-export all tracking functionality
+export { sendToRevenium } from './api-client.js';
+
+export { buildPayload } from './payload-builder.js';
+
+export {
+  sendReveniumMetrics,
+  sendReveniumEmbeddingsMetrics,
+  trackUsageAsync,
+  trackEmbeddingsUsageAsync,
+} from './usage-tracker.js';
+
+// Export utility functions
+export { mapStopReason } from '../../utils/stop-reason-mapper.js';

package/src/core/tracking/payload-builder.ts

@@ -0,0 +1,132 @@
+/**
+ * Payload Builder Module
+ *
+ * Handles construction of Revenium API payloads.
+ * Extracted from tracking.ts for single responsibility.
+ */
+
+import { randomUUID } from 'crypto';
+import { ReveniumPayload, ProviderInfo } from '../../types/index.js';
+import {
+  OpenAIChatResponse,
+  OpenAIEmbeddingResponse,
+  OpenAIChatRequest,
+  OpenAIEmbeddingRequest,
+} from '../../types/function-parameters.js';
+import { getLogger } from '../config/index.js';
+import { mapStopReason } from '../../utils/stop-reason-mapper.js';
+import { buildMetadataFields } from '../../utils/metadata-builder.js';
+import { resolveAzureModelName } from '../../utils/azure-model-resolver.js';
+import { getProviderMetadata } from '../providers/index.js';
+
+// Global logger
+const logger = getLogger();
+
+/**
+ * Build payload for Revenium API
+ *
+ * This shared payload builder eliminates payload duplication between
+ * chat completions and embeddings. Handles both CHAT and EMBED operation types.
+ *
+ * @param operationType - Type of operation (CHAT or EMBED)
+ * @param response - API response from OpenAI/Azure
+ * @param request - Original request parameters
+ * @param startTime - Request start timestamp
+ * @param duration - Request duration in milliseconds
+ * @param providerInfo - Provider information for Azure support
+ * @returns Constructed payload for Revenium API
+ */
+export function buildPayload(
+  operationType: 'CHAT' | 'EMBED',
+  response: OpenAIChatResponse | OpenAIEmbeddingResponse,
+  request: OpenAIChatRequest | OpenAIEmbeddingRequest,
+  startTime: number,
+  duration: number,
+  providerInfo?: ProviderInfo
+): ReveniumPayload {
+  const now = new Date().toISOString();
+  const requestTime = new Date(startTime).toISOString();
+  const usage = response.usage;
+
+  // Resolve model name for Azure deployments
+  const originalModel = response.model;
+  const resolvedModel = providerInfo?.isAzure
+    ? resolveAzureModelName(originalModel)
+    : originalModel;
+
+  // Get provider metadata
+  const providerMetadata = providerInfo
+    ? getProviderMetadata(providerInfo)
+    : { provider: 'OPENAI', modelSource: 'OPENAI' };
+
+  if (providerInfo?.isAzure && resolvedModel !== originalModel) {
+    logger.debug('Azure model name resolved for pricing', {
+      deployment: originalModel,
+      resolved: resolvedModel,
+      provider: providerMetadata.provider,
+    });
+  }
+
+  // Build metadata fields using utility (eliminates repetitive spreading)
+  const metadataFields = buildMetadataFields(request.usageMetadata);
+
+  // Common fields for all operations
+  const commonPayload = {
+    costType: 'AI' as const,
+    model: resolvedModel, // Use resolved model name for accurate pricing
+    responseTime: now,
+    requestDuration: duration,
+    provider: providerMetadata.provider,
+    modelSource: providerMetadata.modelSource,
+    requestTime,
+    completionStartTime: now,
+
+    // Common token counts
+    inputTokenCount: usage.prompt_tokens,
+    totalTokenCount: usage.total_tokens,
+
+    // Metadata fields (processed by utility)
+    ...metadataFields,
+
+    // Fixed middleware source identifier
+    middlewareSource: 'nodejs',
+
+    // Backend calculates costs
+    inputTokenCost: undefined,
+    outputTokenCost: undefined,
+    totalCost: undefined,
+  };
+
+  // Operation-specific fields
+
+  if (operationType !== 'CHAT') {
+    // For embeddings, we don't need the response cast since we use commonPayload
+    return {
+      ...commonPayload,
+      operationType: 'EMBED',
+      transactionId: `embed-${randomUUID()}`,
+      outputTokenCount: 0,
+      reasoningTokenCount: 0,
+      cacheCreationTokenCount: 0,
+      cacheReadTokenCount: 0,
+      stopReason: 'END',
+      isStreamed: false,
+      timeToFirstToken: 0,
+    };
+  }
+  const chatResponse = response as OpenAIChatResponse;
+  const chatUsage = chatResponse.usage;
+
+  return {
+    ...commonPayload,
+    operationType: 'CHAT',
+    transactionId: chatResponse.id || `chat-${randomUUID()}`,
+    outputTokenCount: chatUsage.completion_tokens || 0,
+    reasoningTokenCount: chatUsage.reasoning_tokens || 0,
+    cacheCreationTokenCount: 0,
+    cacheReadTokenCount: chatUsage.cached_tokens || 0,
+    stopReason: mapStopReason(chatResponse.choices?.[0]?.finish_reason, logger),
+    isStreamed: Boolean((request as OpenAIChatRequest).stream),
+    timeToFirstToken: (request as OpenAIChatRequest).stream ? 0 : duration,
+  };
+}

package/src/core/tracking/usage-tracker.ts

@@ -0,0 +1,189 @@
+/**
+ * Usage Tracker Module
+ *
+ * High-level tracking functions that combine payload building and API communication.
+ * Extracted from tracking.ts for better organization.
+ */
+
+import { randomUUID } from 'crypto';
+import { UsageMetadata, ProviderInfo } from '../../types/index.js';
+import {
+  OpenAIChatResponse,
+  OpenAIEmbeddingResponse,
+  OpenAIChatRequest,
+  OpenAIEmbeddingRequest,
+} from '../../types/function-parameters.js';
+import { getLogger } from '../config/index.js';
+import { sendToRevenium } from './api-client.js';
+import { buildPayload } from './payload-builder.js';
+import { safeAsyncOperation } from '../../utils/error-handler.js';
+
+// Global logger
+const logger = getLogger();
+
+/**
+ * Chat completions tracking - now a thin wrapper with Azure support
+ */
+export async function sendReveniumMetrics(
+  response: OpenAIChatResponse,
+  request: OpenAIChatRequest,
+  startTime: number,
+  duration: number,
+  providerInfo?: ProviderInfo
+): Promise<void> {
+  await safeAsyncOperation(
+    async () => {
+      const payload = buildPayload('CHAT', response, request, startTime, duration, providerInfo);
+      await sendToRevenium(payload);
+    },
+    'Chat completion tracking',
+    {
+      logError: true,
+      rethrow: false, // Don't rethrow to maintain fire-and-forget behavior
+      messagePrefix: 'Chat completion tracking failed: ',
+    },
+    logger
+  );
+}
+
+/**
+ * Embeddings tracking - now a thin wrapper with Azure support
+ */
+export async function sendReveniumEmbeddingsMetrics(
+  response: OpenAIEmbeddingResponse,
+  request: OpenAIEmbeddingRequest,
+  startTime: number,
+  duration: number,
+  providerInfo?: ProviderInfo
+): Promise<void> {
+  await safeAsyncOperation(
+    async () => {
+      const payload = buildPayload('EMBED', response, request, startTime, duration, providerInfo);
+      await sendToRevenium(payload);
+    },
+    'Embeddings tracking',
+    {
+      logError: true,
+      rethrow: false, // Don't rethrow to maintain fire-and-forget behavior
+      messagePrefix: 'Embeddings tracking failed: ',
+    },
+    logger
+  );
+}
+
+/**
+ * Fire-and-forget wrapper for chat completions with Azure support
+ */
+export function trackUsageAsync(trackingData: {
+  requestId: string;
+  model: string;
+  promptTokens: number;
+  completionTokens: number;
+  totalTokens: number;
+  reasoningTokens?: number;
+  cachedTokens?: number;
+  duration: number;
+  finishReason: string | null;
+  usageMetadata?: UsageMetadata;
+  isStreamed?: boolean;
+  timeToFirstToken?: number;
+  providerInfo?: ProviderInfo;
+}): void {
+  const mockResponse = {
+    id: trackingData.requestId,
+    model: trackingData.model,
+    usage: {
+      prompt_tokens: trackingData.promptTokens,
+      completion_tokens: trackingData.completionTokens,
+      total_tokens: trackingData.totalTokens,
+      ...(trackingData.reasoningTokens && { reasoning_tokens: trackingData.reasoningTokens }),
+      ...(trackingData.cachedTokens && { cached_tokens: trackingData.cachedTokens }),
+    },
+    choices: [
+      {
+        finish_reason: trackingData.finishReason,
+      },
+    ],
+  };
+
+  const mockRequest: OpenAIChatRequest = {
+    model: trackingData.model,
+    messages: [], // Mock empty messages array for type compliance
+    usageMetadata: trackingData.usageMetadata,
+    stream: trackingData.isStreamed,
+  };
+
+  const startTime = Date.now() - trackingData.duration;
+
+  sendReveniumMetrics(
+    mockResponse,
+    mockRequest,
+    startTime,
+    trackingData.duration,
+    trackingData.providerInfo
+  )
+    .then(() => {
+      logger.debug('Usage tracking completed successfully', {
+        requestId: trackingData.requestId,
+        model: trackingData.model,
+        totalTokens: trackingData.totalTokens,
+        isStreamed: trackingData.isStreamed,
+      });
+    })
+    .catch(error => {
+      logger.warn('Usage tracking failed', {
+        error: error instanceof Error ? error.message : String(error),
+        requestId: trackingData.requestId,
+        model: trackingData.model,
+      });
+    });
+}
+
+/**
+ * Fire-and-forget wrapper for embeddings with Azure support
+ */
+export function trackEmbeddingsUsageAsync(trackingData: {
+  transactionId: string;
+  model: string;
+  promptTokens: number;
+  totalTokens: number;
+  duration: number;
+  usageMetadata?: UsageMetadata;
+  requestStartTime: number;
+  providerInfo?: ProviderInfo;
+}): void {
+  const mockResponse: OpenAIEmbeddingResponse = {
+    model: trackingData.model,
+    usage: {
+      prompt_tokens: trackingData.promptTokens,
+      total_tokens: trackingData.totalTokens,
+    },
+    data: [], // Mock empty data array for type compliance
+    object: 'list',
+  };
+
+  const mockRequest: OpenAIEmbeddingRequest = {
+    model: trackingData.model,
+    input: '', // Mock empty input for type compliance
+    usageMetadata: trackingData.usageMetadata,
+  };
+
+  sendReveniumEmbeddingsMetrics(
+    mockResponse,
+    mockRequest,
+    trackingData.requestStartTime,
+    trackingData.duration,
+    trackingData.providerInfo
+  )
+    .then(() => {
+      logger.debug('Embeddings tracking completed successfully', {
+        transactionId: trackingData.transactionId,
+      });
+    })
+    .catch(error => {
+      logger.warn('Embeddings tracking failed', {
+        error: error instanceof Error ? error.message : String(error),
+        transactionId: trackingData.transactionId,
+      });
+    });
+}

package/src/core/wrapper/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Wrapper module - Main exports
+ *
+ * This module provides a clean interface for OpenAI client wrapping,
+ * separating concerns into focused sub-modules.
+ */
+
+// Re-export all wrapper functionality
+export { patchOpenAI, patchOpenAIInstance, getProviderInfo } from './instance-patcher.js';