@revenium/openai 1.0.10 → 1.0.12

package/examples/getting_started.ts

@@ -0,0 +1,54 @@
+import 'dotenv/config';
+import { initializeReveniumFromEnv, patchOpenAIInstance } from '@revenium/openai';
+import OpenAI from 'openai';
+
+async function main() {
+  const initResult = initializeReveniumFromEnv();
+  if (!initResult.success) {
+    console.error('Failed to initialize Revenium:', initResult.message);
+    process.exit(1);
+  }
+
+  const openai = patchOpenAIInstance(new OpenAI());
+
+  const response = await openai.chat.completions.create({
+    model: 'gpt-4o-mini',
+    messages: [
+      { role: 'system', content: 'You are a helpful assistant.' },
+      { role: 'user', content: 'Please verify you are ready to assist me.' }
+    ],
+
+    /* Optional metadata for advanced reporting, lineage tracking, and cost allocation
+    usageMetadata: {
+      // User identification
+      subscriber: {
+        id: 'user-123',
+        email: 'user@example.com',
+        credential: {
+          name: 'api-key-prod',
+          value: 'key-abc-123'
+        }
+      },
+
+      // Organization & billing
+      organizationId: 'my-customers-name',
+      subscriptionId: 'plan-enterprise-2024',
+
+      // Product & task tracking
+      productId: 'my-product',
+      taskType: 'doc-summary',
+      agent: 'customer-support',
+
+      // Session tracking
+      traceId: 'session-' + Date.now(),
+
+      // Quality metrics
+      responseQualityScore: 0.95
+    }
+    */
+  });
+
+  console.log('Response:', response.choices[0]?.message?.content);
+}
+
+main().catch(console.error);

package/examples/openai-basic.ts

@@ -0,0 +1,147 @@
+/**
+ * OpenAI Basic Example
+ *
+ * Shows how to use Revenium middleware with OpenAI chat completions and embeddings.
+ * Demonstrates seamless metadata integration - all metadata fields are optional!
+ *
+ * Metadata Options:
+ * - Start with basic usage (no metadata) - tracking works automatically
+ * - Add subscriber info for user tracking
+ * - Include organization/product IDs for business analytics
+ * - Use task type and trace ID for detailed analysis
+ *
+ * For complete metadata field reference, see:
+ * https://revenium.readme.io/reference/meter_ai_completion
+ */
+
+import 'dotenv/config';
+import { initializeReveniumFromEnv, patchOpenAIInstance } from '@revenium/openai';
+import OpenAI from 'openai';
+
+async function openaiBasicExample() {
+  console.log(' 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 and patch OpenAI instance
+  const openai = patchOpenAIInstance(new OpenAI());
+
+  // Example 1: Basic chat completion (no metadata)
+  console.log('Example 1: Basic chat completion (automatic tracking)');
+
+  const basicResponse = await openai.chat.completions.create({
+    model: 'gpt-4o-mini',
+    messages: [{ role: 'user', content: 'What is TypeScript in one sentence?' }],
+    // No usageMetadata - still automatically tracked!
+    // 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 without metadata\n');
+
+  // Example 2: Chat completion with rich metadata (all optional!)
+  console.log('Example 2: Chat completion with rich metadata');
+
+  const metadataResponse = await openai.chat.completions.create({
+    model: 'gpt-4o-mini',
+    messages: [
+      { role: 'user', content: 'Explain the benefits of using middleware in 2 sentences.' },
+    ],
+
+    // Optional metadata for advanced reporting, lineage tracking, and cost allocation
+    usageMetadata: {
+      // User identification
+      subscriber: {
+        id: 'user-12345',
+        email: 'developer@company.com',
+        credential: {
+          name: 'api-key-prod',
+          value: 'key-abc-123',
+        },
+      },
+
+      // Organization & billing
+      organizationId: 'my-customer',
+      subscriptionId: 'plan-premium-2024',
+
+      // Product & task tracking
+      productId: 'ai-assistant',
+      taskType: 'explanation-request',
+      agent: 'openai-basic-chat-node',
+
+      // Session tracking
+      traceId: 'session-' + Date.now(),
+
+      // Quality metrics
+      responseQualityScore: 0.95,
+    },
+  });
+
+  console.log('Response:', metadataResponse.choices[0]?.message?.content);
+  console.log('Usage:', metadataResponse.usage);
+  console.log(' Tracked with rich metadata for analytics\n');
+
+  // Example 3: Basic embeddings (no metadata)
+  console.log('Example 3: Basic embeddings (automatic tracking)');
+
+  const basicEmbedding = await openai.embeddings.create({
+    model: 'text-embedding-3-small',
+    input: 'Revenium middleware automatically tracks OpenAI usage',
+    // No usageMetadata - still automatically tracked!
+  });
+
+  console.log('Model:', basicEmbedding.model);
+  console.log('Usage:', basicEmbedding.usage);
+  console.log('Embedding dimensions:', basicEmbedding.data[0]?.embedding.length);
+  console.log('Embeddings automatically tracked without metadata\n');
+
+  // Example 4: Embeddings with metadata (all optional!)
+  console.log(' Example 4: Embeddings with rich metadata');
+
+  const metadataEmbedding = await openai.embeddings.create({
+    model: 'text-embedding-3-small',
+    input: 'Advanced text embedding with comprehensive tracking metadata',
+
+    // Optional metadata for advanced reporting, lineage tracking, and cost allocation
+    usageMetadata: {
+      // User identification
+      subscriber: {
+        id: 'embedding-user-789',
+        email: 'embeddings@company.com',
+        credential: {
+          name: 'api-key-prod',
+          value: 'key-def-456',
+        },
+      },
+
+      // Organization & billing
+      organizationId: 'my-company',
+      subscriptionId: 'plan-enterprise-2024',
+
+      // Product & task tracking
+      productId: 'search-engine',
+      taskType: 'document-embedding',
+      agent: 'openai-basic-embeddings-node',
+
+      // Session tracking
+      traceId: 'embed-' + Date.now(),
+
+      // Quality metrics
+      responseQualityScore: 0.98,
+    },
+  });
+
+  console.log('Model:', metadataEmbedding.model);
+  console.log('Usage:', metadataEmbedding.usage);
+  console.log('Embedding dimensions:', metadataEmbedding.data[0]?.embedding.length);
+  console.log(' Embeddings tracked with metadata for business analytics\n');
+}
+
+// Run the example
+openaiBasicExample().catch(console.error);

package/examples/openai-function-calling.ts

@@ -0,0 +1,259 @@
+/**
+ * OpenAI Function Calling Example
+ *
+ * Demonstrates how Revenium middleware seamlessly tracks function/tool calling usage
+ * with OpenAI chat completions. Shows automatic tracking of:
+ * - Function definitions and calls
+ * - Token usage including function call overhead
+ * - Multi-turn conversations with function execution
+ * - Cost calculation for function calling features
+ *
+ * All metadata fields are optional and work seamlessly with function calling!
+ *
+ * For complete metadata field reference, see:
+ * https://revenium.readme.io/reference/meter_ai_completion
+ *
+ * OpenAI Function Calling Reference:
+ * https://platform.openai.com/docs/guides/function-calling
+ */
+
+import 'dotenv/config';
+import { initializeReveniumFromEnv, patchOpenAIInstance } from '@revenium/openai';
+import OpenAI from 'openai';
+
+// Simulated weather API function
+function getCurrentWeather(location: string, unit: 'celsius' | 'fahrenheit' = 'celsius'): string {
+  // Simulate weather data
+  const temperature = unit === 'celsius' ? 22 : 72;
+  const conditions = 'sunny';
+
+  return JSON.stringify({
+    location,
+    temperature,
+    unit,
+    conditions,
+    forecast: 'Clear skies throughout the day',
+  });
+}
+
+async function openAIFunctionCallingExample() {
+  console.log('🔧 OpenAI Function Calling with Revenium Tracking\n');
+
+  // Initialize Revenium middleware
+  const initResult = initializeReveniumFromEnv();
+  if (!initResult.success) {
+    console.error('❌ Failed to initialize Revenium:', initResult.message);
+    process.exit(1);
+  }
+
+  // Create and patch OpenAI instance
+  const openai = patchOpenAIInstance(new OpenAI());
+
+  // Define function schema for OpenAI
+  const tools: OpenAI.Chat.Completions.ChatCompletionTool[] = [
+    {
+      type: 'function',
+      function: {
+        name: 'get_current_weather',
+        description: 'Get the current weather in a given location',
+        parameters: {
+          type: 'object',
+          properties: {
+            location: {
+              type: 'string',
+              description: 'The city and state, e.g. San Francisco, CA',
+            },
+            unit: {
+              type: 'string',
+              enum: ['celsius', 'fahrenheit'],
+              description: 'The temperature unit to use',
+            },
+          },
+          required: ['location'],
+        },
+      },
+    },
+  ];
+
+  // Example 1: Function calling without metadata (automatic tracking)
+  console.log('📍 Example 1: Basic function calling (automatic tracking)\n');
+
+  const messages: OpenAI.Chat.Completions.ChatCompletionMessageParam[] = [
+    {
+      role: 'user',
+      content: "What's the weather like in San Francisco?",
+    },
+  ];
+
+  // First call - AI decides to use the function
+  const firstResponse = await openai.chat.completions.create({
+    model: 'gpt-4o-mini',
+    messages: messages,
+    tools: tools,
+    tool_choice: 'auto',
+    // No usageMetadata - still automatically tracked!
+  });
+
+  console.log('AI Response (First call):');
+  console.log('Usage:', firstResponse.usage);
+
+  const firstMessage = firstResponse.choices[0]?.message;
+  console.log('Finish reason:', firstResponse.choices[0]?.finish_reason);
+
+  // Check if AI wants to call a function
+  if (firstMessage?.tool_calls) {
+    console.log('\n🔧 AI decided to call function:', firstMessage.tool_calls[0]?.function.name);
+    console.log('Function arguments:', firstMessage.tool_calls[0]?.function.arguments);
+
+    // Execute the function
+    const functionCall = firstMessage.tool_calls[0];
+    const functionArgs = JSON.parse(functionCall?.function.arguments || '{}');
+    const functionResponse = getCurrentWeather(
+      functionArgs.location,
+      functionArgs.unit
+    );
+
+    console.log('Function result:', functionResponse);
+
+    // Add function call and result to conversation
+    messages.push(firstMessage);
+    messages.push({
+      role: 'tool',
+      tool_call_id: functionCall.id,
+      content: functionResponse,
+    });
+
+    // Second call - AI uses function result to answer
+    const secondResponse = await openai.chat.completions.create({
+      model: 'gpt-4o-mini',
+      messages: messages,
+      tools: tools,
+      // No usageMetadata - still automatically tracked!
+    });
+
+    console.log('\n💬 AI Final Response:');
+    console.log('Content:', secondResponse.choices[0]?.message?.content);
+    console.log('Usage:', secondResponse.usage);
+    console.log('✅ Function calling automatically tracked without metadata\n');
+  }
+
+  // Example 2: Function calling with rich metadata
+  console.log('📊 Example 2: Function calling with comprehensive metadata\n');
+
+  const metadataMessages: OpenAI.Chat.Completions.ChatCompletionMessageParam[] = [
+    {
+      role: 'user',
+      content: "I'm planning a trip. What's the weather in Boston and should I bring a jacket?",
+    },
+  ];
+
+  // First call with metadata
+  const metadataFirstResponse = await openai.chat.completions.create({
+    model: 'gpt-4o',
+    messages: metadataMessages,
+    tools: tools,
+    tool_choice: 'auto',
+
+    // ✨ All metadata fields are optional - perfect for tracking AI agents!
+    usageMetadata: {
+      subscriber: {
+        id: 'travel-user-456',
+        email: 'traveler@company.com',
+        credential: {
+          name: 'api-key',
+          value: 'travel-key-789',
+        },
+      },
+      organizationId: 'travel-agency-corp',
+      productId: 'ai-travel-assistant',
+      subscriptionId: 'sub-pro-travel-123',
+      taskType: 'function-calling-weather',
+      traceId: `func-call-${Date.now()}`,
+      agent: 'weather-assistant-node',
+      responseQualityScore: 0.95,
+    },
+  });
+
+  console.log('AI Response with Metadata (First call):');
+  console.log('Usage:', metadataFirstResponse.usage);
+
+  const metadataFirstMessage = metadataFirstResponse.choices[0]?.message;
+  console.log('Finish reason:', metadataFirstResponse.choices[0]?.finish_reason);
+
+  // Process function calls if any
+  if (metadataFirstMessage?.tool_calls) {
+    console.log('\n🔧 Function calls requested:', metadataFirstMessage.tool_calls.length);
+
+    // Execute each function call
+    for (const toolCall of metadataFirstMessage.tool_calls) {
+      console.log('  - Function:', toolCall.function.name);
+      console.log('    Arguments:', toolCall.function.arguments);
+
+      const functionArgs = JSON.parse(toolCall.function.arguments);
+      const functionResponse = getCurrentWeather(
+        functionArgs.location,
+        functionArgs.unit
+      );
+
+      console.log('    Result:', functionResponse);
+
+      // Add function result to conversation
+      metadataMessages.push(metadataFirstMessage);
+      metadataMessages.push({
+        role: 'tool',
+        tool_call_id: toolCall.id,
+        content: functionResponse,
+      });
+    }
+
+    // Second call with metadata - AI generates final response
+    const metadataSecondResponse = await openai.chat.completions.create({
+      model: 'gpt-4o',
+      messages: metadataMessages,
+      tools: tools,
+
+      // ✨ Same metadata carried through the conversation
+      usageMetadata: {
+        subscriber: {
+          id: 'travel-user-456',
+          email: 'traveler@company.com',
+          credential: {
+            name: 'api-key',
+            value: 'travel-key-789',
+          },
+        },
+        organizationId: 'travel-agency-corp',
+        productId: 'ai-travel-assistant',
+        subscriptionId: 'sub-pro-travel-123',
+        taskType: 'function-calling-weather',
+        traceId: `func-call-${Date.now()}`,
+        agent: 'weather-assistant-node',
+        responseQualityScore: 0.98,
+      },
+    });
+
+    console.log('\n💬 AI Final Response with Metadata:');
+    console.log('Content:', metadataSecondResponse.choices[0]?.message?.content);
+    console.log('Usage:', metadataSecondResponse.usage);
+    console.log('✅ Function calling tracked with rich metadata for AI agent analytics\n');
+  }
+
+  // Summary
+  console.log('📈 Function Calling Summary:');
+  console.log('✅ Function definitions work seamlessly with middleware');
+  console.log('✅ Token usage tracked including function call overhead');
+  console.log('✅ Multi-turn conversations fully supported');
+  console.log('✅ All metadata fields optional and work perfectly');
+  console.log('✅ Cost calculation includes function calling tokens');
+  console.log('✅ No type casting required - native TypeScript support');
+  console.log('✅ Perfect for tracking AI agents and tool usage\n');
+
+  console.log('💡 Use Cases:');
+  console.log('   - AI agents with tool access');
+  console.log('   - Customer support bots with API integrations');
+  console.log('   - Data analysis assistants with function execution');
+  console.log('   - Multi-step workflows with external tools');
+}
+
+// Run the example
+openAIFunctionCallingExample().catch(console.error);

package/examples/openai-responses-basic.ts

@@ -0,0 +1,212 @@
+/**
+ * OpenAI Responses API Basic Examples
+ *
+ * This file demonstrates how to use the new OpenAI Responses API with the Revenium middleware.
+ * The Responses API is a new stateful API that brings together capabilities from chat completions
+ * and assistants API in one unified experience.
+ *
+ * Metadata Options:
+ * - Start with basic usage (no metadata) - tracking works automatically
+ * - Add subscriber info for user tracking
+ * - Include organization/product IDs for business analytics
+ * - Use task type and trace ID for detailed analysis
+ *
+ * For complete metadata field reference, see:
+ * https://revenium.readme.io/reference/meter_ai_completion
+ *
+ * Responses API Reference: https://platform.openai.com/docs/api-reference/responses
+ */
+
+import 'dotenv/config';
+import { initializeReveniumFromEnv, patchOpenAIInstance } from '@revenium/openai';
+import OpenAI from 'openai';
+
+// Import types for the new Responses API
+import type { ResponsesCreateParams, ResponsesResponse } from '../src/types/responses-api.js';
+
+async function main() {
+  // Initialize Revenium middleware
+  await initializeReveniumFromEnv();
+
+  // Create OpenAI client
+  const openai = new OpenAI({
+    apiKey: process.env.OPENAI_API_KEY,
+  });
+
+  // Patch the OpenAI instance to add Revenium tracking
+  patchOpenAIInstance(openai);
+
+  console.log(' OpenAI Responses API Basic Examples\n');
+
+  // Example 1: Basic Responses API call (no metadata)
+  console.log(' Example 1: Basic Responses API call (no metadata)');
+  try {
+    const responsesAPI = openai as any; // Type assertion for new API
+
+    if (responsesAPI.responses?.create) {
+      const response: ResponsesResponse = await responsesAPI.responses.create({
+        model: 'gpt-5',
+        input: 'What is the capital of France?',
+      } as ResponsesCreateParams);
+
+      console.log('Response ID:', response.id);
+      console.log('Model:', response.model);
+      console.log('Status:', response.status);
+      console.log('Output Text:', response.output_text);
+      console.log('Usage:', response.usage);
+    } else {
+      throw new Error('Responses API not available');
+    }
+  } catch (error) {
+    console.log('️ Responses API not yet available in this OpenAI SDK version');
+    console.log('   Error:', (error as Error).message);
+  }
+
+  console.log('\n' + '='.repeat(50) + '\n');
+
+  // Example 2: Responses API with rich metadata
+  console.log(' Example 2: Responses API with rich metadata');
+  try {
+    const responsesAPI = openai as any;
+
+    if (responsesAPI.responses?.create) {
+      const response: ResponsesResponse = await responsesAPI.responses.create({
+        model: 'gpt-5',
+        input: [
+          {
+            role: 'user',
+            content: 'Explain quantum computing in simple terms.',
+          },
+        ],
+        max_output_tokens: 150,
+        usageMetadata: {
+          // User identification
+          subscriber: {
+            id: 'user-123',
+            email: 'user@example.com',
+            credential: {
+              name: 'api-key-prod',
+              value: 'key-efg-123',
+            },
+          },
+
+          // Organization & billing
+          organizationId: 'org-456',
+          subscriptionId: 'plan-responses-2024',
+
+          // Product & task tracking
+          productId: 'quantum-explainer',
+          taskType: 'educational-content',
+          agent: 'quantum-tutor',
+
+          // Session tracking
+          traceId: 'trace-789',
+
+          // Quality metrics
+          responseQualityScore: 0.95,
+        },
+      } as ResponsesCreateParams);
+
+      console.log('Response ID:', response.id);
+      console.log('Model:', response.model);
+      console.log('Status:', response.status);
+      console.log('Output Text:', response.output_text?.substring(0, 100) + '...');
+      console.log('Usage:', response.usage);
+    } else {
+      throw new Error('Responses API not available');
+    }
+  } catch (error) {
+    console.log('️ Responses API not yet available in this OpenAI SDK version');
+    console.log('   Error:', (error as Error).message);
+  }
+
+  console.log('\n' + '='.repeat(50) + '\n');
+
+  // Example 3: Basic Responses API with string input (no metadata)
+  console.log(' Example 3: Basic Responses API with string input (no metadata)');
+  try {
+    const responsesAPI = openai as any;
+
+    if (responsesAPI.responses?.create) {
+      const response: ResponsesResponse = await responsesAPI.responses.create({
+        model: 'gpt-5',
+        input: 'Write a haiku about programming.',
+      } as ResponsesCreateParams);
+
+      console.log('Response ID:', response.id);
+      console.log('Model:', response.model);
+      console.log('Status:', response.status);
+      console.log('Output Text:', response.output_text);
+      console.log('Usage:', response.usage);
+    } else {
+      throw new Error('Responses API not available');
+    }
+  } catch (error) {
+    console.log('️ Responses API not yet available in this OpenAI SDK version');
+    console.log('   Error:', (error as Error).message);
+  }
+
+  console.log('\n' + '='.repeat(50) + '\n');
+
+  // Example 4: Advanced Responses API with comprehensive metadata
+  console.log(' Example 4: Advanced Responses API with comprehensive metadata');
+  try {
+    const responsesAPI = openai as any;
+
+    if (responsesAPI.responses?.create) {
+      const response: ResponsesResponse = await responsesAPI.responses.create({
+        model: 'gpt-5',
+        input: [
+          {
+            role: 'user',
+            content: 'Provide a comprehensive overview of the Responses API capabilities.',
+          },
+        ],
+        max_output_tokens: 200,
+        instructions: 'You are a helpful AI assistant specializing in API documentation.',
+        usageMetadata: {
+          // User identification
+          subscriber: {
+            id: 'enterprise-user-456',
+            email: 'enterprise@company.com',
+            credential: {
+              name: 'api-key-prod',
+              value: 'key-hij-456',
+            },
+          },
+
+          // Organization & billing
+          organizationId: 'enterprise-org-789',
+          subscriptionId: 'plan-enterprise-docs-2024',
+
+          // Product & task tracking
+          productId: 'api-documentation-assistant',
+          taskType: 'technical-documentation',
+          agent: 'documentation-expert',
+
+          // Session tracking
+          traceId: 'enterprise-trace-012',
+
+          // Quality metrics
+          responseQualityScore: 0.98,
+        },
+      } as ResponsesCreateParams);
+
+      console.log('Response ID:', response.id);
+      console.log('Model:', response.model);
+      console.log('Status:', response.status);
+      console.log('Output Text:', response.output_text?.substring(0, 150) + '...');
+      console.log('Usage:', response.usage);
+      console.log('Output Array Length:', response.output?.length);
+    } else {
+      throw new Error('Responses API not available');
+    }
+  } catch (error) {
+    console.log('️ Responses API not yet available in this OpenAI SDK version');
+    console.log('   Error:', (error as Error).message);
+  }
+
+  console.log('\n All Responses API examples completed!');
+}
+
+main().catch(console.error);