@retrivora-ai/rag-engine 2.2.9 → 2.3.1

package/dist/{LicenseValidator-CENvo9o2.d.mts → BatchProcessor-7yV-UCHW.d.mts}

@@ -547,38 +547,177 @@ declare class LicenseValidationError extends RetrivoraError {
  */
 declare function wrapError(err: unknown, defaultCode: RetrivoraErrorCode, defaultMessage?: string): RetrivoraError;
 
+/**
+ * Input contract for `LicenseValidator.validate()`.
+ *
+ * At least one source must yield a license key: `licenseKey` field, an
+ * `x-license-key` entry in `headers`, or the process environment variables
+ * (NEXT_PUBLIC_RETRIVORA_LICENSE_KEY / RETRIVORA_LICENSE_KEY).
+ */
 interface LicenseValidationRequest {
+    /** Explicit `rtv_`-prefixed license key passed as a prop (highest priority). */
     licenseKey: string;
+    /** Project ID the caller is running under, checked for license binding match. */
     projectId?: string;
+    /** SDK version reported for minimum-supported-version enforcement (defaults to SDK_VERSION). */
     sdkVersion?: string;
+    /** SDK package identifier sent to server for observability. */
     sdk?: string;
+    /** browser | node — reported for observability only. */
     platform?: string;
+    /** Override base URL of the Retrivora API endpoint. Defaults to env or '/api/retrivora'. */
     retrivoraApiBase?: string;
+    /** Custom headers that may contain `x-license-key` or `Authorization: Bearer`. */
     headers?: Record<string, string>;
 }
+/**
+ * Response contract returned from `LicenseValidator.validate()`.
+ *
+ * Status enumerations are ordered — anything other than ACTIVE means the
+ * widget/chat must be disabled and must not pass server-side handler checks.
+ */
 interface LicenseValidationResponse {
+    /** True only when `licenseStatus` is ACTIVE and SDK version is supported. */
     valid: boolean;
+    /** Lifecycle state of the license record. TERMINATED/SUSPENDED/EXPIRED/REVOKED must block chat. */
     licenseStatus: 'ACTIVE' | 'SUSPENDED' | 'TERMINATED' | 'EXPIRED' | 'REVOKED';
+    /** Minimum SDK version that the server will accept (semver-compare). */
     minimumSupportedVersion: string;
+    /** Latest generally-available SDK version (for upgrade prompts). */
     latestVersion: string;
+    /** True when the SDK version is older than minimumSupportedVersion — UI must force upgrade. */
     forceUpgrade: boolean;
+    /** RFC3339 expiration timestamp or null for perpetual licenses. */
     expiresAt: string | null;
+    /** Human-readable status/reason string, suitable for tooltips/toasts. */
     message: string;
 }
+/**
+ * Client-side orchestrator for license validation.
+ *
+ * Flow:
+ *   1. Resolve the license key (prop → header → env)
+ *   2. Return any fresh (< 5 min old) successful cached result
+ *   3. POST to `{retrivoraApiBase}/v1/license/validate` for server-side DB-backed status
+ *   4. On network or HTTP error, fall back to zero-latency local RSA signature
+ *      verification via `LicenseVerifier.verify()`.
+ *
+ * Caching policy:
+ *   - ONLY successful (valid + ACTIVE + !forceUpgrade) responses are cached
+ *   - Any failed validation immediately purges the cache entry
+ *   - TTL is 5 minutes for success cache to allow TERMINATED/REVOKED status
+ *     changes on the server to propagate quickly.
+ *
+ * Thread safety: Singleton pattern via `getInstance()`. Used by ChatWidget,
+ * useRagChat hook, and the server-side `createLicenseHandler` indirectly through
+ * its own `LicenseVerifier.verify()` path.
+ */
 declare class LicenseValidator {
     private static instance;
     private cache;
     private static readonly SUCCESS_CACHE_TTL_MS;
     private constructor();
+    /** @returns Singleton instance of the validator (shared cache across all consumers). */
     static getInstance(): LicenseValidator;
     /**
-     * Invalidate local validation cache for a license key
+     * Purge entries from the local success cache.
+     *
+     * @param licenseKey - Optional. If provided, only that key's cache entry is
+     *                     removed. If omitted the entire cache is cleared.
+     *                     Callers use this after any 401/403 to ensure the next
+     *                     validate() call re-validates against the server.
      */
     purgeCache(licenseKey?: string): void;
     /**
-     * Validate license status and SDK version against Retrivora License Service
+     * Primary validation entry-point for UI / hook consumers.
+     *
+     * Resolves the license key, consults the local success cache, performs a
+     * server POST for authoritative status, and falls back to local RSA
+     * signature verification if the server can't be reached.
+     *
+     * @throws LicenseValidationError - When no key is provided OR both the
+     *         server call AND the local-RSA fallback report an invalid/expired key.
+     * @throws SDKVersionUnsupportedError - When server reports forceUpgrade=true.
+     * @returns A `LicenseValidationResponse` that the UI can use to enable or
+     *          lock the chat widget.
      */
     validate(request: LicenseValidationRequest): Promise<LicenseValidationResponse>;
 }
 
-export { AuthenticationException as A, decideVisualization as B, type ChatWidgetProps as C, type DocumentUploadProps as D, EmbeddingFailedException as E, type ArchitectureCardProps as F, CarouselRendererStrategy as G, ChartRendererStrategy as H, type IRenderRule as I, type ChatViewportSize as J, DocumentChunker as K, LicenseValidationError as L, type MessageBubbleProps as M, MixedRendererStrategy as N, Pipeline as O, type ProductCardProps as P, type PipelineStep as Q, RateLimitException as R, type SourceCardProps as S, type ProviderPill as T, type RenderSectionDecision as U, VisualizationDecisionEngine as V, type Snippet as W, TableRendererStrategy as X, TextRendererStrategy as Y, wrapError as Z, type ChatWindowProps as a, type ConfigProviderProps as b, type ClientConfig as c, type ProductCarouselProps as d, type ChartType as e, type Chunk as f, type ChunkOptions as g, ConfigurationException as h, type DecisionContext as i, type IRendererStrategy as j, type IntentCategory as k, IntentClassifier as l, type LicenseValidationRequest as m, type LicenseValidationResponse as n, LicenseValidator as o, ProviderNotFoundException as p, type RenderDecision as q, type RenderType as r, RendererRegistry as s, RetrievalException as t, Retrivora as u, RetrivoraError as v, type RetrivoraErrorCode as w, RuleEngine as x, SDKVersionUnsupportedError as y, SDK_VERSION as z };
+/**
+ * BatchProcessor.ts — Handles batch operations with retry logic.
+ *
+ * Provides exponential backoff, partial failure tracking, and
+ * configurable batch sizing for efficient bulk operations.
+ */
+interface BatchOptions {
+    /** Maximum number of items per batch */
+    batchSize?: number;
+    /** Maximum number of retries for transient failures */
+    maxRetries?: number;
+    /** Initial delay before retry in milliseconds */
+    initialDelayMs?: number;
+    /** Maximum delay between retries in milliseconds */
+    maxDelayMs?: number;
+    /** Multiplier for exponential backoff */
+    backoffMultiplier?: number;
+    /** Whether to throw on any partial failure */
+    throwOnPartialFailure?: boolean;
+}
+interface BatchResult<T> {
+    results: T[];
+    errors: Array<{
+        index: number;
+        error: Error;
+        itemCount?: number;
+    }>;
+    totalProcessed: number;
+    totalFailed: number;
+}
+/**
+ * Determines if an error is transient (should retry)
+ */
+declare function isTransientError(error: unknown): boolean;
+declare class BatchProcessor {
+    private static readonly cb;
+    /**
+     * Execute a processor call through the circuit breaker.
+     * Only transient failures count toward opening the circuit.
+     */
+    private static executeWithCircuitBreaker;
+    /**
+     * Processes an array of items in configurable batches with retry logic.
+     *
+     * @param items - Items to process
+     * @param processor - Async function that processes a batch of items
+     * @param options - Configuration for batch size, retries, etc.
+     * @returns Object with results, errors, and statistics
+     *
+     * @example
+     * const docs = [...];
+     * const result = await BatchProcessor.processBatch(
+     *   docs,
+     *   (batch) => vectorDB.batchUpsert(batch),
+     *   { batchSize: 100, maxRetries: 3 }
+     * );
+     */
+    static processBatch<T, R>(items: T[], processor: (batch: T[]) => Promise<R>, options?: BatchOptions): Promise<BatchResult<R>>;
+    /**
+     * Processes items sequentially (one at a time) with retry logic.
+     * Useful for operations that don't support batching or when granular
+     * error tracking is needed.
+     */
+    static processSequential<T, R>(items: T[], processor: (item: T) => Promise<R>, options?: BatchOptions): Promise<BatchResult<R>>;
+    /**
+     * Maps over items with retry logic, returning results in order.
+     * Like Array.map() but with async processing and automatic retries.
+     */
+    static mapWithRetry<T, R>(items: T[], mapper: (item: T) => Promise<R>, options?: BatchOptions): Promise<R[]>;
+    /**
+     * Parallel processor with concurrency limit.
+     * Processes up to `concurrency` items at the same time.
+     */
+    static processConcurrent<T, R>(items: T[], processor: (item: T) => Promise<R>, concurrency?: number, options?: BatchOptions): Promise<BatchResult<R>>;
+}
+
+export { TableRendererStrategy as $, AuthenticationException as A, type BatchOptions as B, type ChatWidgetProps as C, type DocumentUploadProps as D, EmbeddingFailedException as E, SDKVersionUnsupportedError as F, SDK_VERSION as G, decideVisualization as H, type IRenderRule as I, isTransientError as J, type ArchitectureCardProps as K, LicenseValidationError as L, type MessageBubbleProps as M, CarouselRendererStrategy as N, ChartRendererStrategy as O, type ProductCardProps as P, type ChatViewportSize as Q, RateLimitException as R, type SourceCardProps as S, DocumentChunker as T, MixedRendererStrategy as U, VisualizationDecisionEngine as V, Pipeline as W, type PipelineStep as X, type ProviderPill as Y, type RenderSectionDecision as Z, type Snippet as _, type ChatWindowProps as a, TextRendererStrategy as a0, wrapError as a1, type ConfigProviderProps as b, type ClientConfig as c, type ProductCarouselProps as d, BatchProcessor as e, type BatchResult as f, type ChartType as g, type Chunk as h, type ChunkOptions as i, ConfigurationException as j, type DecisionContext as k, type IRendererStrategy as l, type IntentCategory as m, IntentClassifier as n, type LicenseValidationRequest as o, type LicenseValidationResponse as p, LicenseValidator as q, ProviderNotFoundException as r, type RenderDecision as s, type RenderType as t, RendererRegistry as u, RetrievalException as v, Retrivora as w, RetrivoraError as x, type RetrivoraErrorCode as y, RuleEngine as z };

package/dist/{LicenseValidator-CsjJp2PP.d.ts → BatchProcessor-BfzuU4cK.d.ts}

@@ -547,38 +547,177 @@ declare class LicenseValidationError extends RetrivoraError {
  */
 declare function wrapError(err: unknown, defaultCode: RetrivoraErrorCode, defaultMessage?: string): RetrivoraError;
 
+/**
+ * Input contract for `LicenseValidator.validate()`.
+ *
+ * At least one source must yield a license key: `licenseKey` field, an
+ * `x-license-key` entry in `headers`, or the process environment variables
+ * (NEXT_PUBLIC_RETRIVORA_LICENSE_KEY / RETRIVORA_LICENSE_KEY).
+ */
 interface LicenseValidationRequest {
+    /** Explicit `rtv_`-prefixed license key passed as a prop (highest priority). */
     licenseKey: string;
+    /** Project ID the caller is running under, checked for license binding match. */
     projectId?: string;
+    /** SDK version reported for minimum-supported-version enforcement (defaults to SDK_VERSION). */
     sdkVersion?: string;
+    /** SDK package identifier sent to server for observability. */
     sdk?: string;
+    /** browser | node — reported for observability only. */
     platform?: string;
+    /** Override base URL of the Retrivora API endpoint. Defaults to env or '/api/retrivora'. */
     retrivoraApiBase?: string;
+    /** Custom headers that may contain `x-license-key` or `Authorization: Bearer`. */
     headers?: Record<string, string>;
 }
+/**
+ * Response contract returned from `LicenseValidator.validate()`.
+ *
+ * Status enumerations are ordered — anything other than ACTIVE means the
+ * widget/chat must be disabled and must not pass server-side handler checks.
+ */
 interface LicenseValidationResponse {
+    /** True only when `licenseStatus` is ACTIVE and SDK version is supported. */
     valid: boolean;
+    /** Lifecycle state of the license record. TERMINATED/SUSPENDED/EXPIRED/REVOKED must block chat. */
     licenseStatus: 'ACTIVE' | 'SUSPENDED' | 'TERMINATED' | 'EXPIRED' | 'REVOKED';
+    /** Minimum SDK version that the server will accept (semver-compare). */
     minimumSupportedVersion: string;
+    /** Latest generally-available SDK version (for upgrade prompts). */
     latestVersion: string;
+    /** True when the SDK version is older than minimumSupportedVersion — UI must force upgrade. */
     forceUpgrade: boolean;
+    /** RFC3339 expiration timestamp or null for perpetual licenses. */
     expiresAt: string | null;
+    /** Human-readable status/reason string, suitable for tooltips/toasts. */
     message: string;
 }
+/**
+ * Client-side orchestrator for license validation.
+ *
+ * Flow:
+ *   1. Resolve the license key (prop → header → env)
+ *   2. Return any fresh (< 5 min old) successful cached result
+ *   3. POST to `{retrivoraApiBase}/v1/license/validate` for server-side DB-backed status
+ *   4. On network or HTTP error, fall back to zero-latency local RSA signature
+ *      verification via `LicenseVerifier.verify()`.
+ *
+ * Caching policy:
+ *   - ONLY successful (valid + ACTIVE + !forceUpgrade) responses are cached
+ *   - Any failed validation immediately purges the cache entry
+ *   - TTL is 5 minutes for success cache to allow TERMINATED/REVOKED status
+ *     changes on the server to propagate quickly.
+ *
+ * Thread safety: Singleton pattern via `getInstance()`. Used by ChatWidget,
+ * useRagChat hook, and the server-side `createLicenseHandler` indirectly through
+ * its own `LicenseVerifier.verify()` path.
+ */
 declare class LicenseValidator {
     private static instance;
     private cache;
     private static readonly SUCCESS_CACHE_TTL_MS;
     private constructor();
+    /** @returns Singleton instance of the validator (shared cache across all consumers). */
     static getInstance(): LicenseValidator;
     /**
-     * Invalidate local validation cache for a license key
+     * Purge entries from the local success cache.
+     *
+     * @param licenseKey - Optional. If provided, only that key's cache entry is
+     *                     removed. If omitted the entire cache is cleared.
+     *                     Callers use this after any 401/403 to ensure the next
+     *                     validate() call re-validates against the server.
      */
     purgeCache(licenseKey?: string): void;
     /**
-     * Validate license status and SDK version against Retrivora License Service
+     * Primary validation entry-point for UI / hook consumers.
+     *
+     * Resolves the license key, consults the local success cache, performs a
+     * server POST for authoritative status, and falls back to local RSA
+     * signature verification if the server can't be reached.
+     *
+     * @throws LicenseValidationError - When no key is provided OR both the
+     *         server call AND the local-RSA fallback report an invalid/expired key.
+     * @throws SDKVersionUnsupportedError - When server reports forceUpgrade=true.
+     * @returns A `LicenseValidationResponse` that the UI can use to enable or
+     *          lock the chat widget.
      */
     validate(request: LicenseValidationRequest): Promise<LicenseValidationResponse>;
 }
 
-export { AuthenticationException as A, decideVisualization as B, type ChatWidgetProps as C, type DocumentUploadProps as D, EmbeddingFailedException as E, type ArchitectureCardProps as F, CarouselRendererStrategy as G, ChartRendererStrategy as H, type IRenderRule as I, type ChatViewportSize as J, DocumentChunker as K, LicenseValidationError as L, type MessageBubbleProps as M, MixedRendererStrategy as N, Pipeline as O, type ProductCardProps as P, type PipelineStep as Q, RateLimitException as R, type SourceCardProps as S, type ProviderPill as T, type RenderSectionDecision as U, VisualizationDecisionEngine as V, type Snippet as W, TableRendererStrategy as X, TextRendererStrategy as Y, wrapError as Z, type ChatWindowProps as a, type ConfigProviderProps as b, type ClientConfig as c, type ProductCarouselProps as d, type ChartType as e, type Chunk as f, type ChunkOptions as g, ConfigurationException as h, type DecisionContext as i, type IRendererStrategy as j, type IntentCategory as k, IntentClassifier as l, type LicenseValidationRequest as m, type LicenseValidationResponse as n, LicenseValidator as o, ProviderNotFoundException as p, type RenderDecision as q, type RenderType as r, RendererRegistry as s, RetrievalException as t, Retrivora as u, RetrivoraError as v, type RetrivoraErrorCode as w, RuleEngine as x, SDKVersionUnsupportedError as y, SDK_VERSION as z };
+/**
+ * BatchProcessor.ts — Handles batch operations with retry logic.
+ *
+ * Provides exponential backoff, partial failure tracking, and
+ * configurable batch sizing for efficient bulk operations.
+ */
+interface BatchOptions {
+    /** Maximum number of items per batch */
+    batchSize?: number;
+    /** Maximum number of retries for transient failures */
+    maxRetries?: number;
+    /** Initial delay before retry in milliseconds */
+    initialDelayMs?: number;
+    /** Maximum delay between retries in milliseconds */
+    maxDelayMs?: number;
+    /** Multiplier for exponential backoff */
+    backoffMultiplier?: number;
+    /** Whether to throw on any partial failure */
+    throwOnPartialFailure?: boolean;
+}
+interface BatchResult<T> {
+    results: T[];
+    errors: Array<{
+        index: number;
+        error: Error;
+        itemCount?: number;
+    }>;
+    totalProcessed: number;
+    totalFailed: number;
+}
+/**
+ * Determines if an error is transient (should retry)
+ */
+declare function isTransientError(error: unknown): boolean;
+declare class BatchProcessor {
+    private static readonly cb;
+    /**
+     * Execute a processor call through the circuit breaker.
+     * Only transient failures count toward opening the circuit.
+     */
+    private static executeWithCircuitBreaker;
+    /**
+     * Processes an array of items in configurable batches with retry logic.
+     *
+     * @param items - Items to process
+     * @param processor - Async function that processes a batch of items
+     * @param options - Configuration for batch size, retries, etc.
+     * @returns Object with results, errors, and statistics
+     *
+     * @example
+     * const docs = [...];
+     * const result = await BatchProcessor.processBatch(
+     *   docs,
+     *   (batch) => vectorDB.batchUpsert(batch),
+     *   { batchSize: 100, maxRetries: 3 }
+     * );
+     */
+    static processBatch<T, R>(items: T[], processor: (batch: T[]) => Promise<R>, options?: BatchOptions): Promise<BatchResult<R>>;
+    /**
+     * Processes items sequentially (one at a time) with retry logic.
+     * Useful for operations that don't support batching or when granular
+     * error tracking is needed.
+     */
+    static processSequential<T, R>(items: T[], processor: (item: T) => Promise<R>, options?: BatchOptions): Promise<BatchResult<R>>;
+    /**
+     * Maps over items with retry logic, returning results in order.
+     * Like Array.map() but with async processing and automatic retries.
+     */
+    static mapWithRetry<T, R>(items: T[], mapper: (item: T) => Promise<R>, options?: BatchOptions): Promise<R[]>;
+    /**
+     * Parallel processor with concurrency limit.
+     * Processes up to `concurrency` items at the same time.
+     */
+    static processConcurrent<T, R>(items: T[], processor: (item: T) => Promise<R>, concurrency?: number, options?: BatchOptions): Promise<BatchResult<R>>;
+}
+
+export { TableRendererStrategy as $, AuthenticationException as A, type BatchOptions as B, type ChatWidgetProps as C, type DocumentUploadProps as D, EmbeddingFailedException as E, SDKVersionUnsupportedError as F, SDK_VERSION as G, decideVisualization as H, type IRenderRule as I, isTransientError as J, type ArchitectureCardProps as K, LicenseValidationError as L, type MessageBubbleProps as M, CarouselRendererStrategy as N, ChartRendererStrategy as O, type ProductCardProps as P, type ChatViewportSize as Q, RateLimitException as R, type SourceCardProps as S, DocumentChunker as T, MixedRendererStrategy as U, VisualizationDecisionEngine as V, Pipeline as W, type PipelineStep as X, type ProviderPill as Y, type RenderSectionDecision as Z, type Snippet as _, type ChatWindowProps as a, TextRendererStrategy as a0, wrapError as a1, type ConfigProviderProps as b, type ClientConfig as c, type ProductCarouselProps as d, BatchProcessor as e, type BatchResult as f, type ChartType as g, type Chunk as h, type ChunkOptions as i, ConfigurationException as j, type DecisionContext as k, type IRendererStrategy as l, type IntentCategory as m, IntentClassifier as n, type LicenseValidationRequest as o, type LicenseValidationResponse as p, LicenseValidator as q, ProviderNotFoundException as r, type RenderDecision as s, type RenderType as t, RendererRegistry as u, RetrievalException as v, Retrivora as w, RetrivoraError as x, type RetrivoraErrorCode as y, RuleEngine as z };

package/dist/handlers/index.d.mts

@@ -1,3 +1,3 @@
 import 'next/server';
-export { o as HandlerOptions, c as createChatHandler, d as createFeedbackHandler, e as createHealthHandler, f as createHistoryHandler, g as createIngestHandler, p as createLicenseHandler, h as createRagHandler, i as createSessionsHandler, j as createStreamHandler, q as createSuggestionsHandler, k as createUploadHandler, s as sseErrorFrame, l as sseFrame, m as sseMetaFrame, r as sseObservabilityFrame, n as sseTextFrame, t as sseUIFrame } from '../index-Dmq5lH0j.mjs';
+export { b as HandlerOptions, d as createChatHandler, e as createFeedbackHandler, f as createHealthHandler, g as createHistoryHandler, h as createIngestHandler, p as createLicenseHandler, i as createRagHandler, j as createSessionsHandler, k as createStreamHandler, q as createSuggestionsHandler, l as createUploadHandler, s as sseErrorFrame, m as sseFrame, n as sseMetaFrame, r as sseObservabilityFrame, o as sseTextFrame, t as sseUIFrame } from '../index-fnpaCuma.mjs';
 import '../ILLMProvider-teTNQ1lh.mjs';

package/dist/handlers/index.d.ts

@@ -1,3 +1,3 @@
 import 'next/server';
-export { o as HandlerOptions, c as createChatHandler, d as createFeedbackHandler, e as createHealthHandler, f as createHistoryHandler, g as createIngestHandler, p as createLicenseHandler, h as createRagHandler, i as createSessionsHandler, j as createStreamHandler, q as createSuggestionsHandler, k as createUploadHandler, s as sseErrorFrame, l as sseFrame, m as sseMetaFrame, r as sseObservabilityFrame, n as sseTextFrame, t as sseUIFrame } from '../index-BPJ3KDYI.js';
+export { b as HandlerOptions, d as createChatHandler, e as createFeedbackHandler, f as createHealthHandler, g as createHistoryHandler, h as createIngestHandler, p as createLicenseHandler, i as createRagHandler, j as createSessionsHandler, k as createStreamHandler, q as createSuggestionsHandler, l as createUploadHandler, s as sseErrorFrame, m as sseFrame, n as sseMetaFrame, r as sseObservabilityFrame, o as sseTextFrame, t as sseUIFrame } from '../index-DR_O_B-W.js';
 import '../ILLMProvider-teTNQ1lh.js';