@revenium/anthropic 1.0.0

package/README.md

@@ -0,0 +1,807 @@
+# 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.
+
+> **📦 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("\n✅ Streaming 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 https://github.com/revenium/revenium-middleware-anthropic-node-internal.git
+cd revenium-middleware-anthropic-node-internal
+```
+
+### 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`  | ✅       | -                               | Your Revenium API key             |
+| `ANTHROPIC_API_KEY`          | ✅       | -                               | Anthropic Claude API key          |
+| `REVENIUM_METERING_BASE_URL` | ❌       | `https://api.revenium.io/meter` | Revenium metering API base URL    |
+| `REVENIUM_DEBUG`             | ❌       | `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` | ✅ Latest | General purpose, best performance     |
+| `claude-3-5-haiku-latest`  | ✅ Latest | Fast responses, cost-effective        |
+| `claude-3-opus-latest`     | ✅ Latest | Complex reasoning, highest capability |
+| `claude-3-sonnet-20240229` | ✅ Stable | Production workloads                  |
+| `claude-3-haiku-20240307`  | ✅ 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
+- **typescript-monorepo.ts**: TypeScript monorepo integration patterns
+
+All examples are in the `examples/` directory of the installed package.
+
+## 🔄 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](LICENSE) file for details.
+
+## 🤝 Support
+
+For issues, feature requests, or contributions:
+
+- **GitHub Repository**: [revenium/revenium-middleware-anthropic-node-internal](https://github.com/revenium/revenium-middleware-anthropic-node-internal)
+- **Issues**: [Report bugs or request features](https://github.com/revenium/revenium-middleware-anthropic-node-internal/issues)
+- **Contact**: Reach out to the Revenium team for additional support
+
+## Development
+
+For development and testing instructions, see [DEVELOPMENT.md](DEVELOPMENT.md).
+
+---
+
+**Built with ❤️ by Revenium**