@revenium/openai 1.0.11 → 1.0.12

package/README.md

@@ -20,467 +20,64 @@ A professional-grade Node.js middleware that seamlessly integrates with OpenAI a
 - **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:
-
-```bash
-# Create .env file
-echo. > .env  # On Windows (CMD)
-touch .env  # On Mac/Linux
-# OR PowerShell
-New-Item -Path .env -ItemType File
-```
+Create a `.env` 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_BASE_URL=https://api.revenium.io
 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.
+### 3. Run Your First Example
 
-**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:
+Run the [getting started example](https://github.com/revenium/revenium-middleware-openai-node/blob/HEAD/examples/getting_started.ts):
 
 ```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();
+npx tsx node_modules/@revenium/openai/examples/getting_started.ts
 ```
 
-#### 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`:
+Or with debug logging:
 
 ```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_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.
-
-### 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 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
-
-Already have a project? Just install and replace imports:
-
-### Step 1: Install the Package
-
-```bash
-npm install @revenium/openai
-```
-
-### Step 2: Update Your Imports
+# Linux/macOS
+REVENIUM_DEBUG=true npx tsx node_modules/@revenium/openai/examples/getting_started.ts
 
-**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());
+# Windows (PowerShell)
+$env:REVENIUM_DEBUG="true"; npx tsx node_modules/@revenium/openai/examples/getting_started.ts
 ```
 
-### Step 3: Add Environment Variables
-
-Add to your `.env` file:
-
-```env
-# Revenium OpenAI Middleware Configuration
+**For more examples and usage patterns, see [examples/README.md](https://github.com/revenium/revenium-middleware-openai-node/blob/HEAD/examples/README.md).**
 
-# 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 v4.0+
+- TypeScript 5.0+ (for TypeScript projects)
 
-** That's it!** Your existing OpenAI code now automatically tracks usage to Revenium.
+---
 
 ## What Gets Tracked
 
@@ -594,131 +191,54 @@ npm install openai@5.8.2
 - [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
+### Working Examples
 
-The middleware includes comprehensive examples for the new Responses API:
+Complete working examples are included with this package. Each example is fully documented and ready to run.
 
-**Basic Usage:**
+#### Available Examples
 
-```typescript
-import { initializeReveniumFromEnv, patchOpenAIInstance } from '@revenium/openai';
-import OpenAI from 'openai';
+**OpenAI Chat Completions API:**
+- `openai-basic.ts` - Basic chat + embeddings with optional metadata
+- `openai-streaming.ts` - Streaming responses + batch embeddings
 
-// Initialize and patch OpenAI instance
-initializeReveniumFromEnv();
-const openai = patchOpenAIInstance(new OpenAI());
+**OpenAI Responses API (SDK 5.8+):**
+- `openai-responses-basic.ts` - New Responses API with string input
+- `openai-responses-streaming.ts` - Streaming with Responses API
 
-// 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',
-  },
-});
+**Azure OpenAI:**
+- `azure-basic.ts` - Azure chat completions + embeddings
+- `azure-streaming.ts` - Azure streaming responses
+- `azure-responses-basic.ts` - Azure Responses API
+- `azure-responses-streaming.ts` - Azure streaming Responses API
 
-console.log(response.output_text); // "Paris."
-```
+**Detailed Guide:**
+- `examples/README.md` - Complete setup guide with TypeScript and JavaScript patterns
 
-**Streaming Example:**
+#### Running Examples
 
-```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',
-  },
-});
+**Installed via npm?**
+```bash
+# Try these in order:
+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/openai-responses-basic.ts
 
-for await (const chunk of stream) {
-  process.stdout.write(chunk.delta?.content || '');
-}
+# View all examples:
+ls node_modules/@revenium/openai/examples/
 ```
 
-### 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',
-  },
-});
+**Cloned from GitHub?**
+```bash
+npm install
+npm run example:openai-basic
+npm run example:openai-streaming
+npm run example:openai-responses-basic
 
-// 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',
-  },
-});
+# See all example scripts:
+npm run
 ```
 
-### Streaming Support
-
-The middleware automatically handles streaming requests with seamless metadata:
-
-```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 || '');
-}
-// Usage tracking happens automatically when stream completes
-```
+**Browse online:** [`examples/` directory on GitHub](https://github.com/revenium/revenium-middleware-openai-node/tree/HEAD/examples)
 
 ### Temporarily Disabling Tracking
 
@@ -752,46 +272,24 @@ patchOpenAI();
 
 ### 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
-```
+**Use case:** Automatic Azure OpenAI client detection with deployment name mapping and accurate usage tracking.
 
-```typescript
-import { initializeReveniumFromEnv, patchOpenAIInstance } from '@revenium/openai';
-import { AzureOpenAI } from 'openai';
+See complete Azure examples:
+- `examples/azure-basic.ts` - Azure chat completions with environment variable setup
+- `examples/azure-streaming.ts` - Azure streaming responses
+- `examples/azure-responses-basic.ts` - Azure Responses API integration
 
-// 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',
-  },
-});
+**Environment variables needed:**
+```bash
+# Azure OpenAI configuration
+AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
+AZURE_OPENAI_API_KEY="your-azure-api-key"
+AZURE_OPENAI_DEPLOYMENT="gpt-4o"
+AZURE_OPENAI_API_VERSION="2024-12-01-preview"
 
-console.log(response.choices[0].message.content);
+# Revenium configuration
+REVENIUM_METERING_API_KEY="hak_your_revenium_api_key"
+REVENIUM_METERING_BASE_URL="https://api.revenium.io"
 ```
 
 ### Azure Features
@@ -828,107 +326,86 @@ The middleware automatically maps Azure deployment names to standard model names
 
 ## Advanced Usage
 
-### Streaming with Metadata
+### Initialization Options
 
-The middleware seamlessly handles streaming requests with full metadata support:
+The middleware supports three initialization patterns:
+
+**Automatic (Recommended)** - Import and patch OpenAI instance:
 
 ```typescript
-import { initializeReveniumFromEnv, patchOpenAIInstance } from '@revenium/openai';
+import { patchOpenAIInstance } from '@revenium/openai';
 import OpenAI from 'openai';
 
-initializeReveniumFromEnv();
 const openai = patchOpenAIInstance(new OpenAI());
+// Tracking works automatically if env vars are set
+```
 
-// 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(),
-  },
-});
+**Explicit** - Call `initializeReveniumFromEnv()` for error handling control:
+
+```typescript
+import { initializeReveniumFromEnv, patchOpenAIInstance } from '@revenium/openai';
+import OpenAI from 'openai';
 
-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
+
+const openai = patchOpenAIInstance(new OpenAI());
 ```
 
-### Responses API with Metadata
+**Manual** - Use `configure()` to set all options programmatically (see Manual Configuration below).
 
-Full support for OpenAI's new Responses API:
+For detailed examples of all initialization patterns, see [`examples/`](https://github.com/revenium/revenium-middleware-openai-node/blob/HEAD/examples/README.md).
 
-```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',
-  },
-});
+### Streaming Responses
 
-console.log(response.output_text); // "Paris."
-```
+Streaming is fully supported with real-time token tracking and time-to-first-token metrics. The middleware automatically tracks streaming responses without any additional configuration.
 
-### Azure OpenAI Integration
+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.
 
-Automatic Azure OpenAI detection with seamless metadata:
+### Custom Metadata Tracking
 
-```typescript
-import { AzureOpenAI } from 'openai';
+Add business context to track usage by organization, user, task type, or custom fields. Pass a `usageMetadata` object with any of these optional fields:
 
-// 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',
-  },
-});
-```
+| 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 |
 
-### Embeddings with Metadata
+**Resources:**
+- [API Reference](https://revenium.readme.io/reference/meter_ai_completion) - Complete metadata field documentation
 
-Track embeddings usage with optional metadata:
+### OpenAI Responses API
+**Use case:** Using OpenAI's new Responses API with string inputs and simplified interface (SDK 5.8+).
 
-```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',
-  },
-});
+See working examples:
+- `examples/openai-responses-basic.ts` - Basic Responses API usage
+- `examples/openai-responses-streaming.ts` - Streaming with Responses API
 
-console.log('Model:', embedding.model);
-console.log('Usage:', embedding.usage);
-console.log('Embedding dimensions:', embedding.data[0]?.embedding.length);
-```
+### Azure OpenAI Integration
+**Use case:** Automatic Azure OpenAI detection with deployment name resolution and accurate pricing.
+
+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.
+
+Embeddings examples are included in:
+- `examples/openai-basic.ts` - Text embeddings with metadata
+- `examples/openai-streaming.ts` - Batch embeddings processing
 
 ### Manual Configuration
 
@@ -939,7 +416,7 @@ import { configure } from '@revenium/openai';
 
 configure({
   reveniumApiKey: 'hak_your_api_key',
-  reveniumBaseUrl: 'https://api.revenium.io/meter',
+  reveniumBaseUrl: 'https://api.revenium.io',
   apiTimeout: 5000,
   failSilent: true,
   maxRetries: 3,
@@ -954,7 +431,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.io` | 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,14 +440,14 @@ 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.io`)
 - 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.io
   ```
 
 - **Remember:** Your `REVENIUM_METERING_API_KEY` must match your base URL environment
@@ -1070,11 +547,11 @@ export REVENIUM_DEBUG=true
 ```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
+REVENIUM_METERING_BASE_URL=https://api.revenium.io
 
 #  Wrong - Key and URL from different environments
 REVENIUM_METERING_API_KEY=hak_wrong_environment_key
-REVENIUM_METERING_BASE_URL=https://api.revenium.io/meter
+REVENIUM_METERING_BASE_URL=https://api.revenium.io
 ```
 
 #### 3. **TypeScript type errors**
@@ -1149,32 +626,12 @@ For detailed troubleshooting guides, visit [docs.revenium.io](https://docs.reven
 
 ## 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
+This middleware works with all OpenAI chat completion and embedding models, including those available through Azure OpenAI.
 
-All OpenAI models are supported through Azure OpenAI with automatic deployment name resolution:
+**For the current list of supported models, pricing, and capabilities:**
+- [Revenium AI Models API](https://revenium.readme.io/v2.0.0/reference/get_ai_model)
 
-| 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.
+Models are continuously updated as new versions are released by OpenAI and Azure OpenAI. The middleware automatically handles model detection and pricing for accurate usage tracking.
 
 ### API Support Matrix
 
@@ -1187,12 +644,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)