@revenium/openai 1.0.11 → 1.0.12

package/examples/README.md

@@ -1,42 +1,25 @@
-# Revenium OpenAI Middleware - TypeScript Examples
+# Revenium OpenAI Middleware - Examples
 
-**TypeScript-first** examples demonstrating how to use the Revenium OpenAI middleware with full type safety and IntelliSense support.
+**TypeScript-first** examples demonstrating automatic Revenium usage tracking with the OpenAI SDK.
 
-## TypeScript-First Approach
-
-This middleware is designed with **TypeScript developers in mind**:
-
--  **Full Type Safety**: All interfaces are strongly typed with comprehensive JSDoc
--  **IntelliSense Support**: Rich auto-completion and inline documentation
--  **Module Augmentation**: Native `usageMetadata` support in OpenAI SDK calls
--  **Dual Package Exports**: Works with both CommonJS and ES Modules
--  **Zero Configuration**: Auto-initialization with environment variables
-
-## Installation & Setup
+## Getting Started - Step by Step
 
-### 1. Install Dependencies
+### 1. Create Your Project
 
 ```bash
-npm install @revenium/openai openai@^5.8.0
-npm install -D typescript tsx @types/node  # For TypeScript development
-```
+# Create project directory
+mkdir my-openai-project
+cd my-openai-project
 
-### 2. TypeScript Configuration
+# Initialize Node.js project
+npm init -y
+```
 
-Ensure your `tsconfig.json` includes:
+### 2. Install Dependencies
 
-```json
-{
-  "compilerOptions": {
-    "target": "ES2020",
-    "module": "ESNext",
-    "moduleResolution": "node",
-    "esModuleInterop": true,
-    "allowSyntheticDefaultImports": true,
-    "strict": true,
-    "skipLibCheck": true
-  }
-}
+```bash
+npm install @revenium/openai openai dotenv
+npm install -D typescript tsx @types/node  # For TypeScript
 ```
 
 ### 3. Environment Setup
@@ -44,15 +27,13 @@ Ensure your `tsconfig.json` includes:
 Create a `.env` file in your project root:
 
 ```bash
-# Required - OpenAI API key
-OPENAI_API_KEY=sk-your_openai_api_key_here
-
-# Required - Revenium API key
+# Required
 REVENIUM_METERING_API_KEY=hak_your_revenium_api_key
+OPENAI_API_KEY=sk_your_openai_api_key
 
-# Optional (uses defaults if not set)
-REVENIUM_METERING_BASE_URL=https://api.revenium.io/meter
-REVENIUM_DEBUG=false  # Set to true for detailed logging
+# Optional
+REVENIUM_METERING_BASE_URL=https://api.revenium.io
+REVENIUM_DEBUG=false
 
 # Optional - For Azure OpenAI examples
 AZURE_OPENAI_ENDPOINT=https://your-resource-name.openai.azure.com/
@@ -61,301 +42,316 @@ AZURE_OPENAI_DEPLOYMENT=your-deployment-name
 AZURE_OPENAI_API_VERSION=2024-12-01-preview
 ```
 
-### 4. Run TypeScript Examples
+### 4. Run Examples
+
+**If you cloned from GitHub:**
 
 ```bash
-# OpenAI examples
+# Run examples directly
+npx tsx examples/getting_started.ts
 npx tsx examples/openai-basic.ts
 npx tsx examples/openai-streaming.ts
-npx tsx examples/openai-responses-basic.ts
-npx tsx examples/openai-responses-streaming.ts
-
-# Azure OpenAI examples
-npx tsx examples/azure-basic.ts
-npx tsx examples/azure-streaming.ts
-npx tsx examples/azure-responses-basic.ts
-npx tsx examples/azure-responses-streaming.ts
 ```
 
-## Getting Started - Step by Step
+**If you installed via npm:**
 
-This guide walks you through creating a complete project from scratch. For GitHub users who cloned this repository, you can run the included examples directly. For npm users, these examples are also available in your `node_modules/@revenium/openai/examples/` directory.
+Examples are included in your `node_modules/@revenium/openai/examples/` directory:
 
-### Step 1: Create Your First Test
+```bash
+npx tsx node_modules/@revenium/openai/examples/getting_started.ts
+npx tsx node_modules/@revenium/openai/examples/openai-basic.ts
+npx tsx node_modules/@revenium/openai/examples/openai-streaming.ts
+```
 
-#### TypeScript Test
+## Available Examples
 
-Create `test-openai.ts`:
+### `getting_started.ts` - Simple Entry Point
 
-```typescript
-// test-openai.ts
-import "dotenv/config";
-import { initializeReveniumFromEnv, patchOpenAIInstance } from "@revenium/openai";
-import OpenAI from "openai";
+The simplest example to get you started with Revenium tracking:
 
-async function testOpenAI() {
-  try {
-    // Initialize Revenium middleware
-    initializeReveniumFromEnv();
-
-    // Create and patch OpenAI client (returns patched instance)
-    const openai = patchOpenAIInstance(new OpenAI());
-
-    // Make API call with optional metadata
-    const response = await openai.chat.completions.create({
-      model: "gpt-4o",
-      messages: [{ role: "user", content: "What is artificial intelligence?" }],
-      max_tokens: 100,
-      usageMetadata: {
-        subscriber: {
-          id: "test-user",
-          email: "test@example.com",
-        },
-        organizationId: "test-org",
-        taskType: "test-query",
-      },
-    });
-
-    console.log("Response:", response.choices[0].message.content);
-    // Success! Response and metering data sent to Revenium
-  } catch (error) {
-    console.error("Error:", error);
-  }
-}
+- **Minimal setup** - Just import, configure, and start tracking
+- **Complete metadata example** - Shows all 11 optional metadata fields in comments
+- **Ready to customize** - Uncomment the metadata section to add tracking context
 
-testOpenAI();
-```
+**Key Features:**
 
-#### JavaScript Test
+- Auto-initialization from environment variables
+- Native `usageMetadata` support via module augmentation
+- All metadata fields documented with examples
+- Single API call demonstration
 
-Create `test-openai.js`:
+**Perfect for:** First-time users, quick validation, understanding metadata structure
 
-```javascript
-// test-openai.js
-require("dotenv").config();
-const { initializeReveniumFromEnv, patchOpenAIInstance } = require("@revenium/openai");
-const OpenAI = require("openai");
+**See the file for complete code examples.**
 
-async function testOpenAI() {
-  try {
-    // Initialize Revenium middleware
-    initializeReveniumFromEnv();
+### `openai-basic.ts` - Chat Completions and Embeddings
 
-    // Create and patch OpenAI client (returns patched instance)
-    const openai = patchOpenAIInstance(new OpenAI());
+Demonstrates standard OpenAI API usage with automatic tracking:
 
-    // Make API call (metadata optional)
-    const response = await openai.chat.completions.create({
-      model: "gpt-4o-mini",
-      messages: [{ role: "user", content: "What is artificial intelligence?" }],
-      max_tokens: 100,
-    });
+- **Chat completions** - Basic chat API with metadata tracking
+- **Embeddings** - Text embedding generation with usage tracking
+- **Multiple API calls** - Batch operations with consistent metadata
 
-    console.log("Response:", response.choices[0].message.content);
-    // Success! Response and metering data sent to Revenium
-  } catch (error) {
-    console.error("Error:", error);
-  }
-}
+**Key Features:**
 
-testOpenAI();
-```
+- TypeScript module augmentation for native `usageMetadata` support
+- Full type safety with IntelliSense
+- Comprehensive metadata examples
+- Error handling patterns
 
-### Step 2: Update package.json
+**Perfect for:** Understanding basic OpenAI API patterns with tracking
 
-Add a test script to easily run your example:
+**See the file for complete code examples.**
 
-```json
-{
-  "scripts": {
-    "test": "tsx test-openai.ts"
-  },
-  "dependencies": {
-    "@revenium/openai": "^1.0.10",
-    "openai": "^5.8.0",
-    "dotenv": "^16.0.0"
-  },
-  "devDependencies": {
-    "typescript": "^5.0.0",
-    "tsx": "^4.0.0",
-    "@types/node": "^20.0.0"
-  }
-}
-```
+### `openai-streaming.ts` - Real-time Streaming
 
-### Step 3: Run Your Tests
+Demonstrates streaming responses with automatic token tracking:
 
-```bash
-# TypeScript
-npm run test
+- **Streaming chat completions** - Real-time token streaming with metadata
+- **Batch embeddings** - Multiple embedding requests efficiently
+- **Stream processing** - Type-safe event handling
 
-# Or directly
-npx tsx test-openai.ts
+**Key Features:**
 
-# JavaScript
-node test-openai.js
-```
+- Automatic tracking when stream completes
+- Real-time token counting
+- Time-to-first-token metrics
+- Stream error handling
 
-### Step 4: Create Advanced Examples
+**Perfect for:** Real-time applications, chatbots, interactive AI assistants
 
-Explore our comprehensive examples for different use cases:
+**See the file for complete code examples.**
 
-**Standard Chat Completions API:**
-- `openai-basic.ts` - Chat completions with metadata
-- `openai-streaming.ts` - Streaming responses
-- `azure-basic.ts` - Azure OpenAI chat completions
-- `azure-streaming.ts` - Azure OpenAI streaming
+### `openai-function-calling.ts` - Function Calling with Tools
 
-**Responses API (OpenAI SDK 5.8+):**
-- `openai-responses-basic.ts` - New Responses API
-- `openai-responses-streaming.ts` - Responses API streaming
-- `azure-responses-basic.ts` - Azure Responses API
-- `azure-responses-streaming.ts` - Azure Responses API streaming
+Demonstrates OpenAI function calling (tools) with tracking:
 
-### Step 5: Project Structure
+- **Tool definitions** - Define functions for the AI to call
+- **Function execution** - Handle tool calls and return results
+- **Multi-turn conversations** - Manage conversation flow with function results
 
-Here's a recommended project structure:
+**Key Features:**
 
-```
-my-openai-project/
-├── .env                    # Environment variables (never commit!)
-├── .gitignore             # Include .env in here
-├── package.json           # Dependencies and scripts
-├── tsconfig.json          # TypeScript configuration
-├── src/
-│   └── index.ts          # Your application code
-├── examples/             # Copy examples here for reference
-│   ├── openai-basic.ts
-│   └── ...
-└── node_modules/
-    └── @revenium/openai/
-        └── examples/     # npm users: examples available here too
-```
+- Complete function calling workflow
+- Type-safe tool definitions
+- Automatic tracking of tool usage
+- Multi-turn conversation handling
 
-## TypeScript Integration Patterns
+**Perfect for:** AI agents, function-calling applications, structured outputs
 
-### Pattern A: Auto-Initialization (Recommended)
+**See the file for complete code examples.**
 
-```typescript
-import { patchOpenAIInstance } from "@revenium/openai";
-import OpenAI from "openai";
+### `openai-vision.ts` - Vision API with Images
 
-// Auto-initializes from environment variables
-const openai = patchOpenAIInstance(new OpenAI());
-// Already tracked! No explicit init needed if env vars are set
-```
+Demonstrates OpenAI Vision API with image analysis:
 
-### Pattern B: Explicit Initialization
+- **Image URL analysis** - Analyze images from URLs
+- **Base64 images** - Process local images as base64
+- **Multi-image analysis** - Compare multiple images in one request
 
-```typescript
-import { initializeReveniumFromEnv, patchOpenAIInstance } from "@revenium/openai";
-import OpenAI from "openai";
+**Key Features:**
 
-// Explicit initialization with error handling
-const result = initializeReveniumFromEnv();
-if (!result.success) {
-  throw new Error(result.message);
-}
+- Image analysis with GPT-4 Vision
+- Multiple image input methods
+- Detailed image descriptions
+- Usage tracking for vision API calls
 
-const openai = patchOpenAIInstance(new OpenAI());
-```
+**Perfect for:** Image analysis applications, visual search, accessibility tools
 
-### Pattern C: Manual Configuration
+**See the file for complete code examples.**
 
-```typescript
-import { patchOpenAIInstance } from "@revenium/openai";
-import OpenAI from "openai";
+### `openai-responses-basic.ts` - New Responses API
 
-const openai = patchOpenAIInstance(new OpenAI(), {
-  meteringApiKey: "hak_your_key",
-  meteringBaseUrl: "https://api.revenium.io/meter",
-});
-```
+Demonstrates OpenAI's new Responses API (SDK 5.8+):
+
+- **Simplified interface** - Uses `input` instead of `messages` parameter
+- **Stateful API** - Enhanced capabilities for agent-like applications
+- **Unified experience** - Combines chat completions and assistants features
+
+**Key Features:**
+
+- New Responses API patterns
+- Automatic tracking with new API
+- Metadata support
+- Backward compatibility notes
+
+**Perfect for:** Applications using OpenAI's latest API features
+
+**See the file for complete code examples.**
+
+### `openai-responses-streaming.ts` - Responses API Streaming
 
-## Available TypeScript Examples
+Demonstrates streaming with the new Responses API:
 
-### OpenAI Examples
+- **Streaming responses** - Real-time responses with new API
+- **Event handling** - Process response events as they arrive
+- **Usage tracking** - Automatic tracking for streaming responses
 
-| File | Description | Features |
-|------|-------------|----------|
-| `openai-basic.ts` | Basic chat completions | Chat, embeddings, metadata tracking |
-| `openai-streaming.ts` | Streaming responses | Real-time token streaming |
-| `openai-responses-basic.ts` | Responses API (new) | New response format (SDK 5.8+) |
-| `openai-responses-streaming.ts` | Responses API streaming | Streaming with new API |
+**Key Features:**
+
+- Responses API streaming patterns
+- Type-safe event processing
+- Automatic usage metrics
+- Stream completion tracking
+
+**Perfect for:** Real-time applications using the new Responses API
+
+**See the file for complete code examples.**
 
 ### Azure OpenAI Examples
 
-| File | Description | Features |
-|------|-------------|----------|
-| `azure-basic.ts` | Azure chat completions | Azure integration, auto-detection |
-| `azure-streaming.ts` | Azure streaming | Real-time Azure responses |
-| `azure-responses-basic.ts` | Azure Responses API | New API with Azure |
-| `azure-responses-streaming.ts` | Azure Responses streaming | Streaming with Azure Responses API |
+#### `azure-basic.ts` - Azure Chat Completions
+
+Demonstrates Azure OpenAI integration with automatic detection:
+
+- **Azure configuration** - Environment-based Azure setup
+- **Chat completions** - Azure-hosted models with tracking
+- **Automatic detection** - Middleware detects Azure vs OpenAI automatically
+
+**Key Features:**
+
+- Azure OpenAI deployment configuration
+- Model name resolution for Azure
+- Accurate Azure pricing
+- Metadata tracking with Azure
+
+**Perfect for:** Enterprise applications using Azure OpenAI
+
+**See the file for complete code examples.**
+
+#### `azure-streaming.ts` - Azure Streaming
+
+Demonstrates streaming with Azure OpenAI:
+
+- **Azure streaming** - Real-time responses from Azure-hosted models
+- **Deployment resolution** - Automatic Azure deployment name handling
+- **Usage tracking** - Azure-specific metrics and pricing
+
+**Perfect for:** Real-time Azure OpenAI applications
+
+**See the file for complete code examples.**
+
+#### `azure-responses-basic.ts` - Azure Responses API
 
-## TypeScript Requirements
+Demonstrates new Responses API with Azure OpenAI:
 
-**Minimum versions:**
-- TypeScript: 4.5+
-- Node.js: 16.0+
-- OpenAI SDK: 5.0+ (5.8+ for Responses API)
+- **Azure + Responses API** - Combine Azure hosting with new API
+- **Unified interface** - Same Responses API patterns on Azure
+- **Automatic tracking** - Azure-aware usage tracking
+
+**Perfect for:** Azure applications using latest OpenAI features
+
+**See the file for complete code examples.**
+
+#### `azure-responses-streaming.ts` - Azure Responses Streaming
+
+Demonstrates Responses API streaming with Azure OpenAI:
+
+- **Azure streaming** - Real-time Responses API on Azure
+- **Event handling** - Process Azure response events
+- **Complete tracking** - Azure metrics with new API
+
+**Perfect for:** Real-time Azure applications with Responses API
+
+**See the file for complete code examples.**
+
+## TypeScript Configuration
+
+Ensure your `tsconfig.json` includes:
 
-**TypeScript compiler options:**
 ```json
 {
-  "esModuleInterop": true,
-  "allowSyntheticDefaultImports": true,
-  "strict": true,
-  "skipLibCheck": true
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "skipLibCheck": true
+  }
 }
 ```
 
-## TypeScript Troubleshooting
+## Requirements
 
-### Issue: `usageMetadata` property not recognized
+- **Node.js 16+** with TypeScript support
+- **TypeScript 4.5+** for module augmentation features
+- **Valid Revenium API key** (starts with `hak_`)
+- **Valid OpenAI API key** (starts with `sk-`) or Azure OpenAI credentials
+- **OpenAI SDK 5.0+** (5.8+ for Responses API)
 
-**Solution**: Ensure you import the middleware **before** OpenAI:
+## Troubleshooting
+
+### Module Augmentation Not Working
+
+**Problem:** TypeScript doesn't recognize `usageMetadata` in OpenAI SDK calls
+
+**Solution:**
 
 ```typescript
-//  Correct order
-import "@revenium/openai";
-import OpenAI from "openai";
+// ❌ Wrong - missing module augmentation import
+import { initializeReveniumFromEnv } from "@revenium/openai";
 
-//  Wrong order
+// ✅ Correct - import for module augmentation
+import { initializeReveniumFromEnv, patchOpenAIInstance } from "@revenium/openai";
 import OpenAI from "openai";
-import "@revenium/openai";
 ```
 
-### Issue: Type errors with streaming responses
+### Environment Variables Not Loading
 
-**Solution**: The middleware extends OpenAI types automatically. If you see errors:
+**Problem:** `REVENIUM_METERING_API_KEY` or `OPENAI_API_KEY` not found
 
-```typescript
-// Ensure you're using the patched client (correct pattern)
-import { patchOpenAIInstance } from "@revenium/openai";
-import OpenAI from "openai";
+**Solutions:**
+
+- Ensure `.env` file is in project root
+- Check variable names match exactly
+- Verify you're importing `dotenv/config` before the middleware
+- Check API keys have correct prefixes (`hak_` for Revenium, `sk-` for OpenAI)
+
+### TypeScript Compilation Errors
+
+**Problem:** Module resolution or import errors
+
+**Solution:** Verify your `tsconfig.json` settings:
 
-const openai = patchOpenAIInstance(new OpenAI());  // Returns patched instance
+```json
+{
+  "compilerOptions": {
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true
+  }
+}
 ```
 
-### Issue: Examples not found after npm install
+### Azure Configuration Issues
+
+**Problem:** Azure OpenAI not working or incorrect pricing
+
+**Solutions:**
+
+- Verify all Azure environment variables are set (`AZURE_OPENAI_ENDPOINT`, `AZURE_OPENAI_API_KEY`, `AZURE_OPENAI_DEPLOYMENT`)
+- Check deployment name matches your Azure resource
+- Ensure API version is compatible (`2024-12-01-preview` or later recommended)
+- Verify endpoint URL format: `https://your-resource-name.openai.azure.com/`
 
-**Solution**: Examples are included in the package:
+### Debug Mode
+
+Enable detailed logging to troubleshoot issues:
 
 ```bash
-# Check examples are present
-ls node_modules/@revenium/openai/examples/
+# In .env file
+REVENIUM_DEBUG=true
 
-# Copy to your project
-cp -r node_modules/@revenium/openai/examples/ ./examples/
+# Then run examples
+npx tsx examples/getting_started.ts
 ```
 
-## Getting Help
+## Additional Resources
 
 - **Main Documentation**: See root [README.md](https://github.com/revenium/revenium-middleware-openai-node/blob/HEAD/README.md)
-- **Troubleshooting**: See [TROUBLESHOOTING.md](https://github.com/revenium/revenium-middleware-openai-node/blob/HEAD/TROUBLESHOOTING.md)
+- **API Reference**: [Revenium Metadata Fields](https://revenium.readme.io/reference/meter_ai_completion)
+- **OpenAI Documentation**: [OpenAI API Reference](https://platform.openai.com/docs)
 - **Issues**: [Report bugs](https://github.com/revenium/revenium-middleware-openai-node/issues)
-- **Support**: support@revenium.io
-
----
-
-**Built by Revenium** | [Documentation](https://docs.revenium.io) | [npm Package](https://www.npmjs.com/package/@revenium/openai)