@revenium/openai 1.0.11 → 1.0.13

package/README.md

@@ -3,6 +3,7 @@
 [![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)
+[![Website](https://img.shields.io/badge/website-revenium.ai-blue)](https://www.revenium.ai)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 **Transparent TypeScript middleware for automatic Revenium usage tracking with OpenAI**
@@ -12,475 +13,72 @@ A professional-grade Node.js middleware that seamlessly integrates with OpenAI a
 ## 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+)
+- **Optional Metadata** - Track users, organizations, and business context (12 predefined fields, all optional)
+- **Dual API Support** - Chat Completions API + Responses API
 - **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
 
-## Package Migration
-
-This package has been renamed from `revenium-middleware-openai-node` to `@revenium/openai` 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-openai-node
-
-# Install the new package
-npm install @revenium/openai
-```
-
-**Update your imports:**
-
-```typescript
-// Old import
-import { patchOpenAIInstance } from "revenium-middleware-openai-node";
-
-// New import
-import { patchOpenAIInstance } from "@revenium/openai";
-```
-
-All functionality remains exactly the same - only the package name has changed.
-
 ## 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: 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 Integration Guide](#option-3-existing-project-integration)
-
----
-
-## Option 1: Create Project from Scratch
-
-### Step 1: Create Project Directory
+### 1. Create Project Directory
 
 ```bash
-# Create and navigate to your project
+# Create project directory and navigate to it
 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
+# Install packages
+npm install @revenium/openai openai dotenv tsx
+npm install --save-dev typescript @types/node
 ```
 
-### Step 3: Setup Environment Variables
+### 2. Configure Environment Variables
 
-Create a `.env` file in your project root:
+Create a `.env` file:
 
-```bash
-# Create .env file
-echo. > .env  # On Windows (CMD)
-touch .env  # On Mac/Linux
-# OR PowerShell
-New-Item -Path .env -ItemType File
-```
-
-Copy and paste the following into `.env`:
+**NOTE: YOU MUST REPLACE THE PLACEHOLDERS WITH YOUR OWN API KEYS**
 
 ```env
-# Revenium OpenAI Middleware Configuration
-# Copy this file to .env and fill in your actual values
-
-# Required: Your Revenium API key (starts with hak_)
-REVENIUM_METERING_API_KEY=hak_your_revenium_api_key_here
-REVENIUM_METERING_BASE_URL=https://api.revenium.io/meter
-
-# Required: Your OpenAI API key (starts with sk-)
-OPENAI_API_KEY=sk_your_openai_api_key_here
-
-# Optional: Your Azure OpenAI configuration (for Azure testing)
-AZURE_OPENAI_ENDPOINT=https://your-resource-name.openai.azure.com/
-AZURE_OPENAI_API_KEY=your-azure-openai-api-key-here
-AZURE_OPENAI_DEPLOYMENT=your-deployment-name-here
-AZURE_OPENAI_API_VERSION=2024-12-01-preview
-
-# Optional: Enable debug logging
-REVENIUM_DEBUG=false
-```
-
-**NOTE**: Replace each `your_..._here` with your actual values.
-
-**IMPORTANT**: Ensure your `REVENIUM_METERING_API_KEY` matches your `REVENIUM_METERING_BASE_URL` environment. Mismatched credentials will cause authentication failures.
-
-### Step 4: Protect Your API Keys
-
-**CRITICAL SECURITY**: Never commit your `.env` file to version control!
-
-Your `.env` file contains sensitive API keys that must be kept secret:
-
-```bash
-# Verify .env is in your .gitignore
-git check-ignore .env
-```
-
-If the command returns nothing, add `.env` to your `.gitignore`:
-
-```gitignore
-# Environment variables
-.env
-.env.*
-!.env.example
-```
-
-**Best Practice**: Use GitHub's standard Node.gitignore as a starting point:
-- Reference: https://github.com/github/gitignore/blob/main/Node.gitignore
-
-  **Warning:** The following command will overwrite your current `.gitignore` file.
-  To avoid losing custom rules, back up your file first or append instead:
-  `curl https://raw.githubusercontent.com/github/gitignore/main/Node.gitignore >> .gitignore`
-
-  **Note:** Appending may result in duplicate entries if your `.gitignore` already contains some of the patterns from Node.gitignore.  
-  Please review your `.gitignore` after appending and remove any duplicate lines as needed.
-
-This protects your OpenAI API key, Revenium API key, and any other secrets from being accidentally committed to your repository.
-
-### Step 5: 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 6: 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.11",
-    "openai": "^5.8.0",
-    "dotenv": "^16.5.0"
-  }
-}
-```
-
-### Step 7: Run Your Tests
-
-```bash
-# Test TypeScript version
-npm run test-ts
-
-# Test JavaScript version
-npm run test-js
-```
-
-### Step 8: 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: Clone Our Repository
-
-### Step 1: Clone the Repository
-
-```bash
-# Clone the repository
-git clone git@github.com:revenium/revenium-middleware-openai-node.git
-cd revenium-middleware-openai-node
-```
-
-### Step 2: Install Dependencies
-
-```bash
-# Install all dependencies
-npm install
-npm install @revenium/openai
-```
-
-### 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`:
-
-```bash
-# Revenium OpenAI Middleware Configuration
-# Copy this file to .env and fill in your actual values
-
-# Required: Your Revenium API key (starts with hak_)
+REVENIUM_METERING_BASE_URL=https://api.revenium.ai
 REVENIUM_METERING_API_KEY=hak_your_revenium_api_key_here
-REVENIUM_METERING_BASE_URL=https://api.revenium.io/meter
-
-# Required: Your OpenAI API key (starts with sk-)
 OPENAI_API_KEY=sk_your_openai_api_key_here
-
-# Optional: Your Azure OpenAI configuration (for Azure testing)
-AZURE_OPENAI_ENDPOINT=https://your-resource-name.openai.azure.com/
-AZURE_OPENAI_API_KEY=your-azure-openai-api-key-here
-AZURE_OPENAI_DEPLOYMENT=your-deployment-name-here
-AZURE_OPENAI_API_VERSION=2024-12-01-preview
-
-# Optional: Enable debug logging
-REVENIUM_DEBUG=false
 ```
 
-**IMPORTANT**: Ensure your `REVENIUM_METERING_API_KEY` matches your `REVENIUM_METERING_BASE_URL` environment. Mismatched credentials will cause authentication failures.
+### 3. Run Your First Example
 
-### Step 4: Build the Project
+Run the [getting started example](https://github.com/revenium/revenium-middleware-openai-node/blob/HEAD/examples/getting_started.ts):
 
 ```bash
-# Build the middleware
-npm run build
+npx tsx node_modules/@revenium/openai/examples/getting_started.ts
 ```
 
-### Step 5: Run the Examples
-
-The repository includes working example files:
+Or with debug logging:
 
 ```bash
-# Run Chat Completions API examples (using npm scripts)
-npm run example:openai-basic
-npm run example:openai-streaming
-npm run example:azure-basic
-npm run example:azure-streaming
-
-# Run Responses API examples (available with OpenAI SDK 5.8+)
-npm run example:openai-responses-basic
-npm run example:openai-responses-streaming
-npm run example:azure-responses-basic
-npm run example:azure-responses-streaming
-
-# Or run examples directly with tsx
-npx tsx examples/openai-basic.ts
-npx tsx examples/openai-streaming.ts
-npx tsx examples/azure-basic.ts
-npx tsx examples/azure-streaming.ts
-npx tsx examples/openai-responses-basic.ts
-npx tsx examples/openai-responses-streaming.ts
-npx tsx examples/azure-responses-basic.ts
-npx tsx 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
+# Linux/macOS
+REVENIUM_DEBUG=true npx tsx node_modules/@revenium/openai/examples/getting_started.ts
 
-Already have a project? Just install and replace imports:
-
-### Step 1: Install the Package
-
-```bash
-npm install @revenium/openai
+# Windows (PowerShell)
+$env:REVENIUM_DEBUG="true"; npx tsx node_modules/@revenium/openai/examples/getting_started.ts
 ```
 
-### Step 2: Update Your Imports
-
-**Before:**
-
-```typescript
-import OpenAI from 'openai';
-
-const openai = new OpenAI();
-```
+**For more examples and usage patterns, see [examples/README.md](https://github.com/revenium/revenium-middleware-openai-node/blob/HEAD/examples/README.md).**
 
-**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 OpenAI Middleware Configuration
-
-# Required: Your Revenium API key (starts with hak_)
-REVENIUM_METERING_API_KEY=hak_your_revenium_api_key_here
-REVENIUM_METERING_BASE_URL=https://api.revenium.io/meter
-
-# Required: Your OpenAI API key (starts with sk-)
-OPENAI_API_KEY=sk_your_openai_api_key_here
-
-# Optional: Your Azure OpenAI configuration (for Azure testing)
-AZURE_OPENAI_ENDPOINT=https://your-resource-name.openai.azure.com/
-AZURE_OPENAI_API_KEY=your-azure-openai-api-key-here
-AZURE_OPENAI_DEPLOYMENT=your-deployment-name-here
-AZURE_OPENAI_API_VERSION=2024-12-01-preview
-
-# Optional: Enable debug logging
-REVENIUM_DEBUG=false
-```
-
-### Step 4: Optional - Add Metadata
+---
 
-Enhance your existing calls with optional metadata:
+## Requirements
 
-```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',
-  },
-});
-```
+- Node.js 16+
+- OpenAI package v5.0.0 or later
+- TypeScript 5.0+ (for TypeScript projects)
 
-** That's it!** Your existing OpenAI code now automatically tracks usage to Revenium.
+---
 
 ## What Gets Tracked
 
@@ -498,7 +96,7 @@ The middleware automatically captures comprehensive usage data:
 - **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
+- **Quality Metrics** - Response quality scores, task identifiers
 
 ### **Technical Details**
 
@@ -507,443 +105,104 @@ The middleware automatically captures comprehensive usage data:
 - **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());
+## Advanced Usage
 
-// 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',
-  },
-});
+### Initialization Options
 
-console.log(response.output_text); // "Paris."
-```
+The middleware supports three initialization patterns:
 
-**Streaming Example:**
+**Automatic (Recommended)** - Import and patch OpenAI instance:
 
 ```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 { 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',
-  },
-});
+// Tracking works automatically if env vars are set
 ```
 
-### Streaming Support
-
-The middleware automatically handles streaming requests with seamless metadata:
+**Explicit** - Call `initializeReveniumFromEnv()` for error handling control:
 
 ```typescript
 import { initializeReveniumFromEnv, patchOpenAIInstance } from '@revenium/openai';
 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 || '');
+const result = initializeReveniumFromEnv();
+if (!result.success) {
+  console.error('Failed to initialize:', result.message);
+  process.exit(1);
 }
-// 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"
+const openai = patchOpenAIInstance(new OpenAI());
 ```
 
-## Advanced Usage
+**Manual** - Use `configure()` to set all options programmatically (see Manual Configuration below).
 
-### Streaming with Metadata
+For detailed examples of all initialization patterns, see [`examples/`](https://github.com/revenium/revenium-middleware-openai-node/blob/HEAD/examples/README.md).
 
-The middleware seamlessly handles streaming requests with full metadata support:
+### Streaming Responses
 
-```typescript
-import { initializeReveniumFromEnv, patchOpenAIInstance } from '@revenium/openai';
-import OpenAI from 'openai';
+Streaming is fully supported with real-time token tracking. The middleware automatically tracks streaming responses without any additional configuration.
 
-initializeReveniumFromEnv();
-const openai = patchOpenAIInstance(new OpenAI());
+See [`examples/openai-streaming.ts`](https://github.com/revenium/revenium-middleware-openai-node/blob/HEAD/examples/openai-streaming.ts) and [`examples/azure-streaming.ts`](https://github.com/revenium/revenium-middleware-openai-node/blob/HEAD/examples/azure-streaming.ts) for working streaming examples.
 
-// 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(),
-  },
-});
+### Custom Metadata Tracking
 
-for await (const chunk of stream) {
-  process.stdout.write(chunk.choices[0]?.delta?.content || '');
-}
-// Usage tracking happens automatically when stream completes
-```
+Add business context to track usage by organization, user, task type, or custom identifiers. Pass a `usageMetadata` object with any of these optional fields:
 
-### Responses API with Metadata
+| Field | Description | Use Case |
+|-------|-------------|----------|
+| `traceId` | Unique identifier for session or conversation tracking | Link multiple API calls together for debugging, user session analytics, or distributed tracing across services |
+| `taskType` | Type of AI task being performed | Categorize usage by workload (e.g., "chat", "code-generation", "doc-summary") for cost analysis and optimization |
+| `subscriber.id` | Unique user identifier | Track individual user consumption for billing, rate limiting, or user analytics |
+| `subscriber.email` | User email address | Identify users for support, compliance, or usage reports |
+| `subscriber.credential.name` | Authentication credential name | Track which API key or service account made the request |
+| `subscriber.credential.value` | Authentication credential value | Associate usage with specific credentials for security auditing |
+| `organizationId` | Organization or company identifier | Multi-tenant cost allocation, usage quotas per organization |
+| `subscriptionId` | Subscription plan identifier | Track usage against subscription limits, identify plan upgrade opportunities |
+| `productId` | Your product or feature identifier | Attribute AI costs to specific features in your application (e.g., "chatbot", "email-assistant") |
+| `agent` | AI agent or bot identifier | Distinguish between multiple AI agents or automation workflows in your system |
+| `responseQualityScore` | Custom quality rating (0.0-1.0) | Track user satisfaction or automated quality metrics for model performance analysis |
 
-Full support for OpenAI's new Responses API:
+**Resources:**
+- [API Reference](https://revenium.readme.io/reference/meter_ai_completion) - Complete metadata field documentation
 
-```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',
-  },
-});
+### OpenAI Responses API
+**Use case:** Using OpenAI's Responses API with string inputs and simplified interface.
 
-console.log(response.output_text); // "Paris."
-```
+See working examples:
+- `examples/openai-responses-basic.ts` - Basic Responses API usage
+- `examples/openai-responses-streaming.ts` - Streaming with Responses API
 
 ### Azure OpenAI Integration
+**Use case:** Automatic Azure OpenAI detection with deployment name resolution and accurate pricing.
 
-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',
-  },
-});
-```
+See working examples:
+- `examples/azure-basic.ts` - Azure chat completions and embeddings
+- `examples/azure-responses-basic.ts` - Azure Responses API integration
 
 ### Embeddings with Metadata
+**Use case:** Track embeddings usage for search engines, RAG systems, and document processing.
 
-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);
-```
+Embeddings examples are included in:
+- `examples/openai-basic.ts` - Text embeddings with metadata
+- `examples/openai-streaming.ts` - Batch embeddings processing
 
 ### Manual Configuration
 
 For advanced use cases, configure the middleware manually:
 
 ```typescript
-import { configure } from '@revenium/openai';
+import { configure, patchOpenAIInstance } from '@revenium/openai';
+import OpenAI from 'openai';
 
 configure({
   reveniumApiKey: 'hak_your_api_key',
-  reveniumBaseUrl: 'https://api.revenium.io/meter',
-  apiTimeout: 5000,
-  failSilent: true,
-  maxRetries: 3,
+  reveniumBaseUrl: 'https://api.revenium.ai',
+  debug: true,
 });
+
+const openai = patchOpenAIInstance(new OpenAI());
 ```
 
 ## Configuration Options
@@ -954,7 +213,7 @@ configure({
 | ------------------------------ | -------- | ------------------------------- | ---------------------------------------------- |
 | `REVENIUM_METERING_API_KEY`    | true     | -                               | Your Revenium API key (starts with `hak_`)     |
 | `OPENAI_API_KEY`               | true     | -                               | Your OpenAI API key (starts with `sk-`)        |
-| `REVENIUM_METERING_BASE_URL`   | false    | `https://api.revenium.io/meter` | Revenium metering API base URL                 |
+| `REVENIUM_METERING_BASE_URL`   | false    | `https://api.revenium.ai` | Revenium metering API base URL                 |
 | `REVENIUM_DEBUG`               | false    | `false`                         | Enable debug logging (`true`/`false`)          |
 | `AZURE_OPENAI_ENDPOINT`        | false    | -                               | Azure OpenAI endpoint URL (for Azure testing)  |
 | `AZURE_OPENAI_API_KEY`         | false    | -                               | Azure OpenAI API key (for Azure testing)       |
@@ -963,65 +222,34 @@ configure({
 
 **Important Note about `REVENIUM_METERING_BASE_URL`:**
 
-- This variable is **optional** and defaults to the production URL (`https://api.revenium.io/meter`)
+- This variable is **optional** and defaults to the production URL (`https://api.revenium.ai`)
 - 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
   # Default production URL (recommended)
-  REVENIUM_METERING_BASE_URL=https://api.revenium.io/meter
+  REVENIUM_METERING_BASE_URL=https://api.revenium.ai
   ```
 
 - **Remember:** Your `REVENIUM_METERING_API_KEY` must match your base URL environment
 
-### 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)
-}
-```
-
 ## Included Examples
 
-The package includes 8 comprehensive example files in your installation:
-
-**OpenAI Examples:**
-- **openai-basic.ts**: Basic chat completions with metadata tracking
-- **openai-streaming.ts**: Streaming responses with real-time output
-- **openai-responses-basic.ts**: New Responses API usage (OpenAI SDK 5.8+)
-- **openai-responses-streaming.ts**: Streaming with Responses API
-
-**Azure OpenAI Examples:**
-- **azure-basic.ts**: Azure OpenAI chat completions
-- **azure-streaming.ts**: Azure streaming responses
-- **azure-responses-basic.ts**: Azure Responses API
-- **azure-responses-streaming.ts**: Azure streaming Responses API
+The package includes comprehensive example files covering:
 
-**For npm users:** Examples are installed in `node_modules/@revenium/openai/examples/`
+- **Getting Started** - Simple entry point with all metadata fields documented
+- **Chat Completions** - Basic and streaming usage patterns
+- **Responses API** - OpenAI's new API with simplified interface
+- **Azure OpenAI** - Automatic Azure detection and integration
+- **Embeddings** - Text embedding generation with tracking
 
-**For GitHub users:** Examples are in the repository's `examples/` directory
+Run the getting started example:
+```bash
+npx tsx node_modules/@revenium/openai/examples/getting_started.ts
+```
 
-For detailed setup instructions and usage patterns, see [examples/README.md](https://github.com/revenium/revenium-middleware-openai-node/blob/HEAD/examples/README.md).
+For complete example documentation, setup instructions, and all available examples, see [examples/README.md](https://github.com/revenium/revenium-middleware-openai-node/blob/HEAD/examples/README.md).
 
 ## How It Works
 
@@ -1040,141 +268,76 @@ The middleware never blocks your application - if Revenium tracking fails, your
 
 ### Common Issues
 
-#### 1. **No tracking data in dashboard**
+#### No tracking data appears
 
-**Symptoms**: OpenAI calls work but no data appears in Revenium dashboard
-
-**Solution**: Enable debug logging to check middleware status:
+Ensure environment variables are set and enable debug logging:
 
 ```bash
+export REVENIUM_METERING_API_KEY="hak_your_key"
+export OPENAI_API_KEY="sk_your_key"
 export REVENIUM_DEBUG=true
 ```
 
-**Expected output for successful tracking**:
-
-```bash
+Look for these log messages:
+```
 [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 - Key and URL from same environment
-REVENIUM_METERING_API_KEY=hak_your_api_key_here
-REVENIUM_METERING_BASE_URL=https://api.revenium.io/meter
-
-#  Wrong - Key and URL from different environments
-REVENIUM_METERING_API_KEY=hak_wrong_environment_key
-REVENIUM_METERING_BASE_URL=https://api.revenium.io/meter
-```
-
-#### 3. **TypeScript type errors**
-
-**Symptoms**: TypeScript errors about `usageMetadata` property
+#### TypeScript errors with usageMetadata
 
-**Solution**: Ensure you're importing the middleware before OpenAI:
+Import the middleware before OpenAI to enable type augmentation:
 
 ```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**
+#### Azure OpenAI not tracking
 
-**Symptoms**: Azure OpenAI calls not being tracked
-
-**Solution**: Ensure you're using `patchOpenAIInstance()` with your Azure client:
+Ensure you patch the 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:
+Enable detailed 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:
+If issues persist:
 
-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)
+1. Check logs with `REVENIUM_DEBUG=true`
+2. Verify environment variables are set
+3. Test with `examples/getting_started.ts`
+4. Contact support@revenium.io with debug logs
 
 ## Supported Models
 
-### OpenAI Models
+This middleware works with any OpenAI model. Examples in this package include:
 
-| 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                  |
+**Chat Completions:**
+- `gpt-4o-mini`, `gpt-4o` (GPT-4 family)
+- `gpt-5`, `gpt-5-mini`, `gpt-5-nano` (GPT-5 family)
 
-### Azure OpenAI Models
+**Embeddings:**
+- `text-embedding-3-small`, `text-embedding-3-large`
 
-All OpenAI models are supported through Azure OpenAI with automatic deployment name resolution:
+**Azure OpenAI:**
+- Works with any Azure deployment (deployment names automatically resolved)
 
-| 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                  |
+For the complete model list and latest specifications, see the [OpenAI Models Documentation](https://platform.openai.com/docs/models).
 
-**Note**: The middleware automatically maps Azure deployment names to standard model names for accurate pricing and analytics.
+For cost tracking across providers, see the [Revenium Model Catalog](https://revenium.readme.io/v2.0.0/reference/get_ai_model).
 
 ### API Support Matrix
 
@@ -1187,12 +350,6 @@ All OpenAI models are supported through Azure OpenAI with automatic deployment n
 | **Cost Calculation**  | Yes                  | Yes           | Yes            |
 | **Token Counting**    | Yes                  | Yes           | Yes            |
 
-## 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)