@revenium/anthropic 1.0.3 → 1.0.4

package/README.md

@@ -1,806 +1,456 @@
-# Revenium Middleware for Anthropic (Node.js)
-
-[![npm version](https://img.shields.io/npm/v/@revenium/anthropic.svg)](https://www.npmjs.com/package/@revenium/anthropic)
-[![Node Versions](https://img.shields.io/node/v/@revenium/anthropic.svg)](https://www.npmjs.com/package/@revenium/anthropic)
-[![Documentation](https://img.shields.io/badge/docs-revenium.io-blue)](https://docs.revenium.io)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-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
-- **Complete Metering**: Track tokens, costs, and performance metrics automatically
-- **Custom Metadata**: Add business context with native TypeScript support
-- **Streaming Support**: Real-time streaming with comprehensive analytics
-- **Tool Use Support**: Full support for Anthropic's function calling and tools
-- **Multi-modal Support**: Works with text, images, and all Claude capabilities
-- **Type Safe**: Complete TypeScript support with no type casting required
-- **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
-
-You have **3 options** to start using Revenium middleware:
-
-### Option 1: Create Project from Scratch
-
-Perfect for new projects. We'll guide you step-by-step from `mkdir` to running tests.
-[Go to Step-by-Step Guide](#option-1-create-project-from-scratch)
-
-### Option 2: Clone Our Repository
-
-Clone and run the repository with working examples.
-[Go to Repository Guide](#option-2-clone-our-repository)
-
-### Option 3: Add to Existing Project
-
-Already have a project? Just install and replace imports.
-[Go to Quick Integration](#option-3-add-to-existing-project)
-
----
-
-## Option 1: Create Project from Scratch
-
-### Step 1: Create Your Project
-
-```bash
-# Create project directory
-mkdir my-anthropic-project
-cd my-anthropic-project
-
-# Initialize Node.js 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
-```
-
-### Step 3: Setup Environment Variables
-
-Create a `.env` file in your project root:
-
-```bash
-# Create .env file
-echo. > .env  # On Windows (CMD)
-touch .env  # On Mac/Linux
-# OR PowerShell
-New-Item -Path .env -ItemType File
-```
-
-Copy and paste the following into `.env`:
-
-```env
-# Anthropic Configuration
-ANTHROPIC_API_KEY=sk-ant-your_anthropic_api_key_here
-
-# Revenium Configuration
-REVENIUM_METERING_API_KEY=hak_your_revenium_api_key_here
-REVENIUM_METERING_BASE_URL=https://api.revenium.io/meter
-
-# Optional: Enable debug logging
-REVENIUM_DEBUG=true
-```
-
-**NOTE**: Replace each `your_..._here` with your actual values.
-
-**IMPORTANT - Environment Matching**:
-
-- If using QA environment URL `"https://api.qa.hcapp.io/meter"`, ensure your `REVENIUM_METERING_API_KEY` is from the **QA environment**
-- If using Production environment URL `"https://api.revenium.io/meter"`, ensure your `REVENIUM_METERING_API_KEY` is from the **Production environment**
-- **Mismatched environments will cause authentication failures**
-
-### Step 4: Create Your First Test
-
-#### TypeScript Test
-
-Create `test-anthropic.ts`:
-
-```typescript
-// test-anthropic.ts
-import "dotenv/config";
-import "@revenium/anthropic";
-import Anthropic from "@anthropic-ai/sdk";
-
-async function testAnthropic() {
-  try {
-    const anthropic = new Anthropic();
-
-    const response = await anthropic.messages.create({
-      model: "claude-sonnet-4-20250514",
-      max_tokens: 100,
-      messages: [{ role: "user", content: "What is artificial intelligence?" }],
-      usageMetadata: {
-        subscriber: {
-          id: "test-user",
-          email: "test@example.com",
-        },
-        organizationId: "test-org",
-        taskType: "test-query",
-      },
-    });
-
-    const text =
-      response.content[0].type === "text"
-        ? response.content[0].text
-        : "Non-text response";
-
-    console.log("Response:", text);
-    // Success! Response and metering data sent to Revenium
-  } catch (error) {
-    console.error("Error:", error);
-  }
-}
-
-testAnthropic();
-```
-
-#### JavaScript Test
-
-Create `test-anthropic.js`:
-
-```javascript
-// test-anthropic.js
-require("dotenv").config();
-require("@revenium/anthropic");
-const Anthropic = require("@anthropic-ai/sdk");
-
-async function testAnthropic() {
-  try {
-    const anthropic = new Anthropic();
-
-    const response = await anthropic.messages.create({
-      model: "claude-3-5-sonnet-latest",
-      max_tokens: 100,
-      messages: [{ role: "user", content: "What is artificial intelligence?" }],
-    });
-
-    const text =
-      response.content[0].type === "text"
-        ? response.content[0].text
-        : "Non-text response";
-
-    // Success! Response and metering data sent to Revenium
-  } catch (error) {
-    // Handle error appropriately
-  }
-}
-
-testAnthropic();
-```
-
-### Step 5: Update package.json
-
-Add test scripts to your `package.json`:
-
-```json
-{
-  "type": "commonjs",
-  "scripts": {
-    "test-ts": "npx tsx test-anthropic.ts",
-    "test-js": "node test-anthropic.js"
-  }
-}
-```
-
-### Step 6: Run Your Tests
-
-```bash
-# Test TypeScript
-npm run test-ts
-
-# Test JavaScript
-npm run test-js
-```
-
-### Step 7: Create Advanced Examples
-
-#### Streaming Example
-
-Create `examples/streaming.ts`:
-
-```typescript
-// examples/streaming.ts
-import "dotenv/config";
-import "@revenium/anthropic";
-import Anthropic from "@anthropic-ai/sdk";
-
-async function streamingExample() {
-  try {
-    const anthropic = new Anthropic();
-
-    const stream = await anthropic.messages.create({
-      model: "claude-3-5-sonnet-latest",
-      max_tokens: 200,
-      messages: [{ role: "user", content: "Write a short poem about AI" }],
-      stream: true,
-      usageMetadata: {
-        subscriber: {
-          id: "streaming-user",
-          email: "user@example.com",
-        },
-        organizationId: "creative-org",
-        taskType: "creative-writing",
-        agent: "poetry-bot",
-      },
-    });
-
-    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("\nStreaming completed with metering!");
-  } catch (error) {
-    console.error("Streaming error:", error);
-  }
-}
-
-streamingExample();
-```
-
-### Step 8: Create .gitignore
-
-**Important**: Never commit your API keys!
-
-Create `.gitignore`:
-
-```gitignore
-# Environment variables
-.env
-.env.*
-!.env.example
-
-# Dependencies
-node_modules/
-
-# Logs
-*.log
-
-# TypeScript
-dist/
-build/
-```
-
-### Step 9: Run Your Examples
-
-```bash
-# Basic tests
-npm run test-ts
-npm run test-js
-
-# Advanced streaming
-npx tsx examples/streaming.ts
-```
-
-### Step 10: Project Structure
-
-Your final project should look like this:
-
-```
-my-anthropic-project/
-├── examples/               # Advanced examples
-│   └── streaming.ts
-├── .env                    # Environment variables
-├── .gitignore             # Git ignore file
-├── package.json           # Project configuration
-├── test-anthropic.ts      # TypeScript test
-└── test-anthropic.js      # JavaScript test
-```
-
-## Option 2: Clone Our Repository
-
-### Step 1: Clone the Repository
-
-```bash
-# Clone the repository
-git clone git@github.com:revenium/revenium-middleware-anthropic-node.git
-cd revenium-middleware-anthropic-node
-```
-
-### Step 2: Install Dependencies
-
-```bash
-# Install all dependencies
-npm install
-```
-
-### Step 3: Setup Environment Variables
-
-Create a `.env` file in the project root:
-
-```bash
-# Create .env file
-cp .env.example .env  # If available, or create manually
-```
-
-Copy and paste the following into `.env`:
-
-```env
-# Anthropic Configuration
-ANTHROPIC_API_KEY=sk-ant-your_anthropic_api_key_here
-
-# Revenium Configuration
-REVENIUM_METERING_API_KEY=hak_your_revenium_api_key_here
-REVENIUM_METERING_BASE_URL=https://api.revenium.io/meter
-
-# Optional: Enable debug logging
-REVENIUM_DEBUG=true
-```
-
-**IMPORTANT - Environment Matching**:
-
-- If using QA environment URL `"https://api.qa.hcapp.io/meter"`, ensure your `REVENIUM_METERING_API_KEY` is from the **QA environment**
-- If using Production environment URL `"https://api.revenium.io/meter"`, ensure your `REVENIUM_METERING_API_KEY` is from the **Production environment**
-- **Mismatched environments will cause authentication failures**
-
-### Step 4: Build the Project
-
-```bash
-# Build the middleware
-npm run build
-```
-
-### Step 5: Run the Examples
-
-The repository includes working example files:
-
-```bash
-# Run the basic usage examples (shows all initialization methods)
-npm run example:basic
-
-# Run advanced features (streaming, tools, custom metadata)
-npm run example:advanced
-
-# Or run examples directly with tsx
-npx tsx examples/basic-usage.ts
-npx tsx examples/advanced-features.ts
-```
-
-These examples demonstrate:
-
-- All three initialization approaches (auto, explicit, manual)
-- Basic text generation with usage tracking
-- Streaming responses with metadata
-- Tool/function calling support
-- Custom business metadata integration
-- Error handling and debugging
-
-## Option 3: Add to Existing Project
-
-Already have a project? Just install and replace imports:
-
-### Step 1: Install the Package
-
-```bash
-npm install @revenium/anthropic
-```
-
-### Step 2: Set Environment Variables
-
-#### Option A: Use a .env file (Recommended)
-
-Create a `.env` file in your project root:
-
-```env
-ANTHROPIC_API_KEY=sk-ant-your_anthropic_api_key
-REVENIUM_METERING_API_KEY=hak_your_revenium_api_key
-REVENIUM_METERING_BASE_URL=https://api.revenium.io/meter
-REVENIUM_DEBUG=true
-```
-
-#### Option B: Set variables directly in your terminal
-
-**Linux / macOS (bash/zsh)**
-
-```bash
-export ANTHROPIC_API_KEY="sk-ant-your-anthropic-api-key"
-export REVENIUM_METERING_API_KEY="hak-your-revenium-api-key"
-```
-
-**Windows PowerShell**
-
-```bash
-$env:ANTHROPIC_API_KEY="sk-ant-your-anthropic-api-key"
-$env:REVENIUM_METERING_API_KEY="hak-your-revenium-api-key"
-```
-
-**Windows CMD**
-
-```bash
-set ANTHROPIC_API_KEY=sk-ant-your-anthropic-api-key
-set REVENIUM_METERING_API_KEY=hak-your-revenium-api-key
-```
-
-### Step 3: Update Your Code
-
-**Before:**
-
-```typescript
-import Anthropic from "@anthropic-ai/sdk";
-```
-
-**After:**
-
-```typescript
-import "@revenium/anthropic";
-import Anthropic from "@anthropic-ai/sdk";
-```
-
-### Step 4: Use Anthropic Normally
-
-```typescript
-const anthropic = new Anthropic();
-
-// Your existing code works unchanged - metering happens automatically!
-const response = await anthropic.messages.create({
-  model: "claude-3-5-sonnet-latest",
-  max_tokens: 1024,
-  messages: [{ role: "user", content: "Hello, world!" }],
-  // Optional: Add metadata for enhanced tracking
-  usageMetadata: {
-    userId: "user-123",
-    sessionId: "session-456",
-  },
-});
-```
-
----
-
-## What Gets Tracked
-
-The middleware automatically captures:
-
-- **Token Usage**: Input and output tokens for accurate billing
-- **Request Duration**: Total time for each API call
-- **Model Information**: Which Claude model was used
-- **Operation Type**: Chat completion, streaming, tool use, etc.
-- **Error Tracking**: Failed requests and error details
-- **Streaming Metrics**: Time to first token for streaming responses
-- **Custom Metadata**: Business context you provide
-
-## Advanced Usage
-
-### Initialization Options
-
-The middleware supports three initialization patterns:
-
-#### Option A: Automatic Initialization (Simplest)
-
-```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();
-```
-
-#### Option B: Explicit Initialization (More Control)
-
-```typescript
-import { initialize } from "@revenium/anthropic";
-import Anthropic from "@anthropic-ai/sdk";
-
-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();
-```
-
-### Streaming Responses
-
-```typescript
-import "@revenium/anthropic";
-import Anthropic from "@anthropic-ai/sdk";
-
-const anthropic = new Anthropic();
-
-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);
-  }
-}
-```
-
-### 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
-    };
-  };
-}
-```
-
-## 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) |
-
-**Important Note about `REVENIUM_METERING_BASE_URL`:**
-
-- This variable is **optional** and defaults to the production URL (`https://api.revenium.io/meter`)
-- If you don't set it explicitly, the middleware will use the default production endpoint
-- However, you may see console warnings or errors if the middleware cannot determine the correct environment
-- **Best practice:** Always set this variable explicitly to match your environment:
-
-  ```bash
-  # For Production
-  REVENIUM_METERING_BASE_URL=https://api.revenium.io/meter
-
-  # For QA/Testing
-  REVENIUM_METERING_BASE_URL=https://api.qa.hcapp.io/meter
-  ```
-
-- **Remember:** Your `REVENIUM_METERING_API_KEY` must match the environment of your base URL
-
-### 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,
-});
-```
-
-## Troubleshooting
-
-### Common Issues
-
-#### "Missing API Key" Error
-
-```bash
-# Make sure you've set the API key
-export ANTHROPIC_API_KEY="sk-ant-your-actual-api-key"
-
-# Verify it's set
-echo $ANTHROPIC_API_KEY
-```
-
-#### "Requests not being tracked"
-
-```bash
-# Verify Revenium configuration
-export REVENIUM_METERING_API_KEY="hak-your-actual-revenium-key"
-
-# Enable debug logging to see what's happening
-export REVENIUM_DEBUG="true"
-```
-
-#### TypeScript errors with usageMetadata
-
-- Ensure you're importing the middleware before using Anthropic
-- Check that your TypeScript version is 4.5+ for module augmentation
-- Verify you're using the latest version: `npm update @revenium/anthropic`
-
-#### Build/Import Errors
-
-```bash
-# Clean and reinstall
-rm -rf node_modules package-lock.json
-npm install
-
-# For TypeScript projects
-npm run build
-```
-
-### Debug Mode
-
-Enable detailed logging to troubleshoot issues:
-
-```bash
-export REVENIUM_DEBUG="true"
-node your-script.js
-```
-
-This will show:
-
-- Request/response details
-- Token counting information
-- Metering data being sent
-- Error details
-
-Look for log messages like:
-
-- `[Revenium] Anthropic request intercepted`
-- `[Revenium] Usage metadata extracted`
-- `[Revenium] Revenium tracking successful`
-
-## Supported Models
-
-All Claude models are supported:
-
-| Model                      | Status             | Use Case                              |
-| -------------------------- | ------------------ | ------------------------------------- |
-| `claude-3-5-sonnet-latest` | Supported (Latest) | General purpose, best performance     |
-| `claude-3-5-haiku-latest`  | Supported (Latest) | Fast responses, cost-effective        |
-| `claude-3-opus-latest`     | Supported (Latest) | Complex reasoning, highest capability |
-| `claude-3-sonnet-20240229` | Supported (Stable) | Production workloads                  |
-| `claude-3-haiku-20240307`  | Supported (Stable) | High-volume applications              |
-
-## Included Examples
-
-The package includes these example files:
-
-- **basic-usage.ts**: Simple chat completions with all initialization methods
-- **advanced-features.ts**: Streaming, tools, and custom metadata
-
-All examples are in the `examples/` directory of the installed package. For detailed TypeScript patterns and usage, see [examples/README.md](https://github.com/revenium/revenium-middleware-anthropic-node/blob/main/examples/README.md).
-
-## How It Works
-
-1. **Automatic Patching**: When imported, the middleware patches Anthropic's `messages.create` method
-2. **Request Interception**: All Anthropic requests are intercepted to extract metadata
-3. **Usage Extraction**: Token counts, model info, and timing data are captured
-4. **Async Tracking**: Usage data is sent to Revenium in the background (fire-and-forget)
-5. **Transparent Response**: Original Anthropic responses are returned unchanged
-
-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
-
-## License
-
-This project is licensed under the MIT License - see the [LICENSE](https://github.com/revenium/revenium-middleware-anthropic-node/blob/main/LICENSE) file for details.
-
-## Support
-
-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)
-- **Contact**: Reach out to the Revenium team for additional support
-
-## Development
-
-For development and testing instructions, see [DEVELOPMENT.md](https://github.com/revenium/revenium-middleware-anthropic-node/blob/main/DEVELOPMENT.md).
-
----
-
-**Built by Revenium**
+# Revenium Middleware for Anthropic (Node.js)
+
+[![npm version](https://img.shields.io/npm/v/@revenium/anthropic.svg)](https://www.npmjs.com/package/@revenium/anthropic)
+[![Node Versions](https://img.shields.io/node/v/@revenium/anthropic.svg)](https://www.npmjs.com/package/@revenium/anthropic)
+[![Documentation](https://img.shields.io/badge/docs-revenium.io-blue)](https://docs.revenium.io)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+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
+- **Complete Metering**: Track tokens, costs, and performance metrics automatically
+- **Custom Metadata**: Add business context with native TypeScript support
+- **Streaming Support**: Real-time streaming with comprehensive analytics
+- **Tool Use Support**: Full support for Anthropic's function calling and tools
+- **Multi-modal Support**: Works with text, images, and all Claude capabilities
+- **Type Safe**: Complete TypeScript support with no type casting required
+- **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
+
+```bash
+# Create project directory
+mkdir my-anthropic-project
+cd my-anthropic-project
+
+# Initialize Node.js 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
+```
+
+### Step 3: Setup Environment Variables
+
+Create a `.env` file in your project root:
+
+```bash
+# Create .env file
+echo. > .env  # On Windows (CMD)
+touch .env  # On Mac/Linux
+# OR PowerShell
+New-Item -Path .env -ItemType File
+```
+
+Copy and paste the following into `.env`:
+
+```env
+# Anthropic Configuration
+ANTHROPIC_API_KEY=sk-ant-your_anthropic_api_key_here
+
+# Revenium Configuration
+REVENIUM_METERING_API_KEY=hak_your_revenium_api_key_here
+REVENIUM_METERING_BASE_URL=https://api.revenium.io/meter
+
+# Optional: Enable debug logging
+REVENIUM_DEBUG=true
+```
+
+**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)
+
+```bash
+# Download GitHub's standard Node.gitignore
+curl -o .gitignore https://raw.githubusercontent.com/github/gitignore/main/Node.gitignore
+```
+
+**IMPORTANT**: Ensure these patterns are included to protect your environment variables:
+
+```gitignore
+# Environment variables - CRITICAL for API key protection
+.env
+.env.*
+!.env.example
+```
+
+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
+```
+
+**Browse online:** [`examples/` directory](https://github.com/revenium/revenium-middleware-anthropic-node/tree/HEAD/examples)
+
+---
+
+## What Gets Tracked
+
+The middleware automatically captures:
+
+- **Token Usage**: Input and output tokens for accurate billing
+- **Request Duration**: Total time for each API call
+- **Model Information**: Which Claude model was used
+- **Operation Type**: Chat completion, streaming, tool use, etc.
+- **Error Tracking**: Failed requests and error details
+- **Streaming Metrics**: Time to first token for streaming responses
+- **Custom Metadata**: Business context you provide
+
+## Advanced Usage
+
+### Initialization Options
+
+The middleware supports three initialization patterns:
+
+#### Option A: Automatic Initialization (Simplest)
+
+```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();
+```
+
+#### Option B: Explicit Initialization (More Control)
+
+```typescript
+import { initialize } from "@revenium/anthropic";
+import Anthropic from "@anthropic-ai/sdk";
+
+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();
+```
+
+### Streaming Responses
+
+```typescript
+import "@revenium/anthropic";
+import Anthropic from "@anthropic-ai/sdk";
+
+const anthropic = new Anthropic();
+
+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);
+  }
+}
+```
+
+### 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
+    };
+  };
+}
+```
+
+## 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) |
+
+### 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,
+});
+```
+
+## Troubleshooting
+
+### Common Issues
+
+#### "Missing API Key" Error
+
+```bash
+# Make sure you've set the API key
+export ANTHROPIC_API_KEY="sk-ant-your-actual-api-key"
+
+# Verify it's set
+echo $ANTHROPIC_API_KEY
+```
+
+#### "Requests not being tracked"
+
+```bash
+# Verify Revenium configuration
+export REVENIUM_METERING_API_KEY="hak-your-actual-revenium-key"
+
+# Enable debug logging to see what's happening
+export REVENIUM_DEBUG="true"
+```
+
+#### TypeScript errors with usageMetadata
+
+- Ensure you're importing the middleware before using Anthropic
+- Check that your TypeScript version is 4.5+ for module augmentation
+- Verify you're using the latest version: `npm update @revenium/anthropic`
+
+#### Build/Import Errors
+
+```bash
+# Clean and reinstall
+rm -rf node_modules package-lock.json
+npm install
+
+# For TypeScript projects
+npm run build
+```
+
+### Debug Mode
+
+Enable detailed logging to troubleshoot issues:
+
+```bash
+export REVENIUM_DEBUG="true"
+node your-script.js
+```
+
+This will show:
+
+- Request/response details
+- Token counting information
+- Metering data being sent
+- Error details
+
+Look for log messages like:
+
+- `[Revenium] Anthropic request intercepted`
+- `[Revenium] Usage metadata extracted`
+- `[Revenium] Revenium tracking successful`
+
+## Included Examples
+
+The package includes these example files:
+
+- **basic-usage.ts**: Simple chat completions with all initialization methods
+- **advanced-features.ts**: Streaming, tools, and custom metadata
+
+All examples are in the `examples/` directory of the installed package. For detailed TypeScript patterns and usage, see [examples/README.md](https://github.com/revenium/revenium-middleware-anthropic-node/blob/HEAD/examples/README.md).
+
+## How It Works
+
+1. **Automatic Patching**: When imported, the middleware patches Anthropic's `messages.create` method
+2. **Request Interception**: All Anthropic requests are intercepted to extract metadata
+3. **Usage Extraction**: Token counts, model info, and timing data are captured
+4. **Async Tracking**: Usage data is sent to Revenium in the background (fire-and-forget)
+5. **Transparent Response**: Original Anthropic responses are returned unchanged
+
+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)
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/revenium/revenium-middleware-anthropic-node/blob/HEAD/CONTRIBUTING.md)
+
+## Code of Conduct
+
+See [CODE_OF_CONDUCT.md](https://github.com/revenium/revenium-middleware-anthropic-node/blob/HEAD/CODE_OF_CONDUCT.md)
+
+## Security
+
+See [SECURITY.md](https://github.com/revenium/revenium-middleware-anthropic-node/blob/HEAD/SECURITY.md)
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](https://github.com/revenium/revenium-middleware-anthropic-node/blob/HEAD/LICENSE) file for details.
+
+## Support
+
+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
+
+## Development
+
+For development and testing instructions, see [DEVELOPMENT.md](https://github.com/revenium/revenium-middleware-anthropic-node/blob/HEAD/DEVELOPMENT.md).
+
+---
+
+**Built by Revenium**