@revenium/anthropic 1.0.4 → 1.0.6

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 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
+- Improved .env.example with realistic key format examples (hak_, sk-ant-)
+
 ## [1.0.4] - 2025-10-21
 
 ### Changed
@@ -45,6 +60,8 @@ 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
 [1.0.2]: https://github.com/revenium/revenium-middleware-anthropic-node/releases/tag/v1.0.2

package/README.md

@@ -7,8 +7,6 @@
 
 Automatically track and meter your Anthropic Claude API usage with Revenium. This middleware provides seamless integration with **Anthropic Claude SDK**, requiring minimal code changes and featuring native TypeScript support.
 
-> **Note - Package Renamed**: This package has been renamed from `revenium-middleware-anthropic-node` to `@revenium/anthropic` for better organization and simpler naming. Please update your dependencies accordingly.
-
 ## Features
 
 - **Seamless Integration**: Drop-in replacement with zero code changes required
@@ -21,134 +19,60 @@ Automatically track and meter your Anthropic Claude API usage with Revenium. Thi
 - **Fire-and-forget**: Never blocks your application flow
 - **Analytics**: Detailed usage analytics and reporting
 
-## Package Migration
-
-This package has been renamed from `revenium-middleware-anthropic-node` to `@revenium/anthropic` for better organization and simpler naming.
-
-### Migration Steps
-
-If you're upgrading from the old package:
-
-```bash
-# Uninstall the old package
-npm uninstall revenium-middleware-anthropic-node
-
-# Install the new package
-npm install @revenium/anthropic
-```
-
-**Update your imports:**
-
-```typescript
-// Old import
-import "revenium-middleware-anthropic-node";
-
-// New import
-import "@revenium/anthropic";
-```
-
-All functionality remains exactly the same - only the package name has changed.
-
 ## Getting Started
 
-### Quick Start
-
-```bash
-npm install @revenium/anthropic @anthropic-ai/sdk
-```
-
-For complete setup instructions, TypeScript patterns, and usage examples, see [examples/README.md](https://github.com/revenium/revenium-middleware-anthropic-node/blob/HEAD/examples/README.md).
-
-### Step-by-Step Guide
-
-The following guide walks you through creating a new project from scratch:
-
-### Step 1: Create Your Project
+### 1. Create Project Directory
 
 ```bash
-# Create project directory
+# Create and navigate to project directory
 mkdir my-anthropic-project
 cd my-anthropic-project
 
-# Initialize Node.js project
+# Initialize npm project
 npm init -y
-```
-
-### Step 2: Install Dependencies
-
-```bash
-# Install Revenium middleware and Anthropic SDK
-npm install @revenium/anthropic @anthropic-ai/sdk@^0.55.1 dotenv
 
-# For TypeScript projects (optional)
-npm install -D typescript tsx @types/node
+# Install dependencies
+npm install @revenium/anthropic @anthropic-ai/sdk dotenv tsx
+npm install --save-dev typescript @types/node
 ```
 
-### Step 3: Setup Environment Variables
+### 2. Configure Environment Variables
 
-Create a `.env` file in your project root:
+Create a `.env` file:
 
 ```bash
-# Create .env file
-echo. > .env  # On Windows (CMD)
-touch .env  # On Mac/Linux
-# OR PowerShell
-New-Item -Path .env -ItemType File
+REVENIUM_METERING_API_KEY="hak_your_revenium_key"
+ANTHROPIC_API_KEY="sk-ant-your_anthropic_key"
 ```
 
-Copy and paste the following into `.env`:
+> **Note**: `REVENIUM_METERING_BASE_URL` defaults to `https://api.revenium.io` and doesn't need to be set unless using a different environment.
 
-```env
-# Anthropic Configuration
-ANTHROPIC_API_KEY=sk-ant-your_anthropic_api_key_here
+### 3. Run Your First Example
 
-# Revenium Configuration
-REVENIUM_METERING_API_KEY=hak_your_revenium_api_key_here
-REVENIUM_METERING_BASE_URL=https://api.revenium.io/meter
+Run the [getting started example](https://github.com/revenium/revenium-middleware-anthropic-node/blob/HEAD/examples/getting_started.ts):
 
-# Optional: Enable debug logging
-REVENIUM_DEBUG=true
+```bash
+npx tsx node_modules/@revenium/anthropic/examples/getting_started.ts
 ```
 
-**NOTE**: Replace each `your_..._here` with your actual values.
-
-### Step 4: Protect Your API Keys
-
-**CRITICAL**: Create a `.gitignore` file to prevent committing sensitive data like API keys.
-
-**Recommended**: Use the industry-standard [GitHub Node.gitignore](https://github.com/github/gitignore/blob/main/Node.gitignore)
+Or with debug logging:
 
 ```bash
-# Download GitHub's standard Node.gitignore
-curl -o .gitignore https://raw.githubusercontent.com/github/gitignore/main/Node.gitignore
-```
+# Linux/macOS
+REVENIUM_DEBUG=true npx tsx node_modules/@revenium/anthropic/examples/getting_started.ts
 
-**IMPORTANT**: Ensure these patterns are included to protect your environment variables:
-
-```gitignore
-# Environment variables - CRITICAL for API key protection
-.env
-.env.*
-!.env.example
+# Windows (PowerShell)
+$env:REVENIUM_DEBUG="true"; npx tsx node_modules/@revenium/anthropic/examples/getting_started.ts
 ```
 
-Never commit `.env` files containing your API keys to version control.
-
-### Step 5: Follow the Examples
-
-See [examples/README.md](https://github.com/revenium/revenium-middleware-anthropic-node/blob/HEAD/examples/README.md) for complete examples and setup instructions.
-
-**Cloned from GitHub?** Run examples with:
-
-```bash
-npm install
-npm run example:basic
-npm run example:advanced
-```
+**For more examples and TypeScript patterns, see [examples/README.md](https://github.com/revenium/revenium-middleware-anthropic-node/blob/HEAD/examples/README.md).**
 
-**Browse online:** [`examples/` directory](https://github.com/revenium/revenium-middleware-anthropic-node/tree/HEAD/examples)
+## Requirements
 
----
+- Node.js 18+
+- TypeScript 5.0+ (for TypeScript projects)
+- Anthropic SDK (@anthropic-ai/sdk) v0.20.0+
+- Revenium API key
 
 ## What Gets Tracked
 
@@ -168,166 +92,63 @@ The middleware automatically captures:
 
 The middleware supports three initialization patterns:
 
-#### Option A: Automatic Initialization (Simplest)
+**Automatic (Recommended)** - Simply import the middleware and it auto-initializes:
 
 ```typescript
-// Simply import - auto-initializes with graceful fallback
 import "@revenium/anthropic";
 import Anthropic from "@anthropic-ai/sdk";
 
-// If env vars are set, tracking works automatically
 const anthropic = new Anthropic();
+// Tracking works automatically if env vars are set
 ```
 
-#### Option B: Explicit Initialization (More Control)
+**Explicit** - Call `initialize()` for error handling control
 
-```typescript
-import { initialize } from "@revenium/anthropic";
-import Anthropic from "@anthropic-ai/sdk";
+**Manual** - Use `configure()` to set all options programmatically
 
-try {
-  initialize();
-  // Middleware initialized successfully
-} catch (error) {
-  // Handle initialization error appropriately
-  throw new Error(`Initialization failed: ${error.message}`);
-}
-
-const anthropic = new Anthropic();
-```
-
-#### Option C: Manual Configuration (Full Control)
-
-```typescript
-import { configure } from "@revenium/anthropic";
-import Anthropic from "@anthropic-ai/sdk";
-
-configure({
-  reveniumApiKey: "hak_your_api_key_here",
-  reveniumBaseUrl: "https://api.revenium.io/meter",
-  anthropicApiKey: "sk-ant-your_key_here",
-  apiTimeout: 5000,
-  failSilent: true,
-  maxRetries: 3,
-});
-
-const anthropic = new Anthropic();
-```
+For detailed examples of all initialization patterns, see [examples/](https://github.com/revenium/revenium-middleware-anthropic-node/blob/HEAD/examples/README.md).
 
 ### Streaming Responses
 
-```typescript
-import "@revenium/anthropic";
-import Anthropic from "@anthropic-ai/sdk";
-
-const anthropic = new Anthropic();
+Streaming is fully supported with real-time token tracking and time-to-first-token metrics. The middleware automatically tracks streaming responses without any additional configuration.
 
-const stream = await anthropic.messages.create({
-  model: "claude-3-5-sonnet-latest",
-  max_tokens: 1000,
-  messages: [{ role: "user", content: "Write a story about AI" }],
-  stream: true,
-  usageMetadata: {
-    subscriber: {
-      id: "user-123",
-      email: "user@example.com",
-    },
-    organizationId: "story-org",
-    taskType: "creative-writing",
-    agent: "story-writer",
-  },
-});
-
-for await (const event of stream) {
-  if (
-    event.type === "content_block_delta" &&
-    event.delta.type === "text_delta"
-  ) {
-    process.stdout.write(event.delta.text);
-  }
-}
-```
+See [examples/advanced-features.ts](https://github.com/revenium/revenium-middleware-anthropic-node/blob/HEAD/examples/advanced-features.ts) for working streaming examples.
 
 ### Custom Metadata Tracking
 
-Add business context to your AI usage:
-
-```typescript
-// Custom metadata for enhanced tracking (following project structure)
-const customMetadata = {
-  subscriber: {
-    id: "user-789",
-    email: "user@company.com",
-    credential: {
-      name: "premium-user",
-      value: "tier-1",
-    },
-  },
-  organizationId: "org-456",
-  productId: "premium-plan",
-  taskType: "CUSTOMER_SUPPORT",
-  agent: "CustomerSupportBot",
-  traceId: "user-session-123",
-  responseQualityScore: 9.2,
-};
-
-const response = await anthropic.messages.create({
-  model: "claude-3-5-sonnet-latest",
-  max_tokens: 1024,
-  messages: [{ role: "user", content: "Help me with my account" }],
-  usageMetadata: customMetadata,
-});
-```
-
-### Usage Metadata Interface
-
-All metadata fields are optional:
-
-```typescript
-interface UsageMetadata {
-  traceId?: string; // Session or conversation ID
-  taskType?: string; // Type of AI task (e.g., "chat", "analysis")
-  organizationId?: string; // Organization/company ID
-  subscriptionId?: string; // Billing plan ID
-  productId?: string; // Your product/feature ID
-  agent?: string; // AI agent identifier
-  responseQualityScore?: number; // Quality score (0-1)
-  subscriber?: {
-    id?: string; // User ID from your system
-    email?: string; // User's email address
-    credential?: {
-      name?: string; // Credential name
-      value?: string; // Credential value
-    };
-  };
-}
-```
+Add business context to track usage by organization, user, task type, or custom fields. Pass a `usageMetadata` object with any of these optional fields:
+
+| 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
 
 ## Configuration Options
 
 ### Environment Variables
 
-| Variable                     | Required | Default                         | Description                       |
-| ---------------------------- | -------- | ------------------------------- | --------------------------------- |
-| `REVENIUM_METERING_API_KEY`  | Yes      | -                               | Your Revenium API key             |
-| `ANTHROPIC_API_KEY`          | Yes      | -                               | Anthropic Claude API key          |
-| `REVENIUM_METERING_BASE_URL` | No       | `https://api.revenium.io/meter` | Revenium metering API base URL    |
-| `REVENIUM_DEBUG`             | No       | `false`                         | Enable debug logging (true/false) |
+| Variable                     | Required | Default                    | Description                       |
+| ---------------------------- | -------- | -------------------------- | --------------------------------- |
+| `REVENIUM_METERING_API_KEY`  | Yes      | -                          | Your Revenium API key             |
+| `ANTHROPIC_API_KEY`          | Yes      | -                          | Anthropic Claude API key          |
+| `REVENIUM_METERING_BASE_URL` | No       | `https://api.revenium.io`  | Revenium metering API base URL    |
+| `REVENIUM_DEBUG`             | No       | `false`                    | Enable debug logging (true/false) |
 
 ### Manual Configuration
 
-```typescript
-import { configure } from "@revenium/anthropic";
-
-configure({
-  reveniumApiKey: "hak_your_api_key",
-  reveniumBaseUrl: "https://api.revenium.io/meter",
-  anthropicApiKey: "sk-ant-your_key",
-  apiTimeout: 5000,
-  failSilent: true,
-  maxRetries: 3,
-});
-```
+For programmatic configuration instead of environment variables, use the `configure()` function. See the initialization options above and [examples/](https://github.com/revenium/revenium-middleware-anthropic-node/blob/HEAD/examples/README.md) for details.
 
 ## Troubleshooting
 
@@ -370,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:
@@ -411,13 +240,6 @@ All examples are in the `examples/` directory of the installed package. For deta
 
 The middleware never blocks your application - if Revenium tracking fails, your Anthropic requests continue normally.
 
-## Requirements
-
-- Node.js 16+
-- Anthropic SDK (@anthropic-ai/sdk) v0.20.0+
-- TypeScript 5.0+ (for TypeScript projects)
-- Revenium API key
-
 ## Documentation
 
 For detailed documentation, visit [docs.revenium.io](https://docs.revenium.io)
@@ -445,7 +267,7 @@ For issues, feature requests, or contributions:
 - **GitHub Repository**: [revenium/revenium-middleware-anthropic-node](https://github.com/revenium/revenium-middleware-anthropic-node)
 - **Issues**: [Report bugs or request features](https://github.com/revenium/revenium-middleware-anthropic-node/issues)
 - **Documentation**: [docs.revenium.io](https://docs.revenium.io)
-- **Contact**: Reach out to the Revenium team for additional support
+- **Email**: support@revenium.io
 
 ## Development
 

package/dist/cjs/constants.js

@@ -10,7 +10,7 @@ exports.ANTHROPIC_PATTERNS = exports.API_ENDPOINTS = exports.ENV_VARS = exports.
  */
 exports.DEFAULT_CONFIG = {
     /** Default Revenium API base URL */
-    REVENIUM_BASE_URL: 'https://api.revenium.io/meter',
+    REVENIUM_BASE_URL: 'https://api.revenium.io',
     /** Default API timeout in milliseconds */
     API_TIMEOUT: 5000,
     /** Default maximum retries for failed API calls */
@@ -118,7 +118,7 @@ exports.ENV_VARS = {
  */
 exports.API_ENDPOINTS = {
     /** Revenium AI completions endpoint */
-    AI_COMPLETIONS: '/v2/ai/completions',
+    AI_COMPLETIONS: '/meter/v2/ai/completions',
 };
 /**
  * Anthropic model patterns

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) {
@@ -161,7 +160,7 @@ function validateReveniumConfig(config) {
         }
         catch {
             errors.push('reveniumBaseUrl must be a valid URL');
-            suggestions.push('Use format: https://api.revenium.io/meter');
+            suggestions.push('Use format: https://api.revenium.io');
         }
     }
     // Validate optional Anthropic API key

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/constants.js

@@ -7,7 +7,7 @@
  */
 export const DEFAULT_CONFIG = {
     /** Default Revenium API base URL */
-    REVENIUM_BASE_URL: 'https://api.revenium.io/meter',
+    REVENIUM_BASE_URL: 'https://api.revenium.io',
     /** Default API timeout in milliseconds */
     API_TIMEOUT: 5000,
     /** Default maximum retries for failed API calls */
@@ -115,7 +115,7 @@ export const ENV_VARS = {
  */
 export const API_ENDPOINTS = {
     /** Revenium AI completions endpoint */
-    AI_COMPLETIONS: '/v2/ai/completions',
+    AI_COMPLETIONS: '/meter/v2/ai/completions',
 };
 /**
  * Anthropic model patterns

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) {
@@ -150,7 +149,7 @@ export function validateReveniumConfig(config) {
         }
         catch {
             errors.push('reveniumBaseUrl must be a valid URL');
-            suggestions.push('Use format: https://api.revenium.io/meter');
+            suggestions.push('Use format: https://api.revenium.io');
         }
     }
     // Validate optional Anthropic API key

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/constants.d.ts

@@ -7,7 +7,7 @@
  */
 export declare const DEFAULT_CONFIG: {
     /** Default Revenium API base URL */
-    readonly REVENIUM_BASE_URL: "https://api.revenium.io/meter";
+    readonly REVENIUM_BASE_URL: "https://api.revenium.io";
     /** Default API timeout in milliseconds */
     readonly API_TIMEOUT: 5000;
     /** Default maximum retries for failed API calls */
@@ -115,7 +115,7 @@ export declare const ENV_VARS: {
  */
 export declare const API_ENDPOINTS: {
     /** Revenium AI completions endpoint */
-    readonly AI_COMPLETIONS: "/v2/ai/completions";
+    readonly AI_COMPLETIONS: "/meter/v2/ai/completions";
 };
 /**
  * Anthropic model patterns

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

@@ -52,7 +52,7 @@ export interface Subscriber {
  * ```typescript
  * const config: ReveniumConfig = {
  *   reveniumApiKey: 'hak_1234567890abcdef',
- *   reveniumBaseUrl: 'https://api.revenium.io/meter/v2',
+ *   reveniumBaseUrl: 'https://api.revenium.io',
  *   anthropicApiKey: 'sk-ant-1234567890abcdef',
  *   apiTimeout: 8000,
  *   failSilent: true,
@@ -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

@@ -2,16 +2,27 @@
 
 **TypeScript-first** examples demonstrating automatic Revenium usage tracking with the Anthropic SDK.
 
-## Quick Start
+## Getting Started - Step by Step
 
-### 1. Install Dependencies
+### 1. Create Your Project
+
+```bash
+# Create project directory
+mkdir my-anthropic-project
+cd my-anthropic-project
+
+# Initialize Node.js project
+npm init -y
+```
+
+### 2. Install Dependencies
 
 ```bash
 npm install @revenium/anthropic @anthropic-ai/sdk dotenv
 npm install -D typescript tsx @types/node  # For TypeScript
 ```
 
-### 2. Environment Setup
+### 3. Environment Setup
 
 Create a `.env` file in your project root:
 
@@ -21,11 +32,11 @@ REVENIUM_METERING_API_KEY=hak_your_revenium_api_key
 ANTHROPIC_API_KEY=sk-ant-your_anthropic_api_key
 
 # Optional
-REVENIUM_METERING_BASE_URL=https://api.revenium.io/meter
+REVENIUM_METERING_BASE_URL=https://api.revenium.io
 REVENIUM_DEBUG=false
 ```
 
-### 3. Run Examples
+### 4. Run Examples
 
 **If you cloned from GitHub:**
 
@@ -59,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
@@ -76,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
 
@@ -130,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
@@ -152,14 +166,6 @@ import Anthropic from "@anthropic-ai/sdk";
 }
 ```
 
-### IntelliSense Not Working
-
-**Solutions:**
-1. Restart TypeScript language server in your IDE
-2. Ensure `@revenium/anthropic` is imported at the top
-3. Verify `@anthropic-ai/sdk` types are installed
-4. Check TypeScript version is 4.5 or higher
-
 ### Debug Mode
 
 Enable detailed logging to troubleshoot issues:

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/meter/v2"
-    );
+    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/meter",
+        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/meter"
-    );
+    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.4",
+  "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",