@revenium/perplexity 2.0.4 → 2.0.5

package/dist/types/types/function-parameters.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Function Parameter Types
+ *
+ * Comprehensive type definitions for function parameters throughout the middleware.
+ * These interfaces provide type safety by replacing 'any' types with proper,
+ * well-documented interfaces that match Perplexity API structures and internal requirements.
+ *
+ * @fileoverview Type-safe function parameter definitions
+ * @author Revenium
+ * @since 2.0.0
+ */
+import { UsageMetadata } from "./index.js";
+/**
+ * Perplexity API response structure for chat completions
+ *
+ * Represents the complete response structure returned by Perplexity's chat completions API.
+ * Includes usage statistics, response choices, and metadata. Used internally for
+ * processing responses and extracting usage metrics.
+ *
+ * @public
+ */
+export interface PerplexityChatResponse {
+    /** Unique identifier for the chat completion */
+    id: string;
+    /** Model used for the completion */
+    model: string;
+    /** Token usage statistics */
+    usage: {
+        /** Number of tokens in the prompt */
+        prompt_tokens: number;
+        /** Number of tokens in the completion */
+        completion_tokens: number;
+        /** Total tokens used (prompt + completion) */
+        total_tokens: number;
+    };
+    /** Array of completion choices */
+    choices: Array<{
+        /** Reason why the completion finished */
+        finish_reason: string | null;
+        /** Complete message (for non-streaming responses) */
+        message?: {
+            /** Message content */
+            content: string;
+            /** Message role (assistant, user, system) */
+            role: string;
+        };
+        /** Delta message (for streaming responses) */
+        delta?: {
+            /** Incremental content */
+            content?: string;
+            /** Message role */
+            role?: string;
+        };
+    }>;
+    /** Unix timestamp of when the completion was created */
+    created?: number;
+    /** Object type identifier */
+    object?: string;
+}
+/**
+ * Perplexity API request structure for chat completions
+ *
+ * Represents the request parameters sent to Perplexity's chat completions API.
+ * Includes model selection, messages, and optional parameters.
+ *
+ * @public
+ */
+export interface PerplexityChatRequest {
+    /** Model to use for the completion */
+    model: string;
+    /** Array of messages in the conversation */
+    messages: Array<{
+        /** Message role */
+        role: "system" | "user" | "assistant";
+        /** Message content */
+        content: string;
+    }>;
+    /** Maximum number of tokens to generate */
+    max_tokens?: number;
+    /** Temperature for sampling */
+    temperature?: number;
+    /** Top-p for nucleus sampling */
+    top_p?: number;
+    /** Whether to stream the response */
+    stream?: boolean;
+    /** Presence penalty */
+    presence_penalty?: number;
+    /** Frequency penalty */
+    frequency_penalty?: number;
+    /** Usage metadata for Revenium tracking (custom field, not sent to Perplexity) */
+    usageMetadata?: UsageMetadata;
+}
+/**
+ * Perplexity message structure
+ */
+export interface PerplexityMessage {
+    role: "system" | "user" | "assistant";
+    content: string;
+}
+/**
+ * Perplexity cost breakdown (specific to Perplexity API)
+ */
+export interface PerplexityCost {
+    input_tokens_cost: number;
+    output_tokens_cost: number;
+    request_cost: number;
+    total_cost: number;
+}
+/**
+ * Perplexity usage statistics
+ */
+export interface PerplexityUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    search_context_size?: string;
+    cost?: PerplexityCost;
+}
+/**
+ * Perplexity choice structure
+ */
+export interface PerplexityChoice {
+    index: number;
+    message?: {
+        role: string;
+        content: string;
+    };
+    delta?: {
+        role?: string;
+        content?: string;
+    };
+    finish_reason: string | null;
+}
+/**
+ * Perplexity response structure
+ */
+export interface PerplexityResponse {
+    id: string;
+    object: string;
+    created: number;
+    model: string;
+    choices: PerplexityChoice[];
+    usage?: PerplexityUsage;
+}
+/**
+ * Perplexity stream chunk structure
+ */
+export interface PerplexityStreamChunk {
+    id: string;
+    object: string;
+    created: number;
+    model: string;
+    choices: PerplexityChoice[];
+}
+/**
+ * Tracking data structure for usage tracking
+ *
+ * Contains all necessary information for tracking API usage with Revenium.
+ * Used internally by the tracking system.
+ *
+ * @internal
+ */
+export interface TrackingData {
+    /** Unique request identifier */
+    requestId: string;
+    /** Model used for the request */
+    model: string;
+    /** Number of prompt tokens */
+    promptTokens: number;
+    /** Number of completion tokens */
+    completionTokens: number;
+    /** Total number of tokens */
+    totalTokens: number;
+    /** Request duration in milliseconds */
+    duration: number;
+    /** Finish reason from the API */
+    finishReason: string | null;
+    /** Usage metadata */
+    usageMetadata?: UsageMetadata;
+    /** Whether the request was streamed */
+    isStreamed?: boolean;
+    /** Time to first token (for streaming) */
+    timeToFirstToken?: number;
+}
+//# sourceMappingURL=function-parameters.d.ts.map

package/dist/types/types/function-parameters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"function-parameters.d.ts","sourceRoot":"","sources":["../../../src/types/function-parameters.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;;;;;GAQG;AACH,MAAM,WAAW,sBAAsB;IACrC,gDAAgD;IAChD,EAAE,EAAE,MAAM,CAAC;IACX,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,6BAA6B;IAC7B,KAAK,EAAE;QACL,qCAAqC;QACrC,aAAa,EAAE,MAAM,CAAC;QACtB,yCAAyC;QACzC,iBAAiB,EAAE,MAAM,CAAC;QAC1B,8CAA8C;QAC9C,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,kCAAkC;IAClC,OAAO,EAAE,KAAK,CAAC;QACb,yCAAyC;QACzC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;QAC7B,qDAAqD;QACrD,OAAO,CAAC,EAAE;YACR,sBAAsB;YACtB,OAAO,EAAE,MAAM,CAAC;YAChB,6CAA6C;YAC7C,IAAI,EAAE,MAAM,CAAC;SACd,CAAC;QACF,8CAA8C;QAC9C,KAAK,CAAC,EAAE;YACN,0BAA0B;YAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;YACjB,mBAAmB;YACnB,IAAI,CAAC,EAAE,MAAM,CAAC;SACf,CAAC;KACH,CAAC,CAAC;IACH,wDAAwD;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6BAA6B;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAqB;IACpC,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,4CAA4C;IAC5C,QAAQ,EAAE,KAAK,CAAC;QACd,mBAAmB;QACnB,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;QACtC,sBAAsB;QACtB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;IACH,2CAA2C;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+BAA+B;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iCAAiC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,uBAAuB;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,wBAAwB;IACxB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,kFAAkF;IAClF,aAAa,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;IACtC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,KAAK,CAAC,EAAE;QACN,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,KAAK,CAAC,EAAE,eAAe,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,gBAAgB,EAAE,CAAC;CAC7B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,gCAAgC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,iCAAiC;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,kCAAkC;IAClC,gBAAgB,EAAE,MAAM,CAAC;IACzB,6BAA6B;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,qBAAqB;IACrB,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,uCAAuC;IACvC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,0CAA0C;IAC1C,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B"}

package/dist/types/types/index.d.ts

@@ -1,151 +1,130 @@
 /**
- * TypeScript Type Definitions for Perplexity Middleware
+ * Core Types Module
+ *
+ * Central type definitions for the Revenium Perplexity middleware.
+ * This module exports all core types used throughout the application.
  */
-export interface PerplexityMessage {
-    role: "system" | "user" | "assistant";
-    content: string;
-}
-export interface PerplexityChatRequest {
-    model: string;
-    messages: PerplexityMessage[];
-    max_tokens?: number;
-    temperature?: number;
-    top_p?: number;
-    stream?: boolean;
-    presence_penalty?: number;
-    frequency_penalty?: number;
-}
-export interface PerplexityUsage {
-    prompt_tokens: number;
-    completion_tokens: number;
-    total_tokens: number;
-}
-export interface PerplexityChoice {
-    index: number;
-    message?: {
-        role: string;
-        content: string;
-    };
-    delta?: {
-        role?: string;
-        content?: string;
-    };
-    finish_reason: string | null;
-}
-export interface PerplexityResponse {
-    id: string;
-    object: string;
-    created: number;
-    model: string;
-    choices: PerplexityChoice[];
-    usage?: PerplexityUsage;
+export * from "./function-parameters.js";
+/**
+ * Credential information for subscriber authentication
+ */
+export interface Credential {
+    /** The name/type of the credential */
+    name: string;
+    /** The credential value */
+    value: string;
 }
-export interface PerplexityStreamChunk {
-    id: string;
-    object: string;
-    created: number;
-    model: string;
-    choices: PerplexityChoice[];
+/**
+ * Subscriber information for Revenium API
+ */
+export interface Subscriber {
+    /** Unique identifier for the subscriber/user */
+    id?: string;
+    /** Email address of the subscriber */
+    email?: string;
+    /** Optional authentication credential for the subscriber */
+    credential?: Credential;
 }
+/**
+ * Usage metadata interface for tracking additional context
+ */
 export interface UsageMetadata {
-    subscriber?: {
-        id: string;
-        email?: string;
-        credential?: {
-            name: string;
-            value: string;
-        };
-    };
+    /** User identification information */
+    subscriber?: Subscriber;
+    /** Organization or company identifier */
     organizationId?: string;
-    subscriptionId?: string;
+    /** Product or application identifier */
     productId?: string;
-    transactionId?: string;
-    traceId?: string;
-    inputTokenCount?: number;
-    outputTokenCount?: number;
-    totalTokenCount?: number;
-    reasoningTokenCount?: number;
-    cacheCreationTokenCount?: number;
-    cacheReadTokenCount?: number;
-    requestTime?: string;
-    responseTime?: string;
-    completionStartTime?: string;
-    timeToFirstToken?: number;
-    operationType?: string;
+    /** Subscription identifier */
+    subscriptionId?: string;
+    /** Task type classification */
     taskType?: string;
-    agent?: string;
-    stopReason?: string;
-    costType?: string;
+    /** Distributed tracing identifier */
+    traceId?: string;
+    /** Quality score for response evaluation (0.0-1.0 scale) */
     responseQualityScore?: number;
-    subscriberId?: string;
-    subscriberEmail?: string;
-    subscriberCredentialName?: string;
-    subscriberCredential?: string;
+    /** Agent or model variant identifier */
+    agent?: string;
 }
 /**
- * Metering data sent to Revenium
- * Field order matches the expected API format
+ * Provider information for tracking API source
  */
-export interface MeteringData {
-    stopReason: string;
-    costType: string;
-    isStreamed: boolean;
-    taskType: string;
-    agent: string;
-    operationType: string;
-    inputTokenCount: number;
-    outputTokenCount: number;
-    reasoningTokenCount: number;
-    cacheCreationTokenCount: number;
-    cacheReadTokenCount: number;
-    totalTokenCount: number;
-    organizationId: string;
-    productId: string;
-    subscriber: {
-        id: string;
-        email: string;
-        credential: {
-            name: string;
-            value: string;
-        };
-    };
+export interface ProviderInfo {
+    /** The detected AI provider type */
+    provider: string;
+    /** Model source identifier */
+    modelSource: string;
+}
+/**
+ * Logger interface aligned with Go implementation
+ */
+export interface Logger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+/**
+ * Revenium configuration interface
+ */
+export interface ReveniumConfig {
+    /** Revenium API key */
+    reveniumApiKey: string;
+    /** Revenium base URL */
+    reveniumBaseUrl: string;
+    /** Perplexity API key */
+    perplexityApiKey?: string;
+    /** Perplexity base URL */
+    perplexityBaseUrl?: string;
+    /** Debug mode flag */
+    debug?: boolean;
+    /** Custom logger */
+    logger?: Logger;
+}
+/**
+ * Configuration interface (alias for backward compatibility)
+ */
+export interface Config extends ReveniumConfig {
+}
+/**
+ * Revenium API payload structure
+ */
+export interface ReveniumPayload {
+    costType: "AI";
     model: string;
-    transactionId: string;
     responseTime: string;
     requestDuration: number;
     provider: string;
+    modelSource: string;
     requestTime: string;
     completionStartTime: string;
-    timeToFirstToken: number;
-    middlewareSource: string;
-    traceId?: string;
-}
-export interface ChatCompletionResult {
-    content: string;
-    role: string;
-    finishReason: string | null;
-    usage: {
-        promptTokens: number;
-        completionTokens: number;
-        totalTokens: number;
-    };
-    model: string;
-    transactionId: string;
-    rawResponse: PerplexityResponse;
-}
-export interface StreamingResult {
-    stream: AsyncGenerator<PerplexityStreamChunk>;
+    inputTokenCount: number;
+    outputTokenCount: number;
+    totalTokenCount: number;
+    reasoningTokenCount?: number;
+    cacheCreationTokenCount?: number;
+    cacheReadTokenCount?: number;
+    organizationId?: string;
+    subscriptionId?: string;
+    productId?: string;
+    subscriber?: Subscriber;
     transactionId: string;
-    model: string;
-}
-export interface ReveniumConfig {
-    meteringApiKey: string;
-    meteringBaseUrl: string;
-    teamId?: string;
-    enabled: boolean;
+    traceId?: string;
+    taskType?: string;
+    operationType: "CHAT" | "EMBED";
+    stopReason: string;
+    isStreamed: boolean;
+    timeToFirstToken?: number;
+    agent?: string;
+    responseQualityScore?: number;
+    middlewareSource: string;
+    inputTokenCost?: number;
+    outputTokenCost?: number;
+    totalCost?: number;
 }
-export interface PerplexityConfig {
-    apiKey: string;
-    baseUrl: string;
+/**
+ * Metering data interface (legacy, for backward compatibility)
+ */
+export interface MeteringData extends ReveniumPayload {
 }
 //# sourceMappingURL=index.d.ts.map

package/dist/types/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/index.ts"],"names":[],"mappings":"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"}

package/dist/types/utils/constants.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Error message patterns for network-related errors
+ */
+export declare const MESSAGE_PATTERNS_TYPE_NETWORK: string[];
+/**
+ * Error message patterns for configuration-related errors
+ */
+export declare const ERROR_MESSAGE_PATTERNS_TYPE_CONFIG: string[];
+//# sourceMappingURL=constants.d.ts.map

package/dist/types/utils/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/utils/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,6BAA6B,UAIzC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kCAAkC,UAI9C,CAAC"}

package/dist/types/utils/error-handler.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Error Handler Utilities
+ *
+ * Centralized error handling patterns to eliminate repetitive try/catch blocks
+ * and provide consistent error logging and recovery strategies.
+ */
+import { Logger } from '../types/index.js';
+/**
+ * Error handling strategy configuration
+ */
+export interface ErrorHandlingStrategy {
+    /** Whether to log the error */
+    logError?: boolean;
+    /** Whether to re-throw the error */
+    rethrow?: boolean;
+    /** Custom error message prefix */
+    messagePrefix?: string;
+    /** Fallback value to return on error */
+    fallbackValue?: unknown;
+    /** Custom error transformation function */
+    transformError?: (error: unknown) => Error;
+}
+/**
+ * Safe async operation wrapper with comprehensive error handling
+ *
+ * @param operation - The async operation to execute
+ * @param context - Context information for logging
+ * @param strategy - Error handling strategy
+ * @param logger - Logger instance
+ * @returns Promise with result or fallback value
+ */
+export declare function safeAsyncOperation<T>(operation: () => Promise<T>, context: string, strategy?: ErrorHandlingStrategy, logger?: Logger): Promise<T | undefined>;
+/**
+ * Safe sync operation wrapper
+ *
+ * @param operation - The sync operation to execute
+ * @param context - Context information for logging
+ * @param strategy - Error handling strategy
+ * @param logger - Logger instance
+ * @returns Result or fallback value
+ */
+export declare function safeSyncOperation<T>(operation: () => T, context: string, strategy?: ErrorHandlingStrategy, logger?: Logger): T | undefined;
+/**
+ * Validation wrapper that provides clear error messages
+ *
+ * @param value - Value to validate
+ * @param validator - Validation function
+ * @param errorMessage - Error message if validation fails
+ * @returns Validated value
+ */
+export declare function validateOrThrow<T>(value: unknown, validator: (value: unknown) => value is T, errorMessage: string): T;
+/**
+ * Validation wrapper that returns undefined on failure
+ *
+ * @param value - Value to validate
+ * @param validator - Validation function
+ * @param logger - Optional logger for warnings
+ * @param context - Context for logging
+ * @returns Validated value or undefined
+ */
+export declare function validateOrUndefined<T>(value: unknown, validator: (value: unknown) => value is T, logger?: Logger, context?: string): T | undefined;
+/**
+ * Create a retry wrapper for operations that might fail temporarily
+ *
+ * @param operation - Operation to retry
+ * @param maxRetries - Maximum number of retries
+ * @param delayMs - Delay between retries in milliseconds
+ * @param logger - Logger for retry attempts
+ * @returns Promise with operation result
+ */
+export declare function withRetry<T>(operation: () => Promise<T>, maxRetries?: number, delayMs?: number, logger?: Logger): Promise<T>;
+/**
+ * Common error types for better error handling
+ */
+export declare class ValidationError extends Error {
+    readonly context?: Record<string, unknown> | undefined;
+    constructor(message: string, context?: Record<string, unknown> | undefined);
+}
+export declare class ConfigurationError extends Error {
+    readonly context?: Record<string, unknown> | undefined;
+    constructor(message: string, context?: Record<string, unknown> | undefined);
+}
+export declare class NetworkError extends Error {
+    readonly context?: Record<string, unknown> | undefined;
+    constructor(message: string, context?: Record<string, unknown> | undefined);
+}
+/**
+ * Error classification utility
+ */
+export declare function classifyError(error: unknown): {
+    type: 'validation' | 'configuration' | 'network' | 'unknown';
+    message: string;
+    isRetryable: boolean;
+};
+//# sourceMappingURL=error-handler.d.ts.map

package/dist/types/utils/error-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.d.ts","sourceRoot":"","sources":["../../../src/utils/error-handler.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAG3C;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,+BAA+B;IAC/B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,oCAAoC;IACpC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,kCAAkC;IAClC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wCAAwC;IACxC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,2CAA2C;IAC3C,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,CAAC;CAC5C;AAaD;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EACxC,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,qBAA0B,EACpC,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAkBxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,SAAS,EAAE,MAAM,CAAC,EAClB,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,qBAA0B,EACpC,MAAM,CAAC,EAAE,MAAM,GACd,CAAC,GAAG,SAAS,CAkBf;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC/B,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,IAAI,CAAC,EACzC,YAAY,EAAE,MAAM,GACnB,CAAC,CAGH;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EACnC,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,IAAI,CAAC,EACzC,MAAM,CAAC,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,GACf,CAAC,GAAG,SAAS,CAQf;AAED;;;;;;;;GAQG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,UAAU,GAAE,MAAU,EACtB,OAAO,GAAE,MAAa,EACtB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,CAAC,CAAC,CAwBZ;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,KAAK;aAGtB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;gBADjD,OAAO,EAAE,MAAM,EACC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YAAA;CAKpD;AAED,qBAAa,kBAAmB,SAAQ,KAAK;aAGzB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;gBADjD,OAAO,EAAE,MAAM,EACC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YAAA;CAKpD;AAED,qBAAa,YAAa,SAAQ,KAAK;aAGnB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;gBADjD,OAAO,EAAE,MAAM,EACC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YAAA;CAKpD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG;IAC7C,IAAI,EAAE,YAAY,GAAG,eAAe,GAAG,SAAS,GAAG,SAAS,CAAC;IAC7D,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;CACtB,CAwBA"}

package/dist/types/utils/metadata-builder.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Metadata Builder Utilities
+ *
+ * Centralized metadata handling to eliminate repetitive spreading
+ * and provide consistent metadata processing across the codebase.
+ */
+import { UsageMetadata } from '../types/index.js';
+/**
+ * Build metadata object for payload inclusion
+ *
+ * This function eliminates the repetitive spreading pattern and provides
+ * a clean, testable way to handle metadata transformation.
+ * Subscriber object is passed through directly without transformation.
+ *
+ * @param usageMetadata - Source metadata from request
+ * @returns Clean metadata object for payload
+ */
+export declare function buildMetadataFields(usageMetadata?: UsageMetadata): Record<string, unknown>;
+/**
+ * Validate metadata completeness for specific use cases
+ *
+ * @param usageMetadata - Metadata to validate
+ * @param requiredFields - List of required field names
+ * @returns Validation result
+ */
+export declare function validateMetadata(usageMetadata?: UsageMetadata, requiredFields?: (keyof UsageMetadata)[]): {
+    isValid: boolean;
+    missingFields: string[];
+    warnings: string[];
+};
+/**
+ * Merge multiple metadata sources with priority
+ *
+ * @param sources - Metadata sources in priority order (first wins)
+ * @returns Merged metadata object
+ */
+export declare function mergeMetadata(...sources: (UsageMetadata | undefined)[]): UsageMetadata;
+/**
+ * Extract metadata from request parameters safely
+ *
+ * @param params - Request parameters that might contain usageMetadata
+ * @returns Extracted metadata and cleaned parameters
+ */
+export declare function extractMetadata<T extends Record<string, unknown>>(params: T & {
+    usageMetadata?: UsageMetadata;
+}): {
+    metadata: UsageMetadata | undefined;
+    cleanParams: Omit<T, 'usageMetadata'>;
+};
+/**
+ * Create a metadata context for consistent logging
+ * Uses sanitization to protect PII (emails are masked)
+ *
+ * @param usageMetadata - Source metadata
+ * @returns Logging context object with sanitized PII
+ */
+export declare function createLoggingContext(usageMetadata?: UsageMetadata): Record<string, unknown>;
+/**
+ * Sanitize metadata for logging (remove sensitive fields)
+ *
+ * @param usageMetadata - Source metadata
+ * @returns Sanitized metadata safe for logging
+ */
+export declare function sanitizeMetadataForLogging(usageMetadata?: UsageMetadata): Record<string, unknown>;
+//# sourceMappingURL=metadata-builder.d.ts.map

package/dist/types/utils/metadata-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata-builder.d.ts","sourceRoot":"","sources":["../../../src/utils/metadata-builder.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,aAAa,EAAc,MAAM,mBAAmB,CAAC;AAuC9D;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,aAAa,CAAC,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAoB1F;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,aAAa,CAAC,EAAE,aAAa,EAC7B,cAAc,GAAE,CAAC,MAAM,aAAa,CAAC,EAAO,GAC3C;IACD,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAqCA;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,OAAO,EAAE,CAAC,aAAa,GAAG,SAAS,CAAC,EAAE,GAAG,aAAa,CAQtF;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/D,MAAM,EAAE,CAAC,GAAG;IAAE,aAAa,CAAC,EAAE,aAAa,CAAA;CAAE,GAC5C;IACD,QAAQ,EAAE,aAAa,GAAG,SAAS,CAAC;IACpC,WAAW,EAAE,IAAI,CAAC,CAAC,EAAE,eAAe,CAAC,CAAC;CACvC,CAMA;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,aAAa,CAAC,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAgB3F;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,aAAa,CAAC,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA8BjG"}