@revenium/anthropic 1.0.0

package/dist/cjs/utils/error-handling.js

@@ -0,0 +1,233 @@
+"use strict";
+/**
+ * Error handling utilities for Anthropic middleware with structured errors and context building
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ErrorContext = exports.StreamProcessingError = exports.ValidationError = exports.ReveniumApiError = exports.RequestProcessingError = exports.AnthropicPatchingError = exports.ConfigurationError = exports.ReveniumError = void 0;
+exports.getErrorMessage = getErrorMessage;
+exports.getErrorStack = getErrorStack;
+exports.createErrorContext = createErrorContext;
+exports.handleError = handleError;
+exports.withErrorHandling = withErrorHandling;
+exports.withRetry = withRetry;
+const constants_1 = require("../constants");
+/**
+ * Base error class for Revenium middleware errors
+ */
+class ReveniumError extends Error {
+    constructor(message, code, context) {
+        super(message);
+        this.name = 'ReveniumError';
+        this.code = code;
+        this.context = context;
+        // Maintain proper stack trace for where our error was thrown
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, ReveniumError);
+        }
+    }
+}
+exports.ReveniumError = ReveniumError;
+/**
+ * Configuration-related errors
+ */
+class ConfigurationError extends ReveniumError {
+    constructor(message, context) {
+        super(message, 'CONFIGURATION_ERROR', context);
+        this.name = 'ConfigurationError';
+    }
+}
+exports.ConfigurationError = ConfigurationError;
+/**
+ * Anthropic SDK patching errors
+ */
+class AnthropicPatchingError extends ReveniumError {
+    constructor(message, context) {
+        super(message, 'ANTHROPIC_PATCHING_ERROR', context);
+        this.name = 'AnthropicPatchingError';
+    }
+}
+exports.AnthropicPatchingError = AnthropicPatchingError;
+/**
+ * Request processing errors
+ */
+class RequestProcessingError extends ReveniumError {
+    constructor(message, context) {
+        super(message, 'REQUEST_PROCESSING_ERROR', context);
+        this.name = 'RequestProcessingError';
+    }
+}
+exports.RequestProcessingError = RequestProcessingError;
+/**
+ * Revenium API communication errors
+ */
+class ReveniumApiError extends ReveniumError {
+    constructor(message, statusCode, responseBody, context) {
+        super(message, 'REVENIUM_API_ERROR', context);
+        this.name = 'ReveniumApiError';
+        this.statusCode = statusCode;
+        this.responseBody = responseBody;
+    }
+}
+exports.ReveniumApiError = ReveniumApiError;
+/**
+ * Validation errors
+ */
+class ValidationError extends ReveniumError {
+    constructor(message, validationErrors, context) {
+        super(message, 'VALIDATION_ERROR', context);
+        this.name = 'ValidationError';
+        this.validationErrors = validationErrors;
+    }
+}
+exports.ValidationError = ValidationError;
+/**
+ * Stream processing errors
+ */
+class StreamProcessingError extends ReveniumError {
+    constructor(message, context) {
+        super(message, 'STREAM_PROCESSING_ERROR', context);
+        this.name = 'StreamProcessingError';
+    }
+}
+exports.StreamProcessingError = StreamProcessingError;
+/**
+ * Error context builder for consistent error reporting
+ */
+class ErrorContext {
+    constructor() {
+        this.context = {};
+    }
+    /**
+     * Add request ID to error context
+     */
+    withRequestId(requestId) {
+        this.context.requestId = requestId;
+        return this;
+    }
+    /**
+     * Add model information to error context
+     */
+    withModel(model) {
+        this.context.model = model;
+        return this;
+    }
+    /**
+     * Add duration to error context
+     */
+    withDuration(duration) {
+        this.context.duration = duration;
+        return this;
+    }
+    /**
+     * Add HTTP status to error context
+     */
+    withStatus(status) {
+        this.context.status = status;
+        return this;
+    }
+    /**
+     * Add custom field to error context
+     */
+    with(key, value) {
+        this.context[key] = value;
+        return this;
+    }
+    /**
+     * Build the context object
+     */
+    build() {
+        return { ...this.context };
+    }
+}
+exports.ErrorContext = ErrorContext;
+/**
+ * Safe error message extraction
+ */
+function getErrorMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === 'string')
+        return error;
+    if (error && typeof error === 'object' && 'message' in error) {
+        const message = error.message;
+        if (typeof message === 'string')
+            return message;
+    }
+    return 'Unknown error occurred';
+}
+/**
+ * Safe error stack extraction
+ */
+function getErrorStack(error) {
+    if (error instanceof Error && error.stack)
+        return error.stack;
+    return;
+}
+/**
+ * Create error context builder
+ */
+function createErrorContext() {
+    return new ErrorContext();
+}
+/**
+ * Handle and log errors consistently
+ */
+function handleError(error, logger, context) {
+    const message = getErrorMessage(error);
+    const stack = getErrorStack(error);
+    const logContext = {
+        ...context,
+        error: message,
+        stack: stack
+    };
+    if (error instanceof ReveniumError) {
+        logContext.errorCode = error.code;
+        logContext.errorContext = error.context;
+        if (error instanceof ReveniumApiError) {
+            logContext.statusCode = error.statusCode;
+            logContext.responseBody = error.responseBody;
+        }
+        if (error instanceof ValidationError) {
+            logContext.validationErrors = error.validationErrors;
+        }
+    }
+    logger.error('Error occurred', logContext);
+}
+/**
+ * Wrap async function with error handling
+ */
+function withErrorHandling(fn, errorHandler) {
+    return async (...args) => {
+        try {
+            return await fn(...args);
+        }
+        catch (error) {
+            errorHandler(error, ...args);
+            return undefined;
+        }
+    };
+}
+/**
+ * Retry function with exponential backoff
+ */
+async function withRetry(fn, maxRetries = constants_1.RETRY_CONFIG.BASE_DELAY / 1000, // Convert to attempts for backward compatibility
+baseDelay = constants_1.RETRY_CONFIG.BASE_DELAY) {
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt === maxRetries) {
+                break;
+            }
+            // Exponential backoff with jitter using constants
+            const delay = Math.min(baseDelay * Math.pow(2, attempt), constants_1.RETRY_CONFIG.MAX_DELAY);
+            const jitter = Math.random() * constants_1.RETRY_CONFIG.JITTER_FACTOR * delay;
+            await new Promise(resolve => setTimeout(resolve, delay + jitter));
+        }
+    }
+    throw lastError;
+}
+//# sourceMappingURL=error-handling.js.map

package/dist/cjs/utils/validation.js

@@ -0,0 +1,307 @@
+"use strict";
+/**
+ * Validation utilities for Anthropic middleware
+ * Provides type-safe validation with detailed error reporting
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isObject = isObject;
+exports.isString = isString;
+exports.isNumber = isNumber;
+exports.isBoolean = isBoolean;
+exports.validateString = validateString;
+exports.validateNumber = validateNumber;
+exports.validateUsageMetadata = validateUsageMetadata;
+exports.validateReveniumConfig = validateReveniumConfig;
+exports.validateAnthropicMessageParams = validateAnthropicMessageParams;
+const constants_1 = require("../constants");
+/**
+ * Type guard for checking if a value is a non-null object
+ */
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Type guard for checking if a value is a string
+ */
+function isString(value) {
+    return typeof value === 'string';
+}
+/**
+ * Type guard for checking if a value is a number
+ */
+function isNumber(value) {
+    return typeof value === 'number' && !isNaN(value);
+}
+/**
+ * Type guard for checking if a value is a boolean
+ */
+function isBoolean(value) {
+    return typeof value === 'boolean';
+}
+/**
+ * Validate and extract string from unknown value
+ */
+function validateString(value, defaultValue = '') {
+    return isString(value) ? value : defaultValue;
+}
+/**
+ * Validate and extract number from unknown value
+ */
+function validateNumber(value, defaultValue = 0) {
+    return isNumber(value) ? value : defaultValue;
+}
+/**
+ * Validate usage metadata object with Anthropic-specific considerations
+ */
+function validateUsageMetadata(metadata) {
+    if (!isObject(metadata)) {
+        return {};
+    }
+    const validated = {};
+    // Validate string fields
+    const stringFields = [
+        'traceId', 'taskId', 'taskType', 'subscriberEmail', 'subscriberId',
+        'subscriberCredentialName', 'subscriberCredential', 'organizationId',
+        'subscriptionId', 'productId', 'agent'
+    ];
+    for (const field of stringFields) {
+        const value = metadata[field];
+        if (isString(value) && value.trim().length > 0) {
+            validated[field] = value.trim();
+        }
+    }
+    // Validate nested subscriber object
+    const subscriberData = metadata.subscriber;
+    if (isObject(subscriberData)) {
+        const subscriber = {};
+        // Validate subscriber.id
+        if (isString(subscriberData?.id) && subscriberData?.id?.trim()?.length > 0) {
+            subscriber.id = subscriberData?.id?.trim();
+        }
+        // Validate subscriber.email
+        if (isString(subscriberData?.email) && subscriberData?.email?.trim()?.length > 0) {
+            subscriber.email = subscriberData?.email?.trim();
+        }
+        // Validate subscriber.credential object
+        const credentialData = subscriberData?.credential;
+        if (isObject(credentialData)) {
+            const credential = {};
+            if (isString(credentialData?.name) && credentialData?.name?.trim()?.length > 0) {
+                credential.name = credentialData?.name?.trim();
+            }
+            if (isString(credentialData?.value) && credentialData?.value?.trim()?.length > 0) {
+                credential.value = credentialData?.value?.trim();
+            }
+            // Only include credential if it has at least name or value
+            if (credential?.name || credential?.value) {
+                subscriber.credential = credential;
+            }
+        }
+        // Only include subscriber if it has at least one field
+        if (subscriber?.id || subscriber?.email || subscriber?.credential) {
+            validated.subscriber = subscriber;
+        }
+    }
+    // Validate number fields
+    const responseQualityScore = metadata.responseQualityScore;
+    if (isNumber(responseQualityScore) && responseQualityScore >= 0 && responseQualityScore <= 1) {
+        validated.responseQualityScore = responseQualityScore;
+    }
+    return validated;
+}
+/**
+ * Comprehensive Revenium configuration validation for Anthropic
+ */
+function validateReveniumConfig(config) {
+    const errors = [];
+    const warnings = [];
+    const suggestions = [];
+    if (!isObject(config)) {
+        return {
+            isValid: false,
+            errors: ['Configuration must be an object'],
+            warnings: [],
+            suggestions: ['Ensure you are passing a valid configuration object with required fields']
+        };
+    }
+    const cfg = config;
+    // Validate required Revenium API key
+    if (!isString(cfg?.reveniumApiKey)) {
+        errors.push('reveniumApiKey is required and must be a string');
+        suggestions.push('Set REVENIUM_METERING_API_KEY environment variable or provide reveniumApiKey in config');
+    }
+    else if (!cfg?.reveniumApiKey?.trim()) {
+        errors.push('reveniumApiKey cannot be empty');
+    }
+    else if (!cfg?.reveniumApiKey?.startsWith(constants_1.VALIDATION_CONFIG.REVENIUM_API_KEY_PREFIX)) {
+        errors.push(`reveniumApiKey must start with "${constants_1.VALIDATION_CONFIG.REVENIUM_API_KEY_PREFIX}"`);
+        suggestions.push('Obtain a valid Revenium API key from your Revenium dashboard');
+    }
+    else if (cfg?.reveniumApiKey?.length < constants_1.VALIDATION_CONFIG.MIN_API_KEY_LENGTH) {
+        warnings.push('reveniumApiKey appears to be too short - verify it is correct');
+    }
+    // Validate Revenium base URL
+    if (!isString(cfg?.reveniumBaseUrl)) {
+        errors.push('reveniumBaseUrl is required and must be a string');
+    }
+    else if (!cfg?.reveniumBaseUrl?.trim()) {
+        errors.push('reveniumBaseUrl cannot be empty');
+    }
+    else {
+        try {
+            const url = new URL(cfg?.reveniumBaseUrl);
+            if (!url.protocol.startsWith('http')) {
+                errors.push('reveniumBaseUrl must use HTTP or HTTPS protocol');
+            }
+            // Check for localhost/development hostnames (IPv4, IPv6, and named)
+            const localhostHostnames = ['localhost', '127.0.0.1', '::1', '[::1]'];
+            if (localhostHostnames.includes(url.hostname)) {
+                warnings.push('Using localhost for Revenium API - ensure this is intended for development');
+            }
+        }
+        catch {
+            errors.push('reveniumBaseUrl must be a valid URL');
+            suggestions.push('Use format: https://api.revenium.io/meter');
+        }
+    }
+    // Validate optional Anthropic API key
+    if (!isString(cfg?.anthropicApiKey)) {
+        errors.push('anthropicApiKey must be a string if provided');
+    }
+    else if (cfg?.anthropicApiKey?.trim()?.length === 0) {
+        warnings.push('anthropicApiKey is empty - API calls may fail');
+    }
+    else if (!cfg?.anthropicApiKey?.startsWith(constants_1.VALIDATION_CONFIG.ANTHROPIC_API_KEY_PREFIX)) {
+        warnings.push(`anthropicApiKey does not start with "${constants_1.VALIDATION_CONFIG.ANTHROPIC_API_KEY_PREFIX}" - verify it is correct`);
+    }
+    // Validate optional timeout using constants
+    if (cfg?.apiTimeout !== undefined && !isNumber(cfg?.apiTimeout)) {
+        errors.push('apiTimeout must be a number if provided');
+    }
+    else if (cfg?.apiTimeout !== undefined && cfg?.apiTimeout < constants_1.VALIDATION_CONFIG.MIN_API_TIMEOUT) {
+        errors.push(`apiTimeout must be at least ${constants_1.VALIDATION_CONFIG.MIN_API_TIMEOUT}ms`);
+    }
+    else if (cfg?.apiTimeout !== undefined && cfg?.apiTimeout > constants_1.VALIDATION_CONFIG.MAX_API_TIMEOUT) {
+        errors.push(`apiTimeout must not exceed ${constants_1.VALIDATION_CONFIG.MAX_API_TIMEOUT}ms`);
+    }
+    else if (cfg?.apiTimeout !== undefined && cfg?.apiTimeout < constants_1.VALIDATION_CONFIG.LOW_TIMEOUT_WARNING_THRESHOLD) {
+        warnings.push('apiTimeout is very low - may cause timeouts for slow networks');
+    }
+    // Validate optional failSilent
+    if (cfg?.failSilent && !isBoolean(cfg?.failSilent)) {
+        errors.push('failSilent must be a boolean if provided');
+    }
+    // Validate optional maxRetries using constants
+    if (cfg?.maxRetries !== undefined && !isNumber(cfg?.maxRetries)) {
+        errors.push('maxRetries must be a number if provided');
+    }
+    else if (cfg?.maxRetries !== undefined && cfg?.maxRetries < 0) {
+        errors.push('maxRetries cannot be negative');
+    }
+    else if (cfg?.maxRetries !== undefined && cfg?.maxRetries > constants_1.VALIDATION_CONFIG.MAX_RETRY_ATTEMPTS) {
+        errors.push(`maxRetries should not exceed ${constants_1.VALIDATION_CONFIG.MAX_RETRY_ATTEMPTS}`);
+    }
+    else if (cfg?.maxRetries !== undefined && cfg?.maxRetries === 0) {
+        warnings.push('maxRetries is 0 - no retry attempts will be made');
+    }
+    if (errors.length > 0) {
+        return {
+            isValid: false,
+            errors,
+            warnings,
+            suggestions
+        };
+    }
+    // Build validated config
+    const validatedConfig = {
+        reveniumApiKey: cfg?.reveniumApiKey,
+        reveniumBaseUrl: cfg?.reveniumBaseUrl,
+        anthropicApiKey: isString(cfg?.anthropicApiKey) ? cfg?.anthropicApiKey : undefined,
+        apiTimeout: isNumber(cfg?.apiTimeout) ? cfg?.apiTimeout : undefined,
+        failSilent: isBoolean(cfg?.failSilent) ? cfg?.failSilent : undefined,
+        maxRetries: isNumber(cfg?.maxRetries) ? cfg?.maxRetries : undefined
+    };
+    return {
+        isValid: true,
+        errors: [],
+        warnings,
+        config: validatedConfig,
+        suggestions: suggestions.length > 0 ? suggestions : undefined
+    };
+}
+/**
+ * Validate Anthropic message creation parameters
+ */
+function validateAnthropicMessageParams(params) {
+    const errors = [];
+    const warnings = [];
+    if (!isObject(params)) {
+        return {
+            isValid: false,
+            errors: ['Message parameters must be an object'],
+            warnings: []
+        };
+    }
+    const data = params;
+    // Validate required model field
+    if (!isString(data?.model)) {
+        errors.push('model field is required and must be a string');
+    }
+    else if (data?.model?.trim()?.length === 0) {
+        errors.push('model field cannot be empty');
+    }
+    else if (!constants_1.ANTHROPIC_PATTERNS.CLAUDE_MODEL_PATTERN.test(data?.model)) {
+        warnings.push('Model name does not contain "claude" - verify it is a valid Anthropic model');
+    }
+    // Validate required messages array
+    if (!Array.isArray(data?.messages)) {
+        errors.push('messages field is required and must be an array');
+    }
+    else if (data?.messages?.length === 0) {
+        errors.push('messages array cannot be empty');
+    }
+    else {
+        // Validate message structure
+        data?.messages?.forEach((message, index) => {
+            if (!isObject(message)) {
+                errors.push(`Message at index ${index} must be an object`);
+                return;
+            }
+            const msg = message;
+            if (!isString(msg.role)) {
+                errors.push(`Message at index ${index} must have a role field`);
+            }
+            else if (!['user', 'assistant', 'system'].includes(msg.role)) {
+                warnings.push(`Message at index ${index} has unusual role: ${msg.role}`);
+            }
+            if (msg?.content && !isString(msg?.content) && !Array.isArray(msg?.content)) {
+                warnings.push(`Message at index ${index} content should be a string or array`);
+            }
+        });
+    }
+    // Validate optional parameters
+    if (!isNumber(data?.max_tokens)) {
+        warnings.push('max_tokens should be a number');
+    }
+    else if (data?.max_tokens <= 0) {
+        warnings.push('max_tokens should be positive');
+    }
+    else if (data?.max_tokens > constants_1.VALIDATION_CONFIG.HIGH_MAX_TOKENS_THRESHOLD) {
+        warnings.push('max_tokens is very high - verify this is intended');
+    }
+    if (!isNumber(data?.temperature)) {
+        warnings.push('temperature should be a number');
+    }
+    else if (data?.temperature < constants_1.VALIDATION_CONFIG.MIN_TEMPERATURE || data?.temperature > constants_1.VALIDATION_CONFIG.MAX_TEMPERATURE) {
+        warnings.push(`temperature should be between ${constants_1.VALIDATION_CONFIG.MIN_TEMPERATURE} and ${constants_1.VALIDATION_CONFIG.MAX_TEMPERATURE} for Anthropic models`);
+    }
+    if (data?.stream && !isBoolean(data?.stream)) {
+        warnings.push('stream should be a boolean');
+    }
+    return {
+        isValid: errors.length === 0,
+        errors,
+        warnings
+    };
+}
+//# sourceMappingURL=validation.js.map