@revenium/anthropic 1.0.8 → 1.1.0

package/dist/types/types.d.ts

@@ -3,15 +3,6 @@
  */
 /**
  * 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') */
@@ -22,19 +13,6 @@ export interface Credential {
 /**
  * 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 */
@@ -46,19 +24,6 @@ export interface Subscriber {
 }
 /**
  * Revenium configuration interface
- *
- * @public
- * @example
- * ```typescript
- * const config: ReveniumConfig = {
- *   reveniumApiKey: 'hak_your_key_value_here',
- *   reveniumBaseUrl: 'https://api.revenium.ai',
- *   anthropicApiKey: 'sk-ant-your_api_key_here',
- *   apiTimeout: 8000,
- *   failSilent: true,
- *   maxRetries: 3
- * };
- * ```
  */
 export interface ReveniumConfig {
     /** Revenium API key (starts with hak_) - required for tracking */
@@ -73,25 +38,20 @@ export interface ReveniumConfig {
     failSilent?: boolean;
     /** Maximum retries for failed Revenium API calls (default: 3) */
     maxRetries?: number;
+    /**
+     * Enable cost/metrics summary output to terminal after each API request.
+     * - true or 'human': Human-readable format with emojis
+     * - 'json': JSON format for automation
+     * - false: Disabled (default)
+     */
+    printSummary?: boolean | SummaryFormat;
+    /** Revenium team ID for fetching cost metrics from the API. If not provided, the summary will still be printed but without cost information. */
+    teamId?: string;
+    /** Whether to capture prompts and responses for analysis (default: false) */
+    capturePrompts?: boolean;
 }
 /**
  * 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 */
@@ -110,22 +70,13 @@ export interface UsageMetadata {
     agent?: string;
     /** Quality score of AI response (0.0-1.0) for performance tracking */
     responseQualityScore?: number;
+    /** Whether to capture prompts and responses for this request (overrides global config) */
+    capturePrompts?: boolean;
     /** 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) */
@@ -139,18 +90,6 @@ export interface Logger {
 }
 /**
  * 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 */
@@ -166,22 +105,6 @@ export interface MiddlewareStatus {
 }
 /**
  * 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 */
@@ -210,32 +133,12 @@ export interface TrackingData {
     responseTime: Date;
     /** Time to first token in milliseconds (for streaming responses) */
     timeToFirstToken?: number;
+    /** Request body containing Anthropic message parameters */
+    requestBody?: AnthropicMessageParams;
 }
 /**
  * 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 */
@@ -292,17 +195,22 @@ export interface ReveniumPayload {
     responseQualityScore?: number;
     /** Source identifier for the middleware */
     middlewareSource: string;
+    environment?: string;
+    operationSubtype?: string;
+    retryNumber?: number;
+    parentTransactionId?: string;
+    transactionName?: string;
+    region?: string;
+    credentialAlias?: string;
+    traceType?: string;
+    traceName?: 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 */
@@ -312,8 +220,6 @@ export interface AnthropicTextContent {
 }
 /**
  * Image content block for Anthropic messages
- *
- * @public
  */
 export interface AnthropicImageContent {
     /** Content type identifier */
@@ -330,8 +236,6 @@ export interface AnthropicImageContent {
 }
 /**
  * Tool use content block for Anthropic messages
- *
- * @public
  */
 export interface AnthropicToolUseContent {
     /** Content type identifier */
@@ -345,8 +249,6 @@ export interface AnthropicToolUseContent {
 }
 /**
  * Tool result content block for Anthropic messages
- *
- * @public
  */
 export interface AnthropicToolResultContent {
     /** Content type identifier */
@@ -360,21 +262,10 @@ export interface AnthropicToolResultContent {
 }
 /**
  * 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 */
@@ -384,25 +275,6 @@ export interface AnthropicMessage {
 }
 /**
  * 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 */
@@ -432,15 +304,6 @@ export interface AnthropicTool {
 }
 /**
  * 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') */
@@ -451,20 +314,6 @@ export interface AnthropicToolChoice {
 /**
  * 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') */
@@ -483,8 +332,14 @@ export interface AnthropicMessageParams {
     stream?: boolean;
     /** Sequences that will stop generation */
     stop_sequences?: string[];
-    /** System message to set context */
-    system?: string;
+    /** System message to set context - can be string or array of content blocks */
+    system?: string | Array<{
+        type: "text";
+        text: string;
+    } | {
+        type: "image";
+        source: unknown;
+    }>;
     /** Available tools for function calling */
     tools?: AnthropicTool[];
     /** Tool usage configuration */
@@ -556,17 +411,6 @@ export interface AnthropicStreamChunk {
 }
 /**
  * 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 */
@@ -582,16 +426,6 @@ export interface ConfigValidationResult {
 }
 /**
  * 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 */
@@ -643,5 +477,14 @@ export interface EnvironmentConfig {
     apiTimeout?: string;
     failSilent?: string;
     maxRetries?: string;
+    printSummary?: string;
+    teamId?: string;
+    capturePrompts?: string;
 }
+/**
+ * Summary output format options
+ * - 'human': Human-readable formatted output with emojis (default when enabled)
+ * - 'json': JSON formatted output for automation/parsing
+ */
+export type SummaryFormat = "human" | "json";
 //# sourceMappingURL=types.d.ts.map

package/dist/types/utils/prompt-extraction.d.ts

@@ -0,0 +1,10 @@
+import { AnthropicMessageParams, AnthropicResponse, UsageMetadata } from "../types";
+export interface PromptData {
+    systemPrompt?: string;
+    inputMessages?: string;
+    outputResponse?: string;
+    promptsTruncated: boolean;
+}
+export declare function shouldCapturePrompts(metadata?: UsageMetadata): boolean;
+export declare function extractPrompts(params: AnthropicMessageParams, response: AnthropicResponse, metadata?: UsageMetadata): PromptData | null;
+//# sourceMappingURL=prompt-extraction.d.ts.map

package/dist/types/utils/summary-printer.d.ts

@@ -0,0 +1,3 @@
+import { ReveniumPayload } from "../types";
+export declare function printUsageSummary(payload: ReveniumPayload): void;
+//# sourceMappingURL=summary-printer.d.ts.map

package/dist/types/utils/trace-fields.d.ts

@@ -0,0 +1,10 @@
+export declare function getEnvironment(): string | null;
+export declare function getRegion(): Promise<string | null>;
+export declare function getCredentialAlias(): string | null;
+export declare function getTraceType(): string | null;
+export declare function getTraceName(): string | null;
+export declare function detectOperationSubtype(requestBody?: any): string | null;
+export declare function getParentTransactionId(): string | null;
+export declare function getTransactionName(): string | null;
+export declare function getRetryNumber(): number;
+//# sourceMappingURL=trace-fields.d.ts.map

package/examples/advanced.ts

@@ -0,0 +1,128 @@
+import "dotenv/config";
+import "@revenium/anthropic";
+import Anthropic from "@anthropic-ai/sdk";
+import type { UsageMetadata, TrackingData } from "@revenium/anthropic";
+import { trackUsageAsync, getStatus } from "@revenium/anthropic";
+
+async function main() {
+  await streamingWithMetadata();
+  await toolUsage();
+  await manualTracking();
+}
+
+const streamingWithMetadata = async () => {
+  console.log("Revenium Anthropic Middleware - Streaming Example\n");
+  const anthropic = new Anthropic();
+
+  try {
+    const metadata: UsageMetadata = {
+      subscriber: { id: "user-123", email: "user@example.com" },
+      organizationId: "my-org",
+      productId: "my-product",
+      taskType: "streaming-demo",
+      traceId: `session_${Date.now()}`,
+    };
+
+    const stream = await anthropic.messages.create({
+      model: "claude-haiku-4-5",
+      max_tokens: 100,
+      messages: [{ role: "user", content: "Write a haiku about coding." }],
+      stream: true,
+      usageMetadata: metadata,
+    });
+
+    console.log("Response:");
+    for await (const event of stream) {
+      if (
+        event.type === "content_block_delta" &&
+        event.delta.type === "text_delta"
+      ) {
+        process.stdout.write(event.delta.text);
+      }
+    }
+    console.log("\n");
+  } catch (error) {
+    console.error("Error:", error);
+  }
+};
+
+const toolUsage = async () => {
+  console.log("Revenium Anthropic Middleware - Tool Usage Example\n");
+  const anthropic = new Anthropic();
+
+  try {
+    const response = await anthropic.messages.create({
+      model: "claude-haiku-4-5",
+      max_tokens: 200,
+      tools: [
+        {
+          name: "get_weather",
+          description: "Get weather for a location",
+          input_schema: {
+            type: "object",
+            properties: {
+              location: { type: "string", description: "City name" },
+            },
+            required: ["location"],
+          },
+        },
+      ],
+      messages: [{ role: "user", content: "What's the weather in Tokyo?" }],
+      usageMetadata: {
+        subscriber: { id: "tool-user" },
+        taskType: "tool-demo",
+      },
+    });
+
+    for (const block of response.content) {
+      if (block.type === "tool_use") {
+        console.log(`Tool called: ${block.name}`);
+        console.log(`Input: ${JSON.stringify(block.input)}\n`);
+      }
+    }
+  } catch (error) {
+    console.error("Error:", error);
+  }
+};
+
+const manualTracking = async () => {
+  console.log("Revenium Anthropic Middleware - Manual Tracking Example\n");
+
+  try {
+    const now = new Date();
+    const trackingData: TrackingData = {
+      requestId: `manual_${Date.now()}`,
+      model: "claude-haiku-4-5",
+      inputTokens: 25,
+      outputTokens: 150,
+      duration: 2500,
+      isStreamed: false,
+      requestTime: new Date(now.getTime() - 2500),
+      responseTime: now,
+      metadata: {
+        subscriber: { id: "manual-user" },
+        organizationId: "manual-org",
+        taskType: "manual-tracking",
+      },
+    };
+
+    trackUsageAsync(trackingData);
+    console.log("Manual tracking sent successfully");
+    console.log(
+      `Tracked: ${
+        trackingData.inputTokens + trackingData.outputTokens
+      } tokens\n`
+    );
+
+    const status = getStatus();
+    console.log("Middleware Status:", {
+      initialized: status.initialized,
+      patched: status.patched,
+      hasConfig: status.hasConfig,
+    });
+  } catch (error) {
+    console.error("Error:", error);
+  }
+};
+
+main().catch(console.error);

package/examples/basic.ts

@@ -0,0 +1,132 @@
+import "dotenv/config";
+import "@revenium/anthropic";
+import Anthropic from "@anthropic-ai/sdk";
+import {
+  configure,
+  getConfig,
+  getStatus,
+  initialize,
+} from "@revenium/anthropic";
+
+async function main() {
+  await basicUsage();
+  await explicitInitialization();
+  await manualConfiguration();
+}
+
+const basicUsage = async () => {
+  console.log("Revenium Anthropic Middleware - Basic Example\n");
+  const anthropic = new Anthropic();
+  try {
+    const response = await anthropic.messages.create({
+      model: "claude-haiku-4-5",
+      max_tokens: 50,
+      messages: [
+        { role: "user", content: "What is the capital of France? Be concise." },
+      ],
+    });
+
+    const textResponse =
+      response.content[0].type === "text"
+        ? response.content[0].text
+        : "Non-text response";
+    console.log("RESPONSE: \n", textResponse);
+    console.log(
+      `Tokens: ${response.usage?.input_tokens} input + ${response.usage?.output_tokens} output\n`
+    );
+  } catch (error) {
+    console.error("Error: ", error);
+  }
+};
+
+const explicitInitialization = async () => {
+  console.log(
+    "Revenium Anthropic Middleware - Explicit Initialization Example\n"
+  );
+  try {
+    initialize();
+    const status = getStatus();
+    console.log("Middleware status:", {
+      initialized: status.initialized,
+      patched: status.patched,
+      hasConfig: status.hasConfig,
+    });
+
+    const anthropic = new Anthropic();
+    const response = await anthropic.messages.create({
+      model: "claude-haiku-4-5",
+      max_tokens: 50,
+      messages: [
+        {
+          role: "user",
+          content: "What are the benefits of explicit initialization?",
+        },
+      ],
+    });
+    const textResponse =
+      response.content[0].type === "text"
+        ? response.content[0].text
+        : "Non-text response";
+    console.log("RESPONSE: \n", textResponse);
+    console.log(
+      `Tokens: ${response.usage?.input_tokens} input + ${response.usage?.output_tokens} output\n`
+    );
+  } catch (error) {
+    console.error("Error: ", error);
+  }
+};
+
+const manualConfiguration = async () => {
+  console.log("Revenium Anthropic Middleware - Manual Configuration Example\n");
+  try {
+    // Manual configuration with all options
+    configure({
+      // Required: Revenium API configuration
+      reveniumApiKey:
+        process.env.REVENIUM_METERING_API_KEY || "hak_your_api_key_here",
+      reveniumBaseUrl:
+        process.env.REVENIUM_METERING_BASE_URL || "https://api.revenium.ai",
+
+      // Optional: Anthropic API key (can also be set in Anthropic client)
+      anthropicApiKey: process.env.ANTHROPIC_API_KEY,
+
+      // Optional: Performance and reliability settings
+      apiTimeout: 8000, // 8 second timeout (default: 5000)
+      maxRetries: 5, // 5 retry attempts (default: 3)
+      failSilent: false, // Throw errors instead of silent failure (default: true)
+    });
+
+    // Verify configuration
+    const config = getConfig();
+    console.log("Configuration:", {
+      hasReveniumKey: !!config?.reveniumApiKey,
+      baseUrl: config?.reveniumBaseUrl,
+      timeout: config?.apiTimeout,
+      maxRetries: config?.maxRetries,
+    });
+
+    const anthropic = new Anthropic({
+      apiKey: process.env.ANTHROPIC_API_KEY || "sk-ant-your_anthropic_key_here",
+    });
+    const response = await anthropic.messages.create({
+      model: "claude-haiku-4-5",
+      max_tokens: 50,
+      messages: [
+        {
+          role: "user",
+          content:
+            "What are the advantages of manual configuration in enterprise software?",
+        },
+      ],
+    });
+    const textResponse =
+      response.content[0].type === "text"
+        ? response.content[0].text
+        : "Non-text response";
+    console.log("RESPONSE: \n", textResponse);
+  } catch (error) {
+    console.error("Error: ", error);
+  }
+};
+
+main().catch(console.error);