@retrivora-ai/rag-engine 1.9.9 → 2.0.0

package/src/handlers/index.ts

@@ -145,6 +145,62 @@ function getOrCreatePlugin(configOrPlugin: Partial<RagConfig> | VectorPlugin | u
   return _g[cacheKey];
 }
 
+// ─── Telemetry Reporter Helper ───────────────────────────────────────────────
+
+/**
+ * Asynchronously sends telemetry payload to telemetryUrl when telemetry is enabled
+ * or when a licenseKey is set. Non-blocking.
+ */
+function reportTelemetry(
+  req: NextRequest,
+  plugin: VectorPlugin,
+  action: string,
+  status: 'success' | 'error',
+  details: string,
+  trace?: unknown
+) {
+  try {
+    const config = plugin.getConfig();
+    const licenseKey = config.licenseKey || process.env.RAG_LICENSE_KEY || process.env.RETRIVORA_LICENSE_KEY || process.env.NEXT_PUBLIC_RETRIVORA_LICENSE_KEY;
+    const telemetryConfig = config.telemetry;
+
+    const enabled = telemetryConfig?.enabled ?? Boolean(licenseKey);
+    if (!enabled) return;
+
+    const telemetryUrl = telemetryConfig?.url || process.env.TELEMETRY_URL || process.env.NEXT_PUBLIC_TELEMETRY_URL || '/api/telemetry';
+    const host = req.headers.get('host') || 'localhost';
+
+    let absoluteUrl = telemetryUrl;
+    if (!telemetryUrl.startsWith('http')) {
+      const proto = req.headers.get('x-forwarded-proto') || 'http';
+      absoluteUrl = `${proto}://${host}${telemetryUrl}`;
+    }
+
+    const projectId = config.projectId || 'default';
+
+    fetch(absoluteUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-forwarded-for': req.headers.get('x-forwarded-for') || '',
+        'x-real-ip': req.headers.get('x-real-ip') || '',
+      },
+      body: JSON.stringify({
+        trace,
+        licenseKey,
+        projectId,
+        action,
+        status,
+        details,
+      }),
+    }).catch(err => {
+      console.warn('[Retrivora Telemetry] Async report warning:', err.message);
+    });
+  } catch {
+    /* non-blocking */
+  }
+}
+
 // ─── SSE helpers ──────────────────────────────────────────────────────────────
 
 /**
@@ -194,17 +250,6 @@ const SSE_HEADERS: Record<string, string> = {
 
 /**
  * createChatHandler — factory that returns a Next.js App Router POST handler.
- *
- * Accepts either a full/partial `RagConfig` **or** a pre-built `VectorPlugin`
- * instance (preferred for singleton/multi-tenant setups).
- *
- * @example
- * // Option A — pass config (plugin created once at module load time)
- * export const POST = createChatHandler(getRagConfig());
- *
- * // Option B — pass a pre-built plugin (most flexible)
- * const plugin = new VectorPlugin(getRagConfig());
- * export const POST = createChatHandler(plugin);
  */
 export function createChatHandler(
   configOrPlugin?: Partial<RagConfig> | VectorPlugin,
@@ -261,6 +306,8 @@ export function createChatHandler(
         trace: result.trace,
       }).catch(err => console.warn('[createChatHandler] Failed to save assistant message:', err));
 
+      reportTelemetry(req, plugin, 'QUERY_GENERATION', 'success', `Tokens: ${result.trace?.tokens?.totalTokens || 0}, Latency: ${result.trace?.latency?.totalMs || 0}ms`, result.trace);
+
       return NextResponse.json({
         ...result,
         messageId: assistantMsgId,
@@ -268,6 +315,7 @@ export function createChatHandler(
       });
     } catch (err) {
       const message = err instanceof Error ? err.message : 'Internal server error';
+      reportTelemetry(req, plugin, 'QUERY_GENERATION', 'error', message);
       return NextResponse.json({ error: message }, { status: 500 });
     }
   };
@@ -275,25 +323,6 @@ export function createChatHandler(
 
 /**
  * createStreamHandler — factory for a streaming SSE Next.js App Router POST handler.
- *
- * Streams the assistant response as Server-Sent Events (SSE). Each frame is a
- * JSON object with a `type` discriminant:
- *   - `{ type: "text",     text: "..." }`       — incremental text chunk
- *   - `{ type: "metadata", sources: [...] }`    — retrieval metadata (last frame)
- *   - `{ type: "error",    error: "..." }`       — stream-level error
- *
- * @example
- * // src/app/api/chat/route.ts
- * export const POST = createStreamHandler(getRagConfig());
- *
- * // Client-side parsing in useRagChat.ts:
- * // const lines = chunk.split('\n');
- * // for (const line of lines) {
- * //   if (line.startsWith('data: ')) {
- * //     const frame = JSON.parse(line.slice(6));
- * //     if (frame.type === 'text') { ... }
- * //   }
- * // }
  */
 export function createStreamHandler(
   configOrPlugin?: Partial<RagConfig> | VectorPlugin,
@@ -311,7 +340,6 @@ export function createStreamHandler(
     const rateLimited = checkRateLimit(req);
     if (rateLimited) return rateLimited;
 
-    // Parse body first so we can return a normal JSON 400 before opening the stream
     let body: {
       message?: string;
       history?: ChatMessage[];
@@ -380,11 +408,9 @@ export function createStreamHandler(
               // Retrieval metadata object — always the final frame
               enqueue(sseMetaFrame(chunk));
 
-              // ── LLM-driven visualization decision ─────────────────────────
               const responseChunk = chunk as ChatResponse;
               const sources = responseChunk?.sources || [];
 
-              // Emit observability trace if present
               if (responseChunk?.trace) {
                 enqueue(sseObservabilityFrame(responseChunk.trace));
               }
@@ -392,9 +418,6 @@ export function createStreamHandler(
               let uiTransformation = responseChunk?.ui_transformation;
               if (sources.length > 0) {
                 try {
-                  // The pipeline already computed ui_transformation inside askStream().
-                  // We ONLY fall back to the cheap heuristic transform (no LLM call) when
-                  // the pipeline didn't produce one — never call analyzeAndDecide() here.
                   uiTransformation =
                     responseChunk?.ui_transformation ??
                     UITransformer.transform(message, sources, plugin.getConfig());
@@ -423,14 +446,16 @@ export function createStreamHandler(
                 uiTransformation,
                 trace: responseChunk?.trace,
               }).catch(err => console.warn('[createStreamHandler] Failed to save assistant message:', err));
+
+              reportTelemetry(req, plugin, 'QUERY_GENERATION', 'success', `Tokens: ${responseChunk?.trace?.tokens?.totalTokens || 0}, Latency: ${responseChunk?.trace?.latency?.totalMs || 0}ms`, responseChunk?.trace);
             }
           }
         } catch (streamError) {
-          // Do not log or enqueue errors if the client intentionally cancelled/aborted
           if (isActive) {
             const errorMessage =
               streamError instanceof Error ? streamError.message : String(streamError);
             console.error('[createStreamHandler] Stream error:', streamError);
+            reportTelemetry(req, plugin, 'QUERY_GENERATION', 'error', errorMessage);
             try {
               enqueue(sseErrorFrame(errorMessage));
             } catch { /* silent */ }
@@ -480,9 +505,11 @@ export function createIngestHandler(
       }
 
       const results = await plugin.ingest(documents, namespace);
+      reportTelemetry(req, plugin, 'DOCUMENT_INGESTION', 'success', `Ingested ${documents.length} document(s)`);
       return NextResponse.json({ results });
     } catch (err) {
       const message = err instanceof Error ? err.message : 'Internal server error';
+      reportTelemetry(req, plugin, 'DOCUMENT_INGESTION', 'error', message);
       return NextResponse.json({ error: message }, { status: 500 });
     }
   };
@@ -560,20 +587,15 @@ export function createUploadHandler(
             for (const row of parsed.data) {
               i++;
               const rowData = row as Record<string, string>;
-              
-              // Dynamically determine the grouping key (typically the first column like ID or Handle)
               const groupingKey = Object.keys(rowData)[0];
               
-              // Forward-fill ALL empty columns for variants belonging to the same group
               if (lastRowData && groupingKey && rowData[groupingKey] && rowData[groupingKey] === lastRowData[groupingKey]) {
                 for (const key of Object.keys(rowData)) {
-                  // Forward-fill if the current row lacks the field but the previous row has it
                   if (!rowData[key] && lastRowData[key]) {
                     rowData[key] = lastRowData[key];
                   }
                 }
               }
-              // Save a copy of the filled rowData for the next iteration
               lastRowData = { ...rowData };
               
               const contentParts: string[] = [];
@@ -615,9 +637,11 @@ export function createUploadHandler(
       }
 
       const results = await plugin.ingest(documents, namespace);
+      reportTelemetry(req, plugin, 'DOCUMENT_INGESTION', 'success', `Uploaded & ingested ${files.length} file(s)`);
       return NextResponse.json({ message: 'Upload successful', results });
     } catch (err) {
       const message = err instanceof Error ? err.message : 'Upload failed';
+      reportTelemetry(req, plugin, 'DOCUMENT_INGESTION', 'error', message);
       return NextResponse.json({ error: message }, { status: 500 });
     }
   };
@@ -625,6 +649,7 @@ export function createUploadHandler(
 
 /**
  * createSuggestionsHandler — factory for the auto-suggestions endpoint.
+ * Supports both POST (JSON body) and GET (URL search parameters).
  */
 export function createSuggestionsHandler(
   configOrPlugin?: Partial<RagConfig> | VectorPlugin,
@@ -633,25 +658,34 @@ export function createSuggestionsHandler(
   const plugin = getOrCreatePlugin(configOrPlugin);
   const onAuthorize = options?.onAuthorize;
 
-  return async function POST(req: NextRequest) {
+  return async function handler(req: NextRequest) {
     const authResult = await checkAuth(req, onAuthorize);
     if (authResult) return authResult as any;
 
     try {
-      const body = await req.json();
-      const { query, namespace } = body as {
-        query: string;
-        namespace?: string;
-      };
+      let query = '';
+      let namespace: string | undefined = undefined;
+
+      if (req.method === 'POST') {
+        const body = await req.json().catch(() => ({}));
+        query = body.query || '';
+        namespace = body.namespace;
+      } else {
+        const url = new URL(req.url);
+        query = url.searchParams.get('query') || '';
+        namespace = url.searchParams.get('namespace') || undefined;
+      }
 
       if (typeof query !== 'string') {
         return NextResponse.json({ error: 'query is required' }, { status: 400 });
       }
 
       const suggestions = await plugin.getSuggestions(query, namespace);
+      reportTelemetry(req, plugin, 'AUTO_SUGGESTIONS', 'success', `Fetched ${suggestions.length} suggestions for: ${query.slice(0, 30)}`);
       return NextResponse.json({ suggestions });
     } catch (err) {
       const message = err instanceof Error ? err.message : 'Internal server error';
+      reportTelemetry(req, plugin, 'AUTO_SUGGESTIONS', 'error', message);
       return NextResponse.json({ error: message }, { status: 500 });
     }
   };
@@ -828,6 +862,8 @@ export function createRagHandler(
     switch (segment) {
       case 'health':
         return healthHandler(req);
+      case 'suggestions':
+        return suggestionsHandler(req);
       case 'history':
         return historyHandler(req);
       case 'feedback':