@revenium/anthropic 1.0.0

package/dist/types/config.d.ts

@@ -0,0 +1,43 @@
+import { ReveniumConfig, Logger } from './types';
+/**
+ * Default console logger implementation
+ */
+export declare const defaultLogger: Logger;
+/**
+ * Validate Revenium configuration with enhanced error reporting
+ */
+export declare function validateConfig(config: ReveniumConfig): void;
+/**
+ * Get the current global configuration
+ */
+export declare function getConfig(): ReveniumConfig | null;
+/**
+ * Set the global configuration
+ */
+export declare function setConfig(config: ReveniumConfig): void;
+/**
+ * Get the current logger
+ */
+export declare function getLogger(): Logger;
+/**
+ * Set a custom logger
+ */
+export declare function setLogger(logger: Logger): void;
+/**
+ * Initialize configuration from environment variables
+ */
+export declare function initializeConfig(): boolean;
+/**
+ * Get configuration status
+ */
+export declare function getConfigStatus(): {
+    hasConfig: boolean;
+    hasApiKey: boolean;
+    hasAnthropicKey: boolean;
+    baseUrl: string;
+};
+/**
+ * Validate current configuration
+ */
+export declare function validateCurrentConfig(): boolean;
+//# sourceMappingURL=config.d.ts.map

package/dist/types/constants.d.ts

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

package/dist/types/index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Modern Revenium Anthropic Middleware
+ * Clean architecture without backward compatibility constraints
+ */
+import "./types/anthropic-augmentation";
+import { setConfig } from "./config";
+import { trackUsageAsync } from "./tracking";
+/**
+ * Core types for TypeScript developers using Revenium middleware
+ * @public
+ */
+export type { 
+/** Configuration interface for Revenium middleware */
+ReveniumConfig, 
+/** Usage metadata structure for tracking AI API calls */
+UsageMetadata, 
+/** Logger interface for custom logging implementations */
+Logger, 
+/** Middleware status and health information */
+MiddlewareStatus, 
+/** Tracking data structure for manual usage reporting */
+TrackingData, 
+/** Configuration validation result with detailed feedback */
+ConfigValidationResult, 
+/** Request validation result for API call validation */
+RequestValidationResult, } from "./types";
+import type { MiddlewareStatus } from "./types";
+export { setConfig, setLogger, getLogger, getConfig, getConfigStatus, validateCurrentConfig, } from "./config";
+export { patchAnthropic, unpatchAnthropic, isAnthropicPatched, } from "./wrapper";
+export { sendReveniumMetrics, trackUsageAsync, extractUsageFromStream, } from "./tracking";
+export { getCircuitBreakerStats, resetCircuitBreaker, canExecuteRequest, } from "./utils/circuit-breaker";
+export { validateReveniumConfig, validateAnthropicMessageParams, validateUsageMetadata, } from "./utils/validation";
+export declare function initialize(): void;
+/**
+ * Manual initialization with custom configuration
+ */
+export declare function configure(config: Parameters<typeof setConfig>[0]): void;
+/**
+ * Check if the middleware is properly initialized
+ */
+export declare function isInitialized(): boolean;
+/**
+ * Get comprehensive middleware status
+ */
+export declare function getStatus(): MiddlewareStatus;
+/**
+ * Manually track an Anthropic API call (for cases where auto-patching isn't used)
+ */
+export declare function trackAnthropicCall(trackingData: Parameters<typeof trackUsageAsync>[0]): void;
+/**
+ * Reset middleware to initial state (useful for testing)
+ */
+export declare function reset(): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/tracking.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Tracking implementation for Anthropic middleware with resilience patterns
+ */
+import { TrackingData } from "./types";
+/**
+ * Send tracking data to Revenium API with resilience patterns
+ */
+export declare function sendReveniumMetrics(data: TrackingData): Promise<void>;
+/**
+ * Fire-and-forget async tracking wrapper
+ * Ensures tracking never blocks the main application flow
+ */
+export declare function trackUsageAsync(trackingData: TrackingData): void;
+/**
+ * Extract usage data from Anthropic response
+ */
+export declare function extractUsageFromResponse(response: {
+    usage?: {
+        input_tokens?: number;
+        output_tokens?: number;
+        cache_creation_input_tokens?: number;
+        cache_read_input_tokens?: number;
+    };
+    stop_reason?: string;
+}): {
+    inputTokens: number;
+    outputTokens: number;
+    cacheCreationTokens?: number;
+    cacheReadTokens?: number;
+    stopReason?: string;
+};
+/**
+ * Extract usage data from streaming chunks
+ */
+export declare function extractUsageFromStream(chunks: Array<any>): {
+    inputTokens: number;
+    outputTokens: number;
+    cacheCreationTokens?: number;
+    cacheReadTokens?: number;
+    stopReason?: string;
+};
+//# sourceMappingURL=tracking.d.ts.map

package/dist/types/types/anthropic-augmentation.d.ts

@@ -0,0 +1,182 @@
+/**
+ * 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
+ */
+import { UsageMetadata } from "../types";
+export {};
+/**
+ * Module augmentation for Anthropic SDK message creation interfaces
+ *
+ * This declaration extends the official Anthropic SDK interfaces to include
+ * the usageMetadata field across all message creation methods.
+ */
+declare module "@anthropic-ai/sdk/resources/messages" {
+    /**
+     * Base interface for message creation parameters
+     * Extended to include usageMetadata for all message creation operations
+     */
+    interface MessageCreateParamsBase {
+        /**
+         * Optional metadata for enhanced tracking and analytics
+         *
+         * This field enables rich context collection for business analytics,
+         * user tracking, billing, and operational insights. All nested fields
+         * are optional, allowing flexible usage patterns.
+         *
+         * ## Key Use Cases:
+         * - **User Tracking**: Identify and track individual users or subscribers
+         * - **Session Management**: Group related requests with traceId
+         * - **Business Analytics**: Categorize requests by taskType and productId
+         * - **Multi-tenancy**: Organize usage by organizationId
+         * - **Quality Monitoring**: Track response quality scores
+         * - **Custom Analytics**: Add custom fields for specific business needs
+         *
+         * @example Basic user tracking
+         * ```typescript
+         * usageMetadata: {
+         *   subscriber: { id: 'user-123', email: 'user@example.com' },
+         *   organizationId: 'my-company'
+         * }
+         * ```
+         *
+         * @example Session and task tracking
+         * ```typescript
+         * usageMetadata: {
+         *   traceId: 'session-abc-123',
+         *   taskType: 'customer-support',
+         *   productId: 'help-desk'
+         * }
+         * ```
+         *
+         * @example Advanced analytics
+         * ```typescript
+         * usageMetadata: {
+         *   subscriber: { id: 'user-456' },
+         *   taskType: 'content-generation',
+         *   responseQualityScore: 0.95,
+         *   customMetric: 'high-priority'
+         * }
+         * ```
+         *
+         * @public
+         * @since 1.1.0
+         */
+        usageMetadata?: UsageMetadata;
+    }
+    /**
+     * Non-streaming message creation parameters
+     * Extended to include usageMetadata for standard (non-streaming) requests
+     */
+    interface MessageCreateParamsNonStreaming {
+        /**
+         * Optional metadata for enhanced tracking and analytics
+         *
+         * Provides the same rich tracking capabilities as the base interface,
+         * specifically for non-streaming message creation requests.
+         *
+         * @see MessageCreateParamsBase.usageMetadata for detailed documentation
+         * @public
+         * @since 1.1.0
+         */
+        usageMetadata?: UsageMetadata;
+    }
+    /**
+     * Streaming message creation parameters
+     * Extended to include usageMetadata for streaming requests
+     */
+    interface MessageCreateParamsStreaming {
+        /**
+         * Optional metadata for enhanced tracking and analytics
+         *
+         * Provides the same rich tracking capabilities as the base interface,
+         * specifically for streaming message creation requests. Particularly
+         * useful for tracking long-running or real-time interactions.
+         *
+         * @see MessageCreateParamsBase.usageMetadata for detailed documentation
+         * @public
+         * @since 1.1.0
+         */
+        usageMetadata?: UsageMetadata;
+    }
+}
+//# sourceMappingURL=anthropic-augmentation.d.ts.map