@revenium/openai 1.0.13 → 1.0.14

package/examples/README.md

@@ -1,303 +1,381 @@
 # Revenium OpenAI Middleware - Examples
 
-**TypeScript-first** examples demonstrating automatic Revenium usage tracking with the OpenAI SDK.
+This directory contains examples demonstrating how to use the Revenium OpenAI middleware.
 
-## Getting Started - Step by Step
+## Prerequisites
 
-### 1. Create Your Project
+Before running the examples, make sure you have:
 
-```bash
-# Create project directory
-mkdir my-openai-project
-cd my-openai-project
+1. **Node.js 16 or later** installed
+2. **Revenium API Key** - Get one from [Revenium Dashboard](https://app.revenium.ai)
+3. **OpenAI API Key** - Get one from [OpenAI Platform](https://platform.openai.com)
+4. **(Optional) Azure OpenAI credentials** - For Azure examples
 
-# Initialize Node.js project
-npm init -y
-```
+## Setup
 
-### 2. Install Dependencies
+1. **Clone the repository** (if you haven't already):
 
-```bash
-npm install @revenium/openai openai dotenv
-npm install -D typescript tsx @types/node  # For TypeScript
-```
+   ```bash
+   git clone https://github.com/revenium/revenium-middleware-openai-node.git
+   cd revenium-middleware-openai-node
+   ```
 
-### 3. Environment Setup
+2. **Install dependencies**:
 
-Create a `.env` file in your project root:
+   ```bash
+   npm install
+   ```
 
-```bash
-# Required
-REVENIUM_METERING_API_KEY=hak_your_revenium_api_key
-OPENAI_API_KEY=sk_your_openai_api_key
-
-# Optional
-REVENIUM_METERING_BASE_URL=https://api.revenium.ai
-REVENIUM_DEBUG=false
-
-# Optional - For Azure OpenAI examples
-AZURE_OPENAI_ENDPOINT=https://your-resource-name.openai.azure.com/
-AZURE_OPENAI_API_KEY=your-azure-api-key
-AZURE_OPENAI_DEPLOYMENT=your-deployment-name
-AZURE_OPENAI_API_VERSION=2024-12-01-preview
-```
+3. **Configure environment variables**:
+
+   Copy the `.env.example` file to `.env` and edit it with your API keys:
+
+   ```bash
+   cp .env.example .env
+   ```
+
+   See [.env.example](https://github.com/revenium/revenium-middleware-openai-node/blob/HEAD/.env.example) for all available configuration options.
 
-### 4. Run Examples
+## Examples
 
-**If you cloned from GitHub:**
+### 1. Getting Started
+
+**File:** `getting_started.ts`
+
+The simplest example to get you started with Revenium tracking:
+
+- Initialize the middleware
+- Create a basic chat completion
+- Display response and usage metrics
+
+**Run:**
 
 ```bash
-# Run examples directly
+npm run example:getting-started
+# or
 npx tsx examples/getting_started.ts
-npx tsx examples/openai-basic.ts
-npx tsx examples/openai-streaming.ts
 ```
 
-**If you installed via npm:**
+**What it does:**
+
+- Loads configuration from environment variables
+- Creates a simple chat completion request
+- Automatically sends metering data to Revenium API
+- Displays the response
+
+---
+
+### 2. OpenAI Basic
 
-Examples are included in your `node_modules/@revenium/openai/examples/` directory:
+**File:** `openai/basic.ts`
+
+Demonstrates standard OpenAI API usage:
+
+- Chat completions with metadata
+- Embeddings generation
+- Multiple API calls
+
+**Run:**
 
 ```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
+npm run example:openai-basic
+# or
+npx tsx examples/openai/basic.ts
 ```
 
-## Available Examples
+**What it does:**
 
-### `getting_started.ts` - Simple Entry Point
+- Creates chat completions with metadata tracking
+- Generates text embeddings
+- Demonstrates metadata usage for tracking
 
-The simplest example to get you started with Revenium tracking:
+---
 
-- **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
+### 3. OpenAI Metadata
 
-**Key Features:**
+**File:** `openai/metadata.ts`
 
-- Auto-initialization from environment variables
-- Native `usageMetadata` support via module augmentation
-- All metadata fields documented with examples
-- Single API call demonstration
+Demonstrates all available metadata fields:
 
-**Perfect for:** First-time users, quick validation, understanding metadata structure
+- Complete metadata structure
+- All optional fields documented
+- Subscriber information
+
+**Run:**
+
+```bash
+npm run example:openai-metadata
+# or
+npx tsx examples/openai/metadata.ts
+```
 
-**See the file for complete code examples.**
+**What it does:**
 
-### `openai-basic.ts` - Chat Completions and Embeddings
+- Shows all available metadata fields
+- Demonstrates subscriber tracking
+- Includes organization and product tracking
 
-Demonstrates standard OpenAI API usage with automatic tracking:
+**Metadata fields supported:**
 
-- **Chat completions** - Basic chat API with metadata tracking
-- **Embeddings** - Text embedding generation with usage tracking
-- **Multiple API calls** - Batch operations with consistent metadata
+- `traceId` - Session or conversation tracking identifier
+- `taskType` - Type of AI task being performed
+- `agent` - AI agent or bot identifier
+- `organizationId` - Organization identifier
+- `productId` - Product or service identifier
+- `subscriptionId` - Subscription tier identifier
+- `responseQualityScore` - Quality rating (0.0-1.0)
+- `subscriber` - Nested subscriber object with `id`, `email`, `credential` (with `name` and `value`)
 
-**Key Features:**
+---
 
-- TypeScript module augmentation for native `usageMetadata` support
-- Full type safety with IntelliSense
-- Comprehensive metadata examples
-- Error handling patterns
+### 4. OpenAI Streaming
 
-**Perfect for:** Understanding basic OpenAI API patterns with tracking
+**File:** `openai/streaming.ts`
 
-**See the file for complete code examples.**
+Demonstrates streaming responses:
 
-### `openai-streaming.ts` - Real-time Streaming
+- Real-time token streaming
+- Accumulating responses
+- Streaming metrics
 
-Demonstrates streaming responses with automatic token tracking:
+**Run:**
 
-- **Streaming chat completions** - Real-time token streaming with metadata
-- **Batch embeddings** - Multiple embedding requests efficiently
-- **Stream processing** - Type-safe event handling
+```bash
+npm run example:openai-stream
+# or
+npx tsx examples/openai/streaming.ts
+```
 
-**Key Features:**
+**What it does:**
 
-- Automatic tracking when stream completes
-- Real-time token counting
-- Time-to-first-token metrics
-- Stream error handling
+- Creates a streaming chat completion
+- Displays tokens as they arrive in real-time
+- Tracks streaming metrics
+- Sends metering data after stream completes
 
-**Perfect for:** Real-time applications, chatbots, interactive AI assistants
+---
 
-**See the file for complete code examples.**
+### 5. OpenAI Responses API (Basic)
 
-### `openai-responses-basic.ts` - Responses API
+**File:** `openai/responses-basic.ts`
 
 Demonstrates OpenAI's Responses API:
 
-- **Simplified interface** - Uses `input` instead of `messages` parameter
-- **Stateful API** - Enhanced capabilities for agent-like applications
-- **Unified experience** - Combines chat completions and assistants features
+- Simplified interface with `input` parameter
+- Stateful API features
+- Automatic tracking
 
-**Key Features:**
+**Run:**
 
-- New Responses API patterns
-- Automatic tracking with new API
-- Metadata support
-- Backward compatibility notes
+```bash
+npm run example:openai-res-basic
+# or
+npx tsx examples/openai/responses-basic.ts
+```
 
-**Perfect for:** Applications using OpenAI's latest API features
+**What it does:**
 
-**See the file for complete code examples.**
+- Uses the new Responses API
+- Creates responses with metadata
+- Demonstrates simplified interface
 
-### `openai-responses-streaming.ts` - Responses API Streaming
+---
 
-Demonstrates streaming with the new Responses API:
+### 6. OpenAI Responses API (Embeddings)
 
-- **Streaming responses** - Real-time responses with new API
-- **Event handling** - Process response events as they arrive
-- **Usage tracking** - Automatic tracking for streaming responses
+**File:** `openai/responses-embed.ts`
 
-**Key Features:**
+Demonstrates embeddings with Responses API:
 
-- Responses API streaming patterns
-- Type-safe event processing
-- Automatic usage metrics
-- Stream completion tracking
+- Embeddings generation
+- Metadata tracking
+- Usage metrics
 
-**Perfect for:** Real-time applications using the new Responses API
+**Run:**
 
-**See the file for complete code examples.**
+```bash
+npm run example:openai-res-embed
+# or
+npx tsx examples/openai/responses-embed.ts
+```
 
-### Azure OpenAI Examples
+**What it does:**
 
-#### `azure-basic.ts` - Azure Chat Completions
+- Generates text embeddings
+- Tracks embedding usage
+- Demonstrates metadata with embeddings
 
-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
+### 7. OpenAI Responses API (Streaming)
 
-**Key Features:**
+**File:** `openai/responses-streaming.ts`
 
-- Azure OpenAI deployment configuration
-- Model name resolution for Azure
-- Accurate Azure pricing
-- Metadata tracking with Azure
+Demonstrates streaming with Responses API:
 
-**Perfect for:** Enterprise applications using Azure OpenAI
+- Real-time streaming responses
+- Event handling
+- Streaming metrics
 
-**See the file for complete code examples.**
+**Run:**
 
-#### `azure-streaming.ts` - Azure Streaming
+```bash
+npm run example:openai-res-stream
+# or
+npx tsx examples/openai/responses-streaming.ts
+```
 
-Demonstrates streaming with Azure OpenAI:
+**What it does:**
+
+- Creates streaming responses
+- Processes response events in real-time
+- Tracks streaming usage metrics
+
+---
+
+### 8. Azure OpenAI (Basic)
 
-- **Azure streaming** - Real-time responses from Azure-hosted models
-- **Deployment resolution** - Automatic Azure deployment name handling
-- **Usage tracking** - Azure-specific metrics and pricing
+**File:** `azure/basic.ts`
 
-**Perfect for:** Real-time Azure OpenAI applications
+Demonstrates Azure OpenAI integration:
 
-**See the file for complete code examples.**
+- Automatic Azure detection
+- Azure-specific configuration
+- Chat completions with Azure
+
+**Prerequisites:**
+
+To run this example with Azure OpenAI, you need to configure Azure credentials in `.env`:
+
+```bash
+AZURE_OPENAI_API_KEY=your_azure_key
+AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
+AZURE_OPENAI_API_VERSION=your_azure_openai_api_version
+```
 
-#### `azure-responses-basic.ts` - Azure Responses API
+**Run:**
 
-Demonstrates new Responses API with Azure OpenAI:
+```bash
+npm run example:azure-basic
+# or
+npx tsx examples/azure/basic.ts
+```
 
-- **Azure + Responses API** - Combine Azure hosting with new API
-- **Unified interface** - Same Responses API patterns on Azure
-- **Automatic tracking** - Azure-aware usage tracking
+**What it does:**
 
-**Perfect for:** Azure applications using latest OpenAI features
+- Automatically detects Azure configuration
+- Uses Azure OpenAI for chat completions
+- Sends metering data with provider='AZURE_OPENAI'
 
-**See the file for complete code examples.**
+**Important for Azure:**
 
-#### `azure-responses-streaming.ts` - Azure Responses Streaming
+When using Azure OpenAI, you must pass your **deployment name** (not the OpenAI model name) in the `model` parameter. The deployment name is what you configured in Azure Portal.
 
-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
+### 9. Azure OpenAI (Streaming)
 
-**Perfect for:** Real-time Azure applications with Responses API
+**File:** `azure/stream.ts`
 
-**See the file for complete code examples.**
+Demonstrates streaming with Azure OpenAI:
 
-## TypeScript Configuration
+- Real-time streaming from Azure
+- Azure deployment handling
+- Streaming metrics
 
-Ensure your `tsconfig.json` includes:
+**Run:**
 
-```json
-{
-  "compilerOptions": {
-    "target": "ES2020",
-    "module": "ESNext",
-    "moduleResolution": "node",
-    "esModuleInterop": true,
-    "allowSyntheticDefaultImports": true,
-    "strict": true,
-    "skipLibCheck": true
-  }
-}
+```bash
+npm run example:azure-stream
+# or
+npx tsx examples/azure/stream.ts
 ```
 
-## Requirements
+**What it does:**
+
+- Creates streaming chat completions with Azure
+- Displays tokens in real-time
+- Tracks Azure streaming metrics
 
-- **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)
+---
 
-## Troubleshooting
+### 10. Azure Responses API (Basic)
 
-### Module Augmentation Not Working
+**File:** `azure/responses-basic.ts`
 
-**Problem:** TypeScript doesn't recognize `usageMetadata` in OpenAI SDK calls
+Demonstrates Responses API with Azure OpenAI:
 
-**Solution:**
+- Azure + Responses API
+- Simplified interface on Azure
+- Automatic tracking
 
-```typescript
-// ❌ Wrong - missing module augmentation import
-import { initializeReveniumFromEnv } from "@revenium/openai";
+**Run:**
 
-// ✅ Correct - import for module augmentation
-import { initializeReveniumFromEnv, patchOpenAIInstance } from "@revenium/openai";
-import OpenAI from "openai";
+```bash
+npm run example:azure-res-basic
+# or
+npx tsx examples/azure/responses-basic.ts
 ```
 
-### Environment Variables Not Loading
+**What it does:**
+
+- Uses Responses API with Azure OpenAI
+- Creates responses with Azure deployment
+- Tracks Azure usage metrics
 
-**Problem:** `REVENIUM_METERING_API_KEY` or `OPENAI_API_KEY` not found
+---
 
-**Solutions:**
+### 11. Azure Responses API (Streaming)
 
-- 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)
+**File:** `azure/responses-stream.ts`
 
-### TypeScript Compilation Errors
+Demonstrates Responses API streaming with Azure:
 
-**Problem:** Module resolution or import errors
+- Real-time Responses API on Azure
+- Event handling
+- Azure streaming metrics
 
-**Solution:** Verify your `tsconfig.json` settings:
+**Run:**
 
-```json
-{
-  "compilerOptions": {
-    "moduleResolution": "node",
-    "esModuleInterop": true,
-    "allowSyntheticDefaultImports": true,
-    "strict": true
-  }
-}
+```bash
+npm run example:azure-res-stream
+# or
+npx tsx examples/azure/responses-stream.ts
 ```
 
-### Azure Configuration Issues
+**What it does:**
+
+- Creates streaming responses with Azure
+- Processes response events in real-time
+- Tracks Azure streaming usage
+
+---
+
+## Common Issues
+
+### "Client not initialized" error
+
+**Solution:** Make sure to call `Initialize()` before using `GetClient()`.
+
+### "REVENIUM_METERING_API_KEY is required" error
+
+**Solution:** Set the `REVENIUM_METERING_API_KEY` environment variable in your `.env` file.
 
-**Problem:** Azure OpenAI not working or incorrect pricing
+### "invalid Revenium API key format" error
 
-**Solutions:**
+**Solution:** Revenium API keys should start with `hak_`. Check your API key format.
 
-- 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/`
+### Environment variables not loading
+
+**Solution:** Make sure your `.env` file is in the project root directory and contains the required variables.
+
+### Azure example not working
+
+**Solution:** Make sure you have set all required Azure environment variables in your `.env` file:
+
+- `AZURE_OPENAI_API_KEY`
+- `AZURE_OPENAI_ENDPOINT`
+- `AZURE_OPENAI_API_VERSION`
 
 ### Debug Mode
 
@@ -308,12 +386,18 @@ Enable detailed logging to troubleshoot issues:
 REVENIUM_DEBUG=true
 
 # Then run examples
-npx tsx examples/getting_started.ts
+npm run example:getting-started
 ```
 
-## Additional Resources
+## Next Steps
+
+- Check the [main README](https://github.com/revenium/revenium-middleware-openai-node/blob/HEAD/README.md) for detailed documentation
+- Visit the [Revenium Dashboard](https://app.revenium.ai) to view your metering data
+- See [.env.example](https://github.com/revenium/revenium-middleware-openai-node/blob/HEAD/.env.example) for all configuration options
+
+## Support
+
+For issues or questions:
 
-- **Main Documentation**: See root [README.md](https://github.com/revenium/revenium-middleware-openai-node/blob/HEAD/README.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)
+- Documentation: https://docs.revenium.io
+- Email: support@revenium.io

package/examples/azure/basic.ts

@@ -0,0 +1,62 @@
+/**
+ * Azure OpenAI Example
+ * Demonstrates usage with Azure OpenAI.
+ */
+
+import { Initialize, GetClient, UsageMetadata } from "@revenium/openai";
+
+async function main() {
+  // Initialize the middleware
+  Initialize();
+
+  // Get the client
+  const client = GetClient();
+
+  // Create a metadata
+  const metadata: UsageMetadata = {
+    organizationId: "org-azure-demo",
+    productId: "prod-azure-integration",
+    taskType: "question-answering",
+    agent: "azure-assistant",
+  };
+
+  // Create a chat completion
+  // IMPORTANT: For Azure OpenAI, the Model parameter must be your DEPLOYMENT NAME
+  // This is the name you gave to your deployment in Azure Portal, NOT the OpenAI model name
+  // Example: If you created a deployment called "gpt-5-mini-2" in Azure, use that name here
+  //
+
+  const response = await client
+    .chat()
+    .completions()
+    .create(
+      {
+        // NOTE: Make sure REVENIUM_AZURE_DISABLE=0 in your .env file to enable Azure
+        // If Azure is disabled, this will fail because "gpt-5-mini-2" is not a valid OpenAI model name
+        model: "gpt-5-mini-2", // Your Azure deployment name (requires REVENIUM_AZURE_DISABLE=0)
+        messages: [
+          {
+            role: "system" as const,
+            content:
+              "You are a helpful assistant that explains cloud computing concepts.",
+          },
+          {
+            role: "user" as const,
+            content:
+              "Explain the difference between Azure OpenAI and OpenAI native API in 2-3 sentences.",
+          },
+        ],
+        max_completion_tokens: 2000, // Increased for reasoning models (gpt-5-mini uses reasoning tokens)
+        // Note: Reasoning models like gpt-5-mini only support default temperature (1.0)
+      },
+      metadata
+    );
+
+  // Display the response
+  if (response.choices.length > 0) {
+    console.log(`Assistant: ${response.choices[0].message.content}`);
+  }
+  console.log("\nUsage data sent to Revenium! Check your dashboard");
+}
+
+main().catch(console.error);