@revenium/anthropic 1.0.0

package/dist/types/types.d.ts

@@ -0,0 +1,647 @@
+/**
+ * Type definitions for Anthropic middleware
+ */
+/**
+ * Credential information for subscriber authentication
+ *
+ * @public
+ * @example
+ * ```typescript
+ * const credential: Credential = {
+ *   name: 'api-key',
+ *   value: 'sk-1234567890abcdef'
+ * };
+ * ```
+ */
+export interface Credential {
+    /** The name/type of the credential (e.g., 'api-key', 'token', 'bearer') */
+    name: string;
+    /** The actual credential value */
+    value: string;
+}
+/**
+ * Subscriber information for Revenium API
+ * All fields are optional to allow flexible usage
+ *
+ * @public
+ * @example
+ * ```typescript
+ * const subscriber: Subscriber = {
+ *   id: 'user-123',
+ *   email: 'user@example.com',
+ *   credential: {
+ *     name: 'api-key',
+ *     value: 'sk-1234567890abcdef'
+ *   }
+ * };
+ * ```
+ */
+export interface Subscriber {
+    /** Unique identifier for the subscriber */
+    id?: string;
+    /** Email address of the subscriber */
+    email?: string;
+    /** Authentication credential for the subscriber */
+    credential?: Credential;
+}
+/**
+ * Revenium configuration interface
+ *
+ * @public
+ * @example
+ * ```typescript
+ * const config: ReveniumConfig = {
+ *   reveniumApiKey: 'hak_1234567890abcdef',
+ *   reveniumBaseUrl: 'https://api.revenium.io/meter/v2',
+ *   anthropicApiKey: 'sk-ant-1234567890abcdef',
+ *   apiTimeout: 8000,
+ *   failSilent: true,
+ *   maxRetries: 3
+ * };
+ * ```
+ */
+export interface ReveniumConfig {
+    /** Revenium API key (starts with hak_) - required for tracking */
+    reveniumApiKey: string;
+    /** Revenium base URL - endpoint for usage tracking */
+    reveniumBaseUrl: string;
+    /** Anthropic API key (optional if already configured in environment) */
+    anthropicApiKey?: string;
+    /** API timeout in milliseconds (default: 5000) */
+    apiTimeout?: number;
+    /** Whether to fail silently if Revenium tracking fails (default: true) */
+    failSilent?: boolean;
+    /** Maximum retries for failed Revenium API calls (default: 3) */
+    maxRetries?: number;
+}
+/**
+ * Usage metadata for enhanced tracking and analytics
+ *
+ * @public
+ * @example
+ * ```typescript
+ * const metadata: UsageMetadata = {
+ *   subscriber: {
+ *     id: 'user-123',
+ *     email: 'user@example.com'
+ *   },
+ *   traceId: 'trace-abc-123',
+ *   taskType: 'customer-support',
+ *   organizationId: 'org-456',
+ *   productId: 'chat-assistant',
+ *   responseQualityScore: 0.95
+ * };
+ * ```
+ */
+export interface UsageMetadata {
+    /** User identification information with nested structure for detailed tracking */
+    subscriber?: Subscriber;
+    /** Unique identifier for conversation/session tracking across multiple requests */
+    traceId?: string;
+    /** Identifier for specific AI task grouping within a trace */
+    taskId?: string;
+    /** Classification of AI operation (e.g., 'customer-support', 'content-generation', 'code-review') */
+    taskType?: string;
+    /** Customer organization identifier for multi-tenant applications */
+    organizationId?: string;
+    /** Reference to billing plan or subscription tier */
+    subscriptionId?: string;
+    /** Product or feature identifier that is using AI services */
+    productId?: string;
+    /** Agent or bot identifier for automated systems */
+    agent?: string;
+    /** Quality score of AI response (0.0-1.0) for performance tracking */
+    responseQualityScore?: number;
+    /** Allow additional custom fields for extensibility */
+    [key: string]: unknown;
+}
+/**
+ * Logger interface for consistent logging across the middleware
+ *
+ * @public
+ * @example
+ * ```typescript
+ * const customLogger: Logger = {
+ *   debug: (msg, ctx) => console.debug(`[DEBUG] ${msg}`, ctx),
+ *   info: (msg, ctx) => console.info(`[INFO] ${msg}`, ctx),
+ *   warn: (msg, ctx) => console.warn(`[WARN] ${msg}`, ctx),
+ *   error: (msg, ctx) => console.error(`[ERROR] ${msg}`, ctx)
+ * };
+ * ```
+ */
+export interface Logger {
+    /** Log debug messages (only shown when debug mode is enabled) */
+    debug(message: string, context?: Record<string, unknown>): void;
+    /** Log informational messages */
+    info(message: string, context?: Record<string, unknown>): void;
+    /** Log warning messages */
+    warn(message: string, context?: Record<string, unknown>): void;
+    /** Log error messages */
+    error(message: string, context?: Record<string, unknown>): void;
+}
+/**
+ * Middleware status and health information
+ *
+ * @public
+ * @example
+ * ```typescript
+ * const status: MiddlewareStatus = {
+ *   initialized: true,
+ *   patched: true,
+ *   hasConfig: true,
+ *   anthropicVersion: '0.55.1',
+ *   circuitBreakerState: 'CLOSED'
+ * };
+ * ```
+ */
+export interface MiddlewareStatus {
+    /** Whether the middleware has been successfully initialized */
+    initialized: boolean;
+    /** Whether the Anthropic SDK has been patched for tracking */
+    patched: boolean;
+    /** Whether a valid configuration is available */
+    hasConfig: boolean;
+    /** Version of the Anthropic SDK if available */
+    anthropicVersion?: string;
+    /** Current state of the circuit breaker (CLOSED, OPEN, HALF_OPEN) */
+    circuitBreakerState?: string;
+}
+/**
+ * Tracking data structure for manual usage reporting to Revenium API
+ *
+ * @public
+ * @example
+ * ```typescript
+ * const trackingData: TrackingData = {
+ *   requestId: 'req-123',
+ *   model: 'claude-3-5-sonnet-latest',
+ *   inputTokens: 150,
+ *   outputTokens: 75,
+ *   duration: 1250,
+ *   isStreamed: false,
+ *   stopReason: 'end_turn',
+ *   requestTime: new Date('2024-01-01T10:00:00Z'),
+ *   responseTime: new Date('2024-01-01T10:00:01Z')
+ * };
+ * ```
+ */
+export interface TrackingData {
+    /** Unique identifier for the API request */
+    requestId: string;
+    /** AI model used for the request (e.g., 'claude-3-5-sonnet-latest') */
+    model: string;
+    /** Number of tokens in the input/prompt */
+    inputTokens: number;
+    /** Number of tokens in the output/response */
+    outputTokens: number;
+    /** Number of tokens used for cache creation (if applicable) */
+    cacheCreationTokens?: number;
+    /** Number of tokens read from cache (if applicable) */
+    cacheReadTokens?: number;
+    /** Total request duration in milliseconds */
+    duration: number;
+    /** Whether the response was streamed or returned all at once */
+    isStreamed: boolean;
+    /** Reason why the completion stopped (e.g., 'end_turn', 'max_tokens', 'stop_sequence') */
+    stopReason?: string;
+    /** Additional usage metadata for enhanced tracking */
+    metadata?: UsageMetadata;
+    /** Timestamp when the request was initiated */
+    requestTime: Date;
+    /** Timestamp when the response was completed */
+    responseTime: Date;
+    /** Time to first token in milliseconds (for streaming responses) */
+    timeToFirstToken?: number;
+}
+/**
+ * Internal payload structure for Revenium API
+ * This interface represents the exact format expected by Revenium's tracking endpoint
+ *
+ * @internal
+ * @example
+ * ```typescript
+ * const payload: ReveniumPayload = {
+ *   stopReason: 'end_turn',
+ *   costType: 'AI',
+ *   isStreamed: false,
+ *   operationType: 'CHAT',
+ *   inputTokenCount: 150,
+ *   outputTokenCount: 75,
+ *   reasoningTokenCount: 0,
+ *   cacheCreationTokenCount: 0,
+ *   cacheReadTokenCount: 0,
+ *   totalTokenCount: 225,
+ *   model: 'claude-3-5-sonnet-latest',
+ *   transactionId: 'txn-123',
+ *   responseTime: '2024-01-01T10:00:01.000Z',
+ *   requestDuration: 1250,
+ *   provider: 'anthropic'
+ * };
+ * ```
+ */
+export interface ReveniumPayload {
+    /** Reason why the AI completion stopped */
+    stopReason: string;
+    /** Type of cost being tracked (always 'AI' for this middleware) */
+    costType: "AI";
+    /** Whether the response was streamed */
+    isStreamed: boolean;
+    /** Type of AI task being performed */
+    taskType?: string;
+    /** Agent or bot identifier */
+    agent?: string;
+    /** Type of AI operation (always 'CHAT' for Anthropic) */
+    operationType: "CHAT";
+    /** Number of input tokens consumed */
+    inputTokenCount: number;
+    /** Number of output tokens generated */
+    outputTokenCount: number;
+    /** Number of reasoning tokens used (for models that support reasoning) */
+    reasoningTokenCount: number;
+    /** Number of tokens used for cache creation */
+    cacheCreationTokenCount: number;
+    /** Number of tokens read from cache */
+    cacheReadTokenCount: number;
+    /** Total token count (sum of all token types) */
+    totalTokenCount: number;
+    /** Organization identifier for multi-tenant tracking */
+    organizationId?: string;
+    /** Product identifier */
+    productId?: string;
+    /** Subscriber information */
+    subscriber?: Subscriber;
+    /** Subscription identifier */
+    subscriptionId?: string;
+    /** AI model identifier */
+    model: string;
+    /** Unique transaction identifier */
+    transactionId: string;
+    /** ISO timestamp of response completion */
+    responseTime: string;
+    /** Request duration in milliseconds */
+    requestDuration: number;
+    /** AI provider name (always 'anthropic' for this middleware) */
+    provider: string;
+    /** ISO timestamp when the request was initiated */
+    requestTime: string;
+    /** ISO timestamp when completion generation started */
+    completionStartTime: string;
+    /** Time to first token in milliseconds */
+    timeToFirstToken: number;
+    /** Optional trace identifier for request correlation */
+    traceId?: string;
+    /** Source identifier for the middleware */
+    middlewareSource: string;
+}
+/**
+ * Anthropic content block types for message validation
+ * These interfaces match Anthropic's API specification for different content types
+ *
+ * @public
+ */
+/**
+ * Text content block for Anthropic messages
+ *
+ * @public
+ */
+export interface AnthropicTextContent {
+    /** Content type identifier */
+    type: "text";
+    /** The actual text content */
+    text: string;
+}
+/**
+ * Image content block for Anthropic messages
+ *
+ * @public
+ */
+export interface AnthropicImageContent {
+    /** Content type identifier */
+    type: "image";
+    /** Image source configuration */
+    source: {
+        /** Source type (always 'base64' for direct image data) */
+        type: "base64";
+        /** MIME type of the image */
+        media_type: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
+        /** Base64-encoded image data */
+        data: string;
+    };
+}
+/**
+ * Tool use content block for Anthropic messages
+ *
+ * @public
+ */
+export interface AnthropicToolUseContent {
+    /** Content type identifier */
+    type: "tool_use";
+    /** Unique identifier for this tool use */
+    id: string;
+    /** Name of the tool being used */
+    name: string;
+    /** Input parameters for the tool */
+    input: Record<string, unknown>;
+}
+/**
+ * Tool result content block for Anthropic messages
+ *
+ * @public
+ */
+export interface AnthropicToolResultContent {
+    /** Content type identifier */
+    type: "tool_result";
+    /** ID of the tool use this result corresponds to */
+    tool_use_id: string;
+    /** Result content (can be string or structured text blocks) */
+    content?: string | AnthropicTextContent[];
+    /** Whether this result represents an error */
+    is_error?: boolean;
+}
+/**
+ * Union type for all possible Anthropic content blocks
+ *
+ * @public
+ */
+export type AnthropicContentBlock = AnthropicTextContent | AnthropicImageContent | AnthropicToolUseContent | AnthropicToolResultContent;
+/**
+ * Anthropic message structure for validation
+ *
+ * @public
+ * @example
+ * ```typescript
+ * const message: AnthropicMessage = {
+ *   role: 'user',
+ *   content: 'Hello, how can you help me today?'
+ * };
+ * ```
+ */
+export interface AnthropicMessage {
+    /** Role of the message sender */
+    role: "user" | "assistant" | "system";
+    /** Message content (can be simple string or structured content blocks) */
+    content: string | AnthropicContentBlock[];
+}
+/**
+ * Anthropic tool definition for function calling
+ *
+ * @public
+ * @example
+ * ```typescript
+ * const tool: AnthropicTool = {
+ *   name: 'get_weather',
+ *   description: 'Get current weather for a location',
+ *   input_schema: {
+ *     type: 'object',
+ *     properties: {
+ *       location: {
+ *         type: 'string',
+ *         description: 'City name'
+ *       }
+ *     },
+ *     required: ['location']
+ *   }
+ * };
+ * ```
+ */
+export interface AnthropicTool {
+    /** Name of the tool function */
+    name: string;
+    /** Human-readable description of what the tool does */
+    description: string;
+    /** JSON Schema defining the tool's input parameters */
+    input_schema: {
+        /** Schema type (always 'object' for tool inputs) */
+        type: "object";
+        /** Property definitions for the tool parameters */
+        properties: Record<string, {
+            /** Parameter data type */
+            type: "string" | "number" | "boolean" | "array" | "object";
+            /** Human-readable description of the parameter */
+            description?: string;
+            /** Allowed values for string parameters */
+            enum?: string[];
+            /** Item type definition for array parameters */
+            items?: {
+                type: string;
+            };
+        }>;
+        /** List of required parameter names */
+        required?: string[];
+    };
+}
+/**
+ * Anthropic tool choice configuration for controlling tool usage
+ *
+ * @public
+ * @example
+ * ```typescript
+ * const toolChoice: AnthropicToolChoice = {
+ *   type: 'tool',
+ *   name: 'get_weather'
+ * };
+ * ```
+ */
+export interface AnthropicToolChoice {
+    /** How the model should choose tools ('auto', 'any', or 'tool') */
+    type: "auto" | "any" | "tool";
+    /** Specific tool name (required when type is 'tool') */
+    name?: string;
+}
+/**
+ * Anthropic message creation parameters
+ * Complete interface for all parameters supported by Anthropic's messages API
+ *
+ * @public
+ * @example
+ * ```typescript
+ * const params: AnthropicMessageParams = {
+ *   model: 'claude-3-5-sonnet-latest',
+ *   messages: [{ role: 'user', content: 'Hello!' }],
+ *   max_tokens: 1024,
+ *   temperature: 0.7,
+ *   usageMetadata: {
+ *     subscriber: { id: 'user-123' }
+ *   }
+ * };
+ * ```
+ */
+export interface AnthropicMessageParams {
+    /** AI model to use (e.g., 'claude-3-5-sonnet-latest') */
+    model: string;
+    /** Array of conversation messages */
+    messages: AnthropicMessage[];
+    /** Maximum number of tokens to generate */
+    max_tokens?: number;
+    /** Sampling temperature (0.0 to 1.0) */
+    temperature?: number;
+    /** Nucleus sampling parameter (0.0 to 1.0) */
+    top_p?: number;
+    /** Top-k sampling parameter */
+    top_k?: number;
+    /** Whether to stream the response */
+    stream?: boolean;
+    /** Sequences that will stop generation */
+    stop_sequences?: string[];
+    /** System message to set context */
+    system?: string;
+    /** Available tools for function calling */
+    tools?: AnthropicTool[];
+    /** Tool usage configuration */
+    tool_choice?: AnthropicToolChoice;
+    /** Usage metadata for tracking (added by this middleware) */
+    usageMetadata?: UsageMetadata;
+}
+/**
+ * Anthropic response content blocks
+ */
+export interface AnthropicResponseTextContent {
+    type: "text";
+    text: string;
+}
+export interface AnthropicResponseToolUseContent {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+export type AnthropicResponseContent = AnthropicResponseTextContent | AnthropicResponseToolUseContent;
+/**
+ * Anthropic usage statistics
+ */
+export interface AnthropicUsage {
+    input_tokens: number;
+    output_tokens: number;
+    cache_creation_input_tokens?: number;
+    cache_read_input_tokens?: number;
+}
+/**
+ * Anthropic response structure
+ */
+export interface AnthropicResponse {
+    id: string;
+    type: "message";
+    role: "assistant";
+    content: AnthropicResponseContent[];
+    model: string;
+    stop_reason: "end_turn" | "max_tokens" | "stop_sequence" | "tool_use";
+    stop_sequence?: string;
+    usage: AnthropicUsage;
+}
+/**
+ * Stream chunk delta types
+ */
+export interface AnthropicStreamTextDelta {
+    type: "text_delta";
+    text: string;
+}
+export interface AnthropicStreamInputJsonDelta {
+    type: "input_json_delta";
+    partial_json: string;
+}
+export type AnthropicStreamDelta = AnthropicStreamTextDelta | AnthropicStreamInputJsonDelta | {
+    type: string;
+    text?: string;
+    stop_reason?: "end_turn" | "max_tokens" | "stop_sequence" | "tool_use";
+};
+/**
+ * Stream chunk structure for Anthropic streaming
+ */
+export interface AnthropicStreamChunk {
+    type: "message_start" | "content_block_start" | "content_block_delta" | "content_block_stop" | "message_delta" | "message_stop";
+    message?: Partial<AnthropicResponse>;
+    content_block?: AnthropicResponseContent;
+    delta?: AnthropicStreamDelta;
+    usage?: Partial<AnthropicUsage>;
+}
+/**
+ * Configuration validation result with detailed feedback
+ *
+ * @public
+ * @example
+ * ```typescript
+ * const result: ConfigValidationResult = {
+ *   isValid: false,
+ *   errors: ['Missing reveniumApiKey'],
+ *   warnings: ['apiTimeout is very high'],
+ *   suggestions: ['Set REVENIUM_METERING_API_KEY environment variable']
+ * };
+ * ```
+ */
+export interface ConfigValidationResult {
+    /** Whether the configuration is valid and ready to use */
+    isValid: boolean;
+    /** Array of validation errors that prevent usage */
+    errors: string[];
+    /** Array of validation warnings (non-blocking issues) */
+    warnings: string[];
+    /** The validated configuration object (if valid) */
+    config?: ReveniumConfig;
+    /** Helpful suggestions for fixing validation issues */
+    suggestions?: string[];
+}
+/**
+ * Request validation result for API call validation
+ *
+ * @public
+ * @example
+ * ```typescript
+ * const result: RequestValidationResult = {
+ *   isValid: true,
+ *   errors: [],
+ *   warnings: ['Large message count may impact performance']
+ * };
+ * ```
+ */
+export interface RequestValidationResult {
+    /** Whether the request parameters are valid */
+    isValid: boolean;
+    /** Array of validation errors that prevent the request */
+    errors: string[];
+    /** Array of validation warnings (non-blocking issues) */
+    warnings: string[];
+}
+/**
+ * Anthropic SDK method signatures for patching
+ */
+export interface AnthropicMethodSignatures {
+    create: (params: AnthropicMessageParams, options?: Record<string, unknown>) => Promise<AnthropicResponse>;
+    stream: (params: AnthropicMessageParams, options?: Record<string, unknown>) => AsyncIterable<AnthropicStreamChunk>;
+}
+/**
+ * Patching context for tracking
+ */
+export interface PatchingContext {
+    originalMethods: Partial<AnthropicMethodSignatures>;
+    isPatched: boolean;
+    patchedInstances: WeakSet<object>;
+}
+/**
+ * HTTP request options for Revenium API
+ */
+export interface ReveniumRequestOptions {
+    method: "POST";
+    headers: {
+        "Content-Type": "application/json";
+        "x-api-key": string;
+        "User-Agent": string;
+        [key: string]: string;
+    };
+    body: string;
+    timeout?: number;
+    signal?: AbortSignal;
+}
+/**
+ * Environment configuration
+ */
+export interface EnvironmentConfig {
+    reveniumApiKey?: string;
+    reveniumBaseUrl?: string;
+    anthropicApiKey?: string;
+    debug?: boolean;
+    logLevel?: string;
+    apiTimeout?: string;
+    failSilent?: string;
+    maxRetries?: string;
+}
+//# sourceMappingURL=types.d.ts.map