@revenium/openai 1.0.12 → 1.0.13

package/src/index.ts

@@ -6,7 +6,7 @@
  *
  * Environment Variables:
  * REVENIUM_METERING_API_KEY=hak_your_api_key
- * REVENIUM_METERING_BASE_URL=https://api.revenium.io (optional)
+ * REVENIUM_METERING_BASE_URL=https://api.revenium.ai (optional)
  * OPENAI_API_KEY=sk_your_openai_key
  *
  * Simple Usage (auto-initialization):
@@ -77,7 +77,7 @@ export type {
    * ```typescript
    * const config: ReveniumConfig = {
    *   reveniumApiKey: 'hak_your_api_key',
-   *   reveniumBaseUrl: 'https://api.revenium.io',
+   *   reveniumBaseUrl: 'https://api.revenium.ai',
    *   debug: true
    * };
    * ```
@@ -212,7 +212,7 @@ export function initializeRevenium(config: ReveniumConfig): {
     // Apply default base URL if not provided
     const configWithDefaults = {
       ...config,
-      reveniumBaseUrl: config.reveniumBaseUrl || 'https://api.revenium.io',
+      reveniumBaseUrl: config.reveniumBaseUrl || 'https://api.revenium.ai',
     };
 
     validateConfig(configWithDefaults);
@@ -237,6 +237,30 @@ export function initializeRevenium(config: ReveniumConfig): {
   }
 }
 
+/**
+ * Configure Revenium middleware manually
+ * Alias for initializeRevenium() with a more intuitive name
+ *
+ * @param config - Revenium configuration object
+ * @returns Initialization result with success status and message
+ *
+ * @example
+ * ```typescript
+ * import { configure } from '@revenium/openai';
+ *
+ * configure({
+ *   reveniumApiKey: 'hak_your_api_key',
+ *   reveniumBaseUrl: 'https://api.revenium.ai',
+ * });
+ * ```
+ */
+export function configure(config: ReveniumConfig): {
+  success: boolean;
+  message: string;
+} {
+  return initializeRevenium(config);
+}
+
 /**
  * Initialize Revenium middleware from environment variables
  */

package/src/types/index.ts

@@ -80,7 +80,7 @@ export interface Subscriber {
  *   productId: 'chat-assistant',
  *   taskType: 'customer-support',
  *   traceId: 'trace-789',
- *   responseQualityScore: 0.95,
+ *   responseQualityScore: 0.95,  // 0.0-1.0 scale per API spec
  *   agent: 'support-bot-v2'
  * };
  * ```
@@ -98,19 +98,14 @@ export interface UsageMetadata {
 
   /** Task type classification (e.g., 'chat', 'summarization', 'translation') */
   taskType?: string;
-  /** Unique task identifier for request correlation */
-  taskId?: string;
   /** Distributed tracing identifier for request tracking across services */
   traceId?: string;
 
-  /** Quality score for response evaluation (0.0 to 1.0) */
+  /** Quality score for response evaluation (0.0-1.0 scale per API spec) */
   responseQualityScore?: number;
 
   /** Agent or model variant identifier for A/B testing and performance tracking */
   agent?: string;
-
-  /** Allow additional custom fields for extensibility */
-  [key: string]: unknown;
 }
 
 /**
@@ -214,7 +209,7 @@ export interface AzureConfig {
  * ```typescript
  * const config: ReveniumConfig = {
  *   reveniumApiKey: 'hak_your_revenium_api_key',
- *   reveniumBaseUrl: 'https://api.revenium.io',
+ *   reveniumBaseUrl: 'https://api.revenium.ai',
  *   debug: true,
  *   openaiApiKey: process.env.OPENAI_API_KEY
  * };
@@ -223,7 +218,7 @@ export interface AzureConfig {
 export interface ReveniumConfig {
   /** Revenium API key for authentication (required) */
   reveniumApiKey: string;
-  /** Revenium API base URL (optional, defaults to https://api.revenium.io) */
+  /** Revenium API base URL (optional, defaults to https://api.revenium.ai) */
   reveniumBaseUrl?: string;
   /** Enable debug logging (optional, defaults to false) */
   debug?: boolean;
@@ -268,7 +263,7 @@ export interface Logger {
 export interface ReveniumPayload {
   // Core identification
   transactionId: string;
-  operationType: 'CHAT' | 'EMBED';
+  operationType: 'CHAT' | 'GENERATE' | 'EMBED' | 'CLASSIFY' | 'SUMMARIZE' | 'TRANSLATE' | 'OTHER';
   costType: 'AI';
 
   // Model and provider info
@@ -287,14 +282,16 @@ export interface ReveniumPayload {
   inputTokenCount: number;
   outputTokenCount: number;
   totalTokenCount: number;
-  reasoningTokenCount: number;
-  cacheCreationTokenCount: number;
-  cacheReadTokenCount: number;
+  // API Spec: https://revenium.readme.io/reference/meter_ai_completion
+  // "Leave null for models without reasoning capabilities" - NOT in required fields
+  reasoningTokenCount: number | undefined;
+  cacheCreationTokenCount: number | undefined;  // Undefined when provider doesn't report
+  cacheReadTokenCount: number | undefined;      // Undefined when provider doesn't report
 
   // Chat-specific fields
   stopReason: string;
   isStreamed: boolean;
-  timeToFirstToken?: number;
+  timeToFirstToken?: number | undefined;  // Undefined when not tracking TTFB
 
   // Cost information (calculated by backend)
   inputTokenCost?: number;

package/src/types/openai-augmentation.ts

@@ -154,8 +154,7 @@ declare module 'openai/resources/embeddings' {
      *   },
      *   organizationId: 'my-company',
      *   productId: 'vector-search',
-     *   taskType: 'document-indexing',
-     *   taskId: 'batch-index-2024-01'
+     *   taskType: 'document-indexing'
      * }
      * ```
      *

package/src/utils/metadata-builder.ts

@@ -37,7 +37,7 @@ const METADATA_FIELD_MAP: MetadataFieldConfig[] = [
   {
     source: 'responseQualityScore',
     transform: (value: unknown) => {
-      // Ensure quality score is between 0 and 1
+      // Ensure quality score is between 0.0 and 1.0 (API spec requirement)
       if (typeof value === 'number') return Math.max(0, Math.min(1, value));
       return value;
     },
@@ -111,8 +111,10 @@ export function validateMetadata(
     // Check for common issues
     if (usageMetadata.responseQualityScore) {
       const score = usageMetadata.responseQualityScore;
+      // API Spec: https://revenium.readme.io/reference/meter_ai_completion (responseQualityScore)
+      // "typically on a 0.0-1.0 scale"
       if (typeof score !== 'number' || score < 0 || score > 1) {
-        warnings.push('responseQualityScore should be a number between 0 and 1');
+        warnings.push('responseQualityScore should be a number between 0.0 and 1.0');
       }
     }
 
@@ -164,17 +166,23 @@ export function extractMetadata<T extends Record<string, unknown>>(
 
 /**
  * Create a metadata context for consistent logging
+ * Uses sanitization to protect PII (emails are masked)
  *
  * @param usageMetadata - Source metadata
- * @returns Logging context object
+ * @returns Logging context object with sanitized PII
  */
 export function createLoggingContext(usageMetadata?: UsageMetadata): Record<string, unknown> {
   if (!usageMetadata) return {};
+
+  // Use sanitizer to protect PII in logs
+  const sanitized = sanitizeMetadataForLogging(usageMetadata);
+  const sanitizedSubscriber = sanitized.subscriber as { id?: string; email?: string; credential?: unknown };
+
   return {
     traceId: usageMetadata.traceId,
     taskType: usageMetadata.taskType,
     subscriberId: usageMetadata.subscriber?.id,
-    subscriberEmail: usageMetadata.subscriber?.email,
+    subscriberEmail: sanitizedSubscriber?.email,  // ← Now masked: us***@example.com
     organizationId: usageMetadata.organizationId,
     productId: usageMetadata.productId,
     agent: usageMetadata.agent,
@@ -193,18 +201,19 @@ export function sanitizeMetadataForLogging(usageMetadata?: UsageMetadata): Recor
   // Create a copy and handle nested subscriber object
   const { subscriber, ...safeMetadata } = usageMetadata;
 
-  const result = { ...safeMetadata };
+  const result: Record<string, unknown> = { ...safeMetadata };
 
   // Sanitize subscriber object if present
   if (subscriber) {
-    const sanitizedSubscriber: any = {};
+    const sanitizedSubscriber: Record<string, unknown> = {};
 
     if (subscriber.id) {
       sanitizedSubscriber.id = subscriber.id;
     }
 
     if (subscriber.email) {
-      sanitizedSubscriber.email = subscriber.email.replace(/(.{2}).*(@.*)/, '$1***$2');
+      // Mask email: handles single-char emails (a@x.com → a***@x.com)
+      sanitizedSubscriber.email = subscriber.email.replace(/(.{1,2}).*(@.*)/, '$1***$2');
     }
 
     if (subscriber.credential) {

package/src/utils/stop-reason-mapper.ts

@@ -18,8 +18,12 @@ const STOP_REASON_MAP: Record<string, string> = {
   timeout: 'TIMEOUT',
   length: 'TOKEN_LIMIT',
   max_tokens: 'TOKEN_LIMIT',
+  cost_limit: 'COST_LIMIT',
+  completion_limit: 'COMPLETION_LIMIT',
   content_filter: 'ERROR',
   error: 'ERROR',
+  cancelled: 'CANCELLED',
+  canceled: 'CANCELLED',  // Handle both spellings
 
   // Anthropic stop reasons (for consistency across middleware)
   end_turn: 'END',

package/src/utils/url-builder.ts

@@ -15,9 +15,9 @@
  * - If URL has neither → append /meter/v2 and endpoint
  *
  * Examples:
- * - 'https://api.revenium.io' + '/ai/completions' → 'https://api.revenium.io/meter/v2/ai/completions'
- * - 'https://api.revenium.io/meter' + '/ai/completions' → 'https://api.revenium.io/meter/v2/ai/completions'
- * - 'https://api.revenium.io/meter/v2' + '/ai/completions' → 'https://api.revenium.io/meter/v2/ai/completions'
+ * - 'https://api.revenium.ai' + '/ai/completions' → 'https://api.revenium.ai/meter/v2/ai/completions'
+ * - 'https://api.revenium.ai/meter' + '/ai/completions' → 'https://api.revenium.ai/meter/v2/ai/completions'
+ * - 'https://api.revenium.ai/meter/v2' + '/ai/completions' → 'https://api.revenium.ai/meter/v2/ai/completions'
  *
  * @param baseUrl - The base URL from configuration (may include /meter or /meter/v2)
  * @param endpoint - The API endpoint to append (e.g., '/ai/completions')