@revenium/openai 1.0.13 → 1.0.14

package/src/utils/error-handler.ts

@@ -1,251 +0,0 @@
-/**
- * Error Handler Utilities
- *
- * Centralized error handling patterns to eliminate repetitive try/catch blocks
- * and provide consistent error logging and recovery strategies.
- */
-
-import { Logger } from '../types/index.js';
-import { ERROR_MESSAGE_PATTERNS_TYPE_CONFIG, MESSAGE_PATTERNS_TYPE_NETWORK } from './constants.js';
-
-/**
- * Error handling strategy configuration
- */
-export interface ErrorHandlingStrategy {
-  /** Whether to log the error */
-  logError?: boolean;
-  /** Whether to re-throw the error */
-  rethrow?: boolean;
-  /** Custom error message prefix */
-  messagePrefix?: string;
-  /** Fallback value to return on error */
-  fallbackValue?: unknown;
-  /** Custom error transformation function */
-  transformError?: (error: unknown) => Error;
-}
-
-/**
- * Default error handling strategy
- */
-const DEFAULT_STRATEGY: Required<ErrorHandlingStrategy> = {
-  logError: true,
-  rethrow: true,
-  messagePrefix: '',
-  fallbackValue: undefined,
-  transformError: (error: unknown) => (error instanceof Error ? error : new Error(String(error))),
-};
-
-/**
- * Safe async operation wrapper with comprehensive error handling
- *
- * @param operation - The async operation to execute
- * @param context - Context information for logging
- * @param strategy - Error handling strategy
- * @param logger - Logger instance
- * @returns Promise with result or fallback value
- */
-export async function safeAsyncOperation<T>(
-  operation: () => Promise<T>,
-  context: string,
-  strategy: ErrorHandlingStrategy = {},
-  logger?: Logger
-): Promise<T | undefined> {
-  const config = { ...DEFAULT_STRATEGY, ...strategy };
-
-  try {
-    return await operation();
-  } catch (error) {
-    const transformedError = config.transformError(error);
-
-    if (config.logError && logger) {
-      logger.error(`${config.messagePrefix}${context}`, {
-        error: transformedError.message,
-        stack: transformedError.stack,
-      });
-    }
-
-    if (config.rethrow) throw transformedError;
-    return config.fallbackValue as T | undefined;
-  }
-}
-
-/**
- * Safe sync operation wrapper
- *
- * @param operation - The sync operation to execute
- * @param context - Context information for logging
- * @param strategy - Error handling strategy
- * @param logger - Logger instance
- * @returns Result or fallback value
- */
-export function safeSyncOperation<T>(
-  operation: () => T,
-  context: string,
-  strategy: ErrorHandlingStrategy = {},
-  logger?: Logger
-): T | undefined {
-  const config = { ...DEFAULT_STRATEGY, ...strategy };
-
-  try {
-    return operation();
-  } catch (error) {
-    const transformedError = config.transformError(error);
-
-    if (config.logError && logger) {
-      logger.error(`${config.messagePrefix}${context}`, {
-        error: transformedError.message,
-        stack: transformedError.stack,
-      });
-    }
-
-    if (config.rethrow) throw transformedError;
-    return config.fallbackValue as T | undefined;
-  }
-}
-
-/**
- * Validation wrapper that provides clear error messages
- *
- * @param value - Value to validate
- * @param validator - Validation function
- * @param errorMessage - Error message if validation fails
- * @returns Validated value
- */
-export function validateOrThrow<T>(
-  value: unknown,
-  validator: (value: unknown) => value is T,
-  errorMessage: string
-): T {
-  if (!validator(value)) throw new Error(errorMessage);
-  return value;
-}
-
-/**
- * Validation wrapper that returns undefined on failure
- *
- * @param value - Value to validate
- * @param validator - Validation function
- * @param logger - Optional logger for warnings
- * @param context - Context for logging
- * @returns Validated value or undefined
- */
-export function validateOrUndefined<T>(
-  value: unknown,
-  validator: (value: unknown) => value is T,
-  logger?: Logger,
-  context?: string
-): T | undefined {
-  if (!validator(value)) {
-    if (logger && context) {
-      logger.warn(`Validation failed: ${context}`, { value });
-    }
-    return;
-  }
-  return value;
-}
-
-/**
- * Create a retry wrapper for operations that might fail temporarily
- *
- * @param operation - Operation to retry
- * @param maxRetries - Maximum number of retries
- * @param delayMs - Delay between retries in milliseconds
- * @param logger - Logger for retry attempts
- * @returns Promise with operation result
- */
-export async function withRetry<T>(
-  operation: () => Promise<T>,
-  maxRetries: number = 3,
-  delayMs: number = 1000,
-  logger?: Logger
-): Promise<T> {
-  let lastError: Error;
-  for (let attempt = 1; attempt <= maxRetries; attempt++) {
-    try {
-      return await operation();
-    } catch (error) {
-      lastError = error instanceof Error ? error : new Error(String(error));
-
-      if (attempt === maxRetries) {
-        break;
-      }
-
-      if (logger) {
-        logger.warn(`Operation failed, retrying (${attempt}/${maxRetries})`, {
-          error: lastError.message,
-          nextRetryIn: delayMs,
-        });
-      }
-      await new Promise(resolve => setTimeout(resolve, delayMs));
-    }
-  }
-
-  // eslint-disable-next-line no-throw-literal
-  throw lastError!;
-}
-
-/**
- * Common error types for better error handling
- */
-export class ValidationError extends Error {
-  constructor(
-    message: string,
-    public readonly context?: Record<string, unknown>
-  ) {
-    super(message);
-    this.name = 'ValidationError';
-  }
-}
-
-export class ConfigurationError extends Error {
-  constructor(
-    message: string,
-    public readonly context?: Record<string, unknown>
-  ) {
-    super(message);
-    this.name = 'ConfigurationError';
-  }
-}
-
-export class NetworkError extends Error {
-  constructor(
-    message: string,
-    public readonly context?: Record<string, unknown>
-  ) {
-    super(message);
-    this.name = 'NetworkError';
-  }
-}
-
-/**
- * Error classification utility
- */
-export function classifyError(error: unknown): {
-  type: 'validation' | 'configuration' | 'network' | 'unknown';
-  message: string;
-  isRetryable: boolean;
-} {
-  if (error instanceof ValidationError) {
-    return { type: 'validation', message: error.message, isRetryable: false };
-  }
-
-  if (error instanceof ConfigurationError) {
-    return { type: 'configuration', message: error.message, isRetryable: false };
-  }
-
-  if (error instanceof NetworkError) {
-    return { type: 'network', message: error.message, isRetryable: true };
-  }
-
-  const message = error instanceof Error ? error.message : String(error);
-
-  // Classify based on message patterns
-  if (MESSAGE_PATTERNS_TYPE_NETWORK.some(pattern => message.includes(pattern))) {
-    return { type: 'network', message, isRetryable: true };
-  }
-
-  if (ERROR_MESSAGE_PATTERNS_TYPE_CONFIG.some(pattern => message.includes(pattern))) {
-    return { type: 'configuration', message, isRetryable: false };
-  }
-  return { type: 'unknown', message, isRetryable: false };
-}

package/src/utils/metadata-builder.ts

@@ -1,228 +0,0 @@
-/**
- * Metadata Builder Utilities
- *
- * Centralized metadata handling to eliminate repetitive spreading
- * and provide consistent metadata processing across the codebase.
- */
-
-import { UsageMetadata, Subscriber } from '../types/index.js';
-
-/**
- * Metadata field configuration for conditional inclusion
- */
-interface MetadataFieldConfig {
-  /** Source field name in UsageMetadata */
-  source: keyof UsageMetadata;
-  /** Target field name in payload (defaults to source) */
-  target?: string;
-  /** Whether this field is required */
-  required?: boolean;
-  /** Custom transformation function */
-  transform?: (value: unknown) => unknown;
-}
-
-/**
- * Metadata mapping configuration
- * Maps UsageMetadata fields to payload fields with optional transformations
- * Subscriber object is passed through directly without transformation
- */
-const METADATA_FIELD_MAP: MetadataFieldConfig[] = [
-  { source: 'traceId' },
-  { source: 'taskType' },
-  { source: 'agent' },
-  { source: 'organizationId' },
-  { source: 'productId' },
-  { source: 'subscriber' }, // Pass through nested subscriber object directly
-  { source: 'subscriptionId' },
-  {
-    source: 'responseQualityScore',
-    transform: (value: unknown) => {
-      // Ensure quality score is between 0.0 and 1.0 (API spec requirement)
-      if (typeof value === 'number') return Math.max(0, Math.min(1, value));
-      return value;
-    },
-  },
-];
-
-/**
- * Build metadata object for payload inclusion
- *
- * This function eliminates the repetitive spreading pattern and provides
- * a clean, testable way to handle metadata transformation.
- * Subscriber object is passed through directly without transformation.
- *
- * @param usageMetadata - Source metadata from request
- * @returns Clean metadata object for payload
- */
-export function buildMetadataFields(usageMetadata?: UsageMetadata): Record<string, unknown> {
-  if (!usageMetadata) return {};
-  const result: Record<string, unknown> = {};
-
-  // Process all metadata fields including nested subscriber object
-  for (const config of METADATA_FIELD_MAP) {
-    const value = usageMetadata[config.source];
-
-    // Skip undefined values (but allow null, empty strings, objects, etc.)
-    if (value === undefined) continue;
-
-    // Apply transformation if configured
-    const transformedValue = config.transform ? config.transform(value) : value;
-
-    // Use target field name or default to source
-    const targetField = config.target || config.source;
-
-    result[targetField] = transformedValue;
-  }
-  return result;
-}
-
-/**
- * Validate metadata completeness for specific use cases
- *
- * @param usageMetadata - Metadata to validate
- * @param requiredFields - List of required field names
- * @returns Validation result
- */
-export function validateMetadata(
-  usageMetadata?: UsageMetadata,
-  requiredFields: (keyof UsageMetadata)[] = []
-): {
-  isValid: boolean;
-  missingFields: string[];
-  warnings: string[];
-} {
-  const missingFields: string[] = [];
-  const warnings: string[] = [];
-
-  if (!usageMetadata && requiredFields.length > 0) {
-    return {
-      isValid: false,
-      missingFields: requiredFields as string[],
-      warnings: ['No metadata provided'],
-    };
-  }
-
-  if (usageMetadata) {
-    // Check required fields
-    for (const field of requiredFields) {
-      if (!usageMetadata[field]) missingFields.push(String(field));
-    }
-
-    // Check for common issues
-    if (usageMetadata.responseQualityScore) {
-      const score = usageMetadata.responseQualityScore;
-      // API Spec: https://revenium.readme.io/reference/meter_ai_completion (responseQualityScore)
-      // "typically on a 0.0-1.0 scale"
-      if (typeof score !== 'number' || score < 0 || score > 1) {
-        warnings.push('responseQualityScore should be a number between 0.0 and 1.0');
-      }
-    }
-
-    if (usageMetadata.subscriber?.email && !usageMetadata.subscriber.email.includes('@')) {
-      warnings.push('subscriber.email does not appear to be a valid email address');
-    }
-  }
-  return {
-    isValid: missingFields.length === 0,
-    missingFields,
-    warnings,
-  };
-}
-
-/**
- * Merge multiple metadata sources with priority
- *
- * @param sources - Metadata sources in priority order (first wins)
- * @returns Merged metadata object
- */
-export function mergeMetadata(...sources: (UsageMetadata | undefined)[]): UsageMetadata {
-  const result: UsageMetadata = {};
-
-  // Process sources in reverse order so first source wins
-  for (const source of sources.reverse()) {
-    if (source) Object.assign(result, source);
-  }
-  return result;
-}
-
-/**
- * Extract metadata from request parameters safely
- *
- * @param params - Request parameters that might contain usageMetadata
- * @returns Extracted metadata and cleaned parameters
- */
-export function extractMetadata<T extends Record<string, unknown>>(
-  params: T & { usageMetadata?: UsageMetadata }
-): {
-  metadata: UsageMetadata | undefined;
-  cleanParams: Omit<T, 'usageMetadata'>;
-} {
-  const { usageMetadata, ...cleanParams } = params;
-  return {
-    metadata: usageMetadata,
-    cleanParams: cleanParams as Omit<T, 'usageMetadata'>,
-  };
-}
-
-/**
- * Create a metadata context for consistent logging
- * Uses sanitization to protect PII (emails are masked)
- *
- * @param usageMetadata - Source metadata
- * @returns Logging context object with sanitized PII
- */
-export function createLoggingContext(usageMetadata?: UsageMetadata): Record<string, unknown> {
-  if (!usageMetadata) return {};
-
-  // Use sanitizer to protect PII in logs
-  const sanitized = sanitizeMetadataForLogging(usageMetadata);
-  const sanitizedSubscriber = sanitized.subscriber as { id?: string; email?: string; credential?: unknown };
-
-  return {
-    traceId: usageMetadata.traceId,
-    taskType: usageMetadata.taskType,
-    subscriberId: usageMetadata.subscriber?.id,
-    subscriberEmail: sanitizedSubscriber?.email,  // ← Now masked: us***@example.com
-    organizationId: usageMetadata.organizationId,
-    productId: usageMetadata.productId,
-    agent: usageMetadata.agent,
-  };
-}
-
-/**
- * Sanitize metadata for logging (remove sensitive fields)
- *
- * @param usageMetadata - Source metadata
- * @returns Sanitized metadata safe for logging
- */
-export function sanitizeMetadataForLogging(usageMetadata?: UsageMetadata): Record<string, unknown> {
-  if (!usageMetadata) return {};
-
-  // Create a copy and handle nested subscriber object
-  const { subscriber, ...safeMetadata } = usageMetadata;
-
-  const result: Record<string, unknown> = { ...safeMetadata };
-
-  // Sanitize subscriber object if present
-  if (subscriber) {
-    const sanitizedSubscriber: Record<string, unknown> = {};
-
-    if (subscriber.id) {
-      sanitizedSubscriber.id = subscriber.id;
-    }
-
-    if (subscriber.email) {
-      // Mask email: handles single-char emails (a@x.com → a***@x.com)
-      sanitizedSubscriber.email = subscriber.email.replace(/(.{1,2}).*(@.*)/, '$1***$2');
-    }
-
-    if (subscriber.credential) {
-      sanitizedSubscriber.credential = {
-        name: subscriber.credential.name,
-        value: '[REDACTED]',
-      };
-    }
-    result.subscriber = sanitizedSubscriber;
-  }
-  return result;
-}