@retrivora-ai/rag-engine 2.4.5 → 2.4.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -182,3 +182,25 @@ For lightweight deployments, Retrivora includes a standardized Free Tier MVP des
182
182
 
183
183
  See [FREE_TIER_ARCHITECTURE.md](file:///Users/abhinavalkuchi/work/retrivora-ai/packages/sdk/FREE_TIER_ARCHITECTURE.md) for full implementation details, code presets, and limits configuration.
184
184
 
185
+ ---
186
+
187
+ ## 6. Next.js App Router Integration & Framework Lock-in (PKG-1)
188
+
189
+ The SDK's prebuilt server handlers (`createChatHandler`, `createStreamHandler`, `createUploadHandler`) import directly from `next/server`. They are tightly coupled to the Next.js App Router API context and expect standard Next.js requests and responses.
190
+
191
+ If you are deploying in non-Next.js server environments (such as Express, Fastify, Hono, or custom Node.js frameworks), do **not** use the route handlers. Instead, invoke the core `LicensedRetrivora` SDK methods directly within your custom controllers:
192
+ ```typescript
193
+ import { createRetrivora } from '@retrivora-ai/rag-engine';
194
+
195
+ // Framework-agnostic controller example
196
+ app.post('/api/chat', async (req, res) => {
197
+ const sdk = await createRetrivora({
198
+ projectId: 'my-project',
199
+ licenseKey: process.env.RETRIVORA_LICENSE_KEY,
200
+ });
201
+ const answer = await sdk.query(req.body.message);
202
+ res.json(answer);
203
+ });
204
+ ```
205
+
206
+
@@ -696,12 +696,58 @@ declare class LicenseValidator {
696
696
  validate(request: LicenseValidationRequest): Promise<LicenseValidationResponse>;
697
697
  }
698
698
 
699
+ type CircuitState = 'closed' | 'open' | 'half-open';
700
+ interface CircuitBreakerOptions {
701
+ failureThreshold?: number;
702
+ resetTimeoutMs?: number;
703
+ halfOpenMaxCalls?: number;
704
+ }
705
+ declare class CircuitBreaker {
706
+ private state;
707
+ private failureCount;
708
+ private successCount;
709
+ private lastFailureAt;
710
+ private halfOpenCalls;
711
+ private readonly failureThreshold;
712
+ readonly resetTimeoutMs: number;
713
+ private readonly halfOpenMaxCalls;
714
+ constructor(options?: CircuitBreakerOptions);
715
+ record(success: boolean): void;
716
+ canExecute(): boolean;
717
+ /**
718
+ * Increments the half-open probe counter when a call is attempted in
719
+ * half-open state. Must be called after `canExecute()` returns true and
720
+ * the state is half-open. Safe to call in other states (no-op).
721
+ */
722
+ incrementHalfOpen(): void;
723
+ /**
724
+ * Returns the number of milliseconds the caller should wait before retrying.
725
+ * Returns 0 when the circuit is closed or half-open (i.e., calls are allowed).
726
+ *
727
+ * Fix TYPE-1: replaces direct access to private `lastFailureAt` field via
728
+ * `(cb as any).lastFailureAt` in BatchProcessor.
729
+ */
730
+ retryAfterMs(): number;
731
+ wrap<T>(fn: () => Promise<T>): Promise<T>;
732
+ getState(): CircuitState;
733
+ getFailureCount(): number;
734
+ reset(): void;
735
+ }
736
+
699
737
  /**
700
738
  * BatchProcessor.ts — Handles batch operations with retry logic.
701
739
  *
702
740
  * Provides exponential backoff, partial failure tracking, and
703
741
  * configurable batch sizing for efficient bulk operations.
742
+ *
743
+ * Fix ARCH-3: BatchProcessor no longer holds a static module-level
744
+ * CircuitBreaker that was shared across all callers. Each call site
745
+ * that needs circuit-breaking should create its own CircuitBreaker
746
+ * and pass it via BatchOptions.circuitBreaker so failures in one
747
+ * upstream (e.g., Pinecone) do not trip the breaker for unrelated
748
+ * upstreams (e.g., PostgreSQL).
704
749
  */
750
+
705
751
  interface BatchOptions {
706
752
  /** Maximum number of items per batch */
707
753
  batchSize?: number;
@@ -715,6 +761,15 @@ interface BatchOptions {
715
761
  backoffMultiplier?: number;
716
762
  /** Whether to throw on any partial failure */
717
763
  throwOnPartialFailure?: boolean;
764
+ /**
765
+ * Optional circuit breaker scoped to the upstream being called.
766
+ *
767
+ * Fix ARCH-3: provide your own CircuitBreaker instance per upstream so
768
+ * failures in one provider (e.g., Pinecone) do not trip the breaker for
769
+ * unrelated providers (e.g., PostgreSQL). When omitted, calls are made
770
+ * directly without circuit-breaking.
771
+ */
772
+ circuitBreaker?: CircuitBreaker;
718
773
  }
719
774
  interface BatchResult<T> {
720
775
  results: T[];
@@ -731,10 +786,14 @@ interface BatchResult<T> {
731
786
  */
732
787
  declare function isTransientError(error: unknown): boolean;
733
788
  declare class BatchProcessor {
734
- private static readonly cb;
735
789
  /**
736
- * Execute a processor call through the circuit breaker.
737
- * Only transient failures count toward opening the circuit.
790
+ * Execute a processor call, optionally through a caller-provided circuit
791
+ * breaker. Only transient failures count toward opening the circuit.
792
+ *
793
+ * Fix ARCH-3: removed the static module-level `cb` field. Callers must
794
+ * supply their own CircuitBreaker via BatchOptions.circuitBreaker.
795
+ * Fix TYPE-1: uses the public retryAfterMs() and incrementHalfOpen()
796
+ * API instead of accessing private fields via `as any`.
738
797
  */
739
798
  private static executeWithCircuitBreaker;
740
799
  /**
@@ -772,4 +831,4 @@ declare class BatchProcessor {
772
831
  static processConcurrent<T, R>(items: T[], processor: (item: T) => Promise<R>, concurrency?: number, options?: BatchOptions): Promise<BatchResult<R>>;
773
832
  }
774
833
 
775
- export { wrapError as $, AuthenticationException as A, type BatchOptions as B, type ChatWidgetProps as C, type DocumentUploadProps as D, EmbeddingFailedException as E, RetrievalException as F, Retrivora as G, RetrivoraError as H, type IRenderRule as I, type RetrivoraErrorCode as J, SDKVersionUnsupportedError as K, type LicenseTierConfig as L, type MessageBubbleProps as M, SDK_VERSION as N, isTransientError as O, type ProductCardProps as P, type ArchitectureCardProps as Q, type RemoteConfig as R, type SourceCardProps as S, type ChatViewportSize as T, DocumentChunker as U, LicenseConfigResolver as V, Pipeline as W, type PipelineStep as X, type ProviderPill as Y, type RenderSectionDecision as Z, type Snippet as _, type ChatWindowProps as a, 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, ConfigFetcher as j, ConfigurationException as k, type DecisionContext as l, type IRendererStrategy as m, type IntentCategory as n, LicenseValidationError as o, type LicenseValidationRequest as p, type LicenseValidationResponse as q, LicenseValidator as r, type ProviderCredentials as s, ProviderNotFoundException as t, RateLimitException as u, type RemoteEmbeddingConfig as v, type RemoteLLMConfig as w, type RemoteVectorConfig as x, type RenderDecision as y, type RenderType as z };
834
+ export { type RenderSectionDecision as $, AuthenticationException as A, type BatchOptions as B, type ChatWidgetProps as C, type DocumentUploadProps as D, EmbeddingFailedException as E, type RenderDecision as F, type RenderType as G, RetrievalException as H, type IRenderRule as I, Retrivora as J, RetrivoraError as K, type LicenseTierConfig as L, type MessageBubbleProps as M, type RetrivoraErrorCode as N, SDKVersionUnsupportedError as O, type ProductCardProps as P, SDK_VERSION as Q, type RemoteConfig as R, type SourceCardProps as S, isTransientError as T, type ArchitectureCardProps as U, type ChatViewportSize as V, DocumentChunker as W, LicenseConfigResolver as X, Pipeline as Y, type PipelineStep as Z, type ProviderPill as _, type ChatWindowProps as a, type Snippet 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, CircuitBreaker as j, type CircuitBreakerOptions as k, ConfigFetcher as l, ConfigurationException as m, type DecisionContext as n, type IRendererStrategy as o, type IntentCategory as p, LicenseValidationError as q, type LicenseValidationRequest as r, type LicenseValidationResponse as s, LicenseValidator as t, type ProviderCredentials as u, ProviderNotFoundException as v, RateLimitException as w, type RemoteEmbeddingConfig as x, type RemoteLLMConfig as y, type RemoteVectorConfig as z };
@@ -696,12 +696,58 @@ declare class LicenseValidator {
696
696
  validate(request: LicenseValidationRequest): Promise<LicenseValidationResponse>;
697
697
  }
698
698
 
699
+ type CircuitState = 'closed' | 'open' | 'half-open';
700
+ interface CircuitBreakerOptions {
701
+ failureThreshold?: number;
702
+ resetTimeoutMs?: number;
703
+ halfOpenMaxCalls?: number;
704
+ }
705
+ declare class CircuitBreaker {
706
+ private state;
707
+ private failureCount;
708
+ private successCount;
709
+ private lastFailureAt;
710
+ private halfOpenCalls;
711
+ private readonly failureThreshold;
712
+ readonly resetTimeoutMs: number;
713
+ private readonly halfOpenMaxCalls;
714
+ constructor(options?: CircuitBreakerOptions);
715
+ record(success: boolean): void;
716
+ canExecute(): boolean;
717
+ /**
718
+ * Increments the half-open probe counter when a call is attempted in
719
+ * half-open state. Must be called after `canExecute()` returns true and
720
+ * the state is half-open. Safe to call in other states (no-op).
721
+ */
722
+ incrementHalfOpen(): void;
723
+ /**
724
+ * Returns the number of milliseconds the caller should wait before retrying.
725
+ * Returns 0 when the circuit is closed or half-open (i.e., calls are allowed).
726
+ *
727
+ * Fix TYPE-1: replaces direct access to private `lastFailureAt` field via
728
+ * `(cb as any).lastFailureAt` in BatchProcessor.
729
+ */
730
+ retryAfterMs(): number;
731
+ wrap<T>(fn: () => Promise<T>): Promise<T>;
732
+ getState(): CircuitState;
733
+ getFailureCount(): number;
734
+ reset(): void;
735
+ }
736
+
699
737
  /**
700
738
  * BatchProcessor.ts — Handles batch operations with retry logic.
701
739
  *
702
740
  * Provides exponential backoff, partial failure tracking, and
703
741
  * configurable batch sizing for efficient bulk operations.
742
+ *
743
+ * Fix ARCH-3: BatchProcessor no longer holds a static module-level
744
+ * CircuitBreaker that was shared across all callers. Each call site
745
+ * that needs circuit-breaking should create its own CircuitBreaker
746
+ * and pass it via BatchOptions.circuitBreaker so failures in one
747
+ * upstream (e.g., Pinecone) do not trip the breaker for unrelated
748
+ * upstreams (e.g., PostgreSQL).
704
749
  */
750
+
705
751
  interface BatchOptions {
706
752
  /** Maximum number of items per batch */
707
753
  batchSize?: number;
@@ -715,6 +761,15 @@ interface BatchOptions {
715
761
  backoffMultiplier?: number;
716
762
  /** Whether to throw on any partial failure */
717
763
  throwOnPartialFailure?: boolean;
764
+ /**
765
+ * Optional circuit breaker scoped to the upstream being called.
766
+ *
767
+ * Fix ARCH-3: provide your own CircuitBreaker instance per upstream so
768
+ * failures in one provider (e.g., Pinecone) do not trip the breaker for
769
+ * unrelated providers (e.g., PostgreSQL). When omitted, calls are made
770
+ * directly without circuit-breaking.
771
+ */
772
+ circuitBreaker?: CircuitBreaker;
718
773
  }
719
774
  interface BatchResult<T> {
720
775
  results: T[];
@@ -731,10 +786,14 @@ interface BatchResult<T> {
731
786
  */
732
787
  declare function isTransientError(error: unknown): boolean;
733
788
  declare class BatchProcessor {
734
- private static readonly cb;
735
789
  /**
736
- * Execute a processor call through the circuit breaker.
737
- * Only transient failures count toward opening the circuit.
790
+ * Execute a processor call, optionally through a caller-provided circuit
791
+ * breaker. Only transient failures count toward opening the circuit.
792
+ *
793
+ * Fix ARCH-3: removed the static module-level `cb` field. Callers must
794
+ * supply their own CircuitBreaker via BatchOptions.circuitBreaker.
795
+ * Fix TYPE-1: uses the public retryAfterMs() and incrementHalfOpen()
796
+ * API instead of accessing private fields via `as any`.
738
797
  */
739
798
  private static executeWithCircuitBreaker;
740
799
  /**
@@ -772,4 +831,4 @@ declare class BatchProcessor {
772
831
  static processConcurrent<T, R>(items: T[], processor: (item: T) => Promise<R>, concurrency?: number, options?: BatchOptions): Promise<BatchResult<R>>;
773
832
  }
774
833
 
775
- export { wrapError as $, AuthenticationException as A, type BatchOptions as B, type ChatWidgetProps as C, type DocumentUploadProps as D, EmbeddingFailedException as E, RetrievalException as F, Retrivora as G, RetrivoraError as H, type IRenderRule as I, type RetrivoraErrorCode as J, SDKVersionUnsupportedError as K, type LicenseTierConfig as L, type MessageBubbleProps as M, SDK_VERSION as N, isTransientError as O, type ProductCardProps as P, type ArchitectureCardProps as Q, type RemoteConfig as R, type SourceCardProps as S, type ChatViewportSize as T, DocumentChunker as U, LicenseConfigResolver as V, Pipeline as W, type PipelineStep as X, type ProviderPill as Y, type RenderSectionDecision as Z, type Snippet as _, type ChatWindowProps as a, 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, ConfigFetcher as j, ConfigurationException as k, type DecisionContext as l, type IRendererStrategy as m, type IntentCategory as n, LicenseValidationError as o, type LicenseValidationRequest as p, type LicenseValidationResponse as q, LicenseValidator as r, type ProviderCredentials as s, ProviderNotFoundException as t, RateLimitException as u, type RemoteEmbeddingConfig as v, type RemoteLLMConfig as w, type RemoteVectorConfig as x, type RenderDecision as y, type RenderType as z };
834
+ export { type RenderSectionDecision as $, AuthenticationException as A, type BatchOptions as B, type ChatWidgetProps as C, type DocumentUploadProps as D, EmbeddingFailedException as E, type RenderDecision as F, type RenderType as G, RetrievalException as H, type IRenderRule as I, Retrivora as J, RetrivoraError as K, type LicenseTierConfig as L, type MessageBubbleProps as M, type RetrivoraErrorCode as N, SDKVersionUnsupportedError as O, type ProductCardProps as P, SDK_VERSION as Q, type RemoteConfig as R, type SourceCardProps as S, isTransientError as T, type ArchitectureCardProps as U, type ChatViewportSize as V, DocumentChunker as W, LicenseConfigResolver as X, Pipeline as Y, type PipelineStep as Z, type ProviderPill as _, type ChatWindowProps as a, type Snippet 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, CircuitBreaker as j, type CircuitBreakerOptions as k, ConfigFetcher as l, ConfigurationException as m, type DecisionContext as n, type IRendererStrategy as o, type IntentCategory as p, LicenseValidationError as q, type LicenseValidationRequest as r, type LicenseValidationResponse as s, LicenseValidator as t, type ProviderCredentials as u, ProviderNotFoundException as v, RateLimitException as w, type RemoteEmbeddingConfig as x, type RemoteLLMConfig as y, type RemoteVectorConfig as z };