@retrivora-ai/rag-engine 2.3.0 → 2.3.1

package/dist/index-DR_O_B-W.d.ts

@@ -0,0 +1,394 @@
+import { NextRequest } from 'next/server';
+import { i as RagConfig, I as ILLMProvider, C as ChatMessage, c as ChatResponse, f as IngestDocument } from './ILLMProvider-teTNQ1lh.js';
+
+interface ValidationError {
+    field: string;
+    message: string;
+    suggestion?: string;
+    severity: 'error' | 'warning';
+}
+/**
+ * ConfigValidator.ts — Comprehensive configuration validation.
+ * Uses a pluggable architecture to delegate provider-specific checks.
+ */
+declare class ConfigValidator {
+    /**
+     * Validates the entire RagConfig object.
+     */
+    static validate(config: RagConfig): Promise<ValidationError[]>;
+    private static validateVectorDbConfig;
+    private static validateLLMConfig;
+    private static validateEmbeddingConfig;
+    /**
+     * Temporary fallbacks for providers not yet migrated to the pluggable architecture.
+     */
+    private static fallbackVectorValidation;
+    private static fallbackLLMValidation;
+    private static fallbackEmbeddingValidation;
+    private static validateUIConfig;
+    private static validateRAGConfig;
+    private static isValidCSSColor;
+    static validateAndThrow(config: RagConfig): Promise<void>;
+}
+
+/**
+ * Interface for provider-specific configuration validation logic.
+ */
+interface IProviderValidator {
+    /**
+     * Validates the configuration for a specific provider.
+     * @param config - The configuration object to validate.
+     * @returns An array of validation errors (empty if valid).
+     */
+    validate(config: Record<string, unknown>): ValidationError[];
+}
+/**
+ * Result of a provider health check.
+ */
+interface HealthCheckResult {
+    healthy: boolean;
+    provider: string;
+    version?: string;
+    capabilities?: Record<string, unknown>;
+    error?: string;
+    timestamp: number;
+}
+/**
+ * Interface for provider-specific health checking logic.
+ */
+interface IProviderHealthChecker {
+    /**
+     * Performs a health check for a specific provider.
+     * @param config - The configuration object used to connect to the provider.
+     * @returns A promise that resolves to the health check result.
+     */
+    check(config: Record<string, unknown>): Promise<HealthCheckResult>;
+}
+
+/**
+ * VectorPlugin — main orchestrator class.
+ * This is the primary interface for host applications.
+ *
+ * Features:
+ * - Configuration resolution from host + environment
+ * - Configuration validation with detailed error messages
+ * - Provider health checks before initialization
+ * - Multi-provider support (Vector DBs & LLMs)
+ * - Per-tenant data isolation via namespacing
+ */
+declare class VectorPlugin {
+    private config;
+    private pipeline;
+    private validationPromise;
+    constructor(hostConfig?: Partial<RagConfig>);
+    /**
+     * Get the current resolved configuration.
+     */
+    getConfig(): RagConfig;
+    /**
+     * Get the initialized LLM provider (available after the first request).
+     * Used by handlers to pass to UITransformer.analyzeAndDecide() for
+     * LLM-driven visualization decisions.
+     */
+    getLLMProvider(): ILLMProvider | undefined;
+    /**
+     * Perform pre-flight health checks on all configured providers.
+     * Useful to verify connectivity before running operations.
+     *
+     * @returns Health status for vector DB, LLM, and embedding providers
+     */
+    checkHealth(): Promise<{
+        vectorDb: HealthCheckResult;
+        llm: HealthCheckResult;
+        embedding?: HealthCheckResult;
+        allHealthy: boolean;
+    }>;
+    private estimateInputTokens;
+    /**
+     * Run a chat query.
+     */
+    chat(message: string, history?: ChatMessage[], namespace?: string): Promise<ChatResponse>;
+    /**
+     * Run a streaming chat query.
+     */
+    chatStream(message: string, history?: ChatMessage[], namespace?: string): AsyncGenerator<string | ChatResponse, void, unknown>;
+    /**
+     * Ingest documents into the vector database.
+     */
+    ingest(documents: IngestDocument[], namespace?: string): Promise<Array<{
+        docId: string | number;
+        chunksIngested: number;
+    }>>;
+    /**
+     * Get auto-suggestions based on a query prefix.
+     */
+    getSuggestions(query: string, namespace?: string): Promise<string[]>;
+}
+
+/**
+ * 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).
+ */
+interface HandlerOptions {
+    /** 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>;
+}
+/**
+ * Encode a payload as a Server-Sent Events frame.
+ *   data: <json>\n\n
+ */
+declare function sseFrame(payload: unknown): string;
+/** Encode a plain text chunk as an SSE frame. */
+declare function sseTextFrame(text: string): string;
+/** Encode the retrieval metadata with UI transformation as an SSE frame. */
+declare function sseMetaFrame(meta: unknown): string;
+/** Encode the UI transformation result as an SSE frame. */
+declare function sseUIFrame(uiTransformation: unknown): string;
+/** Encode the observability trace as an SSE frame. */
+declare function sseObservabilityFrame(trace: unknown): string;
+/** Encode a stream error as an SSE frame. */
+declare function sseErrorFrame(message: string): string;
+/**
+ * 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.
+ */
+declare function createChatHandler(configOrPlugin?: Partial<RagConfig> | VectorPlugin, options?: HandlerOptions): (req: any, context?: any) => Promise<any>;
+/**
+ * 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`.
+ */
+declare function createStreamHandler(configOrPlugin?: Partial<RagConfig> | VectorPlugin, options?: HandlerOptions): (req: any, context?: any) => Promise<any>;
+/**
+ * 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.
+ */
+declare function createIngestHandler(configOrPlugin?: Partial<RagConfig> | VectorPlugin, options?: HandlerOptions): (req: any, context?: any) => Promise<any>;
+/**
+ * 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.
+ */
+declare function createHealthHandler(configOrPlugin?: Partial<RagConfig> | VectorPlugin, options?: HandlerOptions): (req?: NextRequest) => Promise<any>;
+/**
+ * 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.
+ */
+declare function createLicenseHandler(configOrPlugin?: Partial<RagConfig> | VectorPlugin, options?: HandlerOptions): (req: NextRequest) => Promise<any>;
+/**
+ * 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.
+ */
+declare function createUploadHandler(configOrPlugin?: Partial<RagConfig> | VectorPlugin, options?: HandlerOptions): (req: any, context?: any) => Promise<any>;
+/**
+ * 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.
+ */
+declare function createSuggestionsHandler(configOrPlugin?: Partial<RagConfig> | VectorPlugin, options?: HandlerOptions): (req: NextRequest) => Promise<any>;
+/**
+ * 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.
+ */
+declare function createHistoryHandler(configOrPlugin?: Partial<RagConfig> | VectorPlugin, options?: HandlerOptions): (req: NextRequest) => Promise<any>;
+/**
+ * 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.
+ */
+declare function createFeedbackHandler(configOrPlugin?: Partial<RagConfig> | VectorPlugin, options?: HandlerOptions): (req: NextRequest) => Promise<any>;
+/**
+ * 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.
+ */
+declare function createSessionsHandler(configOrPlugin?: Partial<RagConfig> | VectorPlugin, options?: HandlerOptions): (req?: NextRequest) => Promise<any>;
+/**
+ * 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.
+ */
+declare function createRagHandler(configOrPlugin?: Partial<RagConfig> | VectorPlugin, options?: HandlerOptions): {
+    GET: (req: any, context?: any) => Promise<any>;
+    POST: (req: any, context?: any) => Promise<any>;
+};
+
+export { ConfigValidator as C, type HealthCheckResult as H, type IProviderValidator as I, type ValidationError as V, type IProviderHealthChecker as a, type HandlerOptions as b, VectorPlugin as c, createChatHandler as d, createFeedbackHandler as e, createHealthHandler as f, createHistoryHandler as g, createIngestHandler as h, createRagHandler as i, createSessionsHandler as j, createStreamHandler as k, createUploadHandler as l, sseFrame as m, sseMetaFrame as n, sseTextFrame as o, createLicenseHandler as p, createSuggestionsHandler as q, sseObservabilityFrame as r, sseErrorFrame as s, sseUIFrame as t };