@revenium/openai 1.0.12 → 1.0.14

package/README.md

@@ -3,22 +3,26 @@
 [![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**
 
-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.
+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 Chat Completions API, Embeddings API, and Responses API.
+
+**Go-aligned API for consistent cross-language development!**
 
 ## Features
 
+- **Go-Aligned API** - Same `Initialize()`/`GetClient()` pattern as Go implementation
 - **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 (all fields optional)
+- **Multiple API Support** - Chat Completions, Embeddings, and 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
+- **Automatic .env Loading** - Loads environment variables automatically
 
 ## Getting Started
 
@@ -39,42 +43,28 @@ npm install --save-dev typescript @types/node
 
 ### 2. Configure Environment Variables
 
-Create a `.env` file:
+Create a `.env` file in your project root. See [`.env.example`](https://github.com/revenium/revenium-middleware-openai-node/blob/HEAD/.env.example) for all available configuration options.
 
-**NOTE: YOU MUST REPLACE THE PLACEHOLDERS WITH YOUR OWN API KEYS**
+**Minimum required configuration:**
 
 ```env
-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.ai
 OPENAI_API_KEY=sk_your_openai_api_key_here
 ```
 
-### 3. Run Your First Example
-
-Run the [getting started example](https://github.com/revenium/revenium-middleware-openai-node/blob/HEAD/examples/getting_started.ts):
-
-```bash
-npx tsx node_modules/@revenium/openai/examples/getting_started.ts
-```
-
-Or with debug logging:
+**NOTE: Replace the placeholder values with your actual API keys.**
 
-```bash
-# Linux/macOS
-REVENIUM_DEBUG=true npx tsx node_modules/@revenium/openai/examples/getting_started.ts
-
-# Windows (PowerShell)
-$env:REVENIUM_DEBUG="true"; npx tsx node_modules/@revenium/openai/examples/getting_started.ts
-```
+### 3. Run Your First Example
 
-**For more examples and usage patterns, see [examples/README.md](https://github.com/revenium/revenium-middleware-openai-node/blob/HEAD/examples/README.md).**
+**For complete examples and usage patterns, see [`examples/README.md`](https://github.com/revenium/revenium-middleware-openai-node/blob/HEAD/examples/README.md).**
 
 ---
 
 ## Requirements
 
 - Node.js 16+
-- OpenAI package v4.0+
+- OpenAI package v5.0.0 or later
 - TypeScript 5.0+ (for TypeScript projects)
 
 ---
@@ -95,7 +85,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**
 
@@ -104,545 +94,152 @@ 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
+## API Overview
 
-**References:**
+The middleware provides a Go-aligned API with the following main functions:
 
-- [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)
+- **`Initialize(config?)`** - Initialize the middleware (from environment or explicit config)
+- **`GetClient()`** - Get the global Revenium client instance
+- **`Configure(config)`** - Alias for `Initialize()` for programmatic configuration
+- **`IsInitialized()`** - Check if the middleware is initialized
+- **`Reset()`** - Reset the global client (useful for testing)
 
-### Working Examples
+**For complete API documentation and usage examples, see [`examples/README.md`](https://github.com/revenium/revenium-middleware-openai-node/blob/HEAD/examples/README.md).**
 
-Complete working examples are included with this package. Each example is fully documented and ready to run.
+## Metadata Fields
 
-#### Available Examples
+The middleware supports the following optional metadata fields for tracking:
 
-**OpenAI Chat Completions API:**
-- `openai-basic.ts` - Basic chat + embeddings with optional metadata
-- `openai-streaming.ts` - Streaming responses + batch embeddings
+| Field                   | Type   | Description                                                 |
+| ----------------------- | ------ | ----------------------------------------------------------- |
+| `traceId`               | string | Unique identifier for session or conversation tracking      |
+| `taskType`              | string | Type of AI task being performed (e.g., "chat", "embedding") |
+| `agent`                 | string | AI agent or bot identifier                                  |
+| `organizationId`        | string | Organization or company identifier                          |
+| `productId`             | string | Your product or feature identifier                          |
+| `subscriptionId`        | string | Subscription plan identifier                                |
+| `responseQualityScore`  | number | Custom quality rating (0.0-1.0)                             |
+| `subscriber.id`         | string | Unique user identifier                                      |
+| `subscriber.email`      | string | User email address                                          |
+| `subscriber.credential` | object | Authentication credential (`name` and `value` fields)       |
 
-**OpenAI Responses API (SDK 5.8+):**
-- `openai-responses-basic.ts` - New Responses API with string input
-- `openai-responses-streaming.ts` - Streaming with Responses API
+**All metadata fields are optional.** For complete metadata documentation and usage examples, see:
 
-**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
+- [`examples/README.md`](https://github.com/revenium/revenium-middleware-openai-node/blob/HEAD/examples/README.md) - All usage examples
+- [Revenium API Reference](https://revenium.readme.io/reference/meter_ai_completion) - Complete API documentation
 
-**Detailed Guide:**
-- `examples/README.md` - Complete setup guide with TypeScript and JavaScript patterns
-
-#### Running Examples
-
-**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
-
-# View all examples:
-ls node_modules/@revenium/openai/examples/
-```
-
-**Cloned from GitHub?**
-```bash
-npm install
-npm run example:openai-basic
-npm run example:openai-streaming
-npm run example:openai-responses-basic
-
-# See all example scripts:
-npm run
-```
-
-**Browse online:** [`examples/` directory on GitHub](https://github.com/revenium/revenium-middleware-openai-node/tree/HEAD/examples)
-
-### 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.
+## Configuration Options
 
-## Azure OpenAI Integration
+### Environment Variables
 
-**Azure OpenAI support** The middleware automatically detects Azure OpenAI clients and provides accurate usage tracking and cost calculation.
+For a complete list of all available environment variables with examples, see [`.env.example`](https://github.com/revenium/revenium-middleware-openai-node/blob/HEAD/.env.example).
 
-### Quick Start with Azure OpenAI
+## Examples
 
-**Use case:** Automatic Azure OpenAI client detection with deployment name mapping and accurate usage tracking.
+The package includes comprehensive examples in the [`examples/`](https://github.com/revenium/revenium-middleware-openai-node/blob/HEAD/examples/) directory.
 
-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
+### Getting Started
 
-**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"
-
-# Revenium configuration
-REVENIUM_METERING_API_KEY="hak_your_revenium_api_key"
-REVENIUM_METERING_BASE_URL="https://api.revenium.io"
-```
-
-### 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
-
-### Initialization Options
-
-The middleware supports three initialization patterns:
-
-**Automatic (Recommended)** - Import and patch OpenAI instance:
-
-```typescript
-import { patchOpenAIInstance } from '@revenium/openai';
-import OpenAI from 'openai';
-
-const openai = patchOpenAIInstance(new OpenAI());
-// Tracking works automatically if env vars are set
+npm run example:getting-started
 ```
 
-**Explicit** - Call `initializeReveniumFromEnv()` for error handling control:
+### OpenAI Examples
 
-```typescript
-import { initializeReveniumFromEnv, patchOpenAIInstance } from '@revenium/openai';
-import OpenAI from 'openai';
+| Example                         | Command                             | Description                       |
+| ------------------------------- | ----------------------------------- | --------------------------------- |
+| `openai/basic.ts`               | `npm run example:openai-basic`      | Chat completions and embeddings   |
+| `openai/metadata.ts`            | `npm run example:openai-metadata`   | All metadata fields demonstration |
+| `openai/streaming.ts`           | `npm run example:openai-stream`     | Streaming chat completions        |
+| `openai/responses-basic.ts`     | `npm run example:openai-res-basic`  | Responses API usage               |
+| `openai/responses-embed.ts`     | `npm run example:openai-res-embed`  | Embeddings with Responses API     |
+| `openai/responses-streaming.ts` | `npm run example:openai-res-stream` | Streaming Responses API           |
 
-const result = initializeReveniumFromEnv();
-if (!result.success) {
-  console.error('Failed to initialize:', result.message);
-  process.exit(1);
-}
+### Azure OpenAI Examples
 
-const openai = patchOpenAIInstance(new OpenAI());
-```
-
-**Manual** - Use `configure()` to set all options programmatically (see Manual Configuration below).
-
-For detailed examples of all initialization patterns, see [`examples/`](https://github.com/revenium/revenium-middleware-openai-node/blob/HEAD/examples/README.md).
-
-### Streaming Responses
-
-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.
-
-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.
-
-### Custom Metadata Tracking
-
-Add business context to track usage by organization, user, task type, or custom fields. Pass a `usageMetadata` object with any of these optional fields:
-
-| 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 |
-
-**Resources:**
-- [API Reference](https://revenium.readme.io/reference/meter_ai_completion) - Complete metadata field documentation
-
-### OpenAI Responses API
-**Use case:** Using OpenAI's new Responses API with string inputs and simplified interface (SDK 5.8+).
-
-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.
-
-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
-
-For advanced use cases, configure the middleware manually:
-
-```typescript
-import { configure } from '@revenium/openai';
+| Example                     | Command                            | Description                   |
+| --------------------------- | ---------------------------------- | ----------------------------- |
+| `azure/basic.ts`            | `npm run example:azure-basic`      | Azure chat completions        |
+| `azure/stream.ts`           | `npm run example:azure-stream`     | Azure streaming               |
+| `azure/responses-basic.ts`  | `npm run example:azure-res-basic`  | Azure Responses API           |
+| `azure/responses-stream.ts` | `npm run example:azure-res-stream` | Azure Responses API streaming |
 
-configure({
-  reveniumApiKey: 'hak_your_api_key',
-  reveniumBaseUrl: 'https://api.revenium.io',
-  apiTimeout: 5000,
-  failSilent: true,
-  maxRetries: 3,
-});
-```
-
-## Configuration Options
-
-### Environment Variables
-
-| Variable                       | Required | Default                         | Description                                    |
-| ------------------------------ | -------- | ------------------------------- | ---------------------------------------------- |
-| `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` | 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)       |
-| `AZURE_OPENAI_DEPLOYMENT`      | false    | -                               | Azure OpenAI deployment name (for Azure)       |
-| `AZURE_OPENAI_API_VERSION`     | false    | `2024-12-01-preview`            | Azure OpenAI API version (for Azure)           |
-
-**Important Note about `REVENIUM_METERING_BASE_URL`:**
-
-- 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
-  ```
-
-- **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
-
-**For npm users:** Examples are installed in `node_modules/@revenium/openai/examples/`
-
-**For GitHub users:** Examples are in the repository's `examples/` directory
-
-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 usage patterns, see [`examples/README.md`](https://github.com/revenium/revenium-middleware-openai-node/blob/HEAD/examples/README.md).**
 
 ## 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
+1. **Initialize**: Call `Initialize()` to set up the middleware with your configuration
+2. **Get Client**: Call `GetClient()` to get a wrapped OpenAI client instance
+3. **Make Requests**: Use the client normally - all requests are automatically tracked
 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
+**Supported APIs:**
 
-**Solution**: Enable debug logging to check middleware status:
+- Chat Completions API (`client.chat().completions().create()`)
+- Embeddings API (`client.embeddings().create()`)
+- Responses API (`client.responses().create()` and `client.responses().createStreaming()`)
 
-```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 - Key and URL from same environment
-REVENIUM_METERING_API_KEY=hak_your_api_key_here
-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
-```
-
-#### 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:
+## Troubleshooting
 
-```typescript
-import { AzureOpenAI } from 'openai';
-import { patchOpenAIInstance } from '@revenium/openai';
+### Common Issues
 
-//  Correct
-const azure = patchOpenAIInstance(new AzureOpenAI({...}));
+**No tracking data appears:**
 
-//  Wrong - not patched
-const azure = new AzureOpenAI({...});
-```
+1. Verify environment variables are set correctly in `.env`
+2. Enable debug logging by setting `REVENIUM_DEBUG=true` in `.env`
+3. Check console for `[Revenium]` log messages
+4. Verify your `REVENIUM_METERING_API_KEY` is valid
 
-#### 5. **Responses API not available**
+**Client not initialized error:**
 
-**Symptoms**: `openai.responses.create` is undefined
+- Make sure you call `Initialize()` before `GetClient()`
+- Check that your `.env` file is in the project root
+- Verify `REVENIUM_METERING_API_KEY` is set
 
-**Solution**: Upgrade to OpenAI SDK 5.8+ for Responses API support:
+**Azure OpenAI not working:**
 
-```bash
-npm install openai@^5.8.0
-```
+- Verify all Azure environment variables are set (see `.env.example`)
+- Check that `AZURE_OPENAI_ENDPOINT` and `AZURE_OPENAI_API_KEY` are correct
+- Ensure you're using a valid deployment name in the `model` parameter
 
 ### Debug Mode
 
-Enable comprehensive debug logging:
+Enable detailed logging by adding to your `.env`:
 
-```bash
-export REVENIUM_DEBUG=true
+```env
+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
+If issues persist:
 
-For detailed troubleshooting guides, visit [docs.revenium.io](https://docs.revenium.io)
+1. Enable debug logging (`REVENIUM_DEBUG=true`)
+2. Check the [`examples/`](https://github.com/revenium/revenium-middleware-openai-node/blob/HEAD/examples/) directory for working examples
+3. Review [`examples/README.md`](https://github.com/revenium/revenium-middleware-openai-node/blob/HEAD/examples/README.md) for detailed setup instructions
+4. Contact support@revenium.io with debug logs
 
 ## Supported Models
 
-This middleware works with all OpenAI chat completion and embedding models, including those available through Azure OpenAI.
+This middleware works with any OpenAI model. For the complete model list, see the [OpenAI Models Documentation](https://platform.openai.com/docs/models).
 
-**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)
+### API Support Matrix
 
-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.
+The following table shows what has been tested and verified with working examples:
 
-### API Support Matrix
+| Feature               | Chat Completions | Embeddings | Responses API |
+| --------------------- | ---------------- | ---------- | ------------- |
+| **OpenAI Basic**      | Yes              | Yes        | Yes           |
+| **OpenAI Streaming**  | Yes              | No         | Yes           |
+| **Azure Basic**       | Yes              | No         | Yes           |
+| **Azure Streaming**   | Yes              | No         | Yes           |
+| **Metadata Tracking** | Yes              | Yes        | Yes           |
+| **Token Counting**    | Yes              | Yes        | Yes           |
 
-| Feature               | Chat Completions API | Responses API | Embeddings API |
-| --------------------- | -------------------- | ------------- | -------------- |
-| **Basic Requests**    | Yes                  | Yes           | Yes            |
-| **Streaming**         | Yes                  | Yes           | No             |
-| **Metadata Tracking** | Yes                  | Yes           | Yes            |
-| **Azure OpenAI**      | Yes                  | Yes           | Yes            |
-| **Cost Calculation**  | Yes                  | Yes           | Yes            |
-| **Token Counting**    | Yes                  | Yes           | Yes            |
+**Note:** "Yes" = Tested with working examples in [`examples/`](https://github.com/revenium/revenium-middleware-openai-node/blob/HEAD/examples/) directory
 
 ## Documentation
 
@@ -668,14 +265,11 @@ This project is licensed under the MIT License - see the [LICENSE](https://githu
 
 For issues, feature requests, or contributions:
 
+- **Website**: [www.revenium.ai](https://www.revenium.ai)
 - **GitHub Repository**: [revenium/revenium-middleware-openai-node](https://github.com/revenium/revenium-middleware-openai-node)
 - **Issues**: [Report bugs or request features](https://github.com/revenium/revenium-middleware-openai-node/issues)
 - **Documentation**: [docs.revenium.io](https://docs.revenium.io)
-- **Contact**: Reach out to the Revenium team for additional support
-
-## Development
-
-For development and testing instructions, see [DEVELOPMENT.md](https://github.com/revenium/revenium-middleware-openai-node/blob/HEAD/DEVELOPMENT.md).
+- **Email**: support@revenium.io
 
 ---