@revenium/anthropic 1.0.0

package/dist/cjs/tracking.js

@@ -0,0 +1,252 @@
+"use strict";
+/**
+ * Tracking implementation for Anthropic middleware with resilience patterns
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sendReveniumMetrics = sendReveniumMetrics;
+exports.trackUsageAsync = trackUsageAsync;
+exports.extractUsageFromResponse = extractUsageFromResponse;
+exports.extractUsageFromStream = extractUsageFromStream;
+const node_fetch_1 = __importDefault(require("node-fetch"));
+const config_1 = require("./config");
+const circuit_breaker_1 = require("./utils/circuit-breaker");
+const error_handling_1 = require("./utils/error-handling");
+const constants_1 = require("./constants");
+// Global logger
+const logger = (0, config_1.getLogger)();
+/**
+ * Send tracking data to Revenium API with resilience patterns
+ */
+async function sendReveniumMetrics(data) {
+    const config = (0, config_1.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": constants_1.LOGGING_CONFIG.USER_AGENT,
+        },
+        body: JSON.stringify(payload),
+        timeout: config.apiTimeout || constants_1.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 (0, circuit_breaker_1.executeWithCircuitBreaker)(async () => {
+            return (0, error_handling_1.withRetry)(async () => {
+                logger.debug("Sending request to Revenium API", {
+                    requestId,
+                    url: `${config.reveniumBaseUrl}${constants_1.API_ENDPOINTS.AI_COMPLETIONS}`,
+                    payloadSize: requestOptions.body.length,
+                });
+                let response;
+                try {
+                    response = await (0, node_fetch_1.default)(`${config.reveniumBaseUrl}${constants_1.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 = (0, error_handling_1.createErrorContext)()
+                        .withRequestId(requestId)
+                        .withModel(data.model)
+                        .withStatus(response.status)
+                        .with("responseBody", responseText)
+                        .build();
+                    throw new error_handling_1.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 || constants_1.DEFAULT_CONFIG.MAX_RETRIES);
+        });
+    }
+    catch (error) {
+        const errorContext = (0, error_handling_1.createErrorContext)()
+            .withRequestId(requestId)
+            .withModel(data.model)
+            .withDuration(data.duration)
+            .build();
+        (0, error_handling_1.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 (constants_1.ANTHROPIC_PATTERNS.REVENIUM_STOP_REASON_MAP[stopReason] || "END");
+}
+/**
+ * Fire-and-forget async tracking wrapper
+ * Ensures tracking never blocks the main application flow
+ */
+function trackUsageAsync(trackingData) {
+    const config = (0, config_1.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 = (0, error_handling_1.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
+ */
+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
+ */
+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/cjs/types/anthropic-augmentation.js

@@ -0,0 +1,87 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=anthropic-augmentation.js.map

package/dist/cjs/types.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * Type definitions for Anthropic middleware
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/cjs/utils/circuit-breaker.js

@@ -0,0 +1,232 @@
+"use strict";
+/**
+ * Circuit breaker pattern implementation for handling repeated failures
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CircuitBreaker = exports.DEFAULT_CIRCUIT_CONFIG = exports.CircuitState = void 0;
+exports.getCircuitBreaker = getCircuitBreaker;
+exports.resetCircuitBreaker = resetCircuitBreaker;
+exports.canExecuteRequest = canExecuteRequest;
+exports.executeWithCircuitBreaker = executeWithCircuitBreaker;
+exports.getCircuitBreakerStats = getCircuitBreakerStats;
+const constants_1 = require("../constants");
+/**
+ * Circuit breaker states
+ */
+var CircuitState;
+(function (CircuitState) {
+    CircuitState["CLOSED"] = "CLOSED";
+    CircuitState["OPEN"] = "OPEN";
+    CircuitState["HALF_OPEN"] = "HALF_OPEN"; // Testing if service recovered
+})(CircuitState || (exports.CircuitState = CircuitState = {}));
+/**
+ * Default circuit breaker configuration
+ */
+exports.DEFAULT_CIRCUIT_CONFIG = {
+    failureThreshold: constants_1.CIRCUIT_BREAKER_CONFIG.FAILURE_THRESHOLD,
+    recoveryTimeout: constants_1.CIRCUIT_BREAKER_CONFIG.RECOVERY_TIMEOUT,
+    successThreshold: constants_1.CIRCUIT_BREAKER_CONFIG.SUCCESS_THRESHOLD,
+    timeWindow: constants_1.CIRCUIT_BREAKER_CONFIG.TIME_WINDOW
+};
+/**
+ * Circuit breaker implementation
+ */
+class CircuitBreaker {
+    constructor(config = exports.DEFAULT_CIRCUIT_CONFIG) {
+        this.config = config;
+        this.state = CircuitState.CLOSED;
+        this.failureCount = 0;
+        this.successCount = 0;
+        this.lastFailureTime = 0;
+        this.failures = []; // Timestamps of failures
+        this.lastCleanupTime = 0;
+        this.maxFailureHistorySize = constants_1.CIRCUIT_BREAKER_CONFIG.MAX_FAILURE_HISTORY_SIZE;
+        this.lastCleanupTime = Date.now();
+    }
+    /**
+     * Execute a function with circuit breaker protection
+     */
+    async execute(fn) {
+        if (this.state === CircuitState.OPEN) {
+            if (this.shouldAttemptRecovery()) {
+                this.state = CircuitState.HALF_OPEN;
+                this.successCount = 0;
+            }
+            else {
+                throw new Error('Circuit breaker is OPEN - failing fast');
+            }
+        }
+        try {
+            const result = await fn();
+            this.onSuccess();
+            return result;
+        }
+        catch (error) {
+            this.onFailure();
+            throw error;
+        }
+    }
+    /**
+     * Check if circuit breaker allows execution
+     */
+    canExecute() {
+        if (this.state === CircuitState.CLOSED || this.state === CircuitState.HALF_OPEN)
+            return true;
+        if (this.state === CircuitState.OPEN && this.shouldAttemptRecovery())
+            return true;
+        return false;
+    }
+    /**
+     * Get current circuit breaker state
+     */
+    getState() {
+        return this.state;
+    }
+    /**
+     * Get circuit breaker statistics
+     */
+    getStats() {
+        const now = Date.now();
+        const recentFailures = this.failures.filter(timestamp => now - timestamp < this.config.timeWindow).length;
+        let timeUntilRecovery;
+        if (this.state === CircuitState.OPEN) {
+            const timeSinceLastFailure = now - this.lastFailureTime;
+            timeUntilRecovery = Math.max(0, this.config.recoveryTimeout - timeSinceLastFailure);
+        }
+        return {
+            state: this.state,
+            failureCount: this.failureCount,
+            successCount: this.successCount,
+            recentFailures,
+            timeUntilRecovery
+        };
+    }
+    /**
+     * Reset circuit breaker to closed state
+     */
+    reset() {
+        this.state = CircuitState.CLOSED;
+        this.failureCount = 0;
+        this.successCount = 0;
+        this.lastFailureTime = 0;
+        this.lastCleanupTime = Date.now();
+        this.failures = [];
+    }
+    /**
+     * Handle successful execution
+     */
+    onSuccess() {
+        if (this.state === CircuitState.HALF_OPEN) {
+            this.successCount++;
+            if (this.successCount >= this.config.successThreshold) {
+                this.state = CircuitState.CLOSED;
+                this.failureCount = 0;
+                this.failures = [];
+            }
+        }
+        else if (this.state === CircuitState.CLOSED) {
+            // Reset failure count on success in closed state
+            this.failureCount = 0;
+            this.performPeriodicCleanup();
+        }
+    }
+    /**
+     * Handle failed execution
+     */
+    onFailure() {
+        const now = Date.now();
+        this.failureCount++;
+        this.lastFailureTime = now;
+        // Prevent unbounded growth of failures array
+        if (this.failures.length >= this.maxFailureHistorySize) {
+            this.failures = this.failures.slice(-Math.floor(this.maxFailureHistorySize / 2));
+        }
+        this.failures.push(now);
+        this.cleanupOldFailures();
+        if (this.state === CircuitState.HALF_OPEN) {
+            // Go back to open state on any failure in half-open
+            this.state = CircuitState.OPEN;
+            this.successCount = 0;
+        }
+        else if (this.state === CircuitState.CLOSED) {
+            // Check if we should open the circuit
+            const recentFailures = this.failures.filter(timestamp => now - timestamp < this.config.timeWindow).length;
+            if (recentFailures >= this.config.failureThreshold) {
+                this.state = CircuitState.OPEN;
+            }
+        }
+    }
+    /**
+     * Check if we should attempt recovery from open state
+     */
+    shouldAttemptRecovery() {
+        const now = Date.now();
+        return now - this.lastFailureTime >= this.config.recoveryTimeout;
+    }
+    /**
+     * Remove old failure timestamps outside the time window
+     */
+    cleanupOldFailures() {
+        const now = Date.now();
+        this.failures = this.failures.filter(timestamp => now - timestamp < this.config.timeWindow);
+    }
+    /**
+     * Perform periodic cleanup to prevent memory leaks
+     * Only runs cleanup if enough time has passed since last cleanup
+     */
+    performPeriodicCleanup() {
+        const now = Date.now();
+        const timeSinceLastCleanup = now - this.lastCleanupTime;
+        // Use constants for cleanup thresholds
+        if (timeSinceLastCleanup > constants_1.CIRCUIT_BREAKER_CONFIG.CLEANUP_INTERVAL ||
+            this.failures.length > constants_1.CIRCUIT_BREAKER_CONFIG.CLEANUP_SIZE_THRESHOLD) {
+            this.cleanupOldFailures();
+            this.lastCleanupTime = now;
+        }
+    }
+}
+exports.CircuitBreaker = CircuitBreaker;
+/**
+ * Global circuit breaker instance for Revenium API calls
+ */
+let globalCircuitBreaker = null;
+/**
+ * Get or create the global circuit breaker instance
+ */
+function getCircuitBreaker(config) {
+    if (!globalCircuitBreaker) {
+        const finalConfig = config ? { ...exports.DEFAULT_CIRCUIT_CONFIG, ...config } : exports.DEFAULT_CIRCUIT_CONFIG;
+        globalCircuitBreaker = new CircuitBreaker(finalConfig);
+    }
+    return globalCircuitBreaker;
+}
+/**
+ * Reset the global circuit breaker
+ */
+function resetCircuitBreaker() {
+    if (globalCircuitBreaker) {
+        globalCircuitBreaker.reset();
+    }
+}
+/**
+ * Check if the global circuit breaker allows execution
+ */
+function canExecuteRequest() {
+    const circuitBreaker = getCircuitBreaker();
+    return circuitBreaker.canExecute();
+}
+/**
+ * Execute a function with global circuit breaker protection
+ */
+async function executeWithCircuitBreaker(fn) {
+    const circuitBreaker = getCircuitBreaker();
+    return circuitBreaker.execute(fn);
+}
+/**
+ * Get global circuit breaker statistics
+ */
+function getCircuitBreakerStats() {
+    const circuitBreaker = getCircuitBreaker();
+    return circuitBreaker.getStats();
+}
+//# sourceMappingURL=circuit-breaker.js.map