@revenium/openai 1.0.10 → 1.0.11

package/dist/cjs/index.js

@@ -11,14 +11,14 @@
  * OPENAI_API_KEY=sk_your_openai_key
  *
  * Simple Usage (auto-initialization):
- * import { patchOpenAIInstance } from 'revenium-middleware-openai-node';
+ * import { patchOpenAIInstance } from '@revenium/openai';
  * import OpenAI from 'openai';
  *
  * const openai = patchOpenAIInstance(new OpenAI());
  * // Auto-initializes from environment variables
  *
  * Advanced Usage (explicit initialization):
- * import { initializeReveniumFromEnv, patchOpenAIInstance } from 'revenium-middleware-openai-node';
+ * import { initializeReveniumFromEnv, patchOpenAIInstance } from '@revenium/openai';
  * import OpenAI from 'openai';
  *
  * const result = initializeReveniumFromEnv();

package/dist/cjs/types/openai-augmentation.js

@@ -18,7 +18,7 @@
  *
  * @example Basic usage with chat completions
  * ```typescript
- * import 'revenium-middleware-openai-node';
+ * import '@revenium/openai';
  * import OpenAI from 'openai';
  *
  * const openai = new OpenAI();

package/dist/esm/index.js

@@ -10,14 +10,14 @@
  * OPENAI_API_KEY=sk_your_openai_key
  *
  * Simple Usage (auto-initialization):
- * import { patchOpenAIInstance } from 'revenium-middleware-openai-node';
+ * import { patchOpenAIInstance } from '@revenium/openai';
  * import OpenAI from 'openai';
  *
  * const openai = patchOpenAIInstance(new OpenAI());
  * // Auto-initializes from environment variables
  *
  * Advanced Usage (explicit initialization):
- * import { initializeReveniumFromEnv, patchOpenAIInstance } from 'revenium-middleware-openai-node';
+ * import { initializeReveniumFromEnv, patchOpenAIInstance } from '@revenium/openai';
  * import OpenAI from 'openai';
  *
  * const result = initializeReveniumFromEnv();

package/dist/esm/types/openai-augmentation.js

@@ -17,7 +17,7 @@
  *
  * @example Basic usage with chat completions
  * ```typescript
- * import 'revenium-middleware-openai-node';
+ * import '@revenium/openai';
  * import OpenAI from 'openai';
  *
  * const openai = new OpenAI();

package/dist/types/index.d.ts

@@ -10,14 +10,14 @@
  * OPENAI_API_KEY=sk_your_openai_key
  *
  * Simple Usage (auto-initialization):
- * import { patchOpenAIInstance } from 'revenium-middleware-openai-node';
+ * import { patchOpenAIInstance } from '@revenium/openai';
  * import OpenAI from 'openai';
  *
  * const openai = patchOpenAIInstance(new OpenAI());
  * // Auto-initializes from environment variables
  *
  * Advanced Usage (explicit initialization):
- * import { initializeReveniumFromEnv, patchOpenAIInstance } from 'revenium-middleware-openai-node';
+ * import { initializeReveniumFromEnv, patchOpenAIInstance } from '@revenium/openai';
  * import OpenAI from 'openai';
  *
  * const result = initializeReveniumFromEnv();

package/dist/types/types/openai-augmentation.d.ts

@@ -17,7 +17,7 @@
  *
  * @example Basic usage with chat completions
  * ```typescript
- * import 'revenium-middleware-openai-node';
+ * import '@revenium/openai';
  * import OpenAI from 'openai';
  *
  * const openai = new OpenAI();

package/examples/README.md

@@ -0,0 +1,361 @@
+# Revenium OpenAI Middleware - TypeScript Examples
+
+**TypeScript-first** examples demonstrating how to use the Revenium OpenAI middleware with full type safety and IntelliSense support.
+
+## 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
+
+### 1. Install Dependencies
+
+```bash
+npm install @revenium/openai openai@^5.8.0
+npm install -D typescript tsx @types/node  # For TypeScript development
+```
+
+### 2. TypeScript Configuration
+
+Ensure your `tsconfig.json` includes:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "skipLibCheck": true
+  }
+}
+```
+
+### 3. Environment Setup
+
+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
+REVENIUM_METERING_API_KEY=hak_your_revenium_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 - 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
+```
+
+### 4. Run TypeScript Examples
+
+```bash
+# OpenAI examples
+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
+
+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.
+
+### Step 1: Create Your First Test
+
+#### TypeScript Test
+
+Create `test-openai.ts`:
+
+```typescript
+// test-openai.ts
+import "dotenv/config";
+import { initializeReveniumFromEnv, patchOpenAIInstance } from "@revenium/openai";
+import OpenAI from "openai";
+
+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);
+  }
+}
+
+testOpenAI();
+```
+
+#### JavaScript Test
+
+Create `test-openai.js`:
+
+```javascript
+// test-openai.js
+require("dotenv").config();
+const { initializeReveniumFromEnv, patchOpenAIInstance } = require("@revenium/openai");
+const OpenAI = require("openai");
+
+async function testOpenAI() {
+  try {
+    // Initialize Revenium middleware
+    initializeReveniumFromEnv();
+
+    // Create and patch OpenAI client (returns patched instance)
+    const openai = patchOpenAIInstance(new OpenAI());
+
+    // 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,
+    });
+
+    console.log("Response:", response.choices[0].message.content);
+    // Success! Response and metering data sent to Revenium
+  } catch (error) {
+    console.error("Error:", error);
+  }
+}
+
+testOpenAI();
+```
+
+### Step 2: Update package.json
+
+Add a test script to easily run your example:
+
+```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"
+  }
+}
+```
+
+### Step 3: Run Your Tests
+
+```bash
+# TypeScript
+npm run test
+
+# Or directly
+npx tsx test-openai.ts
+
+# JavaScript
+node test-openai.js
+```
+
+### Step 4: Create Advanced Examples
+
+Explore our comprehensive examples for different use cases:
+
+**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
+
+**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
+
+### Step 5: Project Structure
+
+Here's a recommended project structure:
+
+```
+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
+```
+
+## TypeScript Integration Patterns
+
+### Pattern A: Auto-Initialization (Recommended)
+
+```typescript
+import { patchOpenAIInstance } from "@revenium/openai";
+import OpenAI from "openai";
+
+// Auto-initializes from environment variables
+const openai = patchOpenAIInstance(new OpenAI());
+// Already tracked! No explicit init needed if env vars are set
+```
+
+### Pattern B: Explicit Initialization
+
+```typescript
+import { initializeReveniumFromEnv, patchOpenAIInstance } from "@revenium/openai";
+import OpenAI from "openai";
+
+// Explicit initialization with error handling
+const result = initializeReveniumFromEnv();
+if (!result.success) {
+  throw new Error(result.message);
+}
+
+const openai = patchOpenAIInstance(new OpenAI());
+```
+
+### Pattern C: Manual Configuration
+
+```typescript
+import { patchOpenAIInstance } from "@revenium/openai";
+import OpenAI from "openai";
+
+const openai = patchOpenAIInstance(new OpenAI(), {
+  meteringApiKey: "hak_your_key",
+  meteringBaseUrl: "https://api.revenium.io/meter",
+});
+```
+
+## Available TypeScript Examples
+
+### OpenAI Examples
+
+| 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 |
+
+### 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 |
+
+## TypeScript Requirements
+
+**Minimum versions:**
+- TypeScript: 4.5+
+- Node.js: 16.0+
+- OpenAI SDK: 5.0+ (5.8+ for Responses API)
+
+**TypeScript compiler options:**
+```json
+{
+  "esModuleInterop": true,
+  "allowSyntheticDefaultImports": true,
+  "strict": true,
+  "skipLibCheck": true
+}
+```
+
+## TypeScript Troubleshooting
+
+### Issue: `usageMetadata` property not recognized
+
+**Solution**: Ensure you import the middleware **before** OpenAI:
+
+```typescript
+//  Correct order
+import "@revenium/openai";
+import OpenAI from "openai";
+
+//  Wrong order
+import OpenAI from "openai";
+import "@revenium/openai";
+```
+
+### Issue: Type errors with streaming responses
+
+**Solution**: The middleware extends OpenAI types automatically. If you see errors:
+
+```typescript
+// Ensure you're using the patched client (correct pattern)
+import { patchOpenAIInstance } from "@revenium/openai";
+import OpenAI from "openai";
+
+const openai = patchOpenAIInstance(new OpenAI());  // Returns patched instance
+```
+
+### Issue: Examples not found after npm install
+
+**Solution**: Examples are included in the package:
+
+```bash
+# Check examples are present
+ls node_modules/@revenium/openai/examples/
+
+# Copy to your project
+cp -r node_modules/@revenium/openai/examples/ ./examples/
+```
+
+## Getting Help
+
+- **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)
+- **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)

package/examples/azure-basic.ts

@@ -0,0 +1,194 @@
+/**
+ * ️ Azure OpenAI Basic Example
+ *
+ * Shows how to use Revenium middleware with Azure OpenAI chat completions and embeddings.
+ * Demonstrates seamless metadata integration with Azure - all metadata fields are optional!
+ */
+
+import 'dotenv/config';
+import { initializeReveniumFromEnv, patchOpenAIInstance } from '@revenium/openai';
+import { AzureOpenAI } from 'openai';
+
+async function azureBasicExample() {
+  console.log('️ Azure OpenAI Basic Usage with Seamless Metadata Integration\n');
+
+  // Initialize Revenium middleware
+  const initResult = initializeReveniumFromEnv();
+  if (!initResult.success) {
+    console.error(' Failed to initialize Revenium:', initResult.message);
+    process.exit(1);
+  }
+
+  // Create Azure OpenAI instance and patch it
+  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 || '2024-12-01-preview',
+    })
+  );
+
+  console.log(' Azure OpenAI client configured and patched');
+  console.log(' Endpoint:', process.env.AZURE_OPENAI_ENDPOINT);
+  console.log(' API Version:', process.env.AZURE_OPENAI_API_VERSION || '2024-12-01-preview');
+  console.log();
+
+  // Check if we have a chat model configured
+  const deployment = process.env.AZURE_OPENAI_DEPLOYMENT;
+  const isChatModel = deployment && !deployment.includes('embedding');
+
+  if (!isChatModel) {
+    console.log('️  Note: Current Azure deployment appears to be for embeddings.');
+    console.log('   To test chat completions, update .env to use a chat model:');
+    console.log('   - Comment out the embeddings section');
+    console.log('   - Uncomment the chat testing section');
+    console.log('   - Set AZURE_OPENAI_DEPLOYMENT=gpt-4o');
+    console.log('\n   Skipping chat examples and testing embeddings instead...\n');
+  } else {
+    // Example 1: Basic Azure chat completion (no metadata)
+    console.log(' Example 1: Basic Azure chat completion (automatic tracking)');
+
+    const basicResponse = await azure.chat.completions.create({
+      model: deployment,
+      messages: [{ role: 'user', content: 'What are the benefits of using Azure OpenAI?' }],
+      // No usageMetadata - still automatically tracked with Azure provider info!
+      // No max_tokens - let response complete naturally
+    });
+
+    console.log(' Response:', basicResponse.choices[0]?.message?.content);
+    console.log(' Usage:', basicResponse.usage);
+    console.log(' Automatically tracked to Revenium with Azure provider metadata\n');
+  }
+
+  if (isChatModel) {
+    // Example 2: Azure chat completion with rich metadata (all optional!)
+    console.log(' Example 2: Azure chat completion with rich metadata');
+
+    const metadataResponse = await azure.chat.completions.create({
+      model: deployment,
+      messages: [
+        {
+          role: 'user',
+          content: 'Explain how Azure OpenAI differs from standard OpenAI in 3 points.',
+        },
+      ],
+
+      //  All metadata fields are optional - add what you need for Azure analytics!
+      // Note: Nested subscriber structure for consistency across language implementations
+      usageMetadata: {
+        // User tracking (optional) - nested subscriber object
+        subscriber: {
+          id: 'azure-user-789',
+          email: 'azure-dev@company.com',
+          credential: {
+            name: 'azure-key',
+            value: 'azure789',
+          },
+        },
+
+        // Business context (optional)
+        organizationId: 'enterprise-corp',
+        productId: 'azure-ai-platform',
+
+        // Task classification (optional)
+        taskType: 'azure-comparison',
+        traceId: `azure-${Date.now()}`,
+
+        // Azure-specific fields (optional)
+        agent: 'azure-basic-chat-node',
+        responseQualityScore: 0.92,
+      },
+    });
+
+    console.log(' Response:', metadataResponse.choices[0]?.message?.content);
+    console.log(' Usage:', metadataResponse.usage);
+    console.log(' Tracked with Azure provider + rich metadata for enterprise analytics\n');
+  }
+
+  // Example 3: Azure embeddings (requires embeddings model)
+  console.log(' Example 3: Azure embeddings');
+
+  if (isChatModel) {
+    console.log('️  Note: Current deployment is a chat model (gpt-4o).');
+    console.log('   Embeddings require an embedding model like text-embedding-3-large.');
+    console.log('   To test embeddings, switch .env to embeddings configuration.');
+    console.log('   Skipping embeddings examples.\n');
+  } else {
+    console.log(' Example 3a: Basic Azure embeddings (automatic tracking)');
+
+    const basicEmbedding = await azure.embeddings.create({
+      model: deployment || 'text-embedding-3-large',
+      input:
+        'Azure OpenAI provides enterprise-grade AI capabilities with enhanced security and compliance',
+      // No usageMetadata - still automatically tracked with Azure provider info!
+    });
+
+    console.log(' Model:', basicEmbedding.model);
+    console.log(' Usage:', basicEmbedding.usage);
+    console.log(' Embedding dimensions:', basicEmbedding.data[0]?.embedding.length);
+    console.log(' Azure embeddings automatically tracked without metadata\n');
+
+    // Example 4: Azure embeddings with metadata (all optional!)
+    console.log(' Example 3b: Azure embeddings with rich metadata');
+
+    const metadataEmbedding = await azure.embeddings.create({
+      model: deployment || 'text-embedding-3-large',
+      input:
+        'Enterprise document processing with Azure OpenAI embeddings and comprehensive tracking',
+
+      //  All metadata fields are optional - perfect for Azure enterprise use cases!
+      // Note: Nested subscriber structure matches Python middleware for consistency
+      usageMetadata: {
+        subscriber: {
+          id: 'azure-embed-user-456',
+          email: 'embeddings@enterprise-corp.com',
+          credential: {
+            name: 'azure-embed-key',
+            value: 'embed456',
+          },
+        },
+        organizationId: 'enterprise-corp',
+        taskType: 'enterprise-document-embedding',
+        productId: 'azure-search-platform',
+        traceId: `azure-embed-${Date.now()}`,
+        agent: 'azure-basic-embeddings-node',
+      },
+    });
+
+    console.log(' Model:', metadataEmbedding.model);
+    console.log(' Usage:', metadataEmbedding.usage);
+    console.log(' Embedding dimensions:', metadataEmbedding.data[0]?.embedding.length);
+    console.log(' Azure embeddings tracked with metadata for enterprise analytics\n');
+  }
+
+  // Summary
+  console.log(' Azure OpenAI Summary:');
+  console.log(' Azure OpenAI automatically detected and tracked');
+  console.log(' Model name resolution for accurate pricing');
+  console.log(' Provider metadata includes "Azure" for analytics');
+  if (isChatModel) {
+    console.log(' Chat completions work with or without metadata');
+  } else {
+    console.log(' Embeddings work with or without metadata');
+  }
+  console.log(' All metadata fields are optional');
+  console.log(' No type casting required - native TypeScript support');
+  console.log(' Enterprise-grade tracking with Azure compliance');
+
+  if (!isChatModel) {
+    console.log('\n To test Azure chat completions:');
+    console.log('   1. Edit .env file');
+    console.log('   2. Comment out embeddings section');
+    console.log('   3. Uncomment chat section');
+    console.log('   4. Run this example again');
+  } else {
+    console.log('\n To test Azure embeddings:');
+    console.log('   1. Edit .env file');
+    console.log('   2. Comment out chat section');
+    console.log('   3. Uncomment embeddings section');
+    console.log('   4. Run this example again');
+  }
+}
+
+// Run the example
+azureBasicExample().catch(console.error);