@retrivora-ai/rag-engine 2.2.9 → 2.3.1

package/src/handlers/index.ts

@@ -5,16 +5,38 @@ import { ChatMessage, ChatResponse } from '../types';
 import { DocumentParser } from '../utils/DocumentParser';
 import { UITransformer } from '../utils/UITransformer';
 import { DatabaseStorage, HistoryMessage } from '../core/DatabaseStorage';
-import { LicenseVerifier } from '../core/LicenseVerifier';
+import { LicenseVerifier, LicensePayload } from '../core/LicenseVerifier';
 import { SDK_VERSION } from '../version';
+import { FreeTierLimitsGuard, FREE_TIER_QUOTAS } from '../core/FreeTierLimitsGuard';
 
+/**
+ * Shared options accepted by every handler factory.
+ *
+ * Pass `onAuthorize` to plug in per-request auth rules; the callback is
+ * called before rate-limiting, license enforcement, or any business logic
+ * runs.  Return `true` or the resolved promise `true` to allow, `false`
+ * to get a 401, or return a `Response` to fully control the denial (for
+ * example redirecting an OAuth-style flow to a login page).
+ */
 export interface HandlerOptions {
-  onAuthorize?: (req: NextRequest) => boolean | Promise<boolean> | Response | Promise<Response>;
+  /** Optional synchronous or asynchronous authorization gate. */
+  onAuthorize?: (req: NextRequest) => boolean | Response | Promise<boolean | Response>;
+  /**
+   * Optional scope resolver for multi-tenant deployments.
+   *
+   * Returns an allow-list of project ids that the caller is authorized to
+   * access on the `sessions`, `history`, and `feedback` endpoints. When
+   * the callback returns a non-empty array, server-side filtering is
+   * applied to every `listSessions`, `getHistory`, `clearHistory`,
+   * `listFeedback`, and `getFeedback` call so the caller can never leak
+   * another tenant's data even when client-side filters are tampered with.
+   */
+  onResolveScope?: (req: NextRequest) => string[] | undefined | Promise<string[] | undefined>;
 }
 
 async function checkAuth(
   req: NextRequest,
-  onAuthorize?: (req: NextRequest) => boolean | Promise<boolean> | Response | Promise<Response>
+  onAuthorize?: (req: NextRequest) => boolean | Response | Promise<boolean | Response>
 ): Promise<Response | null> {
   if (!onAuthorize) return null;
   try {
@@ -109,6 +131,115 @@ function checkRateLimit(req: NextRequest): Response | null {
   return null;
 }
 
+// ─── Free Tier Limits Guard ───────────────────────────────────────────────────
+
+const FREE_TIER_NAMES = new Set(['hobby', 'free', 'free_trial', 'trial']);
+
+function isFreeTier(tier?: string | null): boolean {
+  if (!tier) return true;
+  return FREE_TIER_NAMES.has(tier.toLowerCase().trim());
+}
+
+const _freeTierGuardInstance: any = _g.__retrivoraFreeTierGuard ??
+  (_g.__retrivoraFreeTierGuard = new (FreeTierLimitsGuard as any)());
+
+function createPaymentRequiredResponse(reason: string, details?: Record<string, unknown>): Response {
+  const body = {
+    type: 'https://retrivora.com/docs/errors/payment-required',
+    title: 'Payment Required',
+    status: 402,
+    detail: reason,
+    code: 'FREE_TIER_LIMIT_EXCEEDED',
+    instance: undefined as string | undefined,
+    ...(details ?? {}),
+    quota: {
+      maxDailyRequestUnits: FREE_TIER_QUOTAS.MAX_DAILY_REQUEST_UNITS,
+      maxTrialRequestUnits: FREE_TIER_QUOTAS.MAX_TRIAL_REQUEST_UNITS,
+      maxDocuments: FREE_TIER_QUOTAS.MAX_DOCUMENTS,
+      maxStorageBytes: FREE_TIER_QUOTAS.MAX_STORAGE_BYTES,
+      upgradeUrl: 'https://retrivora.com/pricing',
+    },
+  };
+  return new Response(JSON.stringify(body), {
+    status: 402,
+    headers: {
+      'Content-Type': 'application/problem+json',
+    },
+  });
+}
+
+// ─── License Enforcement ──────────────────────────────────────────────────────
+
+/**
+ * Resolve the license key from a request, trying (in priority order):
+ *   1. `x-license-key` header
+ *   2. Body property `licenseKey` (already-parsed body, optional)
+ *   3. `Authorization: Bearer <key>` header
+ *   4. SDK/plugin config and environment variables
+ */
+function resolveLicenseKey(
+  req: NextRequest,
+  config: RagConfig,
+  bodyLicenseKey?: string
+): string {
+  return (
+    req.headers.get('x-license-key') ||
+    bodyLicenseKey ||
+    req.headers.get('authorization')?.replace(/^Bearer\s+/i, '') ||
+    config.licenseKey ||
+    process.env.NEXT_PUBLIC_RETRIVORA_LICENSE_KEY ||
+    process.env.RETRIVORA_LICENSE_KEY ||
+    process.env.RAG_LICENSE_KEY ||
+    ''
+  );
+}
+
+/**
+ * Enforce a valid Retrivora license key.
+ *
+ * - Extracts license key from headers / body / env / config
+ * - Performs cryptographic + expiration validation via `LicenseVerifier.verify`
+ * - Returns `null` when validation passes (contains the decoded payload for future tier checks)
+ * - Returns a 403 Response ready to be sent when validation fails
+ *
+ * In development (`NODE_ENV !== 'production'`) a missing key still produces a
+ * console warning but passes (fail-open local-dev behavior); in production any
+ * invalid / expired / missing key produces a hard 403.
+ */
+function enforceLicense(
+  req: NextRequest,
+  config: RagConfig,
+  bodyLicenseKey?: string
+): { ok: true; payload: LicensePayload } | { ok: false; response: Response } {
+  const rawKey = resolveLicenseKey(req, config, bodyLicenseKey);
+  const licenseKey = (rawKey || '').trim().replace(/^["']|["']$/g, '').trim();
+  const projectId = config.projectId || 'my-rag-app';
+
+  try {
+    const payload = LicenseVerifier.verify(licenseKey, projectId);
+    return { ok: true, payload };
+  } catch (err: any) {
+    const message =
+      err instanceof Error
+        ? err.message
+        : 'Missing or invalid RETRIVORA_LICENSE_KEY. Set NEXT_PUBLIC_RETRIVORA_LICENSE_KEY in your environment or contact your administrator.';
+    const body = {
+      error: {
+        code: 'LICENSE_REVOKED',
+        message: 'Your Retrivora license key has been terminated, suspended, or revoked. Access denied.',
+      },
+      details: message,
+    };
+    return {
+      ok: false,
+      response: new Response(JSON.stringify(body), {
+        status: 403,
+        headers: { 'Content-Type': 'application/json' },
+      }),
+    };
+  }
+}
+
 // ─── Input Sanitization ───────────────────────────────────────────────────────
 
 const MAX_MESSAGE_LENGTH = 8000;
@@ -205,8 +336,6 @@ function reportTelemetry(
       details,
     };
 
-    console.log(`[Retrivora SDK Telemetry] Dispatching telemetry -> Feature: "${action}", Status: "${status}", Project: "${projectId}", Latency: ${latencyMs}ms`);
-
     fetch(absoluteUrl, {
       method: 'POST',
       headers: {
@@ -272,7 +401,29 @@ const SSE_HEADERS: Record<string, string> = {
 // ─── Handler Factories ────────────────────────────────────────────────────────
 
 /**
- * createChatHandler — factory that returns a Next.js App Router POST handler.
+ * Build a Next.js App Router POST handler for **synchronous** RAG chat.
+ *
+ * Pipeline (in execution order):
+ *   1. `options.onAuthorize` — custom authorization gate (optional)
+ *   2. In-memory IP rate limiter (30 req / 60 s sliding window)
+ *   3. JSON body parse → `enforceLicense()` RSA signature validation
+ *   4. Input sanitization + length / toxicity / PII / prompt-injection heuristics
+ *   5. User-message persistence via `DatabaseStorage`
+ *   6. LLM-driven RAG retrieval via `plugin.chat()`
+ *   7. Observability UI transformation + response persistence
+ *   8. JSON response (`ChatResponse` shape)
+ *
+ * Use this handler when you don't need streaming (e.g. server-side SDKs).
+ * For streaming use `createStreamHandler` — the same pipeline but with
+ * Server-Sent Events for incremental tokens.
+ *
+ * @param configOrPlugin - Either a partial `RagConfig` (a plugin will be
+ *                         created or reused for you) or an already-constructed
+ *                         `VectorPlugin` instance.
+ * @param options         - See `HandlerOptions`.  `onAuthorize` is recommended
+ *                         for multi-tenant deployments to gate access.
+ * @returns An async `POST(req, ctx)` function suitable for being the default
+ *          export of a Next.js route file.
  */
 export function createChatHandler(
   configOrPlugin?: Partial<RagConfig> | VectorPlugin,
@@ -290,9 +441,38 @@ export function createChatHandler(
     const rateLimited = checkRateLimit(req);
     if (rateLimited) return rateLimited;
 
+    const config = plugin.getConfig();
+
     try {
       const body = await req.json();
       const bodyObj = (body ?? {}) as any;
+
+      // 2. License enforcement (after body parse so we can read body.licenseKey)
+      const licenseCheck = enforceLicense(req as NextRequest, config, bodyObj?.licenseKey);
+      if (!licenseCheck.ok) return licenseCheck.response as any;
+
+      // 2b. Free Tier limits check (hobby / free / free_trial tiers)
+      if (isFreeTier(licenseCheck.payload.tier)) {
+        const estimatedInputTokens = Math.ceil(
+          ((bodyObj.message?.length || 0) +
+            (Array.isArray(bodyObj.messages)
+              ? bodyObj.messages.reduce((a: number, m: any) => a + (m?.content?.length || m?.text?.length || 0), 0)
+              : 0) +
+            (bodyObj.history?.reduce((a: number, m: any) => a + (m?.content?.length || m?.text?.length || 0), 0) || 0)) / 4
+        );
+        const chatCheck = (FreeTierLimitsGuard as any).checkRequestAllowed({
+          operationType: 'chat',
+          inputTokens: estimatedInputTokens,
+          projectId: licenseCheck.payload.projectId,
+        });
+        if (!chatCheck.allowed) {
+          return createPaymentRequiredResponse(
+            chatCheck.reason || 'Free tier quota exceeded.',
+            { tier: licenseCheck.payload.tier, projectId: licenseCheck.payload.projectId }
+          );
+        }
+      }
+
       let rawMessage = bodyObj.message;
       if (!rawMessage && Array.isArray(bodyObj.messages) && bodyObj.messages.length > 0) {
         const lastMsg = bodyObj.messages[bodyObj.messages.length - 1];
@@ -304,7 +484,7 @@ export function createChatHandler(
       const history = bodyObj.history || (Array.isArray(bodyObj.messages) ? bodyObj.messages.slice(0, -1) : []);
       const { namespace, sessionId = 'default', messageId, userMessageId } = bodyObj;
 
-      // 2. Input sanitization
+      // 3. Input sanitization
       const sanitized = sanitizeInput(rawMessage ?? '');
       if (!sanitized.ok) {
         return NextResponse.json({ error: { code: 'INVALID_INPUT', message: sanitized.error } }, { status: 400 });
@@ -348,7 +528,30 @@ export function createChatHandler(
 }
 
 /**
- * createStreamHandler — factory for a streaming SSE Next.js App Router POST handler.
+ * Build a Next.js App Router POST handler for **streaming** RAG chat via SSE.
+ *
+ * Same pipeline as `createChatHandler`, but the `plugin.chat()` call is run
+ * in streaming mode and every token is immediately emitted as a Server-Sent
+ * Event frame. The stream contains frames for `text`, `thinking`,
+ * `metadata`, `ui_transformation`, `observability`, and a terminal `done`.
+ *
+ * Multipart upload short-circuit: When the request `Content-Type` is
+ * `multipart/form-data` the request is transparently delegated to
+ * `createUploadHandler` (which also runs its own `enforceLicense()` gate).
+ *
+ * Pipeline (in execution order):
+ *   1. `options.onAuthorize` — custom authorization gate (optional)
+ *   2. In-memory IP rate limiter (30 req / 60 s sliding window)
+ *   3. JSON body parse (or form-data upload delegation)
+ *   4. `enforceLicense()` RSA signature validation — 403 if missing / terminated
+ *   5. Input sanitization + length / toxicity / PII / prompt-injection heuristics
+ *   6. User-message persistence via `DatabaseStorage`
+ *   7. Streaming RAG retrieval via `plugin.chat({ stream: true })`
+ *   8. Persist assistant message + emit SSE frames
+ *
+ * @param configOrPlugin - Partial `RagConfig` or an existing `VectorPlugin`.
+ * @param options         - See `HandlerOptions`.
+ * @returns Async `POST(req, ctx)` function for `app/.../route.ts`.
  */
 export function createStreamHandler(
   configOrPlugin?: Partial<RagConfig> | VectorPlugin,
@@ -366,6 +569,8 @@ export function createStreamHandler(
     const rateLimited = checkRateLimit(req);
     if (rateLimited) return rateLimited;
 
+    const config = plugin.getConfig();
+
     let body: {
       message?: string;
       history?: ChatMessage[];
@@ -373,9 +578,11 @@ export function createStreamHandler(
       sessionId?: string;
       messageId?: string;
       userMessageId?: string;
+      licenseKey?: string;
     };
     try {
       if (req.headers.get('content-type')?.includes('multipart/form-data')) {
+        // Uploads bypass the JSON body parse — createUploadHandler enforces its own license check
         const uploader = createUploadHandler(plugin, { onAuthorize });
         return uploader(req);
       }
@@ -388,6 +595,33 @@ export function createStreamHandler(
     }
 
     const bodyObj = (body ?? {}) as any;
+
+    // 2b. License enforcement (for JSON-body requests)
+    const licenseCheck = enforceLicense(req as NextRequest, config, bodyObj?.licenseKey);
+    if (!licenseCheck.ok) return licenseCheck.response as any;
+
+    // 2c. Free Tier limits check (hobby / free / free_trial tiers)
+    if (isFreeTier(licenseCheck.payload.tier)) {
+      const estimatedInputTokens = Math.ceil(
+        ((bodyObj.message?.length || 0) +
+          (Array.isArray(bodyObj.messages)
+            ? bodyObj.messages.reduce((a: number, m: any) => a + (m?.content?.length || m?.text?.length || 0), 0)
+            : 0) +
+          (bodyObj.history?.reduce((a: number, m: any) => a + (m?.content?.length || m?.text?.length || 0), 0) || 0)) / 4
+      );
+      const chatCheck = (FreeTierLimitsGuard as any).checkRequestAllowed({
+        operationType: 'chat_stream',
+        inputTokens: estimatedInputTokens,
+        projectId: licenseCheck.payload.projectId,
+      });
+      if (!chatCheck.allowed) {
+        return createPaymentRequiredResponse(
+          chatCheck.reason || 'Free tier quota exceeded.',
+          { tier: licenseCheck.payload.tier, projectId: licenseCheck.payload.projectId }
+        );
+      }
+    }
+
     let rawMessage = bodyObj.message;
     if (!rawMessage && Array.isArray(bodyObj.messages) && bodyObj.messages.length > 0) {
       const lastMsg = bodyObj.messages[bodyObj.messages.length - 1];
@@ -399,7 +633,7 @@ export function createStreamHandler(
     const history = bodyObj.history || (Array.isArray(bodyObj.messages) ? bodyObj.messages.slice(0, -1) : []);
     const { namespace, sessionId = 'default', messageId, userMessageId } = bodyObj;
 
-    // 2. Input sanitization
+    // 3. Input sanitization
     const sanitized = sanitizeInput(rawMessage ?? '');
     if (!sanitized.ok) {
       return new Response(
@@ -530,7 +764,19 @@ export function createStreamHandler(
 }
 
 /**
- * createIngestHandler — factory for the document ingestion endpoint.
+ * Build a POST handler that ingests raw pre-parsed documents into the vector DB.
+ *
+ * Unlike `createUploadHandler` (which takes files and does parsing/splitting),
+ * this endpoint expects the caller to supply `documents[]` already split and
+ * prepared. This is useful for bulk backfill jobs, migrations, or programmatic
+ * sync pipelines.
+ *
+ * Security: Requires a valid license (RSA signature check via `enforceLicense`)
+ * AFTER JSON body parse so the optional `body.licenseKey` override is read.
+ *
+ * @param configOrPlugin - Partial `RagConfig` or existing `VectorPlugin`.
+ * @param options         - Optional `onAuthorize` gate.
+ * @returns Async POST handler.
  */
 export function createIngestHandler(
   configOrPlugin?: Partial<RagConfig> | VectorPlugin,
@@ -543,8 +789,15 @@ export function createIngestHandler(
     const authResult = await checkAuth(req, onAuthorize);
     if (authResult) return authResult as any;
 
+    const config = plugin.getConfig();
+
     try {
       const body = await req.json();
+
+      // License enforcement before ingestion
+      const licenseCheck = enforceLicense(req as NextRequest, config, body?.licenseKey);
+      if (!licenseCheck.ok) return licenseCheck.response as any;
+
       const { documents, namespace } = body as {
         documents: Array<{ docId: string; content: string; metadata?: Record<string, unknown> }>;
         namespace?: string;
@@ -554,6 +807,29 @@ export function createIngestHandler(
         return NextResponse.json({ error: 'documents array is required' }, { status: 400 });
       }
 
+      // Free Tier ingestion limits check
+      if (isFreeTier(licenseCheck.payload.tier)) {
+        const totalIncomingBytes = documents.reduce(
+          (sum, d) => sum + Buffer.byteLength(d.content || '', 'utf8'),
+          0
+        );
+        const ingestCheck = (FreeTierLimitsGuard as any).checkIngestionAllowed(
+          { documentCount: documents.length },
+          totalIncomingBytes
+        );
+        if (!ingestCheck.allowed) {
+          return createPaymentRequiredResponse(
+            ingestCheck.reason || 'Free tier ingestion limit reached.',
+            {
+              tier: licenseCheck.payload.tier,
+              projectId: licenseCheck.payload.projectId,
+              documents: documents.length,
+              incomingBytes: totalIncomingBytes,
+            }
+          );
+        }
+      }
+
       const results = await plugin.ingest(documents, namespace);
       reportTelemetry(req, plugin, 'DOCUMENT_INGESTION', 'success', `Ingested ${documents.length} document(s)`);
       return NextResponse.json({ results });
@@ -566,7 +842,28 @@ export function createIngestHandler(
 }
 
 /**
- * createHealthHandler — factory for the health-check endpoint.
+ * Build a GET handler that returns health / readiness status.
+ *
+ * Response shape (200 OK):
+ * ```json
+ * {
+ *   "ok": true,
+ *   "status": "healthy",
+ *   "sdkVersion": "x.y.z",
+ *   "timestamp": "ISO string",
+ *   "embedding": { "provider": "...", "ok": true  },
+ *   "vectorStore": { "provider": "...", "ok": true }
+ * }
+ * ```
+ *
+ * License check: This endpoint is intentionally **NOT** license-gated so
+ * orchestrators (Kubernetes, uptime probes, Vercel cron pings) can use it
+ * to assert the process is alive even when no license has been configured
+ * yet during deploy.
+ *
+ * @param configOrPlugin - Partial `RagConfig` or existing `VectorPlugin`.
+ * @param options         - Optional `onAuthorize` gate (rarely used here).
+ * @returns Async GET handler.
  */
 export function createHealthHandler(
   configOrPlugin?: Partial<RagConfig> | VectorPlugin,
@@ -597,7 +894,19 @@ export function createHealthHandler(
 }
 
 /**
- * createLicenseHandler — factory for the license validation endpoint (/v1/license/validate).
+ * Build a POST handler for the SDK-facing `/v1/license/validate` endpoint.
+ *
+ * Client flow: `LicenseValidator.validate()` calls this URL, receives
+ * authoritative DB-backed status (ACTIVE / TERMINATED / SUSPENDED / EXPIRED /
+ * REVOKED), and falls back to pure-local `LicenseVerifier.verify()` if the
+ * server is unreachable or returns an error.
+ *
+ * This handler does NOT enforce license — it is the verifier itself. It does,
+ * however, still apply rate limiting to mitigate abuse.
+ *
+ * @param configOrPlugin - Partial `RagConfig` or existing `VectorPlugin`.
+ * @param options         - Optional `onAuthorize` gate.
+ * @returns Async POST handler returning `LicenseValidationResponse` JSON.
  */
 export function createLicenseHandler(
   configOrPlugin?: Partial<RagConfig> | VectorPlugin,
@@ -615,15 +924,17 @@ export function createLicenseHandler(
     try {
       const body = await req.json().catch(() => ({}));
       const config = plugin.getConfig();
-      const licenseKey =
+      const rawKey =
         req.headers.get('x-license-key') ||
         body?.licenseKey ||
         req.headers.get('authorization')?.replace(/^Bearer\s+/i, '') ||
         config.licenseKey ||
-        process.env.RETRIVORA_LICENSE_KEY ||
         process.env.NEXT_PUBLIC_RETRIVORA_LICENSE_KEY ||
+        process.env.RETRIVORA_LICENSE_KEY ||
         '';
 
+      const licenseKey = (rawKey || '').trim().replace(/^["']|["']$/g, '').trim();
+
       const projectId = body?.projectId || config.projectId || 'my-rag-app';
 
       const payload = LicenseVerifier.verify(licenseKey, projectId);
@@ -655,7 +966,21 @@ export function createLicenseHandler(
 }
 
 /**
- * createUploadHandler — factory for the file upload ingestion endpoint.
+ * Build a POST handler that accepts `multipart/form-data` file uploads.
+ *
+ * Workflow:
+ *   1. `onAuthorize` → license enforcement via `enforceLicense` (no JSON body,
+ *      so the key must come from headers or the environment).
+ *   2. Read FormData files[] list → max 25 files per request, 100 MB each.
+ *   3. Per-file: use `DocumentParser` to extract raw text by MIME type (PDF,
+ *      DOCX, TXT, MD, HTML, JSON, CSV, images via OCR fallback, etc.).
+ *   4. Chunk by the configured chunker (RecursiveCharacter, semantic, etc.).
+ *   5. Call `plugin.ingest()` to embed and insert into the vector store.
+ *   6. Return JSON summary per file (status, chunks ingested, docId).
+ *
+ * @param configOrPlugin - Partial `RagConfig` or existing `VectorPlugin`.
+ * @param options         - Optional `onAuthorize` gate.
+ * @returns Async POST handler.
  */
 export function createUploadHandler(
   configOrPlugin?: Partial<RagConfig> | VectorPlugin,
@@ -668,6 +993,11 @@ export function createUploadHandler(
     const authResult = await checkAuth(req, onAuthorize);
     if (authResult) return authResult as any;
 
+    // License enforcement (uploads use headers/env for license key, no JSON body)
+    const config = plugin.getConfig();
+    const licenseCheck = enforceLicense(req as NextRequest, config);
+    if (!licenseCheck.ok) return licenseCheck.response as any;
+
     try {
       const formData = await req.formData();
       const files = formData.getAll('files') as File[];
@@ -679,6 +1009,28 @@ export function createUploadHandler(
         return NextResponse.json({ error: 'No files provided' }, { status: 400 });
       }
 
+      // Free Tier upload limits check (before parsing to fail fast on large uploads)
+      if (isFreeTier(licenseCheck.payload.tier)) {
+        const totalUploadBytes = files.reduce((sum, f) => sum + (f.size || 0), 0);
+        const uploadCheck = (FreeTierLimitsGuard as any).checkIngestionAllowed(
+          { documentCount: files.length },
+          totalUploadBytes
+        );
+        if (!uploadCheck.allowed) {
+          return createPaymentRequiredResponse(
+            uploadCheck.reason || 'Free tier upload limit reached.',
+            {
+              tier: licenseCheck.payload.tier,
+              projectId: licenseCheck.payload.projectId,
+              fileCount: files.length,
+              totalUploadBytes,
+              maxFileSizeBytes: FREE_TIER_QUOTAS.MAX_FILE_SIZE_BYTES,
+              maxStorageBytes: FREE_TIER_QUOTAS.MAX_STORAGE_BYTES,
+            }
+          );
+        }
+      }
+
       const documents: { docId: string; content: string; metadata?: Record<string, unknown> }[] = [];
 
       for (const file of files) {
@@ -803,8 +1155,21 @@ export function createUploadHandler(
 }
 
 /**
- * createSuggestionsHandler — factory for the auto-suggestions endpoint.
- * Supports both POST (JSON body) and GET (URL search parameters).
+ * Build a GET/POST handler for auto-suggestions (used by ChatWidget prompt chips).
+ *
+ * Requests:
+ *   - GET  `?query=...&namespace=...`
+ *   - POST `{ query: string, namespace?: string, licenseKey?: string }`
+ *
+ * Response (200 OK): `{ suggestions: string[] }`
+ *
+ * License enforcement: Runs BEFORE body parse on headers/env, and if the POST
+ * body contains a `licenseKey` override the check is repeated with the body
+ * key included so the per-request override is honored.
+ *
+ * @param configOrPlugin - Partial `RagConfig` or existing `VectorPlugin`.
+ * @param options         - Optional `onAuthorize` gate.
+ * @returns Async handler accepting both GET and POST methods.
  */
 export function createSuggestionsHandler(
   configOrPlugin?: Partial<RagConfig> | VectorPlugin,
@@ -817,14 +1182,26 @@ export function createSuggestionsHandler(
     const authResult = await checkAuth(req, onAuthorize);
     if (authResult) return authResult as any;
 
+    // License enforcement for auto-suggestions endpoint
+    const config = plugin.getConfig();
+    const licenseCheck = enforceLicense(req, config);
+    if (!licenseCheck.ok) return licenseCheck.response as any;
+
     try {
       let query = '';
       let namespace: string | undefined = undefined;
+      let bodyLicenseKey: string | undefined = undefined;
 
       if (req.method === 'POST') {
         const body = await req.json().catch(() => ({}));
         query = body.query || '';
         namespace = body.namespace;
+        bodyLicenseKey = body.licenseKey;
+        // Re-check license if body contained a key override
+        if (bodyLicenseKey) {
+          const recheck = enforceLicense(req, config, bodyLicenseKey);
+          if (!recheck.ok) return recheck.response as any;
+        }
       } else {
         const url = new URL(req.url);
         query = url.searchParams.get('query') || '';
@@ -847,7 +1224,19 @@ export function createSuggestionsHandler(
 }
 
 /**
- * createHistoryHandler — factory for GET /api/retrivora/history and POST /api/retrivora/history/clear.
+ * Build a handler for chat-history listing and clearing.
+ *
+ * Routes dispatched by `createRagHandler`:
+ *   - GET  `/history?sessionId=...&limit=...` → returns `{ messages: HistoryMessage[] }`
+ *   - POST `/history/clear` with `{ sessionId? }` JSON body → returns `{ ok: true }`
+ *
+ * Storage: Uses `DatabaseStorage` (default SQLite or custom configured driver).
+ * License enforcement is handled by the upstream `createRagHandler` router when
+ * this handler is composed through it; standalone usage is rare.
+ *
+ * @param configOrPlugin - Partial `RagConfig` or existing `VectorPlugin`.
+ * @param options         - Optional `onAuthorize` gate.
+ * @returns Async handler accepting GET (list) or POST (clear) methods.
  */
 export function createHistoryHandler(
   configOrPlugin?: Partial<RagConfig> | VectorPlugin,
@@ -856,17 +1245,20 @@ export function createHistoryHandler(
   const plugin = getOrCreatePlugin(configOrPlugin);
   const storage = new DatabaseStorage(plugin.getConfig());
   const onAuthorize = options?.onAuthorize;
+  const onResolveScope = options?.onResolveScope;
 
   return async function handler(req: NextRequest) {
     const authResult = await checkAuth(req, onAuthorize);
     if (authResult) return authResult as any;
 
+    const scope = onResolveScope ? await onResolveScope(req) : undefined;
+
     const url = new URL(req.url);
     const sessionId = url.searchParams.get('sessionId') || 'default';
 
     if (req.method === 'GET') {
       try {
-        const history = await storage.getHistory(sessionId);
+        const history = await storage.getHistory(sessionId, scope);
         return NextResponse.json({ history });
       } catch (err) {
         const message = err instanceof Error ? err.message : 'Failed to fetch history';
@@ -876,7 +1268,7 @@ export function createHistoryHandler(
       try {
         const body = await req.json().catch(() => ({}));
         const sid = body.sessionId || sessionId;
-        await storage.clearHistory(sid);
+        await storage.clearHistory(sid, scope);
         return NextResponse.json({ success: true });
       } catch (err) {
         const message = err instanceof Error ? err.message : 'Failed to clear history';
@@ -888,7 +1280,17 @@ export function createHistoryHandler(
 }
 
 /**
- * createFeedbackHandler — factory for POST /api/retrivora/feedback.
+ * Build a POST handler for collecting thumbs-up / thumbs-down user feedback.
+ *
+ * Request: `{ messageId, sessionId?, rating: 1 | -1, comment?, reason? }`
+ * Response: `{ ok: true, id: string }` (201 Created)
+ *
+ * Feedback is written to `DatabaseStorage.feedback` for RAG pipeline
+ * evaluation, offline fine-tuning dataset curation, and support triage.
+ *
+ * @param configOrPlugin - Partial `RagConfig` or existing `VectorPlugin`.
+ * @param options         - Optional `onAuthorize` gate.
+ * @returns Async POST handler.
  */
 export function createFeedbackHandler(
   configOrPlugin?: Partial<RagConfig> | VectorPlugin,
@@ -897,20 +1299,23 @@ export function createFeedbackHandler(
   const plugin = getOrCreatePlugin(configOrPlugin);
   const storage = new DatabaseStorage(plugin.getConfig());
   const onAuthorize = options?.onAuthorize;
+  const onResolveScope = options?.onResolveScope;
 
   return async function handler(req: NextRequest) {
     const authResult = await checkAuth(req, onAuthorize);
     if (authResult) return authResult as any;
 
+    const scope = onResolveScope ? await onResolveScope(req) : undefined;
+
     if (req.method === 'GET') {
       try {
         const url = new URL(req.url);
         const messageId = url.searchParams.get('messageId');
         if (!messageId) {
-          const feedbackList = await storage.listFeedback();
+          const feedbackList = await storage.listFeedback(scope);
           return NextResponse.json({ feedback: feedbackList });
         }
-        const feedback = await storage.getFeedback(messageId);
+        const feedback = await storage.getFeedback(messageId, scope);
         return NextResponse.json({ feedback });
       } catch (err) {
         const message = err instanceof Error ? err.message : 'Failed to fetch feedback';
@@ -932,6 +1337,17 @@ export function createFeedbackHandler(
         if (!rating) {
           return NextResponse.json({ error: 'rating is required' }, { status: 400 });
         }
+        if (scope && scope.length > 0) {
+          const matches = scope.some(
+            (pid) => pid && (sessionId === pid || sessionId.startsWith(pid) || sessionId.includes(pid))
+          );
+          if (!matches) {
+            return NextResponse.json(
+              { error: 'sessionId is outside the authorized project scope' },
+              { status: 403 }
+            );
+          }
+        }
 
         await storage.saveFeedback({ messageId, sessionId, rating, comment });
         return NextResponse.json({ success: true });
@@ -945,7 +1361,17 @@ export function createFeedbackHandler(
 }
 
 /**
- * createSessionsHandler — factory for GET /api/retrivora/sessions.
+ * Build a GET handler that lists the set of chat sessions.
+ *
+ * Response: `{ sessions: { id, title, lastMessageAt, preview }[] }`
+ *
+ * Sessions are read from `DatabaseStorage`. Combined with `createHistoryHandler`
+ * this enables a sidebar of prior conversations for custom UIs built on top of
+ * the `useRagChat` headless hook.
+ *
+ * @param configOrPlugin - Partial `RagConfig` or existing `VectorPlugin`.
+ * @param options         - Optional `onAuthorize` gate.
+ * @returns Async GET handler returning a session listing.
  */
 export function createSessionsHandler(
   configOrPlugin?: Partial<RagConfig> | VectorPlugin,
@@ -954,15 +1380,16 @@ export function createSessionsHandler(
   const plugin = getOrCreatePlugin(configOrPlugin);
   const storage = new DatabaseStorage(plugin.getConfig());
   const onAuthorize = options?.onAuthorize;
+  const onResolveScope = options?.onResolveScope;
 
   return async function GET(req?: NextRequest) {
     if (req) {
       const authResult = await checkAuth(req, onAuthorize);
       if (authResult) return authResult as any;
     }
-    void req;
     try {
-      const sessions = await storage.listSessions();
+      const scope = req && onResolveScope ? await onResolveScope(req) : undefined;
+      const sessions = await storage.listSessions(scope);
       return NextResponse.json({ sessions });
     } catch (err) {
       const message = err instanceof Error ? err.message : 'Failed to list sessions';
@@ -972,8 +1399,36 @@ export function createSessionsHandler(
 }
 
 /**
- * createRagHandler — factory that returns GET and POST handlers for a catch-all route
- * (e.g. `src/app/api/retrivora/[[...retrivora]]/route.ts`).
+ * Build a Next.js catch-all route that dispatches to every sub-handler by path.
+ *
+ * Intended drop-in export:
+ * ```ts
+ * // app/api/retrivora/[[...retrivora]]/route.ts
+ * import { createRagHandler } from '@retrivora-ai/rag-engine';
+ * const { GET, POST } = createRagHandler({ /* RagConfig *\/ });
+ * export { GET, POST };
+ * ```
+ *
+ * Segments dispatched (POST unless marked GET):
+ *   - `chat`                → createStreamHandler  (SSE streaming chat)
+ *   - `upload`              → createUploadHandler  (file ingestion)
+ *   - `suggestions`         → createSuggestionsHandler (GET/POST)
+ *   - `v1/license/validate` → createLicenseHandler
+ *   - `health`              → createHealthHandler  (GET)
+ *   - `feedback`            → createFeedbackHandler
+ *   - `history`             → createHistoryHandler (GET/POST)
+ *   - `sessions`            → createSessionsHandler (GET)
+ *   - Any other segment     → 404 with a JSON error body
+ *
+ * This is the **recommended** way to mount the SDK in a Next.js app. Using
+ * any single handler individually without its license enforcement gate is a
+ * security anti-pattern — prefer `createRagHandler` unless you have a very
+ * specific reason to split routes up.
+ *
+ * @param configOrPlugin - Partial `RagConfig` or existing `VectorPlugin`.
+ * @param options         - Optional `onAuthorize` gate (propagated to every
+ *                          sub-handler so auth rules apply uniformly).
+ * @returns An object `{ GET, POST }` to re-export as your route file defaults.
  */
 export function createRagHandler(
   configOrPlugin?: Partial<RagConfig> | VectorPlugin,
@@ -981,16 +1436,18 @@ export function createRagHandler(
 ) {
   const plugin = getOrCreatePlugin(configOrPlugin);
   const onAuthorize = options?.onAuthorize;
-
-  const chatHandler = createChatHandler(plugin, { onAuthorize });
-  const streamHandler = createStreamHandler(plugin, { onAuthorize });
-  const uploadHandler = createUploadHandler(plugin, { onAuthorize });
-  const healthHandler = createHealthHandler(plugin, { onAuthorize });
-  const suggestionsHandler = createSuggestionsHandler(plugin, { onAuthorize });
-  const historyHandler = createHistoryHandler(plugin, { onAuthorize });
-  const feedbackHandler = createFeedbackHandler(plugin, { onAuthorize });
-  const sessionsHandler = createSessionsHandler(plugin, { onAuthorize });
-  const licenseHandler = createLicenseHandler(plugin, { onAuthorize });
+  const onResolveScope = options?.onResolveScope;
+  const scopeableOptions: HandlerOptions = { onAuthorize, onResolveScope };
+
+  const chatHandler = createChatHandler(plugin, scopeableOptions);
+  const streamHandler = createStreamHandler(plugin, scopeableOptions);
+  const uploadHandler = createUploadHandler(plugin, scopeableOptions);
+  const healthHandler = createHealthHandler(plugin, scopeableOptions);
+  const suggestionsHandler = createSuggestionsHandler(plugin, scopeableOptions);
+  const historyHandler = createHistoryHandler(plugin, scopeableOptions);
+  const feedbackHandler = createFeedbackHandler(plugin, scopeableOptions);
+  const sessionsHandler = createSessionsHandler(plugin, scopeableOptions);
+  const licenseHandler = createLicenseHandler(plugin, scopeableOptions);
 
   async function routePostRequest(req: any, segment: string) {
     switch (segment) {