@revenium/anthropic 1.0.5 → 1.0.6

package/CHANGELOG.md

@@ -2,12 +2,20 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.0.6] - 2025-10-24
+
+### Added
+- Comprehensive metadata fields table in README with practical use cases for all 11 fields
+- New `getting_started.ts` example showing complete metadata integration
+
+### Changed
+- Streamlined Getting Started tutorial with clearer step-by-step instructions
+- Improved documentation with direct links to example files
+
 ## [1.0.5] - 2025-10-23
 
 ### Changed
-- Updated .gitignore to GitHub official standard for professional presentation
 - Improved .env.example with realistic key format examples (hak_, sk-ant-)
-- Created initial public repository structure
 
 ## [1.0.4] - 2025-10-21
 
@@ -52,6 +60,7 @@ All notable changes to this project will be documented in this file.
 - Configurable retry logic
 - Debug logging support
 
+[1.0.6]: https://github.com/revenium/revenium-middleware-anthropic-node/releases/tag/v1.0.6
 [1.0.5]: https://github.com/revenium/revenium-middleware-anthropic-node/releases/tag/v1.0.5
 [1.0.4]: https://github.com/revenium/revenium-middleware-anthropic-node/releases/tag/v1.0.4
 [1.0.3]: https://github.com/revenium/revenium-middleware-anthropic-node/releases/tag/v1.0.3

package/README.md

@@ -21,30 +21,51 @@ Automatically track and meter your Anthropic Claude API usage with Revenium. Thi
 
 ## Getting Started
 
-**Installation:**
+### 1. Create Project Directory
 
 ```bash
-npm install @revenium/anthropic @anthropic-ai/sdk
+# Create and navigate to project directory
+mkdir my-anthropic-project
+cd my-anthropic-project
+
+# Initialize npm project
+npm init -y
+
+# Install dependencies
+npm install @revenium/anthropic @anthropic-ai/sdk dotenv tsx
+npm install --save-dev typescript @types/node
 ```
 
-**Quick Start:**
+### 2. Configure Environment Variables
 
-```typescript
-import "@revenium/anthropic";
-import Anthropic from "@anthropic-ai/sdk";
+Create a `.env` file:
 
-const client = new Anthropic();
-// Middleware automatically tracks all requests
+```bash
+REVENIUM_METERING_API_KEY="hak_your_revenium_key"
+ANTHROPIC_API_KEY="sk-ant-your_anthropic_key"
 ```
 
-**Environment Setup:**
+> **Note**: `REVENIUM_METERING_BASE_URL` defaults to `https://api.revenium.io` and doesn't need to be set unless using a different environment.
+
+### 3. Run Your First Example
+
+Run the [getting started example](https://github.com/revenium/revenium-middleware-anthropic-node/blob/HEAD/examples/getting_started.ts):
 
 ```bash
-export ANTHROPIC_API_KEY="sk-ant-your_anthropic_key"
-export REVENIUM_METERING_API_KEY="hak_your_revenium_key"
+npx tsx node_modules/@revenium/anthropic/examples/getting_started.ts
 ```
 
-**For complete step-by-step setup, TypeScript configuration, and running examples, see [examples/README.md](https://github.com/revenium/revenium-middleware-anthropic-node/blob/HEAD/examples/README.md).**
+Or with debug logging:
+
+```bash
+# Linux/macOS
+REVENIUM_DEBUG=true npx tsx node_modules/@revenium/anthropic/examples/getting_started.ts
+
+# Windows (PowerShell)
+$env:REVENIUM_DEBUG="true"; npx tsx node_modules/@revenium/anthropic/examples/getting_started.ts
+```
+
+**For more examples and TypeScript patterns, see [examples/README.md](https://github.com/revenium/revenium-middleware-anthropic-node/blob/HEAD/examples/README.md).**
 
 ## Requirements
 
@@ -97,13 +118,19 @@ See [examples/advanced-features.ts](https://github.com/revenium/revenium-middlew
 
 Add business context to track usage by organization, user, task type, or custom fields. Pass a `usageMetadata` object with any of these optional fields:
 
-- **subscriber**: User ID, email, and credentials
-- **organizationId**: Organization or company identifier
-- **taskType**: Type of AI task (e.g., chat, analysis, generation)
-- **agent**: AI agent or bot identifier
-- **traceId**: Session or conversation tracking
-- **productId**: Your product or feature identifier
-- **responseQualityScore**: Custom quality metrics
+| Field | Description | Use Case |
+|-------|-------------|----------|
+| `traceId` | Unique identifier for session or conversation tracking | Link multiple API calls together for debugging, user session analytics, or distributed tracing across services |
+| `taskType` | Type of AI task being performed | Categorize usage by workload (e.g., "chat", "code-generation", "doc-summary") for cost analysis and optimization |
+| `subscriber.id` | Unique user identifier | Track individual user consumption for billing, rate limiting, or user analytics |
+| `subscriber.email` | User email address | Identify users for support, compliance, or usage reports |
+| `subscriber.credential.name` | Authentication credential name | Track which API key or service account made the request |
+| `subscriber.credential.value` | Authentication credential value | Associate usage with specific credentials for security auditing |
+| `organizationId` | Organization or company identifier | Multi-tenant cost allocation, usage quotas per organization |
+| `subscriptionId` | Subscription plan identifier | Track usage against subscription limits, identify plan upgrade opportunities |
+| `productId` | Your product or feature identifier | Attribute AI costs to specific features in your application (e.g., "chatbot", "email-assistant") |
+| `agent` | AI agent or bot identifier | Distinguish between multiple AI agents or automation workflows in your system |
+| `responseQualityScore` | Custom quality rating (0.0-1.0) | Track user satisfaction or automated quality metrics for model performance analysis |
 
 **Resources:**
 - [API Reference](https://revenium.readme.io/reference/meter_ai_completion) - Complete metadata field documentation
@@ -164,6 +191,14 @@ npm install
 npm run build
 ```
 
+### OpenRouter Users
+
+**Note:** Revenium's automatic token cost calculation uses AI model names from the providers themselves (e.g., `claude-sonnet-4-20250514`).
+
+If you are using a service like OpenRouter that changes model names (from `claude-sonnet-4-20250514` to `anthropic/claude-sonnet-4`), automatic cost calculations may not work properly in Revenium (though all other processing will work normally).
+
+Supporting OpenRouter AI model names is something we're working on for the future. If this is critical for your use case, please use the 'provide feedback' button in the Help Center to let us know.
+
 ### Debug Mode
 
 Enable detailed logging to troubleshoot issues:

package/dist/cjs/tracking.js

@@ -142,6 +142,7 @@ function buildReveniumPayload(data) {
         completionStartTime: completionStartTime,
         timeToFirstToken: data.timeToFirstToken || 0,
         traceId: data.metadata?.traceId,
+        responseQualityScore: data.metadata?.responseQualityScore, // Fixed: Now sending to Revenium
         middlewareSource: "nodejs",
     };
 }

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

@@ -68,7 +68,6 @@
  *       credential: { name: 'api-key', value: 'sk-...' }
  *     },
  *     traceId: 'analysis-session-789',
- *     taskId: 'task-001',
  *     taskType: 'data-analysis',
  *     organizationId: 'enterprise-client',
  *     subscriptionId: 'premium-plan',

package/dist/cjs/utils/validation.js

@@ -60,8 +60,7 @@ function validateUsageMetadata(metadata) {
     const validated = {};
     // Validate string fields
     const stringFields = [
-        'traceId', 'taskId', 'taskType', 'subscriberEmail', 'subscriberId',
-        'subscriberCredentialName', 'subscriberCredential', 'organizationId',
+        'traceId', 'taskType', 'organizationId',
         'subscriptionId', 'productId', 'agent'
     ];
     for (const field of stringFields) {

package/dist/cjs/wrapper.js

@@ -61,8 +61,10 @@ function getMessagesPrototype() {
  * Patch Anthropic SDK by modifying prototype methods
  */
 function patchAnthropic() {
-    if (patchingContext.isPatched)
+    if (patchingContext.isPatched) {
+        logger.debug('Anthropic SDK already patched, skipping duplicate initialization');
         return;
+    }
     try {
         // Access the Messages class prototype using sophisticated prototype access
         const messagesPrototype = getMessagesPrototype();

package/dist/esm/tracking.js

@@ -133,6 +133,7 @@ function buildReveniumPayload(data) {
         completionStartTime: completionStartTime,
         timeToFirstToken: data.timeToFirstToken || 0,
         traceId: data.metadata?.traceId,
+        responseQualityScore: data.metadata?.responseQualityScore, // Fixed: Now sending to Revenium
         middlewareSource: "nodejs",
     };
 }

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

@@ -67,7 +67,6 @@
  *       credential: { name: 'api-key', value: 'sk-...' }
  *     },
  *     traceId: 'analysis-session-789',
- *     taskId: 'task-001',
  *     taskType: 'data-analysis',
  *     organizationId: 'enterprise-client',
  *     subscriptionId: 'premium-plan',

package/dist/esm/utils/validation.js

@@ -49,8 +49,7 @@ export function validateUsageMetadata(metadata) {
     const validated = {};
     // Validate string fields
     const stringFields = [
-        'traceId', 'taskId', 'taskType', 'subscriberEmail', 'subscriberId',
-        'subscriberCredentialName', 'subscriberCredential', 'organizationId',
+        'traceId', 'taskType', 'organizationId',
         'subscriptionId', 'productId', 'agent'
     ];
     for (const field of stringFields) {

package/dist/esm/wrapper.js

@@ -53,8 +53,10 @@ function getMessagesPrototype() {
  * Patch Anthropic SDK by modifying prototype methods
  */
 export function patchAnthropic() {
-    if (patchingContext.isPatched)
+    if (patchingContext.isPatched) {
+        logger.debug('Anthropic SDK already patched, skipping duplicate initialization');
         return;
+    }
     try {
         // Access the Messages class prototype using sophisticated prototype access
         const messagesPrototype = getMessagesPrototype();

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

@@ -67,7 +67,6 @@
  *       credential: { name: 'api-key', value: 'sk-...' }
  *     },
  *     traceId: 'analysis-session-789',
- *     taskId: 'task-001',
  *     taskType: 'data-analysis',
  *     organizationId: 'enterprise-client',
  *     subscriptionId: 'premium-plan',

package/dist/types/types.d.ts

@@ -98,8 +98,6 @@ export interface UsageMetadata {
     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 */
@@ -290,6 +288,8 @@ export interface ReveniumPayload {
     timeToFirstToken: number;
     /** Optional trace identifier for request correlation */
     traceId?: string;
+    /** Quality score of the AI response (0.0-1.0) for performance tracking */
+    responseQualityScore?: number;
     /** Source identifier for the middleware */
     middlewareSource: string;
 }

package/examples/.claude/settings.local.json

@@ -0,0 +1,18 @@
+{
+  "permissions": {
+    "allow": [
+      "Read(//Users/daithi/git/rev/git/revenium-middleware-anthropic-node/**)",
+      "Bash(npm init:*)",
+      "Bash(npm install:*)",
+      "Bash(cp:*)",
+      "Bash(npx tsx:*)",
+      "WebFetch(domain:revenium.readme.io)",
+      "Bash(tee:*)",
+      "Bash(npm run clean:*)",
+      "Bash(npm run build:*)",
+      "Bash(node -e \"require(''@revenium/anthropic''); console.log(''✅ Option A (Auto-init) - Import works'')\")"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

package/examples/README.md

@@ -70,6 +70,7 @@ Demonstrates the three ways to initialize the Revenium middleware:
 - **Manual configuration** - Use `configure()` for custom settings
 
 **Key Features:**
+
 - TypeScript module augmentation for native `usageMetadata` support
 - Full type safety with IntelliSense
 - Interface validation using `satisfies` operator
@@ -87,8 +88,9 @@ Demonstrates advanced Anthropic SDK features with automatic tracking:
 - **Error handling** - Comprehensive error handling patterns
 
 **Key Features:**
+
 - Type-safe event handling and stream processing
-- Advanced metadata patterns with interface extensions
+- Advanced metadata patterns with custom fields support
 - Generic functions with type constraints
 - Custom logger integration
 
@@ -141,6 +143,7 @@ import Anthropic from "@anthropic-ai/sdk";
 **Problem:** `REVENIUM_METERING_API_KEY` or `ANTHROPIC_API_KEY` not found
 
 **Solutions:**
+
 - Ensure `.env` file is in project root
 - Check variable names match exactly
 - Verify you're importing `dotenv/config` before the middleware

package/examples/advanced-features.ts

@@ -7,7 +7,7 @@
  * • Manual tracking for custom scenarios with full type safety
  * • Comprehensive error handling with typed error responses
  * • Generic functions with type constraints
- * • Advanced metadata patterns with interface extensions
+ * • Advanced metadata patterns with custom fields support
  * • Type-safe event handling and stream processing
  *
  * All features leverage TypeScript's type system for maximum safety and IntelliSense.
@@ -30,29 +30,11 @@ import type {
 
 import { trackUsageAsync, getStatus, setLogger } from "@revenium/anthropic";
 
-// =============================================================================
-// ADVANCED TYPESCRIPT TYPE DEFINITIONS
-// =============================================================================
-
-/**
- * Extended metadata interface for advanced scenarios
- */
-interface AdvancedUsageMetadata extends UsageMetadata {
-  /** Session identifier for multi-turn conversations */
-  readonly sessionId?: string;
-  /** User role for RBAC scenarios */
-  readonly userRole?: "admin" | "user" | "guest";
-  /** Feature being used */
-  readonly feature?: "chat" | "completion" | "analysis" | "generation";
-  /** Request priority for resource allocation */
-  readonly priority?: "low" | "normal" | "high";
-}
-
 /**
  * Streaming event types with full type safety
  */
 type StreamEvent =
-  | { type: "start"; timestamp: Date; metadata: AdvancedUsageMetadata }
+  | { type: "start"; timestamp: Date; metadata: UsageMetadata }
   | { type: "content"; content: string; timestamp: Date }
   | { type: "complete"; totalTokens: number; duration: number; timestamp: Date }
   | { type: "error"; error: string; timestamp: Date };
@@ -113,7 +95,7 @@ async function demonstrateAdvancedFeatures(): Promise<void> {
     );
 
     // Create strongly typed metadata with satisfies operator
-    const advancedMetadata: AdvancedUsageMetadata = {
+    const advancedMetadata: UsageMetadata = {
       subscriber: {
         id: "artist-456",
         email: "artist@creative-studio.com",
@@ -126,12 +108,8 @@ async function demonstrateAdvancedFeatures(): Promise<void> {
       productId: "story-generator-pro",
       taskType: "creative-writing",
       agent: "storyteller-v2",
-      // Advanced metadata extensions
-      sessionId: `session_${Date.now()}`,
-      userRole: "user",
-      feature: "generation",
-      priority: "normal",
-    } satisfies AdvancedUsageMetadata;
+      traceId: `session_${Date.now()}`,
+    } satisfies UsageMetadata;
 
     // Type-safe streaming with event tracking
     const streamEvents: StreamEvent[] = [];
@@ -258,16 +236,13 @@ async function demonstrateAdvancedFeatures(): Promise<void> {
       "\nExample 3: Educational content with different metadata pattern..."
     );
 
-    const educationalMetadata: AdvancedUsageMetadata = {
+    const educationalMetadata: UsageMetadata = {
       subscriber: { id: "student-789" },
       organizationId: "green-tech-edu",
       productId: "sustainability-tutor",
       taskType: "educational-query",
-      sessionId: `edu_session_${Date.now()}`,
-      userRole: "guest",
-      feature: "analysis",
-      priority: "low",
-    } satisfies AdvancedUsageMetadata;
+      traceId: `edu_session_${Date.now()}`,
+    } satisfies UsageMetadata;
 
     const stream2 = await anthropic.messages.create({
       model: "claude-3-5-sonnet-latest",
@@ -308,7 +283,7 @@ async function demonstrateAdvancedFeatures(): Promise<void> {
     console.log("Example 4: Weather tool with advanced TypeScript patterns...");
 
     // Create tool-specific metadata with type safety
-    const toolMetadata: AdvancedUsageMetadata = {
+    const toolMetadata: UsageMetadata = {
       subscriber: {
         id: "weather-user-456",
         email: "user@weather-app.com",
@@ -317,11 +292,8 @@ async function demonstrateAdvancedFeatures(): Promise<void> {
       productId: "smart-weather-assistant",
       taskType: "tool-usage",
       agent: "weather-bot-v3",
-      sessionId: `weather_${Date.now()}`,
-      userRole: "user",
-      feature: "chat",
-      priority: "normal",
-    } satisfies AdvancedUsageMetadata;
+      traceId: `weather_${Date.now()}`,
+    } satisfies UsageMetadata;
 
     const toolStream = await anthropic.messages.create({
       model: "claude-3-5-sonnet-latest",
@@ -391,7 +363,6 @@ async function demonstrateAdvancedFeatures(): Promise<void> {
     console.log("   • Type-safe metadata with satisfies operator");
     console.log("   • Strongly typed event handling and streaming");
     console.log("   • Custom logger implementation with typed interfaces");
-    console.log("   • Advanced metadata patterns with interface extensions");
     console.log("   • Comprehensive error handling with typed responses");
     console.log("   • Generic functions with type constraints");
     console.log("   • Full IntelliSense support throughout\n");
@@ -461,9 +432,7 @@ function checkEnvironment(): void {
     console.error("   REVENIUM_METERING_API_KEY=hak_your_api_key");
     console.error("   ANTHROPIC_API_KEY=sk-ant-your_anthropic_key");
     console.error("\nOptional (uses defaults if not set):");
-    console.error(
-      "   REVENIUM_METERING_BASE_URL=https://api.revenium.io"
-    );
+    console.error("   REVENIUM_METERING_BASE_URL=https://api.revenium.io");
     console.error("   REVENIUM_DEBUG=true  # For detailed logging");
     process.exit(1);
   }
@@ -480,7 +449,6 @@ if (require.main === module) {
       );
       console.log("\nTypeScript Features Demonstrated:");
       console.log("   • Type-safe streaming with event handling");
-      console.log("   • Advanced metadata patterns with interface extensions");
       console.log("   • Custom logger implementation with typed interfaces");
       console.log("   • Manual tracking with full type safety");
       console.log("   • Comprehensive error handling with typed responses");

package/examples/basic-usage.ts

@@ -23,7 +23,7 @@ import "dotenv/config";
 import "@revenium/anthropic";
 import Anthropic from "@anthropic-ai/sdk";
 
-// Import types for full TypeScript support
+// Import types and functions for full TypeScript support
 import type {
   UsageMetadata,
   ReveniumConfig,
@@ -31,6 +31,9 @@ import type {
   MiddlewareStatus,
 } from "@revenium/anthropic";
 
+// Import initialization and configuration functions
+import { initialize, getStatus, configure, getConfig } from "@revenium/anthropic";
+
 async function demonstrateBasicUsage() {
   console.log("Revenium Anthropic Middleware - Basic Usage Examples\n");
 
@@ -42,16 +45,14 @@ async function demonstrateBasicUsage() {
     "Just import the middleware - it auto-configures from environment variables\n"
   );
 
-  // Simply import the middleware - auto-initialization happens automatically
-  await import("@revenium/anthropic");
-
+  // The middleware was already imported at the top of the file - auto-initialization happens automatically
   const anthropic = new Anthropic();
 
   try {
     // Example 1: Basic request without metadata (still tracked automatically)
     console.log("Example 1: Basic request without metadata...");
     const basicResponse = await anthropic.messages.create({
-      model: "claude-sonnet-4-20250514",
+      model: "claude-3-5-sonnet-latest",
       max_tokens: 50,
       messages: [
         { role: "user", content: "What is the capital of France? Be concise." },
@@ -72,7 +73,7 @@ async function demonstrateBasicUsage() {
     // Example 2: Request with rich metadata for enhanced tracking
     console.log("Example 2: Request with rich metadata...");
     const metadataResponse = await anthropic.messages.create({
-      model: "claude-sonnet-4-20250514",
+      model: "claude-3-5-sonnet-latest",
       max_tokens: 80,
       messages: [
         { role: "user", content: "Explain quantum computing in one sentence." },
@@ -130,9 +131,6 @@ async function demonstrateExplicitInitialization() {
   );
 
   try {
-    // Import initialization functions
-    const { initialize, getStatus } = await import("@revenium/anthropic");
-
     // Explicitly initialize with clear error feedback
     initialize();
     console.log("✓ Explicit initialization successful!");
@@ -148,7 +146,7 @@ async function demonstrateExplicitInitialization() {
     // Now use Anthropic with guaranteed tracking
     const anthropic = new Anthropic();
     const response = await anthropic.messages.create({
-      model: "claude-sonnet-4-20250514",
+      model: "claude-3-5-sonnet-latest",
       max_tokens: 60,
       messages: [
         {
@@ -190,17 +188,13 @@ async function demonstrateManualConfiguration() {
   console.log("Option C: Manual Configuration (Full Control)");
 
   try {
-    // Import configuration function
-    const { configure, getConfig } = await import("@revenium/anthropic");
-
     // 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.io",
+        process.env.REVENIUM_METERING_BASE_URL || "https://api.revenium.io",
 
       // Optional: Anthropic API key (can also be set in Anthropic client)
       anthropicApiKey: process.env.ANTHROPIC_API_KEY,
@@ -228,7 +222,7 @@ async function demonstrateManualConfiguration() {
     });
 
     const response = await anthropic.messages.create({
-      model: "claude-sonnet-4-20250514",
+      model: "claude-3-5-sonnet-latest",
       max_tokens: 80,
       messages: [
         {
@@ -285,9 +279,7 @@ function checkEnvironment() {
     console.error("   REVENIUM_METERING_API_KEY=hak_your_api_key");
     console.error("   ANTHROPIC_API_KEY=sk-ant-your_anthropic_key");
     console.error("\nOptional (uses defaults if not set):");
-    console.error(
-      "   REVENIUM_METERING_BASE_URL=https://api.revenium.io"
-    );
+    console.error("   REVENIUM_METERING_BASE_URL=https://api.revenium.io");
     console.error("   REVENIUM_DEBUG=true  # For detailed logging");
     process.exit(1);
   }

package/examples/getting_started.ts

@@ -0,0 +1,50 @@
+import 'dotenv/config';
+import '@revenium/anthropic';
+import Anthropic from '@anthropic-ai/sdk';
+
+async function main() {
+  // Create Anthropic client
+  const anthropic = new Anthropic();
+
+  // Chat completion with metadata
+  const response = await anthropic.messages.create({
+    model: 'claude-3-5-sonnet-latest',
+    max_tokens: 2000,
+    messages: [
+      { role: 'user', content: 'Please verify you are ready to assist me.' }
+    ],
+
+    /* Optional metadata for advanced reporting, lineage tracking, and cost allocation
+    usageMetadata: {
+      // User identification
+      subscriber: {
+        id: 'user-123',
+        email: 'user@example.com',
+        credential: {
+          name: 'api-key-prod',
+          value: 'key-abc-123'
+        }
+      },
+
+      // Organization & billing
+      organizationId: 'my-customers-name',
+      subscriptionId: 'plan-enterprise-2024',
+
+      // Product & task tracking
+      productId: 'my-product',
+      taskType: 'doc-summary',
+      agent: 'customer-support',
+
+      // Session tracking
+      traceId: 'session-' + Date.now(),
+
+      // Quality metrics
+      responseQualityScore: 0.95
+    }
+    */
+  });
+
+  console.log('Response:', response.content[0]?.text);
+}
+
+main().catch(console.error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@revenium/anthropic",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "Transparent TypeScript middleware for automatic Revenium usage tracking with Anthropic Claude AI",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",