@revenium/openai 1.0.11 → 1.0.12

package/examples/openai-vision.ts

@@ -0,0 +1,289 @@
+/**
+ * OpenAI Vision Example
+ *
+ * Demonstrates how Revenium middleware seamlessly tracks GPT-4o vision API usage
+ * with multimodal inputs (text + images). Shows automatic tracking of:
+ * - Vision API calls with image URLs
+ * - Token usage including image processing tokens
+ * - Cost calculation for vision features
+ * - Different image detail levels (low, high, auto)
+ *
+ * All metadata fields are optional and work seamlessly with vision API!
+ *
+ * For complete metadata field reference, see:
+ * https://revenium.readme.io/reference/meter_ai_completion
+ *
+ * OpenAI Vision API Reference:
+ * https://platform.openai.com/docs/guides/vision
+ */
+
+import 'dotenv/config';
+import { initializeReveniumFromEnv, patchOpenAIInstance } from '@revenium/openai';
+import OpenAI from 'openai';
+
+async function openAIVisionExample() {
+  console.log('🖼️  OpenAI Vision API 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());
+
+  // Sample image URLs for demonstration
+  const imageUrl = 'https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg';
+
+  // Example 1: Basic vision request without metadata (automatic tracking)
+  console.log('📸 Example 1: Basic vision analysis (automatic tracking)\n');
+
+  const basicVisionResponse = await openai.chat.completions.create({
+    model: 'gpt-4o-mini',
+    messages: [
+      {
+        role: 'user',
+        content: [
+          {
+            type: 'text',
+            text: 'What is in this image? Describe it in one sentence.',
+          },
+          {
+            type: 'image_url',
+            image_url: {
+              url: imageUrl,
+            },
+          },
+        ],
+      },
+    ],
+    max_tokens: 300,
+    // No usageMetadata - still automatically tracked!
+  });
+
+  console.log('AI Response:', basicVisionResponse.choices[0]?.message?.content);
+  console.log('Usage:', basicVisionResponse.usage);
+  console.log('✅ Vision API automatically tracked without metadata\n');
+
+  // Example 2: Vision with detailed image analysis and metadata
+  console.log('🔍 Example 2: High-detail vision analysis with comprehensive metadata\n');
+
+  const detailedVisionResponse = await openai.chat.completions.create({
+    model: 'gpt-4o',
+    messages: [
+      {
+        role: 'user',
+        content: [
+          {
+            type: 'text',
+            text: 'Please analyze this image in detail. Describe the scene, colors, composition, and any notable features.',
+          },
+          {
+            type: 'image_url',
+            image_url: {
+              url: imageUrl,
+              detail: 'high', // High detail for better analysis (costs more tokens)
+            },
+          },
+        ],
+      },
+    ],
+    max_tokens: 500,
+
+    // ✨ All metadata fields are optional - perfect for tracking vision AI!
+    usageMetadata: {
+      subscriber: {
+        id: 'vision-user-123',
+        email: 'vision@company.com',
+        credential: {
+          name: 'api-key',
+          value: 'vision-key-456',
+        },
+      },
+      organizationId: 'image-analysis-corp',
+      productId: 'ai-vision-platform',
+      subscriptionId: 'sub-vision-pro-789',
+      taskType: 'image-analysis-detailed',
+      traceId: `vision-${Date.now()}`,
+      agent: 'vision-analyzer-node',
+      responseQualityScore: 0.96,
+    },
+  });
+
+  console.log('AI Detailed Analysis:', detailedVisionResponse.choices[0]?.message?.content);
+  console.log('Usage:', detailedVisionResponse.usage);
+  console.log('✅ Vision API tracked with rich metadata for image analytics\n');
+
+  // Example 3: Multiple images in one request
+  console.log('🖼️ 🖼️  Example 3: Multiple images with low-detail mode\n');
+
+  const multiImageResponse = await openai.chat.completions.create({
+    model: 'gpt-4o-mini',
+    messages: [
+      {
+        role: 'user',
+        content: [
+          {
+            type: 'text',
+            text: 'Compare these two images. What do they have in common?',
+          },
+          {
+            type: 'image_url',
+            image_url: {
+              url: imageUrl,
+              detail: 'low', // Low detail for cost-effective processing
+            },
+          },
+          {
+            type: 'image_url',
+            image_url: {
+              url: 'https://upload.wikimedia.org/wikipedia/commons/thumb/3/3f/Placeholder_view_vector.svg/310px-Placeholder_view_vector.svg.png',
+              detail: 'low',
+            },
+          },
+        ],
+      },
+    ],
+    max_tokens: 300,
+
+    // ✨ Tracking multi-image requests
+    usageMetadata: {
+      subscriber: {
+        id: 'multi-vision-user-789',
+        email: 'multi@company.com',
+        credential: {
+          name: 'api-key',
+          value: 'multi-key-999',
+        },
+      },
+      organizationId: 'comparison-ai-corp',
+      productId: 'image-comparison-tool',
+      subscriptionId: 'sub-comparison-basic-456',
+      taskType: 'multi-image-comparison',
+      traceId: `multi-vision-${Date.now()}`,
+      agent: 'comparison-analyzer-node',
+      responseQualityScore: 0.88,
+    },
+  });
+
+  console.log('AI Comparison:', multiImageResponse.choices[0]?.message?.content);
+  console.log('Usage:', multiImageResponse.usage);
+  console.log('✅ Multiple images tracked with metadata for comparison analytics\n');
+
+  // Example 4: Vision with conversation context
+  console.log('💬 Example 4: Vision with multi-turn conversation\n');
+
+  const conversationMessages: OpenAI.Chat.Completions.ChatCompletionMessageParam[] = [
+    {
+      role: 'user',
+      content: [
+        {
+          type: 'text',
+          text: 'What colors are prominent in this image?',
+        },
+        {
+          type: 'image_url',
+          image_url: {
+            url: imageUrl,
+            detail: 'auto', // Auto detail - OpenAI decides optimal level
+          },
+        },
+      ],
+    },
+  ];
+
+  const firstTurnResponse = await openai.chat.completions.create({
+    model: 'gpt-4o-mini',
+    messages: conversationMessages,
+    max_tokens: 200,
+
+    usageMetadata: {
+      subscriber: {
+        id: 'conversation-user-456',
+        email: 'conversation@company.com',
+        credential: {
+          name: 'api-key',
+          value: 'conv-key-123',
+        },
+      },
+      organizationId: 'chat-vision-corp',
+      productId: 'interactive-vision-assistant',
+      subscriptionId: 'sub-interactive-premium-321',
+      taskType: 'conversational-vision',
+      traceId: `conv-vision-${Date.now()}`,
+      agent: 'conversation-vision-node',
+    },
+  });
+
+  console.log('First Turn - AI:', firstTurnResponse.choices[0]?.message?.content);
+  console.log('Usage:', firstTurnResponse.usage);
+
+  // Add AI response to conversation
+  conversationMessages.push({
+    role: 'assistant',
+    content: firstTurnResponse.choices[0]?.message?.content || '',
+  });
+
+  // Follow-up question without image
+  conversationMessages.push({
+    role: 'user',
+    content: 'Based on those colors, what mood does the image convey?',
+  });
+
+  const secondTurnResponse = await openai.chat.completions.create({
+    model: 'gpt-4o-mini',
+    messages: conversationMessages,
+    max_tokens: 200,
+
+    usageMetadata: {
+      subscriber: {
+        id: 'conversation-user-456',
+        email: 'conversation@company.com',
+        credential: {
+          name: 'api-key',
+          value: 'conv-key-123',
+        },
+      },
+      organizationId: 'chat-vision-corp',
+      productId: 'interactive-vision-assistant',
+      subscriptionId: 'sub-interactive-premium-321',
+      taskType: 'conversational-vision-followup',
+      traceId: `conv-vision-${Date.now()}`,
+      agent: 'conversation-vision-node',
+    },
+  });
+
+  console.log('Second Turn - AI:', secondTurnResponse.choices[0]?.message?.content);
+  console.log('Usage:', secondTurnResponse.usage);
+  console.log('✅ Multi-turn vision conversation fully tracked\n');
+
+  // Summary
+  console.log('📈 Vision API Summary:');
+  console.log('✅ Image analysis with URLs fully supported');
+  console.log('✅ Token usage tracked including image processing tokens');
+  console.log('✅ Multiple images in one request work seamlessly');
+  console.log('✅ Detail levels (low, high, auto) all supported');
+  console.log('✅ Multi-turn conversations with image context tracked');
+  console.log('✅ All metadata fields optional and work perfectly');
+  console.log('✅ Cost calculation includes vision-specific tokens');
+  console.log('✅ No type casting required - native TypeScript support\n');
+
+  console.log('💡 Use Cases:');
+  console.log('   - Image content moderation and analysis');
+  console.log('   - Product catalog image descriptions');
+  console.log('   - Document and diagram understanding');
+  console.log('   - Visual question answering systems');
+  console.log('   - Accessibility tools (image descriptions)');
+  console.log('   - Quality control and inspection automation\n');
+
+  console.log('💰 Cost Optimization Tips:');
+  console.log('   - Use "low" detail for simple images to save tokens');
+  console.log('   - Use "high" detail only when fine details matter');
+  console.log('   - Use "auto" to let OpenAI optimize automatically');
+  console.log('   - Revenium tracks all token usage for accurate cost analytics');
+}
+
+// Run the example
+openAIVisionExample().catch(console.error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@revenium/openai",
-  "version": "1.0.11",
+  "version": "1.0.12",
   "description": "Transparent TypeScript middleware for automatic Revenium usage tracking with OpenAI",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -25,10 +25,6 @@
     "dev": "tsc --watch",
     "clean": "node -e \"const fs = require('fs'); if (fs.existsSync('dist')) fs.rmSync('dist', {recursive: true, force: true})\"",
     "prepublishOnly": "npm run clean && npm run build",
-    "lint": "eslint src/**/*.ts",
-    "lint:fix": "eslint src/**/*.ts --fix",
-    "format": "prettier --write src/**/*.ts",
-    "format:check": "prettier --check src/**/*.ts",
     "example:openai-basic": "npm run build && npx ts-node examples/openai-basic.ts",
     "example:openai-streaming": "npm run build && npx ts-node examples/openai-streaming.ts",
     "example:azure-basic": "npm run build && npx ts-node examples/azure-basic.ts",
@@ -61,11 +57,7 @@
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
-    "@typescript-eslint/eslint-plugin": "^6.21.0",
-    "@typescript-eslint/parser": "^6.21.0",
     "dotenv": "^16.5.0",
-    "eslint": "^8.0.0",
-    "prettier": "^3.0.0",
     "rimraf": "^6.0.1",
     "ts-node": "^10.9.2",
     "tsx": "^4.20.6",
@@ -76,7 +68,9 @@
   },
   "files": [
     "dist/**/*",
+    "src/**/*",
     "examples/**/*",
+    ".env.example",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"

package/src/core/config/azure-config.ts

@@ -0,0 +1,72 @@
+/**
+ * Azure Configuration Module
+ *
+ * Handles Azure-specific configuration logic.
+ * Extracted from provider.ts for better separation of concerns.
+ */
+
+import { AzureConfig } from '../../types/index.js';
+import { OpenAIClientInstance } from '../../types/function-parameters.js';
+import { getLogger } from './manager.js';
+
+// Global logger
+const logger = getLogger();
+
+/**
+ * Gather Azure configuration from client and environment
+ *
+ * @param client - OpenAI/AzureOpenAI client instance
+ * @returns AzureConfig object
+ */
+export function gatherAzureConfig(client: OpenAIClientInstance): AzureConfig {
+  const config: AzureConfig = {};
+  try {
+    // Extract from client baseURL if available
+    if (client?.baseURL) {
+      const baseUrl =
+        typeof client.baseURL === 'string' ? client.baseURL : client.baseURL?.toString();
+      config.endpoint = baseUrl;
+    }
+
+    // Extract from environment variables
+    if (process.env.AZURE_OPENAI_ENDPOINT) {
+      config.endpoint = process.env.AZURE_OPENAI_ENDPOINT;
+    }
+
+    if (process.env.AZURE_OPENAI_DEPLOYMENT) {
+      config.deployment = process.env.AZURE_OPENAI_DEPLOYMENT;
+    }
+
+    if (process.env.AZURE_OPENAI_API_VERSION) {
+      config.apiVersion = process.env.AZURE_OPENAI_API_VERSION;
+    } else {
+      // Default to preferred API version from Python learnings
+      config.apiVersion = '2024-12-01-preview';
+    }
+
+    if (process.env.AZURE_OPENAI_API_KEY) {
+      config.apiKey = process.env.AZURE_OPENAI_API_KEY;
+    }
+
+    if (process.env.AZURE_OPENAI_TENANT_ID) {
+      config.tenantId = process.env.AZURE_OPENAI_TENANT_ID;
+    }
+
+    if (process.env.AZURE_OPENAI_RESOURCE_GROUP) {
+      config.resourceGroup = process.env.AZURE_OPENAI_RESOURCE_GROUP;
+    }
+
+    logger.debug('Azure configuration gathered', {
+      hasEndpoint: !!config.endpoint,
+      hasDeployment: !!config.deployment,
+      hasApiKey: !!config.apiKey,
+      apiVersion: config.apiVersion,
+    });
+  } catch (error) {
+    logger.warn('Error gathering Azure configuration', {
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+
+  return config;
+}

package/src/core/config/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Configuration module - Main exports
+ *
+ * This module provides a clean interface for configuration management,
+ * separating concerns into focused sub-modules.
+ */
+
+// Re-export all configuration functionality
+export { loadConfigFromEnv, loadAzureConfigFromEnv, hasAzureConfigInEnv } from './loader.js';
+
+export { validateConfig, validateAzureConfig } from './validator.js';
+
+export {
+  getConfig,
+  setConfig,
+  getLogger,
+  setLogger,
+  initializeConfig,
+  defaultLogger,
+} from './manager.js';
+
+// Export Azure-specific configuration
+export * from './azure-config.js';

package/src/core/config/loader.ts

@@ -0,0 +1,66 @@
+/**
+ * Configuration Loader Module
+ *
+ * Handles loading configuration from environment variables.
+ * Separated from validation and management for single responsibility.
+ */
+
+import { ReveniumConfig, AzureConfig } from '../../types/index.js';
+
+/**
+ * Default Revenium base URL for consistency with other middleware
+ */
+const DEFAULT_REVENIUM_BASE_URL = 'https://api.revenium.io';
+
+/**
+ * Load configuration from environment variables
+ */
+export function loadConfigFromEnv(): ReveniumConfig | null {
+  const reveniumApiKey = process.env.REVENIUM_METERING_API_KEY || process.env.REVENIUM_API_KEY;
+  const reveniumBaseUrl =
+    process.env.REVENIUM_METERING_BASE_URL ||
+    process.env.REVENIUM_BASE_URL ||
+    DEFAULT_REVENIUM_BASE_URL;
+  const openaiApiKey = process.env.OPENAI_API_KEY;
+
+  if (!reveniumApiKey) return null;
+  return {
+    reveniumApiKey,
+    reveniumBaseUrl,
+    openaiApiKey,
+  };
+}
+
+/**
+ * Load Azure configuration from environment variables
+ */
+export function loadAzureConfigFromEnv(): AzureConfig | null {
+  const endpoint = process.env.AZURE_OPENAI_ENDPOINT;
+  const deployment = process.env.AZURE_OPENAI_DEPLOYMENT;
+  const apiVersion = process.env.AZURE_OPENAI_API_VERSION;
+  const apiKey = process.env.AZURE_OPENAI_API_KEY;
+  const tenantId = process.env.AZURE_OPENAI_TENANT_ID;
+  const resourceGroup = process.env.AZURE_OPENAI_RESOURCE_GROUP;
+
+  // Return null if no Azure config is present
+  if (!endpoint && !deployment && !apiKey) return null;
+  return {
+    endpoint,
+    deployment,
+    apiVersion: apiVersion || '2024-12-01-preview', // Default from Python learnings
+    apiKey,
+    tenantId,
+    resourceGroup,
+  };
+}
+
+/**
+ * Check if Azure configuration is available in environment
+ */
+export function hasAzureConfigInEnv(): boolean {
+  return !!(
+    process.env.AZURE_OPENAI_ENDPOINT ||
+    process.env.AZURE_OPENAI_DEPLOYMENT ||
+    process.env.AZURE_OPENAI_API_KEY
+  );
+}

package/src/core/config/manager.ts

@@ -0,0 +1,94 @@
+/**
+ * Configuration Manager Module
+ *
+ * Handles global configuration state management and logging.
+ * Separated from loading and validation for single responsibility.
+ */
+
+import { ReveniumConfig, Logger } from '../../types/index.js';
+import { loadConfigFromEnv, hasAzureConfigInEnv } from './loader.js';
+import { validateConfig } from './validator.js';
+
+/**
+ * Default console logger implementation
+ */
+export const defaultLogger: Logger = {
+  debug: (message: string, ...args: unknown[]) => {
+    if (process.env.REVENIUM_DEBUG === 'true') {
+      console.debug(`[Revenium Debug] ${message}`, ...args);
+    }
+  },
+  info: (message: string, ...args: unknown[]) => {
+    console.info(`[Revenium] ${message}`, ...args);
+  },
+  warn: (message: string, ...args: unknown[]) => {
+    console.warn(`[Revenium Warning] ${message}`, ...args);
+  },
+  error: (message: string, ...args: unknown[]) => {
+    console.error(`[Revenium Error] ${message}`, ...args);
+  },
+};
+
+/**
+ * Global configuration instance
+ */
+let globalConfig: ReveniumConfig | null = null;
+let globalLogger: Logger = defaultLogger;
+
+/**
+ * Get the current global configuration
+ */
+export function getConfig(): ReveniumConfig | null {
+  return globalConfig;
+}
+
+/**
+ * Set the global configuration
+ */
+export function setConfig(config: ReveniumConfig): void {
+  validateConfig(config);
+  globalConfig = config;
+  globalLogger.debug('Revenium configuration updated', {
+    baseUrl: config.reveniumBaseUrl,
+    hasApiKey: !!config.reveniumApiKey,
+    hasOpenAIKey: !!config.openaiApiKey,
+  });
+}
+
+/**
+ * Get the current logger
+ */
+export function getLogger(): Logger {
+  return globalLogger;
+}
+
+/**
+ * Set a custom logger
+ */
+export function setLogger(logger: Logger): void {
+  globalLogger = logger;
+}
+
+/**
+ * Initialize configuration from environment variables
+ */
+export function initializeConfig(): boolean {
+  const envConfig = loadConfigFromEnv();
+  if (envConfig) {
+    try {
+      setConfig(envConfig);
+      globalLogger.debug('Revenium middleware initialized from environment variables');
+
+      // Log Azure config availability for debugging
+      if (hasAzureConfigInEnv()) {
+        globalLogger.debug('Azure OpenAI configuration detected in environment');
+      }
+
+      return true;
+    } catch (error) {
+      globalLogger.error('Failed to initialize Revenium configuration:', error);
+      return false;
+    }
+  }
+  return false;
+}

package/src/core/config/validator.ts

@@ -0,0 +1,89 @@
+/**
+ * Configuration Validator Module
+ *
+ * Handles validation of configuration objects.
+ * Separated from loading and management for single responsibility.
+ */
+
+import { ReveniumConfig, AzureConfig } from '../../types/index.js';
+
+/**
+ * Validate Revenium configuration
+ */
+export function validateConfig(config: ReveniumConfig): void {
+  if (!config.reveniumApiKey) {
+    throw new Error(
+      'Revenium API key is required. Set REVENIUM_METERING_API_KEY environment variable or provide reveniumApiKey in config.'
+    );
+  }
+
+  if (!config.reveniumApiKey.startsWith('hak_')) {
+    throw new Error('Invalid Revenium API key format. Revenium API keys should start with "hak_"');
+  }
+
+  if (!config.reveniumBaseUrl) {
+    throw new Error(
+      'Revenium base URL is missing. This should not happen as a default URL should be provided.'
+    );
+  }
+
+  // Validate URL format
+  try {
+    new URL(config.reveniumBaseUrl);
+  } catch (error) {
+    throw new Error(`Invalid Revenium base URL format: ${config.reveniumBaseUrl}`);
+  }
+}
+
+/**
+ * Validate Azure configuration completeness
+ *
+ * @param config - Azure configuration to validate
+ * @returns validation result with missing fields
+ */
+export function validateAzureConfig(config: AzureConfig): {
+  isValid: boolean;
+  missingFields: string[];
+  warnings: string[];
+} {
+  const missingFields: string[] = [];
+  const warnings: string[] = [];
+
+  // Required fields for basic Azure OpenAI operation
+  if (!config.endpoint) {
+    missingFields.push('endpoint');
+  }
+
+  if (!config.apiKey) {
+    missingFields.push('apiKey');
+  }
+
+  // Optional but recommended fields
+  if (!config.deployment) {
+    warnings.push('deployment name not specified - may need to be included in model parameter');
+  }
+
+  if (!config.apiVersion) {
+    warnings.push('API version not specified - using default 2024-12-01-preview');
+  }
+
+  // Validate endpoint format
+  if (config.endpoint) {
+    try {
+      new URL(config.endpoint);
+      if (!config.endpoint.toLowerCase().includes('azure')) {
+        warnings.push(
+          'endpoint does not contain "azure" - please verify this is an Azure OpenAI endpoint'
+        );
+      }
+    } catch (error) {
+      missingFields.push('valid endpoint URL');
+    }
+  }
+
+  return {
+    isValid: missingFields.length === 0,
+    missingFields,
+    warnings,
+  };
+}