@revenium/openai 1.0.9 → 1.0.11

package/examples/openai-basic.ts

@@ -0,0 +1,125 @@
+/**
+ * OpenAI Basic Example
+ *
+ * Shows how to use Revenium middleware with OpenAI chat completions and embeddings.
+ * Demonstrates seamless metadata integration - all metadata fields are optional!
+ */
+
+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.' },
+    ],
+
+    //  All metadata fields are optional - add what you need!
+    // Note: Nested subscriber structure matches Python middleware for consistency
+    usageMetadata: {
+      // User tracking (optional) - nested subscriber object
+      subscriber: {
+        id: 'user-12345',
+        email: 'developer@company.com',
+        credential: {
+          name: 'api-key',
+          value: 'key123',
+        },
+      },
+
+      // Business context (optional)
+      organizationId: 'my-customer',
+      productId: 'ai-assistant',
+
+      // Task classification (optional)
+      taskType: 'explanation-request',
+      traceId: `session-${Date.now()}`,
+
+      // Custom fields (optional)
+      agent: 'openai-basic-chat-node',
+    },
+  });
+
+  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',
+
+    //  All metadata fields are optional - customize for your use case!
+    // Note: Nested subscriber structure for consistency across language implementations
+    usageMetadata: {
+      subscriber: {
+        id: 'embedding-user-789',
+        email: 'embeddings@company.com',
+        credential: {
+          name: 'embed-key',
+          value: 'embed123',
+        },
+      },
+      organizationId: 'my-company',
+      taskType: 'document-embedding',
+      productId: 'search-engine',
+      traceId: `embed-${Date.now()}`,
+      agent: 'openai-basic-embeddings-node',
+    },
+  });
+
+  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-responses-basic.ts

@@ -0,0 +1,183 @@
+/**
+ * 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.
+ *
+ * Reference: https://learn.microsoft.com/en-us/azure/ai-foundry/openai/how-to/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: {
+          subscriber: {
+            id: 'user-123',
+            email: 'user@example.com',
+            credential: {
+              name: 'api-key',
+              value: 'sk-...',
+            },
+          },
+          organizationId: 'org-456',
+          productId: 'quantum-explainer',
+          taskType: 'educational-content',
+          traceId: 'trace-789',
+          agent: 'quantum-tutor',
+          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: {
+          subscriber: {
+            id: 'enterprise-user-456',
+            email: 'enterprise@company.com',
+            credential: {
+              name: 'enterprise-key',
+              value: 'sk-enterprise-...',
+            },
+          },
+          organizationId: 'enterprise-org-789',
+          productId: 'api-documentation-assistant',
+          taskType: 'technical-documentation',
+          traceId: 'enterprise-trace-012',
+          agent: 'documentation-expert',
+          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);

package/examples/openai-responses-streaming.ts

@@ -0,0 +1,203 @@
+/**
+ * OpenAI Responses API Streaming Examples
+ *
+ * This file demonstrates how to use the new OpenAI Responses API with streaming enabled
+ * using the Revenium middleware. The Responses API supports streaming for real-time
+ * response generation.
+ *
+ * Reference: https://learn.microsoft.com/en-us/azure/ai-foundry/openai/how-to/responses
+ */
+
+import 'dotenv/config';
+import { initializeReveniumFromEnv, patchOpenAIInstance } from '@revenium/openai';
+import OpenAI from 'openai';
+
+// Import types for the new Responses API
+import type { ResponsesCreateParams } 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 Streaming Examples\n');
+
+  // Example 1: Basic Responses API streaming (no metadata)
+  console.log(' Example 1: Basic Responses API streaming (no metadata)');
+  try {
+    const responsesAPI = openai as any; // Type assertion for new API
+
+    if (responsesAPI.responses?.create) {
+      const stream = await responsesAPI.responses.create({
+        model: 'gpt-5',
+        input: 'Tell me a short story about a robot learning to paint.',
+        stream: true,
+      } as ResponsesCreateParams);
+
+      console.log('Streaming response:');
+      for await (const event of stream) {
+        if (event.type === 'response.output_text.delta') {
+          process.stdout.write(event.delta);
+        }
+      }
+      console.log('\n Stream completed');
+    } 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 streaming with rich metadata
+  console.log(' Example 2: Responses API streaming with rich metadata');
+  try {
+    const responsesAPI = openai as any;
+
+    if (responsesAPI.responses?.create) {
+      const stream = await responsesAPI.responses.create({
+        model: 'gpt-5',
+        input: [
+          {
+            role: 'user',
+            content: 'Explain the concept of machine learning in a conversational way.',
+          },
+        ],
+        stream: true,
+        max_output_tokens: 200,
+        usageMetadata: {
+          subscriber: {
+            id: 'streaming-user-123',
+            email: 'streaming@example.com',
+            credential: {
+              name: 'streaming-key',
+              value: 'sk-streaming-...',
+            },
+          },
+          organizationId: 'streaming-org-456',
+          productId: 'ml-educator',
+          taskType: 'educational-streaming',
+          traceId: 'stream-trace-789',
+          agent: 'ml-tutor-stream',
+          responseQualityScore: 0.92,
+        },
+      } as ResponsesCreateParams);
+
+      console.log('Streaming response with metadata:');
+      for await (const event of stream) {
+        if (event.type === 'response.output_text.delta') {
+          process.stdout.write(event.delta);
+        }
+      }
+      console.log('\n Stream with metadata completed');
+    } 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 streaming with array input (no metadata)
+  console.log(' Example 3: Basic Responses API streaming with array input (no metadata)');
+  try {
+    const responsesAPI = openai as any;
+
+    if (responsesAPI.responses?.create) {
+      const stream = await responsesAPI.responses.create({
+        model: 'gpt-5',
+        input: [
+          {
+            role: 'user',
+            content: 'Write a poem about the beauty of code.',
+          },
+        ],
+        stream: true,
+      } as ResponsesCreateParams);
+
+      console.log('Streaming poetry:');
+      for await (const event of stream) {
+        if (event.type === 'response.output_text.delta') {
+          process.stdout.write(event.delta);
+        }
+      }
+      console.log('\n Poetry stream completed');
+    } 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 streaming with comprehensive metadata
+  console.log(' Example 4: Advanced Responses API streaming with comprehensive metadata');
+  try {
+    const responsesAPI = openai as any;
+
+    if (responsesAPI.responses?.create) {
+      const stream = await responsesAPI.responses.create({
+        model: 'gpt-5',
+        input: [
+          {
+            role: 'user',
+            content:
+              'Provide a detailed explanation of how streaming APIs work in real-time applications.',
+          },
+        ],
+        stream: true,
+        max_output_tokens: 300,
+        instructions:
+          'You are a technical expert explaining streaming APIs with practical examples.',
+        usageMetadata: {
+          subscriber: {
+            id: 'advanced-streaming-user-789',
+            email: 'advanced@enterprise.com',
+            credential: {
+              name: 'enterprise-streaming-key',
+              value: 'sk-enterprise-streaming-...',
+            },
+          },
+          organizationId: 'enterprise-streaming-org-012',
+          productId: 'streaming-api-educator',
+          taskType: 'advanced-technical-streaming',
+          traceId: 'advanced-stream-trace-345',
+          agent: 'streaming-expert',
+          responseQualityScore: 0.97,
+        },
+      } as ResponsesCreateParams);
+
+      console.log('Advanced streaming response:');
+      let deltaCount = 0;
+      for await (const event of stream) {
+        if (event.type === 'response.output_text.delta') {
+          process.stdout.write(event.delta);
+          deltaCount++;
+        }
+      }
+      console.log(`\n Advanced stream completed (${deltaCount} delta events)`);
+    } 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 streaming examples completed!');
+}
+
+main().catch(console.error);

package/examples/openai-streaming.ts

@@ -0,0 +1,161 @@
+/**
+ *  OpenAI Streaming Example
+ *
+ * Shows how to use Revenium middleware with streaming OpenAI responses and batch embeddings.
+ * Demonstrates seamless metadata integration with streaming - all metadata fields are optional!
+ */
+
+import 'dotenv/config';
+import { initializeReveniumFromEnv, patchOpenAIInstance } from '@revenium/openai';
+import OpenAI from 'openai';
+
+async function openaiStreamingExample() {
+  console.log(' OpenAI Streaming 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 streaming (no metadata)
+  console.log(' Example 1: Basic streaming chat (automatic tracking)');
+  console.log(' Assistant: ');
+
+  const basicStream = await openai.chat.completions.create({
+    model: 'gpt-4o-mini',
+    messages: [{ role: 'user', content: 'Count from 1 to 5 slowly' }],
+    stream: true,
+    // No usageMetadata - still automatically tracked when stream completes!
+    // No max_tokens - let response complete naturally
+  });
+
+  for await (const chunk of basicStream) {
+    const content = chunk.choices[0]?.delta?.content || '';
+    if (content) {
+      process.stdout.write(content);
+    }
+  }
+
+  console.log('\n Streaming automatically tracked to Revenium without metadata\n');
+
+  // Example 2: Streaming with rich metadata (all optional!)
+  console.log(' Example 2: Streaming chat with rich metadata');
+  console.log(' Assistant: ');
+
+  const metadataStream = await openai.chat.completions.create({
+    model: 'gpt-4o-mini',
+    messages: [{ role: 'user', content: 'Write a haiku about middleware' }],
+    stream: true,
+
+    //  All metadata fields are optional - add what you need for analytics!
+    // Note: Nested subscriber structure matches Python middleware implementation
+    usageMetadata: {
+      // User tracking (optional) - nested subscriber object
+      subscriber: {
+        id: 'streaming-user-456',
+        email: 'poet@company.com',
+        credential: {
+          name: 'stream-key',
+          value: 'stream456',
+        },
+      },
+
+      // Business context (optional)
+      organizationId: 'creative-company',
+      productId: 'ai-poet',
+
+      // Task classification (optional)
+      taskType: 'creative-writing',
+      traceId: `stream-${Date.now()}`,
+
+      // Custom fields (optional)
+      agent: 'openai-streaming-chat-metadata-node',
+      responseQualityScore: 0.9,
+    },
+  });
+
+  for await (const chunk of metadataStream) {
+    const content = chunk.choices[0]?.delta?.content || '';
+    if (content) {
+      process.stdout.write(content);
+    }
+  }
+
+  console.log('\n Streaming tracked with rich metadata for analytics\n');
+
+  // Example 3: Batch embeddings (no metadata)
+  console.log(' Example 3: Batch embeddings (automatic tracking)');
+
+  const batchEmbeddings = await openai.embeddings.create({
+    model: 'text-embedding-3-small',
+    input: [
+      'First document for batch processing',
+      'Second document for batch processing',
+      'Third document for batch processing',
+    ],
+    // No usageMetadata - still automatically tracked!
+  });
+
+  console.log(' Model:', batchEmbeddings.model);
+  console.log(' Usage:', batchEmbeddings.usage);
+  console.log(' Embeddings count:', batchEmbeddings.data.length);
+  console.log(' Batch embeddings automatically tracked without metadata\n');
+
+  // Example 4: Embeddings with metadata for batch processing
+  console.log(' Example 4: Batch embeddings with metadata');
+
+  const metadataBatchEmbeddings = await openai.embeddings.create({
+    model: 'text-embedding-3-small',
+    input: [
+      'Document 1: Streaming responses provide real-time feedback',
+      'Document 2: Metadata enables rich business analytics',
+      'Document 3: Batch processing improves efficiency',
+    ],
+
+    //  All metadata fields are optional - perfect for batch operations!
+    usageMetadata: {
+      // User tracking (optional) - nested subscriber object
+      subscriber: {
+        id: 'batch-processor-123',
+        email: 'batch@data-company.com',
+        credential: {
+          name: 'batch-key',
+          value: 'batch-value-456',
+        },
+      },
+
+      // Business context (optional)
+      organizationId: 'data-company',
+      productId: 'document-search',
+
+      // Task classification (optional)
+      taskType: 'batch-document-embedding',
+      traceId: `batch-${Date.now()}`,
+
+      // Custom fields (optional)
+      agent: 'openai-batch-embeddings-metadata-node',
+    },
+  });
+
+  console.log(' Model:', metadataBatchEmbeddings.model);
+  console.log(' Usage:', metadataBatchEmbeddings.usage);
+  console.log(' Embeddings count:', metadataBatchEmbeddings.data.length);
+  console.log(' Batch embeddings tracked with metadata for business insights\n');
+
+  // Summary
+  console.log(' Summary:');
+  console.log(' Streaming responses work seamlessly with metadata');
+  console.log(' Usage tracked automatically when streams complete');
+  console.log(' Batch embeddings supported with optional metadata');
+  console.log(' All metadata fields are optional');
+  console.log(' No type casting required - native TypeScript support');
+  console.log(' Real-time streaming + comprehensive analytics');
+}
+
+// Run the example
+openaiStreamingExample().catch(console.error);