@retrivora-ai/rag-engine 1.9.6 → 1.9.7

package/src/core/Retrivora.ts

@@ -3,6 +3,7 @@ import { ChatMessage, ChatResponse, IngestDocument } from '../types';
 import { ConfigResolver } from './ConfigResolver';
 import { ConfigValidator } from './ConfigValidator';
 import { Pipeline } from './Pipeline';
+import { wrapError, RetrivoraErrorCode } from '../exceptions';
 
 /**
  * Public SDK facade matching the prompt-level Retrivora API.
@@ -20,27 +21,65 @@ export class Retrivora {
   }
 
   async initialize(): Promise<void> {
-    await ConfigValidator.validateAndThrow(this.config);
-    await this.pipeline.initialize();
+    try {
+      await ConfigValidator.validateAndThrow(this.config);
+    } catch (err) {
+      throw wrapError(err, 'CONFIGURATION_ERROR');
+    }
+    try {
+      await this.pipeline.initialize();
+    } catch (err) {
+      throw wrapError(err, 'AUTHENTICATION_ERROR');
+    }
   }
 
   async ingest(
     documents: IngestDocument[],
     namespace?: string,
   ): Promise<Array<{ docId: string | number; chunksIngested: number }>> {
-    return this.pipeline.ingest(documents, namespace);
+    try {
+      return await this.pipeline.ingest(documents, namespace);
+    } catch (err) {
+      const msg = String(err);
+      let defaultCode: RetrivoraErrorCode = 'RETRIEVAL_FAILED';
+      if (msg.includes('Embed') || msg.includes('embed')) {
+        defaultCode = 'EMBEDDING_FAILED';
+      }
+      throw wrapError(err, defaultCode);
+    }
   }
 
   async ask(question: string, history: ChatMessage[] = [], namespace?: string): Promise<ChatResponse> {
-    return this.pipeline.ask(question, history, namespace);
+    try {
+      return await this.pipeline.ask(question, history, namespace);
+    } catch (err) {
+      const msg = String(err);
+      let defaultCode: RetrivoraErrorCode = 'RETRIEVAL_FAILED';
+      if (msg.includes('Embed') || msg.includes('embed')) {
+        defaultCode = 'EMBEDDING_FAILED';
+      }
+      throw wrapError(err, defaultCode);
+    }
   }
 
-  askStream(
+  async *askStream(
     question: string,
     history: ChatMessage[] = [],
     namespace?: string,
   ): AsyncIterable<string | ChatResponse> {
-    return this.pipeline.askStream(question, history, namespace);
+    try {
+      const stream = this.pipeline.askStream(question, history, namespace);
+      for await (const chunk of stream) {
+        yield chunk;
+      }
+    } catch (err) {
+      const msg = String(err);
+      let defaultCode: RetrivoraErrorCode = 'RETRIEVAL_FAILED';
+      if (msg.includes('Embed') || msg.includes('embed')) {
+        defaultCode = 'EMBEDDING_FAILED';
+      }
+      throw wrapError(err, defaultCode);
+    }
   }
 
   getPipeline(): Pipeline {
@@ -49,3 +88,4 @@ export class Retrivora {
 }
 
 export type { RetrievalConfig, UniversalRagConfig };
+

package/src/core/VectorPlugin.ts

@@ -5,6 +5,7 @@ import { Pipeline } from './Pipeline';
 import { ProviderHealthCheck, HealthCheckResult } from './ProviderHealthCheck';
 import { IngestDocument, ChatResponse } from '../types';
 import { ChatMessage } from '../types';
+import { wrapError, RetrivoraErrorCode } from '../exceptions';
 
 /**
  * VectorPlugin — main orchestrator class.
@@ -27,6 +28,8 @@ export class VectorPlugin {
     
     // Start validation early
     this.validationPromise = ConfigValidator.validateAndThrow(this.config);
+    // Prevent unhandled promise rejection warning
+    this.validationPromise.catch(() => {});
     
     this.pipeline = new Pipeline(this.config);
   }
@@ -70,31 +73,82 @@ export class VectorPlugin {
    * Run a chat query.
    */
   async chat(message: string, history: ChatMessage[] = [], namespace?: string): Promise<ChatResponse> {
-    await this.validationPromise;
-    return this.pipeline.ask(message, history, namespace);
+    try {
+      await this.validationPromise;
+    } catch (err) {
+      throw wrapError(err, 'CONFIGURATION_ERROR');
+    }
+    try {
+      return await this.pipeline.ask(message, history, namespace);
+    } catch (err) {
+      const msg = String(err);
+      let defaultCode: RetrivoraErrorCode = 'RETRIEVAL_FAILED';
+      if (msg.includes('Embed') || msg.includes('embed')) {
+        defaultCode = 'EMBEDDING_FAILED';
+      }
+      throw wrapError(err, defaultCode);
+    }
   }
 
   /**
    * Run a streaming chat query.
    */
   async *chatStream(message: string, history: ChatMessage[] = [], namespace?: string) {
-    await this.validationPromise;
-    yield* this.pipeline.askStream(message, history, namespace);
+    try {
+      await this.validationPromise;
+    } catch (err) {
+      throw wrapError(err, 'CONFIGURATION_ERROR');
+    }
+    try {
+      const stream = this.pipeline.askStream(message, history, namespace);
+      for await (const chunk of stream) {
+        yield chunk;
+      }
+    } catch (err) {
+      const msg = String(err);
+      let defaultCode: RetrivoraErrorCode = 'RETRIEVAL_FAILED';
+      if (msg.includes('Embed') || msg.includes('embed')) {
+        defaultCode = 'EMBEDDING_FAILED';
+      }
+      throw wrapError(err, defaultCode);
+    }
   }
 
   /**
    * Ingest documents into the vector database.
    */
   async ingest(documents: IngestDocument[], namespace?: string): Promise<Array<{ docId: string | number; chunksIngested: number }>> {
-    await this.validationPromise;
-    return this.pipeline.ingest(documents, namespace);
+    try {
+      await this.validationPromise;
+    } catch (err) {
+      throw wrapError(err, 'CONFIGURATION_ERROR');
+    }
+    try {
+      return await this.pipeline.ingest(documents, namespace);
+    } catch (err) {
+      const msg = String(err);
+      let defaultCode: RetrivoraErrorCode = 'RETRIEVAL_FAILED';
+      if (msg.includes('Embed') || msg.includes('embed')) {
+        defaultCode = 'EMBEDDING_FAILED';
+      }
+      throw wrapError(err, defaultCode);
+    }
   }
 
   /**
    * Get auto-suggestions based on a query prefix.
    */
   async getSuggestions(query: string, namespace?: string): Promise<string[]> {
-    await this.validationPromise;
-    return this.pipeline.getSuggestions(query, namespace);
+    try {
+      await this.validationPromise;
+    } catch (err) {
+      throw wrapError(err, 'CONFIGURATION_ERROR');
+    }
+    try {
+      return await this.pipeline.getSuggestions(query, namespace);
+    } catch (err) {
+      throw wrapError(err, 'RETRIEVAL_FAILED');
+    }
   }
 }
+

package/src/exceptions/index.ts

@@ -57,3 +57,55 @@ export class AuthenticationException extends RetrivoraError {
     super(message, 'AUTHENTICATION_ERROR', details);
   }
 }
+
+/**
+ * Wraps any unknown error into an appropriate RetrivoraError subclass.
+ */
+export function wrapError(
+  err: unknown,
+  defaultCode: RetrivoraErrorCode,
+  defaultMessage?: string,
+): RetrivoraError {
+  if (err instanceof RetrivoraError) {
+    return err;
+  }
+
+  const error = err as any;
+  const message = error?.message || defaultMessage || String(err);
+  const status = error?.status || error?.statusCode || error?.response?.status;
+  const code = error?.code;
+
+  // 1. Rate Limit Recognition
+  if (status === 429 || /rate[- ]?limit/i.test(message) || code === 'RATE_LIMIT_EXCEEDED') {
+    return new RateLimitException(message, err);
+  }
+
+  // 2. Authentication Recognition
+  if (
+    status === 401 ||
+    status === 403 ||
+    /unauthorized|auth|api[- ]?key/i.test(message) ||
+    code === 'INVALID_API_KEY'
+  ) {
+    return new AuthenticationException(message, err);
+  }
+
+  // Fallback Mapping based on defaultCode
+  switch (defaultCode) {
+    case 'PROVIDER_NOT_FOUND':
+      return new ProviderNotFoundException('provider', message, err);
+    case 'EMBEDDING_FAILED':
+      return new EmbeddingFailedException(message, err);
+    case 'RETRIEVAL_FAILED':
+      return new RetrievalException(message, err);
+    case 'RATE_LIMITED':
+      return new RateLimitException(message, err);
+    case 'CONFIGURATION_ERROR':
+      return new ConfigurationException(message, err);
+    case 'AUTHENTICATION_ERROR':
+      return new AuthenticationException(message, err);
+    default:
+      return new RetrivoraError(message, defaultCode, err);
+  }
+}
+

package/src/handlers/index.ts

@@ -413,5 +413,76 @@ export function createSuggestionsHandler(configOrPlugin?: Partial<RagConfig> | V
   };
 }
 
+/**
+ * createRagHandler — factory that returns GET and POST handlers for a catch-all route
+ * (e.g. `src/app/api/retrivora/[[...retrivora]]/route.ts`).
+ */
+export function createRagHandler(configOrPlugin?: Partial<RagConfig> | VectorPlugin) {
+  const plugin =
+    configOrPlugin instanceof VectorPlugin
+      ? configOrPlugin
+      : new VectorPlugin(configOrPlugin);
+
+  const chatHandler = createChatHandler(plugin);
+  const streamHandler = createStreamHandler(plugin);
+  const uploadHandler = createUploadHandler(plugin);
+  const healthHandler = createHealthHandler(plugin);
+  const suggestionsHandler = createSuggestionsHandler(plugin);
+
+  async function routePostRequest(req: NextRequest, segment: string) {
+    switch (segment) {
+      case 'chat':
+        return streamHandler(req);
+      case 'chat-sync':
+        return chatHandler(req);
+      case 'upload':
+        return uploadHandler(req);
+      case 'suggestions':
+        return suggestionsHandler(req);
+      case 'health':
+        return healthHandler();
+      default:
+        return NextResponse.json({ error: `Not Found: POST segment "${segment}" not supported.` }, { status: 404 });
+    }
+  }
+
+  async function routeGetRequest(req: NextRequest, segment: string) {
+    if (segment === 'health') {
+      return healthHandler();
+    }
+    return NextResponse.json({ error: `Method Not Allowed: GET is only supported for "health" segment.` }, { status: 405 });
+  }
+
+  async function getSegment(context: any): Promise<string> {
+    const resolvedParams = typeof context?.params?.then === 'function'
+      ? await context.params
+      : context?.params;
+    
+    const segments: string[] = resolvedParams?.retrivora || [];
+    return segments[0] || 'chat';
+  }
+
+  return {
+    GET: async (req: NextRequest, context: any) => {
+      try {
+        const segment = await getSegment(context);
+        return await routeGetRequest(req, segment);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : 'GET Routing failed';
+        return NextResponse.json({ error: msg }, { status: 500 });
+      }
+    },
+    POST: async (req: NextRequest, context: any) => {
+      try {
+        const segment = await getSegment(context);
+        return await routePostRequest(req, segment);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : 'POST Routing failed';
+        return NextResponse.json({ error: msg }, { status: 500 });
+      }
+    }
+  };
+}
+
 // Re-export SSE helpers so host apps can use them in custom handlers
 export { sseFrame, sseTextFrame, sseMetaFrame, sseErrorFrame, sseUIFrame, sseObservabilityFrame };

package/src/hooks/useRagChat.ts

@@ -115,7 +115,10 @@ export function useRagChat(
 
         const response = await fetch(apiUrl, {
           method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
+          headers: { 
+            'Content-Type': 'application/json',
+            ...(options.headers || {})
+          },
           signal: controller.signal,
           body: JSON.stringify({
             message: trimmed,

package/src/index.ts

@@ -1,3 +1,5 @@
+'use client';
+
 /**
  * Package entry point — public API exported to consumers of this npm package.
  * This entry point is CLIENT-SAFE and can be imported in React Client Components.

package/src/llm/LLMFactory.ts

@@ -83,11 +83,12 @@ export class LLMFactory {
           return new UniversalLLMAdapter(llmConfig);
         }
         throw new ProviderNotFoundException(
-          'LLM',
-          String(llmConfig.provider),
-          `[LLMFactory] Unknown provider "${llmConfig.provider}". ` +
-          `Built-in providers: ${LLMFactory.listProviders().join(', ')}. ` +
-          `Register a custom provider with LLMFactory.register().`
+          'llm',
+          llmConfig.provider ?? 'undefined',
+          {
+            message: `Unknown provider "${llmConfig.provider}". Register a custom provider with LLMFactory.register().`,
+            available: LLMFactory.listProviders()
+          }
         );
       }
     }

package/src/server.ts

@@ -28,8 +28,8 @@ export type { ValidationError } from './core/ConfigValidator';
 export type { BatchOptions, BatchResult } from './core/BatchProcessor';
 
 // ── Core Orchestration ─────────────────────────────────────────
-export { VectorPlugin } from './core/VectorPlugin';
 export { Retrivora } from './core/Retrivora';
+export { VectorPlugin } from './core/VectorPlugin';
 export { Pipeline } from './core/Pipeline';
 export { ConfigResolver } from './core/ConfigResolver';
 export { ProviderRegistry } from './core/ProviderRegistry';
@@ -37,18 +37,6 @@ export { ConfigValidator } from './core/ConfigValidator';
 export { ProviderHealthCheck } from './core/ProviderHealthCheck';
 export { BatchProcessor } from './core/BatchProcessor';
 
-// ── Exceptions ────────────────────────────────────────────────
-export {
-  RetrivoraError,
-  ProviderNotFoundException,
-  EmbeddingFailedException,
-  RetrievalException,
-  RateLimitException,
-  ConfigurationException,
-  AuthenticationException,
-} from './exceptions';
-export type { RetrivoraErrorCode } from './exceptions';
-
 // ── Configuration Helpers ──────────────────────────────────────
 export { getRagConfig } from './config/serverConfig';
 export { ConfigBuilder, PRESETS, createFromPreset } from './config/ConfigBuilder';
@@ -86,8 +74,23 @@ export {
   createIngestHandler,
   createHealthHandler,
   createUploadHandler,
+  createRagHandler,
   sseFrame,
   sseTextFrame,
   sseMetaFrame,
   sseErrorFrame,
 } from './handlers';
+
+// ── Exceptions ────────────────────────────────────────────────
+export type { RetrivoraErrorCode } from './exceptions';
+export {
+  RetrivoraError,
+  ProviderNotFoundException,
+  EmbeddingFailedException,
+  RetrievalException,
+  RateLimitException,
+  ConfigurationException,
+  AuthenticationException,
+  wrapError,
+} from './exceptions';
+

package/src/types/chat.ts

@@ -49,6 +49,8 @@ export interface UseRagChatOptions {
   onReply?: (message: RagMessage) => void;
   /** Called on error */
   onError?: (error: string) => void;
+  /** Optional custom headers to send with the chat request */
+  headers?: Record<string, string>;
 }
 
 export interface UseRagChatReturn {

package/src/types/props.ts

@@ -1,8 +1,37 @@
-import { ReactNode, CSSProperties, MouseEvent } from 'react';
+import { ReactNode, CSSProperties, MouseEvent, ElementType } from 'react';
 import { Product, VectorMatch } from './index';
 import { RagMessage } from './chat';
 import { UIConfig } from '../config/RagConfig';
 
+export interface ArchitectureCardProps {
+  icon: ReactNode;
+  title: string;
+  description: string;
+  badge: string;
+  badgeColor: string;
+}
+
+export interface Snippet {
+  id: string;
+  title: string;
+  description: string;
+  code: string;
+  language: string;
+}
+
+export interface PipelineStep {
+  step: string;
+  Icon: ElementType;
+  title: string;
+  desc: string;
+  colors: { from: string; to: string };
+}
+
+export interface ProviderPill {
+  Icon: ElementType;
+  label: string;
+}
+
 export type ChatViewportSize = 'compact' | 'medium' | 'large';
 
 export interface ChatWindowProps {
@@ -26,6 +55,10 @@ export interface ChatWindowProps {
   isMaximized?: boolean;
   /** Called when the user clicks 'Add to Cart' on a product */
   onAddToCart?: (product: Product) => void;
+  /** Optional custom API URL to send chat messages to */
+  apiUrl?: string;
+  /** Optional custom headers to send with the chat request */
+  headers?: Record<string, string>;
 }
 
 export interface ChatWidgetProps {
@@ -33,6 +66,10 @@ export interface ChatWidgetProps {
   position?: 'bottom-right' | 'bottom-left';
   /** Called when the user clicks 'Add to Cart' on a product */
   onAddToCart?: (product: Product) => void;
+  /** Optional custom API URL to send chat messages to */
+  apiUrl?: string;
+  /** Optional custom headers to send with the chat request */
+  headers?: Record<string, string>;
 }
 
 export interface MessageBubbleProps {