qarpeo 0.0.0-alpha.10

package/dist/runtime/server/utils/queue-fallback.d.ts

@@ -0,0 +1,2 @@
+declare const queueHandler: null;
+export default queueHandler;

package/dist/runtime/server/utils/queue-fallback.mjs

@@ -0,0 +1,2 @@
+const queueHandler = null;
+export default queueHandler;

package/dist/runtime/server/utils/queue.d.ts

@@ -0,0 +1,4 @@
+import type { QueueMessageBatch } from "../../index";
+export type QueueHandler<T = any> = (batch: QueueMessageBatch<T>) => void | Promise<void>;
+/** Defines a type-safe consumer event handler for incoming Cloudflare Queue batches. */
+export declare function defineQueueHandler<T = any>(handler: QueueHandler<T>): QueueHandler<T>;

package/dist/runtime/server/utils/queue.mjs

@@ -0,0 +1,3 @@
+export function defineQueueHandler(handler) {
+  return handler;
+}

package/dist/runtime/server/utils/rag.d.ts

@@ -0,0 +1,25 @@
+import type { ChunkOptions, RAGPipelineConfig, RAGPipeline } from "../../../types";
+export type { ChunkOptions, RAGDocument, RAGChunk, RAGChunkMatch, RAGPipelineConfig, RAGQueryOptions, RAGContextResult, RAGAnswerOptions, RAGAnswerResult, RAGPipeline, } from "../../../types";
+/**
+ * Splits raw text into overlapping contextual chunks respecting paragraph,
+ * sentence, and word boundaries.
+ */
+export declare function splitTextIntoChunks(text: string, options?: ChunkOptions): string[];
+/**
+ * Creates an edge-native RAG (Retrieval-Augmented Generation) pipeline backed by
+ * Cloudflare Vectorize and Workers AI.
+ *
+ * @example
+ *   // server/utils/rag.ts
+ *   export const docsRAG = createRAGPipeline({
+ *     binding: "VECTORIZE",
+ *     embeddingModel: "@cf/baai/bge-base-en-v1.5",
+ *   })
+ *
+ *   // Ingest docs:
+ *   await docsRAG.indexDocument({ id: "auth-guide", text: "..." })
+ *
+ *   // Answer questions:
+ *   const { answer, sources } = await docsRAG.answer("How do I enable MFA?")
+ */
+export declare function createRAGPipeline(config?: RAGPipelineConfig): RAGPipeline;

package/dist/runtime/server/utils/rag.mjs

@@ -0,0 +1,333 @@
+import { getVectorizeBinding } from "../../vectorize.mjs";
+import { embedText, generateText, defineTool } from "./ai.mjs";
+const GLOBAL_RAG_KEY = "__qarpeo_dev_mock_rag__";
+function getDevMockRAGStore() {
+  const g = globalThis;
+  if (!g[GLOBAL_RAG_KEY]) {
+    g[GLOBAL_RAG_KEY] = /* @__PURE__ */ new Map();
+  }
+  return g[GLOBAL_RAG_KEY];
+}
+function cosineSimilarity(a, b) {
+  if (!a || !b || a.length !== b.length) return 0;
+  let dotProduct = 0;
+  let normA = 0;
+  let normB = 0;
+  for (let i = 0; i < a.length; i++) {
+    dotProduct += a[i] * b[i];
+    normA += a[i] * a[i];
+    normB += b[i] * b[i];
+  }
+  if (normA === 0 || normB === 0) return 0;
+  return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));
+}
+const DEFAULT_SEPARATORS = ["\n\n", "\n", ". ", "? ", "! ", "; ", ", ", " "];
+export function splitTextIntoChunks(text, options) {
+  if (!text || typeof text !== "string") return [];
+  const chunkSize = options?.chunkSize ?? 800;
+  const chunkOverlap = options?.chunkOverlap ?? 100;
+  const separators = options?.separators ?? DEFAULT_SEPARATORS;
+  const cleanText = text.trim();
+  if (cleanText.length <= chunkSize) {
+    return [cleanText];
+  }
+  function splitRecursive(content, separatorIndex) {
+    if (content.length <= chunkSize) {
+      return [content];
+    }
+    if (separatorIndex >= separators.length) {
+      const hardChunks = [];
+      let start = 0;
+      while (start < content.length) {
+        const end = Math.min(start + chunkSize, content.length);
+        hardChunks.push(content.slice(start, end));
+        start += chunkSize - chunkOverlap;
+      }
+      return hardChunks;
+    }
+    const separator = separators[separatorIndex];
+    const parts = content.split(separator);
+    const chunks = [];
+    let currentChunk = "";
+    for (let i = 0; i < parts.length; i++) {
+      const part = parts[i];
+      const candidate = currentChunk ? `${currentChunk}${separator}${part}` : part;
+      if (candidate.length <= chunkSize) {
+        currentChunk = candidate;
+      } else {
+        if (currentChunk) {
+          chunks.push(currentChunk);
+          if (chunkOverlap > 0 && currentChunk.length > chunkOverlap) {
+            const overlapText = currentChunk.slice(currentChunk.length - chunkOverlap);
+            currentChunk = `${overlapText}${separator}${part}`;
+          } else {
+            currentChunk = part;
+          }
+        } else {
+          const subChunks = splitRecursive(part, separatorIndex + 1);
+          chunks.push(...subChunks);
+          currentChunk = "";
+        }
+      }
+    }
+    if (currentChunk.trim().length > 0) {
+      chunks.push(currentChunk);
+    }
+    return chunks;
+  }
+  return splitRecursive(cleanText, 0).map((c) => c.trim()).filter((c) => c.length > 0);
+}
+export function createRAGPipeline(config) {
+  const bindingName = config?.binding || "VECTORIZE";
+  const aiBindingName = config?.aiBinding || "AI";
+  const embeddingModel = config?.embeddingModel || "@cf/baai/bge-base-en-v1.5";
+  const llmModel = config?.llmModel || "@cf/meta/llama-3.3-70b-instruct";
+  const defaultChunking = config?.chunking || { chunkSize: 800, chunkOverlap: 100 };
+  const defaultNamespace = config?.namespace;
+  function resolveVectorize(event) {
+    try {
+      return getVectorizeBinding(bindingName, event || config?.event);
+    } catch {
+      return null;
+    }
+  }
+  return {
+    chunkText(text, options) {
+      return splitTextIntoChunks(text, { ...defaultChunking, ...options });
+    },
+    async indexDocument(doc, options) {
+      const chunkTexts = splitTextIntoChunks(doc.text, { ...defaultChunking, ...options?.chunking });
+      if (chunkTexts.length === 0) {
+        return { chunksIndexed: 0 };
+      }
+      const namespace = doc.namespace || defaultNamespace;
+      const event = options?.event || config?.event;
+      let embeddings = [];
+      try {
+        embeddings = await embedText(chunkTexts, {
+          model: embeddingModel,
+          binding: aiBindingName,
+          event
+        });
+      } catch {
+        embeddings = chunkTexts.map((txt) => {
+          const vec = new Array(768).fill(0);
+          for (let i = 0; i < txt.length; i++) {
+            vec[i % 768] = (vec[i % 768] + txt.charCodeAt(i)) / 1e3;
+          }
+          return vec;
+        });
+      }
+      const vectors = chunkTexts.map((text, i) => {
+        const chunkId = `${doc.id}#chunk-${i}`;
+        const values = embeddings[i] || new Array(768).fill(0);
+        const metadata = {
+          ...doc.metadata || {},
+          documentId: doc.id,
+          chunkIndex: i,
+          totalChunks: chunkTexts.length,
+          text
+        };
+        return {
+          id: chunkId,
+          values,
+          namespace,
+          metadata
+        };
+      });
+      const vectorize = resolveVectorize(event);
+      let mutationId;
+      if (vectorize) {
+        const res = await vectorize.upsert(vectors);
+        mutationId = res?.mutationId;
+      } else {
+        const store = getDevMockRAGStore();
+        for (const v of vectors) {
+          store.set(v.id, {
+            id: v.id,
+            vector: v.values,
+            documentId: doc.id,
+            chunkIndex: v.metadata.chunkIndex,
+            totalChunks: v.metadata.totalChunks,
+            text: v.metadata.text,
+            namespace: v.namespace,
+            metadata: v.metadata
+          });
+        }
+        mutationId = `mock_mut_${Date.now()}`;
+      }
+      return { chunksIndexed: vectors.length, mutationId };
+    },
+    async indexDocuments(docs, options) {
+      const batchSize = options?.batchSize || 10;
+      let totalChunks = 0;
+      for (let i = 0; i < docs.length; i += batchSize) {
+        const batch = docs.slice(i, i + batchSize);
+        await Promise.all(
+          batch.map(async (doc) => {
+            const res = await this.indexDocument(doc, options);
+            totalChunks += res.chunksIndexed;
+          })
+        );
+      }
+      return { totalIndexed: docs.length, totalChunks };
+    },
+    async deleteDocument(documentId, options) {
+      const maxChunks = options?.maxChunks || 100;
+      const idsToDelete = [];
+      for (let i = 0; i < maxChunks; i++) {
+        idsToDelete.push(`${documentId}#chunk-${i}`);
+      }
+      const vectorize = resolveVectorize(options?.event || config?.event);
+      if (vectorize) {
+        await vectorize.deleteByIds(idsToDelete);
+      } else {
+        const store = getDevMockRAGStore();
+        for (const [id, item] of store.entries()) {
+          if (item.documentId === documentId) {
+            store.delete(id);
+          }
+        }
+      }
+    },
+    async query(queryText, options) {
+      const topK = options?.topK || 5;
+      const minScore = options?.minScore ?? 0;
+      const namespace = options?.namespace || defaultNamespace;
+      const event = options?.event || config?.event;
+      let queryVector = [];
+      try {
+        const emb = await embedText(queryText, {
+          model: embeddingModel,
+          binding: aiBindingName,
+          event
+        });
+        queryVector = emb[0] || [];
+      } catch {
+        queryVector = new Array(768).fill(0);
+        for (let i = 0; i < queryText.length; i++) {
+          queryVector[i % 768] = (queryVector[i % 768] + queryText.charCodeAt(i)) / 1e3;
+        }
+      }
+      const vectorize = resolveVectorize(event);
+      if (vectorize) {
+        const res = await vectorize.query(queryVector, {
+          topK,
+          returnMetadata: "all",
+          namespace,
+          filter: options?.filter
+        });
+        const matches = [];
+        for (const m of res.matches || []) {
+          if (m.score < minScore) continue;
+          const meta = m.metadata || {};
+          matches.push({
+            id: m.id,
+            text: meta.text || "",
+            documentId: meta.documentId || m.id.split("#chunk-")[0] || m.id,
+            chunkIndex: meta.chunkIndex ?? 0,
+            totalChunks: meta.totalChunks ?? 1,
+            score: m.score,
+            metadata: meta
+          });
+        }
+        return matches;
+      } else {
+        const store = getDevMockRAGStore();
+        const candidates = [];
+        for (const item of store.values()) {
+          if (namespace && item.namespace !== namespace) continue;
+          const sim = cosineSimilarity(queryVector, item.vector);
+          const hasKeyword = queryText.toLowerCase().split(/\s+/).some((w) => w.length > 2 && item.text.toLowerCase().includes(w));
+          const score = hasKeyword ? Math.max(sim, 0.75) : sim;
+          if (score >= minScore) {
+            candidates.push({ item, score });
+          }
+        }
+        candidates.sort((a, b) => b.score - a.score);
+        return candidates.slice(0, topK).map(({ item, score }) => ({
+          id: item.id,
+          text: item.text,
+          documentId: item.documentId,
+          chunkIndex: item.chunkIndex,
+          totalChunks: item.totalChunks,
+          score,
+          metadata: item.metadata || {}
+        }));
+      }
+    },
+    async retrieveContext(queryText, options) {
+      const matches = await this.query(queryText, options);
+      if (matches.length === 0) {
+        return {
+          contextText: "No relevant documents found.",
+          matches: []
+        };
+      }
+      const blocks = matches.map((m, idx) => {
+        const title = m.metadata.title || m.documentId;
+        const sourceInfo = m.metadata.url ? ` (${m.metadata.url})` : "";
+        return `[Source ${idx + 1}: ${title}${sourceInfo} | Relevance: ${(m.score * 100).toFixed(0)}%]
+${m.text}`;
+      });
+      return {
+        contextText: blocks.join("\n\n"),
+        matches
+      };
+    },
+    async answer(queryText, options) {
+      const { contextText, matches } = await this.retrieveContext(queryText, options);
+      const defaultSystem = "You are an intelligent, factual assistant. Answer the user's question accurately based strictly on the provided Context below.\nIf the context does not contain sufficient information to answer the question, state honestly that the documentation does not contain this information.\nCite the relevant Source numbers when quoting facts.";
+      const systemPrompt = `${options?.system || defaultSystem}
+
+Context:
+${contextText}`;
+      let answer = "";
+      try {
+        answer = await generateText({
+          model: llmModel,
+          system: systemPrompt,
+          prompt: queryText,
+          temperature: options?.temperature ?? 0.2,
+          maxTokens: options?.maxTokens,
+          binding: aiBindingName,
+          event: options?.event || config?.event
+        });
+      } catch (err) {
+        answer = `[Dev Mock] Based on ${matches.length} retrieved context sources, here is the answer for: "${queryText}".`;
+      }
+      return {
+        answer,
+        sources: matches,
+        query: queryText
+      };
+    },
+    asTool(toolOptions) {
+      const self = this;
+      return defineTool({
+        name: toolOptions?.name || "searchKnowledge",
+        description: toolOptions?.description || "Search knowledge base and documentation for factual context and technical references.",
+        parameters: {
+          type: "object",
+          properties: {
+            query: {
+              type: "string",
+              description: "The search query or technical keywords to search for"
+            }
+          },
+          required: ["query"]
+        },
+        async execute({ query }) {
+          const { contextText, matches } = await self.retrieveContext(query, {
+            topK: toolOptions?.topK,
+            minScore: toolOptions?.minScore
+          });
+          return {
+            resultsCount: matches.length,
+            context: contextText
+          };
+        }
+      });
+    }
+  };
+}

package/dist/runtime/server/utils/ratelimit.d.ts

@@ -0,0 +1,45 @@
+import type { AppRateLimitRule } from "../../../types";
+export interface RateLimitCheckResult {
+    /** Whether the request is permitted */
+    success: boolean;
+    /** Number of remaining requests permitted in the current window */
+    remaining: number;
+    /** Max limit for this window */
+    limit: number;
+    /** Seconds until the rate limit window resets */
+    reset: number;
+}
+export interface CheckRateLimitOptions extends AppRateLimitRule {
+    /** Optional custom identifier/key to rate limit against (defaults to client IP + route path) */
+    key?: string;
+    /** Storage backend override ('auto' | 'kv' | 'memory') */
+    backend?: "auto" | "kv" | "memory";
+    /** Custom binding name override */
+    binding?: string;
+    /** Custom error message when rate limit is exceeded */
+    message?: string;
+    /** Explicit event context */
+    event?: any;
+}
+/** Parses duration string (e.g. '10s', '1m', '15m', '1h', '1d') or number into seconds. */
+export declare function parseRateLimitWindow(window: string | number | undefined, defaultSeconds?: number): number;
+/** Extracts the client IP address from request headers or socket. */
+export declare function getClientIp(event: any): string;
+/**
+ * Evaluates whether a request or key is within the allowed rate limit.
+ *
+ * @example
+ *   const res = await checkRateLimit(event, { max: 10, window: "1m" })
+ *   if (!res.success) {
+ *     // exceeded
+ *   }
+ */
+export declare function checkRateLimit(eventOrKey: any, options?: CheckRateLimitOptions): Promise<RateLimitCheckResult>;
+/**
+ * Asserts that a request or key is within the rate limit. If exceeded, automatically sets standard
+ * rate limit headers and throws an HTTP 429 error.
+ *
+ * @example
+ *   await assertRateLimit(event, { max: 5, window: "1m" })
+ */
+export declare function assertRateLimit(eventOrKey: any, options?: CheckRateLimitOptions): Promise<RateLimitCheckResult>;

package/dist/runtime/server/utils/ratelimit.mjs

@@ -0,0 +1,182 @@
+import { createError, getRequestHeader, getRequestURL } from "nuxt/server";
+import { getKVBinding } from "../../kv.mjs";
+import { getRateLimitBinding } from "../../ratelimit.mjs";
+function setResponseHeaderSafe(event, name, value) {
+  if (!event) return;
+  try {
+    if (typeof event.node?.res?.setHeader === "function") {
+      event.node.res.setHeader(name, value);
+    } else if (event.headers && typeof event.headers.set === "function") {
+      event.headers.set(name, value);
+    } else if (event.response?.headers && typeof event.response.headers.set === "function") {
+      event.response.headers.set(name, value);
+    }
+  } catch {
+  }
+}
+const memoryStore = /* @__PURE__ */ new Map();
+export function parseRateLimitWindow(window, defaultSeconds = 60) {
+  if (window === void 0 || window === null) return defaultSeconds;
+  if (typeof window === "number") return Math.max(1, Math.floor(window));
+  const trimmed = window.trim().toLowerCase();
+  const match = trimmed.match(
+    /^(\d+(?:\.\d+)?)\s*(s|sec|seconds|m|min|minutes|h|hr|hours|d|days)?$/
+  );
+  if (!match) {
+    const parsed = Number(trimmed);
+    return isNaN(parsed) ? defaultSeconds : Math.max(1, Math.floor(parsed));
+  }
+  const value = parseFloat(match[1]);
+  const unit = match[2] || "s";
+  switch (unit) {
+    case "s":
+    case "sec":
+    case "seconds":
+      return Math.max(1, Math.floor(value));
+    case "m":
+    case "min":
+    case "minutes":
+      return Math.max(1, Math.floor(value * 60));
+    case "h":
+    case "hr":
+    case "hours":
+      return Math.max(1, Math.floor(value * 3600));
+    case "d":
+    case "days":
+      return Math.max(1, Math.floor(value * 86400));
+    default:
+      return defaultSeconds;
+  }
+}
+export function getClientIp(event) {
+  if (!event) return "127.0.0.1";
+  const cfIp = getRequestHeader(event, "cf-connecting-ip");
+  if (cfIp && typeof cfIp === "string" && cfIp.trim()) {
+    return cfIp.trim();
+  }
+  const xForwardedFor = getRequestHeader(event, "x-forwarded-for");
+  if (xForwardedFor && typeof xForwardedFor === "string") {
+    const firstIp = xForwardedFor.split(",")[0]?.trim();
+    if (firstIp) return firstIp;
+  }
+  const xRealIp = getRequestHeader(event, "x-real-ip");
+  if (xRealIp && typeof xRealIp === "string" && xRealIp.trim()) {
+    return xRealIp.trim();
+  }
+  const req = event.node?.req || event;
+  return req.socket?.remoteAddress || "127.0.0.1";
+}
+export async function checkRateLimit(eventOrKey, options) {
+  const isEvent = eventOrKey && typeof eventOrKey === "object" && ("node" in eventOrKey || "headers" in eventOrKey || "req" in eventOrKey);
+  const event = isEvent ? eventOrKey : options?.event;
+  const max = options?.max ?? 100;
+  const windowSecs = parseRateLimitWindow(options?.window, 60);
+  const backend = options?.backend ?? "auto";
+  let limitKey;
+  if (options?.key) {
+    limitKey = options.key;
+  } else if (isEvent) {
+    const ip = getClientIp(event);
+    let pathname = "";
+    try {
+      pathname = getRequestURL(event).pathname;
+    } catch {
+      pathname = event.path || "/";
+    }
+    limitKey = `${ip}:${pathname}`;
+  } else if (typeof eventOrKey === "string" && eventOrKey.trim()) {
+    limitKey = eventOrKey.trim();
+  } else {
+    limitKey = "anonymous";
+  }
+  if (backend === "auto") {
+    try {
+      const binding = getRateLimitBinding(options?.binding, event);
+      if (binding && typeof binding.limit === "function") {
+        const result = await binding.limit({ key: limitKey });
+        return {
+          success: result.success,
+          remaining: result.success ? 1 : 0,
+          limit: max,
+          reset: windowSecs
+        };
+      }
+    } catch {
+    }
+  }
+  if (backend === "kv" || backend === "auto") {
+    try {
+      const kv = getKVBinding(options?.binding, event);
+      if (kv && typeof kv.get === "function") {
+        const nowSec = Math.floor(Date.now() / 1e3);
+        const bucket = Math.floor(nowSec / windowSecs);
+        const kvKey = `_rl:${limitKey}:${bucket}`;
+        const raw = await kv.get(kvKey);
+        const count = raw ? parseInt(raw, 10) : 0;
+        const reset2 = windowSecs - nowSec % windowSecs;
+        if (count >= max) {
+          return {
+            success: false,
+            remaining: 0,
+            limit: max,
+            reset: reset2
+          };
+        }
+        await kv.put(kvKey, String(count + 1), {
+          expirationTtl: Math.max(60, windowSecs * 2)
+        });
+        return {
+          success: true,
+          remaining: Math.max(0, max - (count + 1)),
+          limit: max,
+          reset: reset2
+        };
+      }
+    } catch {
+    }
+  }
+  const now = Date.now();
+  const windowMs = windowSecs * 1e3;
+  let timestamps = memoryStore.get(limitKey) || [];
+  timestamps = timestamps.filter((t) => now - t < windowMs);
+  const reset = timestamps.length > 0 ? Math.ceil((timestamps[0] + windowMs - now) / 1e3) : windowSecs;
+  if (timestamps.length >= max) {
+    memoryStore.set(limitKey, timestamps);
+    return {
+      success: false,
+      remaining: 0,
+      limit: max,
+      reset: Math.max(1, reset)
+    };
+  }
+  timestamps.push(now);
+  memoryStore.set(limitKey, timestamps);
+  return {
+    success: true,
+    remaining: Math.max(0, max - timestamps.length),
+    limit: max,
+    reset: Math.max(1, reset)
+  };
+}
+export async function assertRateLimit(eventOrKey, options) {
+  const isEvent = eventOrKey && typeof eventOrKey === "object" && ("node" in eventOrKey || "headers" in eventOrKey || "req" in eventOrKey);
+  const event = isEvent ? eventOrKey : options?.event;
+  const result = await checkRateLimit(eventOrKey, options);
+  if (event) {
+    setResponseHeaderSafe(event, "X-RateLimit-Limit", String(result.limit));
+    setResponseHeaderSafe(event, "X-RateLimit-Remaining", String(result.remaining));
+    setResponseHeaderSafe(event, "X-RateLimit-Reset", String(result.reset));
+  }
+  if (!result.success) {
+    if (event) {
+      setResponseHeaderSafe(event, "Retry-After", String(result.reset));
+    }
+    throw createError({
+      statusCode: 429,
+      statusMessage: "Too Many Requests",
+      message: options?.message || "Rate limit exceeded. Please try again later.",
+      data: result
+    });
+  }
+  return result;
+}