@revenium/anthropic 1.0.0

package/dist/esm/constants.js

@@ -0,0 +1,141 @@
+/**
+ * Configuration constants for Revenium Anthropic middleware
+ * Centralizes all magic numbers and default values
+ */
+/**
+ * Default configuration values
+ */
+export const DEFAULT_CONFIG = {
+    /** Default Revenium API base URL */
+    REVENIUM_BASE_URL: 'https://api.revenium.io/meter',
+    /** Default API timeout in milliseconds */
+    API_TIMEOUT: 5000,
+    /** Default maximum retries for failed API calls */
+    MAX_RETRIES: 3,
+    /** Default fail silent behavior */
+    FAIL_SILENT: true,
+    /** Minimum allowed API timeout */
+    MIN_API_TIMEOUT: 1000,
+    /** Maximum allowed API timeout */
+    MAX_API_TIMEOUT: 60000,
+    /** Maximum allowed retry attempts */
+    MAX_RETRY_ATTEMPTS: 10,
+    /** Warning threshold for low API timeout */
+    LOW_TIMEOUT_WARNING_THRESHOLD: 3000,
+};
+/**
+ * Circuit breaker configuration constants
+ */
+export const CIRCUIT_BREAKER_CONFIG = {
+    /** Default number of failures before opening circuit */
+    FAILURE_THRESHOLD: 5,
+    /** Default recovery timeout in milliseconds (30 seconds) */
+    RECOVERY_TIMEOUT: 30000,
+    /** Default number of successful calls needed to close circuit */
+    SUCCESS_THRESHOLD: 3,
+    /** Default time window for counting failures (1 minute) */
+    TIME_WINDOW: 60000,
+    /** Maximum failure history size to prevent memory leaks */
+    MAX_FAILURE_HISTORY_SIZE: 1000,
+    /** Periodic cleanup interval (5 minutes) */
+    CLEANUP_INTERVAL: 300000,
+    /** Cleanup trigger threshold for failures array size */
+    CLEANUP_SIZE_THRESHOLD: 100,
+};
+/**
+ * Retry configuration constants
+ */
+export const RETRY_CONFIG = {
+    /** Base delay for exponential backoff in milliseconds */
+    BASE_DELAY: 1000,
+    /** Maximum delay for exponential backoff */
+    MAX_DELAY: 5000,
+    /** Jitter factor for randomizing delays */
+    JITTER_FACTOR: 0.1,
+};
+/**
+ * Validation constants
+ */
+export const VALIDATION_CONFIG = {
+    /** Minimum API key length */
+    MIN_API_KEY_LENGTH: 20,
+    /** Required API key prefix for Revenium */
+    REVENIUM_API_KEY_PREFIX: 'hak_',
+    /** Required API key prefix for Anthropic */
+    ANTHROPIC_API_KEY_PREFIX: 'sk-ant-',
+    /** Maximum tokens warning threshold */
+    HIGH_MAX_TOKENS_THRESHOLD: 4096,
+    /** Temperature range */
+    MIN_TEMPERATURE: 0,
+    MAX_TEMPERATURE: 1,
+    /** Response quality score range */
+    MIN_QUALITY_SCORE: 0,
+    MAX_QUALITY_SCORE: 1,
+    /** API timeout constraints */
+    MIN_API_TIMEOUT: 1000,
+    MAX_API_TIMEOUT: 60000,
+    LOW_TIMEOUT_WARNING_THRESHOLD: 3000,
+    /** Retry constraints */
+    MAX_RETRY_ATTEMPTS: 10,
+};
+/**
+ * Logging constants
+ */
+export const LOGGING_CONFIG = {
+    /** Middleware name for log prefixes */
+    MIDDLEWARE_NAME: 'Revenium',
+    /** User agent string for API requests */
+    USER_AGENT: 'revenium-middleware-anthropic-node/1.0.0',
+    /** Debug environment variable name */
+    DEBUG_ENV_VAR: 'REVENIUM_DEBUG',
+};
+/**
+ * Environment variable names
+ */
+export const ENV_VARS = {
+    /** Revenium API key */
+    REVENIUM_API_KEY: 'REVENIUM_METERING_API_KEY',
+    /** Revenium base URL */
+    REVENIUM_BASE_URL: 'REVENIUM_METERING_BASE_URL',
+    /** Anthropic API key */
+    ANTHROPIC_API_KEY: 'ANTHROPIC_API_KEY',
+    /** Debug mode */
+    DEBUG: 'REVENIUM_DEBUG',
+    /** Log level */
+    LOG_LEVEL: 'REVENIUM_LOG_LEVEL',
+    /** API timeout */
+    API_TIMEOUT: 'REVENIUM_API_TIMEOUT',
+    /** Fail silent mode */
+    FAIL_SILENT: 'REVENIUM_FAIL_SILENT',
+    /** Maximum retries */
+    MAX_RETRIES: 'REVENIUM_MAX_RETRIES',
+};
+/**
+ * API endpoints
+ */
+export const API_ENDPOINTS = {
+    /** Revenium AI completions endpoint */
+    AI_COMPLETIONS: '/v2/ai/completions',
+};
+/**
+ * Anthropic model patterns
+ */
+export const ANTHROPIC_PATTERNS = {
+    /** Pattern to identify Claude models */
+    CLAUDE_MODEL_PATTERN: /claude/i,
+    /** Known Anthropic stop reasons */
+    STOP_REASONS: {
+        END_TURN: 'end_turn',
+        MAX_TOKENS: 'max_tokens',
+        STOP_SEQUENCE: 'stop_sequence',
+        TOOL_USE: 'tool_use',
+    },
+    /** Revenium stop reason mappings */
+    REVENIUM_STOP_REASON_MAP: {
+        'end_turn': 'END',
+        'max_tokens': 'TOKEN_LIMIT',
+        'stop_sequence': 'END_SEQUENCE',
+        'tool_use': 'END',
+    },
+};
+//# sourceMappingURL=constants.js.map

package/dist/esm/index.js

@@ -0,0 +1,121 @@
+/**
+ * Modern Revenium Anthropic Middleware
+ * Clean architecture without backward compatibility constraints
+ */
+// Import type augmentations to extend Anthropic types with usageMetadata
+import "./types/anthropic-augmentation.js";
+import { initializeConfig, getLogger, setConfig, getConfig, getConfigStatus, } from "./config.js";
+import { patchAnthropic, unpatchAnthropic, isAnthropicPatched, } from "./wrapper.js";
+import { trackUsageAsync } from "./tracking.js";
+import { getCircuitBreakerStats, resetCircuitBreaker, } from "./utils/circuit-breaker.js";
+// Export configuration functions
+export { setConfig, setLogger, getLogger, getConfig, getConfigStatus, validateCurrentConfig, } from "./config.js";
+// Export wrapper control functions
+export { patchAnthropic, unpatchAnthropic, isAnthropicPatched, } from "./wrapper.js";
+// Export tracking functions
+export { sendReveniumMetrics, trackUsageAsync, extractUsageFromStream, } from "./tracking.js";
+// Export utility functions
+export { getCircuitBreakerStats, resetCircuitBreaker, canExecuteRequest, } from "./utils/circuit-breaker.js";
+export { validateReveniumConfig, validateAnthropicMessageParams, validateUsageMetadata, } from "./utils/validation.js";
+/**
+ * Initialize the Revenium middleware with configuration from environment variables
+ * This function can be called explicitly for better error handling and control
+ *
+ *
+ *
+ */
+// Global logger
+const logger = getLogger();
+export function initialize() {
+    const initialized = initializeConfig();
+    if (!initialized) {
+        throw new Error("Failed to initialize Revenium middleware: missing required environment variables. " +
+            "Set REVENIUM_METERING_API_KEY or call configure() with manual configuration.");
+    }
+    try {
+        patchAnthropic();
+        logger.info("Revenium Anthropic middleware initialized successfully");
+        logger.debug("Environment variables found and configuration loaded");
+    }
+    catch (patchError) {
+        const errorMessage = patchError instanceof Error ? patchError.message : String(patchError);
+        throw new Error(`Failed to patch Anthropic SDK: ${errorMessage}`);
+    }
+}
+/**
+ * Auto-initialization with graceful fallback
+ * Attempts to initialize automatically but doesn't throw on failure
+ */
+function autoInitialize() {
+    try {
+        initialize();
+    }
+    catch (error) {
+        // Log debug message but don't throw - allow manual configuration later
+        logger.debug("Auto-initialization failed, manual configuration required", {
+            error: error instanceof Error ? error.message : String(error),
+            suggestion: "Call initialize() or configure() explicitly for detailed error information",
+        });
+    }
+}
+// Perform auto-initialization with graceful fallback
+autoInitialize();
+/**
+ * Manual initialization with custom configuration
+ */
+export function configure(config) {
+    setConfig(config);
+    patchAnthropic();
+    getLogger().info("Revenium Anthropic middleware configured successfully");
+}
+/**
+ * Check if the middleware is properly initialized
+ */
+export function isInitialized() {
+    return isAnthropicPatched() && !!getConfig();
+}
+/**
+ * Get comprehensive middleware status
+ */
+export function getStatus() {
+    const configStatus = getConfigStatus();
+    const circuitBreakerStats = getCircuitBreakerStats();
+    let anthropicVersion;
+    try {
+        // Try to get Anthropic version - use dynamic require for compatibility
+        const anthropicPackage = globalThis.require?.("@anthropic-ai/sdk/package.json");
+        anthropicVersion = anthropicPackage?.version;
+    }
+    catch {
+        // Ignore if we can't get the version
+    }
+    return {
+        initialized: isInitialized(),
+        patched: isAnthropicPatched(),
+        hasConfig: configStatus.hasConfig,
+        anthropicVersion,
+        circuitBreakerState: circuitBreakerStats.state,
+    };
+}
+/**
+ * Manually track an Anthropic API call (for cases where auto-patching isn't used)
+ */
+export function trackAnthropicCall(trackingData) {
+    return trackUsageAsync(trackingData);
+}
+/**
+ * Reset middleware to initial state (useful for testing)
+ */
+export function reset() {
+    try {
+        unpatchAnthropic();
+        resetCircuitBreaker();
+        logger.debug("Middleware reset completed");
+    }
+    catch (error) {
+        logger.error("Error during middleware reset", {
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/esm/tracking.js

@@ -0,0 +1,243 @@
+/**
+ * Tracking implementation for Anthropic middleware with resilience patterns
+ */
+import fetch from "node-fetch";
+import { getConfig, getLogger } from "./config.js";
+import { executeWithCircuitBreaker } from "./utils/circuit-breaker.js";
+import { withRetry, ReveniumApiError, createErrorContext, handleError, } from "./utils/error-handling.js";
+import { DEFAULT_CONFIG, API_ENDPOINTS, LOGGING_CONFIG, ANTHROPIC_PATTERNS, } from "./constants.js";
+// Global logger
+const logger = getLogger();
+/**
+ * Send tracking data to Revenium API with resilience patterns
+ */
+export async function sendReveniumMetrics(data) {
+    const config = getConfig();
+    if (!config)
+        throw new Error("Revenium configuration not available");
+    const requestId = data.requestId;
+    logger.debug("Preparing to send metrics to Revenium", {
+        requestId,
+        model: data.model,
+        inputTokens: data.inputTokens,
+        outputTokens: data.outputTokens,
+        duration: data.duration,
+        isStreamed: data.isStreamed,
+    });
+    // Build payload using exact structure from working implementations
+    const payload = buildReveniumPayload(data);
+    // Create request options
+    const requestOptions = {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "x-api-key": config.reveniumApiKey,
+            "User-Agent": LOGGING_CONFIG.USER_AGENT,
+        },
+        body: JSON.stringify(payload),
+        timeout: config.apiTimeout || DEFAULT_CONFIG.API_TIMEOUT,
+    };
+    // Add abort signal for timeout
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), requestOptions.timeout);
+    requestOptions.signal = controller.signal;
+    // Handle abort signal errors to prevent unhandled error events
+    controller.signal.addEventListener("abort", () => {
+        // Silently handle abort - this is expected behavior for timeouts
+    });
+    try {
+        // Execute with circuit breaker and retry logic
+        await executeWithCircuitBreaker(async () => {
+            return withRetry(async () => {
+                logger.debug("Sending request to Revenium API", {
+                    requestId,
+                    url: `${config.reveniumBaseUrl}${API_ENDPOINTS.AI_COMPLETIONS}`,
+                    payloadSize: requestOptions.body.length,
+                });
+                let response;
+                try {
+                    response = await fetch(`${config.reveniumBaseUrl}${API_ENDPOINTS.AI_COMPLETIONS}`, requestOptions);
+                }
+                catch (fetchError) {
+                    // Handle AbortError and other fetch errors
+                    if (fetchError instanceof Error && fetchError.name === "AbortError") {
+                        throw new Error(`Request timeout after ${requestOptions.timeout}ms`);
+                    }
+                    throw fetchError;
+                }
+                if (!response.ok) {
+                    const responseText = await response
+                        .text()
+                        .catch(() => "Unable to read response");
+                    const errorContext = createErrorContext()
+                        .withRequestId(requestId)
+                        .withModel(data.model)
+                        .withStatus(response.status)
+                        .with("responseBody", responseText)
+                        .build();
+                    throw new ReveniumApiError(`Revenium API error: ${response.status} ${response.statusText}`, response.status, responseText, errorContext);
+                }
+                logger.debug("Successfully sent metrics to Revenium", {
+                    requestId,
+                    status: response.status,
+                    duration: data.duration,
+                });
+                return response;
+            }, config.maxRetries || DEFAULT_CONFIG.MAX_RETRIES);
+        });
+    }
+    catch (error) {
+        const errorContext = createErrorContext()
+            .withRequestId(requestId)
+            .withModel(data.model)
+            .withDuration(data.duration)
+            .build();
+        handleError(error, logger, errorContext);
+        // Always fail silently for tracking errors to prevent breaking user's application
+        // Tracking errors should never break the user's main application flow
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
+/**
+ * Build Revenium payload from tracking data
+ */
+function buildReveniumPayload(data) {
+    const now = new Date().toISOString();
+    const requestTime = data.requestTime.toISOString();
+    const completionStartTime = data.responseTime.toISOString();
+    return {
+        stopReason: getStopReason(data.stopReason),
+        costType: "AI",
+        isStreamed: data.isStreamed,
+        taskType: data.metadata?.taskType,
+        agent: data.metadata?.agent,
+        operationType: "CHAT",
+        inputTokenCount: data.inputTokens,
+        outputTokenCount: data.outputTokens,
+        reasoningTokenCount: 0, // Anthropic doesn't currently have reasoning tokens
+        cacheCreationTokenCount: data.cacheCreationTokens || 0,
+        cacheReadTokenCount: data.cacheReadTokens || 0,
+        totalTokenCount: data.inputTokens + data.outputTokens,
+        organizationId: data.metadata?.organizationId,
+        productId: data.metadata?.productId,
+        subscriber: data.metadata?.subscriber, // Pass through nested subscriber object directly
+        subscriptionId: data.metadata?.subscriptionId,
+        model: data.model,
+        transactionId: data.requestId,
+        responseTime: now,
+        requestDuration: Math.round(data.duration),
+        provider: "Anthropic",
+        requestTime: requestTime,
+        completionStartTime: completionStartTime,
+        timeToFirstToken: data.timeToFirstToken || 0,
+        traceId: data.metadata?.traceId,
+        middlewareSource: "nodejs",
+    };
+}
+/**
+ * Normalize stop reason for Revenium API
+ */
+function getStopReason(stopReason) {
+    if (!stopReason)
+        return "END";
+    // Use predefined mapping from constants
+    return (ANTHROPIC_PATTERNS.REVENIUM_STOP_REASON_MAP[stopReason] || "END");
+}
+/**
+ * Fire-and-forget async tracking wrapper
+ * Ensures tracking never blocks the main application flow
+ */
+export function trackUsageAsync(trackingData) {
+    const config = getConfig();
+    if (!config)
+        return logger.warn("Revenium configuration not available - skipping tracking", {
+            requestId: trackingData.requestId,
+        });
+    // Run tracking in background without awaiting
+    sendReveniumMetrics(trackingData)
+        .then(() => {
+        logger.debug("Revenium tracking completed successfully", {
+            requestId: trackingData.requestId,
+            model: trackingData.model,
+            totalTokens: trackingData.inputTokens + trackingData.outputTokens,
+        });
+    })
+        .catch((error) => {
+        const errorContext = createErrorContext()
+            .withRequestId(trackingData.requestId)
+            .withModel(trackingData.model)
+            .build();
+        logger.warn("Revenium tracking failed", {
+            error: error instanceof Error ? error.message : String(error),
+            requestId: trackingData.requestId,
+            context: errorContext,
+        });
+    });
+}
+/**
+ * Extract usage data from Anthropic response
+ */
+export function extractUsageFromResponse(response) {
+    const usage = response.usage || {};
+    return {
+        inputTokens: usage.input_tokens || 0,
+        outputTokens: usage.output_tokens || 0,
+        cacheCreationTokens: usage.cache_creation_input_tokens,
+        cacheReadTokens: usage.cache_read_input_tokens,
+        stopReason: response.stop_reason,
+    };
+}
+/**
+ * Extract usage data from streaming chunks
+ */
+export function extractUsageFromStream(chunks) {
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let cacheCreationTokens;
+    let cacheReadTokens;
+    let stopReason;
+    for (const chunk of chunks) {
+        let usage = null;
+        // According to Anthropic docs, usage data appears in:
+        // 1. message_start event: chunk.message.usage (initial token count)
+        // 2. message_delta event: chunk.usage (final token count)
+        // 3. Direct usage field on chunk
+        if (chunk?.type === "message_start" && chunk?.message?.usage) {
+            usage = chunk?.message?.usage;
+        }
+        else if (chunk?.usage) {
+            usage = chunk?.usage;
+        }
+        else if (chunk?.delta?.usage) {
+            usage = chunk?.delta?.usage;
+        }
+        //Verify usage with optional chaining
+        // Use the highest token counts found (message_delta should have final counts)
+        if (usage?.input_tokens) {
+            inputTokens = Math.max(inputTokens, usage?.input_tokens);
+        }
+        if (usage?.output_tokens) {
+            outputTokens = Math.max(outputTokens, usage?.output_tokens);
+        }
+        if (usage?.cache_creation_input_tokens) {
+            cacheCreationTokens = usage?.cache_creation_input_tokens;
+        }
+        if (usage?.cache_read_input_tokens) {
+            cacheReadTokens = usage?.cache_read_input_tokens;
+        }
+        // Extract stop reason from delta
+        if (chunk?.delta?.stop_reason) {
+            stopReason = chunk?.delta?.stop_reason;
+        }
+    }
+    return {
+        inputTokens,
+        outputTokens,
+        cacheCreationTokens,
+        cacheReadTokens,
+        stopReason,
+    };
+}
+//# sourceMappingURL=tracking.js.map

package/dist/esm/types/anthropic-augmentation.js

@@ -0,0 +1,86 @@
+/**
+ * TypeScript module augmentation for Anthropic SDK
+ *
+ * This file extends Anthropic's existing types to include the usageMetadata field
+ * through TypeScript's declaration merging feature. This allows developers to
+ * use usageMetadata directly in Anthropic API calls without type casting or
+ * TypeScript errors.
+ *
+ * ## What is Module Augmentation?
+ *
+ * Module augmentation is a TypeScript feature that allows you to extend existing
+ * interfaces from external libraries. When you import this middleware, TypeScript
+ * automatically recognizes the usageMetadata field as a valid parameter.
+ *
+ * ## Benefits:
+ * - **Type Safety**: Full IntelliSense support for usageMetadata
+ * - **No Type Casting**: Use usageMetadata directly without `as any`
+ * - **Automatic Validation**: TypeScript validates the structure at compile time
+ * - **Better Developer Experience**: Auto-completion and error detection
+ *
+ * ## Usage Examples:
+ *
+ * ### Basic Usage:
+ * ```typescript
+ * import 'revenium-middleware-anthropic-node';
+ * import Anthropic from '@anthropic-ai/sdk';
+ *
+ * const anthropic = new Anthropic();
+ *
+ * const response = await anthropic.messages.create({
+ *   model: 'claude-3-5-sonnet-latest',
+ *   max_tokens: 1024,
+ *   messages: [{ role: 'user', content: 'Hello!' }],
+ *   usageMetadata: {  // TypeScript recognizes this natively
+ *     subscriber: { id: 'user-123', email: 'user@example.com' },
+ *     organizationId: 'my-company',
+ *     taskType: 'customer-support',
+ *     traceId: 'session-abc-123'
+ *   }
+ * });
+ * ```
+ *
+ * ### Streaming Usage:
+ * ```typescript
+ * const stream = await anthropic.messages.stream({
+ *   model: 'claude-3-5-sonnet-latest',
+ *   max_tokens: 1024,
+ *   messages: [{ role: 'user', content: 'Generate a report' }],
+ *   usageMetadata: {
+ *     taskType: 'content-generation',
+ *     productId: 'report-generator',
+ *     responseQualityScore: 0.95
+ *   }
+ * });
+ * ```
+ *
+ * ### Advanced Usage with All Fields:
+ * ```typescript
+ * const response = await anthropic.messages.create({
+ *   model: 'claude-3-5-sonnet-latest',
+ *   max_tokens: 2048,
+ *   messages: [{ role: 'user', content: 'Complex analysis task' }],
+ *   usageMetadata: {
+ *     subscriber: {
+ *       id: 'user-456',
+ *       email: 'analyst@company.com',
+ *       credential: { name: 'api-key', value: 'sk-...' }
+ *     },
+ *     traceId: 'analysis-session-789',
+ *     taskId: 'task-001',
+ *     taskType: 'data-analysis',
+ *     organizationId: 'enterprise-client',
+ *     subscriptionId: 'premium-plan',
+ *     productId: 'analytics-suite',
+ *     agent: 'data-analyst-bot',
+ *     responseQualityScore: 0.98,
+ *     customField: 'custom-value'  // Extensible with custom fields
+ *   }
+ * });
+ * ```
+ *
+ * @public
+ * @since 1.1.0
+ */
+export {};
+//# sourceMappingURL=anthropic-augmentation.js.map

package/dist/esm/types.js

@@ -0,0 +1,5 @@
+/**
+ * Type definitions for Anthropic middleware
+ */
+export {};
+//# sourceMappingURL=types.js.map