@revenium/openai 1.0.8

package/README.md

@@ -0,0 +1,1095 @@
+# 🚀 Revenium OpenAI Middleware for Node.js
+
+[![npm version](https://img.shields.io/npm/v/@revenium/openai.svg)](https://www.npmjs.com/package/@revenium/openai)
+[![Node.js](https://img.shields.io/badge/Node.js-16%2B-green)](https://nodejs.org/)
+[![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)
+
+> **📦 Package Renamed**: This package has been renamed from `revenium-middleware-openai-node` to `@revenium/openai` for better organization and simpler naming. Please update your dependencies accordingly.
+
+**Transparent TypeScript middleware for automatic Revenium usage tracking with OpenAI**
+
+A professional-grade Node.js middleware that seamlessly integrates with OpenAI and Azure OpenAI to provide automatic usage tracking, billing analytics, and comprehensive metadata collection. Features native TypeScript support with zero type casting required and supports both traditional Chat Completions API and the new Responses API.
+
+## ✨ Features
+
+- 🔄 **Seamless Integration** - Native TypeScript support, no type casting required
+- 📊 **Optional Metadata** - Track users, organizations, and custom metadata (all fields optional)
+- 🎯 **Dual API Support** - Chat Completions API + new Responses API (OpenAI SDK 5.8+)
+- ☁️ **Azure OpenAI Support** - Full Azure OpenAI integration with automatic detection
+- 🛡️ **Type Safety** - Complete TypeScript support with IntelliSense
+- 🌊 **Streaming Support** - Handles regular and streaming requests seamlessly
+- ⚡ **Fire-and-Forget** - Never blocks your application flow
+- 🔧 **Zero Configuration** - Auto-initialization from environment variables
+
+## 🚀 Getting Started
+
+Choose your preferred approach to get started quickly:
+
+### 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: Try the Examples
+
+Quick testing with the included example files.
+[👉 Go to Examples Guide](#option-2-try-the-examples)
+
+### Option 3: Add to Existing Project
+
+Already have a project? Just install and replace imports.
+[👉 Go to Integration Guide](#option-3-existing-project-integration)
+
+---
+
+## Option 1: Create Project from Scratch
+
+### Step 1: Create Project Directory
+
+```bash
+# Create and navigate to your project
+mkdir my-openai-project
+cd my-openai-project
+
+# Initialize npm project
+npm init -y
+```
+
+### Step 2: Install Dependencies
+
+```bash
+# Install the middleware and OpenAI SDK
+npm install @revenium/openai openai@^5.8.0 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
+# OpenAI Configuration
+OPENAI_API_KEY=sk-your_openai_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-openai.ts`:
+
+```typescript
+import 'dotenv/config';
+import { initializeReveniumFromEnv, patchOpenAIInstance } from '@revenium/openai';
+import OpenAI from 'openai';
+
+async function testOpenAI() {
+  try {
+    // Initialize Revenium middleware
+    const initResult = initializeReveniumFromEnv();
+    if (!initResult.success) {
+      console.error('❌ Failed to initialize Revenium:', initResult.message);
+      process.exit(1);
+    }
+
+    // Create and patch OpenAI instance
+    const openai = patchOpenAIInstance(new OpenAI());
+
+    const response = await openai.chat.completions.create({
+      model: 'gpt-4o-mini',
+      max_tokens: 100,
+      messages: [{ role: 'user', content: 'What is artificial intelligence?' }],
+      usageMetadata: {
+        subscriber: {
+          id: 'user-456',
+          email: 'user@demo-org.com',
+          credential: {
+            name: 'demo-api-key',
+            value: 'demo-key-123',
+          },
+        },
+        organizationId: 'demo-org-123',
+        productId: 'ai-assistant-v2',
+        taskType: 'educational-query',
+        agent: 'openai-basic-demo',
+        traceId: 'session-' + Date.now(),
+      },
+    });
+
+    const text = response.choices[0]?.message?.content || 'No response';
+    console.log('Response:', text);
+  } catch (error) {
+    console.error('Error:', error);
+  }
+}
+
+testOpenAI();
+```
+
+#### JavaScript Test
+
+Create `test-openai.js`:
+
+```javascript
+require('dotenv').config();
+const {
+  initializeReveniumFromEnv,
+  patchOpenAIInstance,
+} = require('@revenium/openai');
+const OpenAI = require('openai');
+
+async function testOpenAI() {
+  try {
+    // Initialize Revenium middleware
+    const initResult = initializeReveniumFromEnv();
+    if (!initResult.success) {
+      console.error('❌ Failed to initialize Revenium:', initResult.message);
+      process.exit(1);
+    }
+
+    // Create and patch OpenAI instance
+    const openai = patchOpenAIInstance(new OpenAI());
+
+    const response = await openai.chat.completions.create({
+      model: 'gpt-4o-mini',
+      max_tokens: 100,
+      messages: [{ role: 'user', content: 'What is artificial intelligence?' }],
+      usageMetadata: {
+        subscriber: {
+          id: 'user-456',
+          email: 'user@demo-org.com',
+        },
+        organizationId: 'demo-org-123',
+        taskType: 'educational-query',
+      },
+    });
+
+    const text = response.choices[0]?.message?.content || 'No response';
+    console.log('Response:', text);
+  } catch (error) {
+    // Handle error appropriately
+  }
+}
+
+testOpenAI();
+```
+
+### Step 5: Add Package Scripts
+
+Update your `package.json`:
+
+```json
+{
+  "name": "my-openai-project",
+  "version": "1.0.0",
+  "type": "commonjs",
+  "scripts": {
+    "test-ts": "npx tsx test-openai.ts",
+    "test-js": "node test-openai.js"
+  },
+  "dependencies": {
+    "@revenium/openai": "^1.0.7",
+    "openai": "^5.8.0",
+    "dotenv": "^16.5.0"
+  }
+}
+```
+
+### Step 6: Run Your Tests
+
+```bash
+# Test TypeScript version
+npm run test-ts
+
+# Test JavaScript version
+npm run test-js
+```
+
+### Step 7: Project Structure
+
+Your project should now look like this:
+
+```
+my-openai-project/
+├── .env                   # Environment variables
+├── .gitignore             # Git ignore file
+├── package.json           # Project configuration
+├── test-openai.ts         # TypeScript test
+└── test-openai.js         # JavaScript test
+```
+
+## Option 2: Try the Examples
+
+### Step 1: Install the Package
+
+```bash
+npm install @revenium/openai openai@^5.8.0
+```
+
+### Step 2: Set Environment Variables
+
+```bash
+# OpenAI Configuration
+export OPENAI_API_KEY="sk-your-openai-api-key"
+
+# Revenium Configuration
+export REVENIUM_METERING_API_KEY="hak-your-revenium-api-key"
+export REVENIUM_METERING_BASE_URL="https://api.revenium.io/meter"
+
+# Optional: Enable debug logging
+export 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 3: Run the Included Examples
+
+The package includes working example files:
+
+### Chat Completions API (Current)
+
+- **[OpenAI Basic](examples/openai-basic.ts)** - Chat completions and embeddings with optional metadata
+- **[OpenAI Streaming](examples/openai-streaming.ts)** - Streaming responses and batch embeddings with optional metadata
+- **[Azure Basic](examples/azure-basic.ts)** - Azure OpenAI chat completions and embeddings with optional metadata
+- **[Azure Streaming](examples/azure-streaming.ts)** - Azure OpenAI streaming and batch embeddings with optional metadata
+
+### Responses API (New)
+
+- **[OpenAI Responses Basic](examples/openai-responses-basic.ts)** - New Responses API with optional metadata
+- **[OpenAI Responses Streaming](examples/openai-responses-streaming.ts)** - Streaming Responses API with optional metadata
+- **[Azure Responses Basic](examples/azure-responses-basic.ts)** - Azure Responses API with optional metadata
+- **[Azure Responses Streaming](examples/azure-responses-streaming.ts)** - Azure streaming Responses API with optional metadata
+
+```bash
+# Chat Completions API examples
+npx tsx node_modules/@revenium/openai/examples/openai-basic.ts
+npx tsx node_modules/@revenium/openai/examples/openai-streaming.ts
+npx tsx node_modules/@revenium/openai/examples/azure-basic.ts
+npx tsx node_modules/@revenium/openai/examples/azure-streaming.ts
+
+# Responses API examples (available with OpenAI SDK 5.8+)
+npx tsx node_modules/@revenium/openai/examples/openai-responses-basic.ts
+npx tsx node_modules/@revenium/openai/examples/openai-responses-streaming.ts
+npx tsx node_modules/@revenium/openai/examples/azure-responses-basic.ts
+npx tsx node_modules/@revenium/openai/examples/azure-responses-streaming.ts
+```
+
+These examples demonstrate:
+
+- **Chat Completions API** - Traditional OpenAI chat completions and embeddings
+- **Responses API** - New OpenAI Responses API with enhanced capabilities
+- **Azure OpenAI** - Full Azure OpenAI integration with automatic detection
+- **Streaming Support** - Real-time response streaming with metadata tracking
+- **Optional Metadata** - Rich business context and user tracking
+- **Error Handling** - Robust error handling and debugging
+
+## Option 3: Existing Project Integration
+
+Already have a project? Just install and replace imports:
+
+### Step 1: Install the Package
+
+```bash
+npm install @revenium/openai
+```
+
+### Step 2: Update Your Imports
+
+**Before:**
+
+```typescript
+import OpenAI from 'openai';
+
+const openai = new OpenAI();
+```
+
+**After:**
+
+```typescript
+import { initializeReveniumFromEnv, patchOpenAIInstance } from '@revenium/openai';
+import OpenAI from 'openai';
+
+// Initialize Revenium middleware
+initializeReveniumFromEnv();
+
+// Patch your OpenAI instance
+const openai = patchOpenAIInstance(new OpenAI());
+```
+
+### Step 3: Add Environment Variables
+
+Add to your `.env` file:
+
+```env
+REVENIUM_METERING_API_KEY=hak_your_revenium_api_key_here
+REVENIUM_METERING_BASE_URL=https://api.revenium.io/meter
+REVENIUM_DEBUG=true
+```
+
+### Step 4: Optional - Add Metadata
+
+Enhance your existing calls with optional metadata:
+
+```typescript
+// Your existing code works unchanged
+const response = await openai.chat.completions.create({
+  model: 'gpt-4o-mini',
+  messages: [{ role: 'user', content: 'Hello!' }],
+  // Add optional metadata for better analytics
+  usageMetadata: {
+    subscriber: { id: 'user-123' },
+    organizationId: 'my-company',
+    taskType: 'chat',
+  },
+});
+```
+
+**✅ That's it!** Your existing OpenAI code now automatically tracks usage to Revenium.
+
+## 📊 What Gets Tracked
+
+The middleware automatically captures comprehensive usage data:
+
+### **🔢 Usage Metrics**
+
+- **Token Counts** - Input tokens, output tokens, total tokens
+- **Model Information** - Model name, provider (OpenAI/Azure), API version
+- **Request Timing** - Request duration, response time
+- **Cost Calculation** - Estimated costs based on current pricing
+
+### **🏷️ Business Context (Optional)**
+
+- **User Tracking** - Subscriber ID, email, credentials
+- **Organization Data** - Organization ID, subscription ID, product ID
+- **Task Classification** - Task type, agent identifier, trace ID
+- **Quality Metrics** - Response quality scores, custom metadata
+
+### **🔧 Technical Details**
+
+- **API Endpoints** - Chat completions, embeddings, responses API
+- **Request Types** - Streaming vs non-streaming
+- **Error Tracking** - Failed requests, error types, retry attempts
+- **Environment Info** - Development vs production usage
+
+## OpenAI Responses API Support
+
+This middleware includes **full support** for OpenAI's new Responses API, which is designed to replace the traditional Chat Completions API with enhanced capabilities for agent-like applications.
+
+### What is the Responses API?
+
+The Responses API is OpenAI's new stateful API that:
+
+- Uses `input` instead of `messages` parameter for simplified interaction
+- Provides unified experience combining chat completions and assistants capabilities
+- Supports advanced features like background tasks, function calling, and code interpreter
+- Offers better streaming and real-time response generation
+- Works with GPT-5 and other advanced models
+
+### API Comparison
+
+**Traditional Chat Completions:**
+
+```javascript
+const response = await openai.chat.completions.create({
+  model: 'gpt-4o',
+  messages: [{ role: 'user', content: 'Hello' }],
+});
+```
+
+**New Responses API:**
+
+```javascript
+const response = await openai.responses.create({
+  model: 'gpt-5',
+  input: 'Hello', // Simplified input parameter
+});
+```
+
+### Key Differences
+
+| Feature                | Chat Completions             | Responses API                       |
+| ---------------------- | ---------------------------- | ----------------------------------- |
+| **Input Format**       | `messages: [...]`            | `input: "string"` or `input: [...]` |
+| **Models**             | GPT-4, GPT-4o, etc.          | GPT-5, GPT-4o, etc.                 |
+| **Response Structure** | `choices[0].message.content` | `output_text`                       |
+| **Stateful**           | No                           | Yes (with `store: true`)            |
+| **Advanced Features**  | Limited                      | Built-in tools, reasoning, etc.     |
+| **Temperature**        | Supported                    | Not supported with GPT-5            |
+
+### Requirements & Installation
+
+**OpenAI SDK Version:**
+
+- **Minimum:** `5.8.0` (when Responses API was officially released)
+- **Recommended:** `5.8.2` or later (tested and verified)
+- **Current:** `6.2.0` (latest available)
+
+**Installation:**
+
+```bash
+# Install latest version with Responses API support
+npm install openai@^5.8.0
+
+# Or install specific tested version
+npm install openai@5.8.2
+```
+
+### Current Status
+
+✅ **The Responses API is officially available in OpenAI SDK 5.8+**
+
+**Official Release:**
+
+- ✅ Released by OpenAI in SDK version 5.8.0
+- ✅ Fully documented in official OpenAI documentation
+- ✅ Production-ready with GPT-5 and other supported models
+- ✅ Complete middleware support with Revenium integration
+
+**Middleware Features:**
+
+- ✅ Full Responses API support (streaming & non-streaming)
+- ✅ Seamless metadata tracking identical to Chat Completions
+- ✅ Type-safe TypeScript integration
+- ✅ Complete token tracking including reasoning tokens
+- ✅ Azure OpenAI compatibility
+
+**References:**
+
+- [OpenAI Responses API Documentation](https://platform.openai.com/docs/guides/migrate-to-responses)
+- [Azure OpenAI Responses API Documentation](https://learn.microsoft.com/en-us/azure/ai-foundry/openai/how-to/responses)
+
+### Responses API Examples
+
+The middleware includes comprehensive examples for the new Responses API:
+
+**Basic Usage:**
+
+```typescript
+import { initializeReveniumFromEnv, patchOpenAIInstance } from '@revenium/openai';
+import OpenAI from 'openai';
+
+// Initialize and patch OpenAI instance
+initializeReveniumFromEnv();
+const openai = patchOpenAIInstance(new OpenAI());
+
+// Simple string input
+const response = await openai.responses.create({
+  model: 'gpt-5',
+  input: 'What is the capital of France?',
+  max_output_tokens: 150,
+  usageMetadata: {
+    subscriber: { id: 'user-123', email: 'user@example.com' },
+    organizationId: 'org-456',
+    productId: 'quantum-explainer',
+    taskType: 'educational-content',
+  },
+});
+
+console.log(response.output_text); // "Paris."
+```
+
+**Streaming Example:**
+
+```typescript
+const stream = await openai.responses.create({
+  model: 'gpt-5',
+  input: 'Write a short story about AI',
+  stream: true,
+  max_output_tokens: 500,
+  usageMetadata: {
+    subscriber: { id: 'user-123', email: 'user@example.com' },
+    organizationId: 'org-456',
+  },
+});
+
+for await (const chunk of stream) {
+  process.stdout.write(chunk.delta?.content || '');
+}
+```
+
+### Adding Custom Metadata
+
+Track users, organizations, and custom data with seamless TypeScript integration:
+
+```typescript
+import { initializeReveniumFromEnv, patchOpenAIInstance } from '@revenium/openai';
+import OpenAI from 'openai';
+
+// Initialize and patch OpenAI instance
+initializeReveniumFromEnv();
+const openai = patchOpenAIInstance(new OpenAI());
+
+const response = await openai.chat.completions.create({
+  model: 'gpt-4',
+  messages: [{ role: 'user', content: 'Summarize this document' }],
+  // Add custom tracking metadata - all fields optional, no type casting needed!
+  usageMetadata: {
+    subscriber: {
+      id: 'user-12345',
+      email: 'john@acme-corp.com',
+    },
+    organizationId: 'acme-corp',
+    productId: 'document-ai',
+    taskType: 'document-summary',
+    agent: 'doc-summarizer-v2',
+    traceId: 'session-abc123',
+  },
+});
+
+// Same metadata works with Responses API
+const responsesResult = await openai.responses.create({
+  model: 'gpt-5',
+  input: 'Summarize this document',
+  // Same metadata structure - seamless compatibility!
+  usageMetadata: {
+    subscriber: {
+      id: 'user-12345',
+      email: 'john@acme-corp.com',
+    },
+    organizationId: 'acme-corp',
+    productId: 'document-ai',
+    taskType: 'document-summary',
+    agent: 'doc-summarizer-v2',
+    traceId: 'session-abc123',
+  },
+});
+```
+
+### Streaming Support
+
+The middleware automatically handles streaming requests with seamless metadata:
+
+```typescript
+import { initializeReveniumFromEnv, patchOpenAIInstance } from 'revenium-middleware-openai-node';
+import OpenAI from 'openai';
+
+// Initialize and patch OpenAI instance
+initializeReveniumFromEnv();
+const openai = patchOpenAIInstance(new OpenAI());
+
+const stream = await openai.chat.completions.create({
+  model: 'gpt-4',
+  messages: [{ role: 'user', content: 'Tell me a story' }],
+  stream: true,
+  // Metadata works seamlessly with streaming - all fields optional!
+  usageMetadata: {
+    organizationId: 'story-app',
+    taskType: 'creative-writing',
+  },
+});
+
+for await (const chunk of stream) {
+  process.stdout.write(chunk.choices[0]?.delta?.content || '');
+}
+// Usage tracking happens automatically when stream completes
+```
+
+### Temporarily Disabling Tracking
+
+If you need to disable Revenium tracking temporarily, you can unpatch the OpenAI client:
+
+```javascript
+import { unpatchOpenAI, patchOpenAI } from '@revenium/openai-middleware';
+
+// Disable tracking
+unpatchOpenAI();
+
+// Your OpenAI calls now bypass Revenium tracking
+await openai.chat.completions.create({...});
+
+// Re-enable tracking
+patchOpenAI();
+```
+
+**Common use cases:**
+
+- **Debugging**: Isolate whether issues are caused by the middleware
+- **Testing**: Compare behavior with/without tracking
+- **Conditional tracking**: Enable/disable based on environment
+- **Troubleshooting**: Temporary bypass during incident response
+
+**Note**: This affects all OpenAI instances globally since we patch the prototype methods.
+
+## Azure OpenAI Integration
+
+**Azure OpenAI support** The middleware automatically detects Azure OpenAI clients and provides accurate usage tracking and cost calculation.
+
+### Quick Start with Azure OpenAI
+
+```bash
+# Set your Azure OpenAI environment variables
+export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
+export AZURE_OPENAI_API_KEY="your-azure-api-key"
+export AZURE_OPENAI_DEPLOYMENT="gpt-4o"  # Your deployment name
+export AZURE_OPENAI_API_VERSION="2024-12-01-preview"  # Optional, defaults to latest
+
+# Set your Revenium credentials
+export REVENIUM_METERING_API_KEY="hak_your_revenium_api_key"
+# export REVENIUM_METERING_BASE_URL="https://api.revenium.io/meter"  # Optional: defaults to this URL
+```
+
+```typescript
+import { initializeReveniumFromEnv, patchOpenAIInstance } from '@revenium/openai';
+import { AzureOpenAI } from 'openai';
+
+// Initialize Revenium middleware
+initializeReveniumFromEnv();
+
+// Create and patch Azure OpenAI client
+const azure = patchOpenAIInstance(
+  new AzureOpenAI({
+    endpoint: process.env.AZURE_OPENAI_ENDPOINT,
+    apiKey: process.env.AZURE_OPENAI_API_KEY,
+    apiVersion: process.env.AZURE_OPENAI_API_VERSION,
+  })
+);
+
+// Your existing Azure OpenAI code works with seamless metadata
+const response = await azure.chat.completions.create({
+  model: 'gpt-4o', // Uses your deployment name
+  messages: [{ role: 'user', content: 'Hello from Azure!' }],
+  // Optional metadata with native TypeScript support
+  usageMetadata: {
+    organizationId: 'my-company',
+    taskType: 'azure-chat',
+  },
+});
+
+console.log(response.choices[0].message.content);
+```
+
+### Azure Features
+
+- **Automatic Detection**: Detects Azure OpenAI clients automatically
+- **Model Name Resolution**: Maps Azure deployment names to standard model names for accurate pricing
+- **Provider Metadata**: Correctly tags requests with `provider: "Azure"` and `modelSource: "OPENAI"`
+- **Deployment Support**: Works with any Azure deployment name (simple or complex)
+- **Endpoint Flexibility**: Supports all Azure OpenAI endpoint formats
+- **Zero Code Changes**: Existing Azure OpenAI code works without modification
+
+### Azure Environment Variables
+
+| Variable                   | Required | Description                                    | Example                              |
+| -------------------------- | -------- | ---------------------------------------------- | ------------------------------------ |
+| `AZURE_OPENAI_ENDPOINT`    | Yes      | Your Azure OpenAI endpoint URL                 | `https://acme.openai.azure.com/`     |
+| `AZURE_OPENAI_API_KEY`     | Yes      | Your Azure OpenAI API key                      | `abc123...`                          |
+| `AZURE_OPENAI_DEPLOYMENT`  | No       | Default deployment name                        | `gpt-4o` or `text-embedding-3-large` |
+| `AZURE_OPENAI_API_VERSION` | No       | API version (defaults to `2024-12-01-preview`) | `2024-12-01-preview`                 |
+
+### Azure Model Name Resolution
+
+The middleware automatically maps Azure deployment names to standard model names for accurate pricing:
+
+```typescript
+// Azure deployment names → Standard model names for pricing
+"gpt-4o-2024-11-20"     → "gpt-4o"
+"gpt4o-prod"            → "gpt-4o"
+"o4-mini"               → "gpt-4o-mini"
+"gpt-35-turbo-dev"      → "gpt-3.5-turbo"
+"text-embedding-3-large" → "text-embedding-3-large"  // Direct match
+"embedding-3-large"     → "text-embedding-3-large"
+```
+
+## 🔧 Advanced Usage
+
+### Streaming with Metadata
+
+The middleware seamlessly handles streaming requests with full metadata support:
+
+```typescript
+import { initializeReveniumFromEnv, patchOpenAIInstance } from '@revenium/openai';
+import OpenAI from 'openai';
+
+initializeReveniumFromEnv();
+const openai = patchOpenAIInstance(new OpenAI());
+
+// Chat Completions API streaming
+const stream = await openai.chat.completions.create({
+  model: 'gpt-4o-mini',
+  messages: [{ role: 'user', content: 'Tell me a story' }],
+  stream: true,
+  usageMetadata: {
+    subscriber: { id: 'user-123', email: 'user@example.com' },
+    organizationId: 'story-app',
+    taskType: 'creative-writing',
+    traceId: 'session-' + Date.now(),
+  },
+});
+
+for await (const chunk of stream) {
+  process.stdout.write(chunk.choices[0]?.delta?.content || '');
+}
+// Usage tracking happens automatically when stream completes
+```
+
+### Responses API with Metadata
+
+Full support for OpenAI's new Responses API:
+
+```typescript
+// Simple string input with metadata
+const response = await openai.responses.create({
+  model: 'gpt-5',
+  input: 'What is the capital of France?',
+  max_output_tokens: 150,
+  usageMetadata: {
+    subscriber: { id: 'user-123', email: 'user@example.com' },
+    organizationId: 'org-456',
+    productId: 'geography-tutor',
+    taskType: 'educational-query',
+  },
+});
+
+console.log(response.output_text); // "Paris."
+```
+
+### Azure OpenAI Integration
+
+Automatic Azure OpenAI detection with seamless metadata:
+
+```typescript
+import { AzureOpenAI } from 'openai';
+
+// Create and patch Azure OpenAI client
+const azure = patchOpenAIInstance(
+  new AzureOpenAI({
+    endpoint: process.env.AZURE_OPENAI_ENDPOINT,
+    apiKey: process.env.AZURE_OPENAI_API_KEY,
+    apiVersion: process.env.AZURE_OPENAI_API_VERSION,
+  })
+);
+
+// Your existing Azure OpenAI code works with seamless metadata
+const response = await azure.chat.completions.create({
+  model: 'gpt-4o', // Uses your deployment name
+  messages: [{ role: 'user', content: 'Hello from Azure!' }],
+  usageMetadata: {
+    organizationId: 'my-company',
+    taskType: 'azure-chat',
+    agent: 'azure-assistant',
+  },
+});
+```
+
+### Embeddings with Metadata
+
+Track embeddings usage with optional metadata:
+
+```typescript
+const embedding = await openai.embeddings.create({
+  model: 'text-embedding-3-small',
+  input: 'Advanced text embedding with comprehensive tracking metadata',
+  usageMetadata: {
+    subscriber: { id: 'embedding-user-789', email: 'embeddings@company.com' },
+    organizationId: 'my-company',
+    taskType: 'document-embedding',
+    productId: 'search-engine',
+    traceId: `embed-${Date.now()}`,
+    agent: 'openai-embeddings-node',
+  },
+});
+
+console.log('Model:', embedding.model);
+console.log('Usage:', embedding.usage);
+console.log('Embedding dimensions:', embedding.data[0]?.embedding.length);
+```
+
+### Manual Configuration
+
+For advanced use cases, configure the middleware manually:
+
+```typescript
+import { configure } from '@revenium/openai';
+
+configure({
+  reveniumApiKey: 'hak_your_api_key',
+  reveniumBaseUrl: 'https://api.revenium.io/meter',
+  apiTimeout: 5000,
+  failSilent: true,
+  maxRetries: 3,
+});
+```
+
+## 🛠️ Configuration Options
+
+### Environment Variables
+
+| Variable                     | Required | Default                         | Description                       |
+| ---------------------------- | -------- | ------------------------------- | --------------------------------- |
+| `REVENIUM_METERING_API_KEY`  | ✅       | -                               | Your Revenium API key             |
+| `OPENAI_API_KEY`             | ✅       | -                               | OpenAI 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
+
+### Usage Metadata Options
+
+All metadata fields are optional and help provide better analytics:
+
+```typescript
+interface UsageMetadata {
+  traceId?: string; // Session or conversation ID
+  taskType?: string; // Type of AI task (e.g., "chat", "summary")
+  subscriber?: {
+    // User information (nested structure)
+    id?: string; // User ID from your system
+    email?: string; // User's email address
+    credential?: {
+      // User credentials
+      name?: string; // Credential name
+      value?: string; // Credential value
+    };
+  };
+  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)
+}
+```
+
+## How It Works
+
+1. **Automatic Patching**: When imported, the middleware patches OpenAI's methods:
+   - `chat.completions.create` (Chat Completions API)
+   - `responses.create` (Responses API - when available)
+   - `embeddings.create` (Embeddings API)
+2. **Request Interception**: All OpenAI 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 OpenAI responses are returned unchanged
+
+The middleware never blocks your application - if Revenium tracking fails, your OpenAI requests continue normally.
+
+## 🔍 Troubleshooting
+
+### Common Issues
+
+#### 1. **No tracking data in dashboard**
+
+**Symptoms**: OpenAI calls work but no data appears in Revenium dashboard
+
+**Solution**: Enable debug logging to check middleware status:
+
+```bash
+export REVENIUM_DEBUG=true
+```
+
+**Expected output for successful tracking**:
+
+```bash
+[Revenium Debug] OpenAI chat.completions.create intercepted
+[Revenium Debug] Revenium tracking successful
+
+# For Responses API:
+[Revenium Debug] OpenAI responses.create intercepted
+[Revenium Debug] Revenium tracking successful
+```
+
+#### 2. **Environment mismatch errors**
+
+**Symptoms**: Authentication errors or 401/403 responses
+
+**Solution**: Ensure your API key matches your base URL environment:
+
+```bash
+# ✅ Correct - Production key with production URL
+REVENIUM_METERING_API_KEY=hak_prod_key_here
+REVENIUM_METERING_BASE_URL=https://api.revenium.io/meter
+
+# ✅ Correct - QA key with QA URL
+REVENIUM_METERING_API_KEY=hak_qa_key_here
+REVENIUM_METERING_BASE_URL=https://api.qa.hcapp.io/meter
+
+# ❌ Wrong - Production key with QA URL
+REVENIUM_METERING_API_KEY=hak_prod_key_here
+REVENIUM_METERING_BASE_URL=https://api.qa.hcapp.io/meter
+```
+
+#### 3. **TypeScript type errors**
+
+**Symptoms**: TypeScript errors about `usageMetadata` property
+
+**Solution**: Ensure you're importing the middleware before OpenAI:
+
+```typescript
+// ✅ Correct order
+import { initializeReveniumFromEnv, patchOpenAIInstance } from '@revenium/openai';
+import OpenAI from 'openai';
+
+// ❌ Wrong order
+import OpenAI from 'openai';
+import { initializeReveniumFromEnv, patchOpenAIInstance } from '@revenium/openai';
+```
+
+#### 4. **Azure OpenAI not working**
+
+**Symptoms**: Azure OpenAI calls not being tracked
+
+**Solution**: Ensure you're using `patchOpenAIInstance()` with your Azure client:
+
+```typescript
+import { AzureOpenAI } from 'openai';
+import { patchOpenAIInstance } from '@revenium/openai';
+
+// ✅ Correct
+const azure = patchOpenAIInstance(new AzureOpenAI({...}));
+
+// ❌ Wrong - not patched
+const azure = new AzureOpenAI({...});
+```
+
+#### 5. **Responses API not available**
+
+**Symptoms**: `openai.responses.create` is undefined
+
+**Solution**: Upgrade to OpenAI SDK 5.8+ for Responses API support:
+
+```bash
+npm install openai@^5.8.0
+```
+
+### Debug Mode
+
+Enable comprehensive debug logging:
+
+```bash
+export REVENIUM_DEBUG=true
+```
+
+This will show:
+
+- ✅ Middleware initialization status
+- ✅ Request interception confirmations
+- ✅ Metadata extraction details
+- ✅ Tracking success/failure messages
+- ✅ Error details and stack traces
+
+### Getting Help
+
+If you're still experiencing issues:
+
+1. **Check the logs** with `REVENIUM_DEBUG=true`
+2. **Verify environment variables** are set correctly
+3. **Test with minimal example** from our documentation
+4. **Contact support** with debug logs and error details
+
+For detailed troubleshooting guides, visit [docs.revenium.io](https://docs.revenium.io)
+
+## 🤖 Supported Models
+
+### OpenAI Models
+
+| Model Family      | Models                                                                       | APIs Supported              |
+| ----------------- | ---------------------------------------------------------------------------- | --------------------------- |
+| **GPT-4o**        | `gpt-4o`, `gpt-4o-2024-11-20`, `gpt-4o-2024-08-06`, `gpt-4o-2024-05-13`      | Chat Completions, Responses |
+| **GPT-4o Mini**   | `gpt-4o-mini`, `gpt-4o-mini-2024-07-18`                                      | Chat Completions, Responses |
+| **GPT-4 Turbo**   | `gpt-4-turbo`, `gpt-4-turbo-2024-04-09`, `gpt-4-turbo-preview`               | Chat Completions            |
+| **GPT-4**         | `gpt-4`, `gpt-4-0613`, `gpt-4-0314`                                          | Chat Completions            |
+| **GPT-3.5 Turbo** | `gpt-3.5-turbo`, `gpt-3.5-turbo-0125`, `gpt-3.5-turbo-1106`                  | Chat Completions            |
+| **GPT-5**         | `gpt-5` (when available)                                                     | Responses API               |
+| **Embeddings**    | `text-embedding-3-large`, `text-embedding-3-small`, `text-embedding-ada-002` | Embeddings                  |
+
+### Azure OpenAI Models
+
+All OpenAI models are supported through Azure OpenAI with automatic deployment name resolution:
+
+| Azure Deployment         | Resolved Model           | API Support                 |
+| ------------------------ | ------------------------ | --------------------------- |
+| `gpt-4o-2024-11-20`      | `gpt-4o`                 | Chat Completions, Responses |
+| `gpt4o-prod`             | `gpt-4o`                 | Chat Completions, Responses |
+| `o4-mini`                | `gpt-4o-mini`            | Chat Completions, Responses |
+| `gpt-35-turbo-dev`       | `gpt-3.5-turbo`          | Chat Completions            |
+| `text-embedding-3-large` | `text-embedding-3-large` | Embeddings                  |
+| `embedding-3-large`      | `text-embedding-3-large` | Embeddings                  |
+
+**Note**: The middleware automatically maps Azure deployment names to standard model names for accurate pricing and analytics.
+
+### API Support Matrix
+
+| Feature               | Chat Completions API | Responses API | Embeddings API |
+| --------------------- | -------------------- | ------------- | -------------- |
+| **Basic Requests**    | ✅                   | ✅            | ✅             |
+| **Streaming**         | ✅                   | ✅            | ❌             |
+| **Metadata Tracking** | ✅                   | ✅            | ✅             |
+| **Azure OpenAI**      | ✅                   | ✅            | ✅             |
+| **Cost Calculation**  | ✅                   | ✅            | ✅             |
+| **Token Counting**    | ✅                   | ✅            | ✅             |
+
+## Requirements
+
+- Node.js 16+
+- OpenAI package v4.0+
+- TypeScript 5.0+ (for TypeScript projects)
+
+## Documentation
+
+For detailed documentation, visit [docs.revenium.io](https://docs.revenium.io)
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md)
+
+## Code of Conduct
+
+See [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)
+
+## Security
+
+See [SECURITY.md](./SECURITY.md)
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.
+
+## Acknowledgments
+
+- Built by the Revenium team