qarpeo 0.0.0-alpha.10

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

@@ -0,0 +1,607 @@
+import "#qarpeo/agents-registry";
+import { getAIBinding } from "../../ai.mjs";
+import { getCloudflareEnv } from "../../bindings.mjs";
+import { getVectorizeBinding } from "../../vectorize.mjs";
+import { getR2Binding } from "../../blob.mjs";
+const GLOBAL_AGENT_REGISTRY_KEY = "__qarpeo_agent_registry__";
+function getAgentRegistry() {
+  const g = globalThis;
+  if (!g[GLOBAL_AGENT_REGISTRY_KEY]) {
+    g[GLOBAL_AGENT_REGISTRY_KEY] = /* @__PURE__ */ new Map();
+  }
+  return g[GLOBAL_AGENT_REGISTRY_KEY];
+}
+export function registerAgentDefinition(definition) {
+  if (definition && definition.name) {
+    getAgentRegistry().set(definition.name, definition);
+  }
+}
+export function getAgentDefinition(name) {
+  return getAgentRegistry().get(name);
+}
+export function getAllAgentDefinitions() {
+  return Array.from(getAgentRegistry().values());
+}
+export function defineTool(tool) {
+  return tool;
+}
+export function defineAgent(definition) {
+  registerAgentDefinition(definition);
+  return definition;
+}
+export function getAgentDurableObject(agentName, id = "default", bindingName = "QARPEO_AGENT_DO", event) {
+  const env = getCloudflareEnv(event);
+  const binding = env[bindingName];
+  if (!binding || typeof binding.idFromName !== "function") {
+    throw new Error(
+      `[qarpeo.agents] Durable Object binding "${bindingName}" is not available. Ensure "qarpeo.agents: true" is enabled.`
+    );
+  }
+  const doId = binding.idFromName(`${agentName}:${id}`);
+  return binding.get(doId);
+}
+function serializeToolSchemas(toolsInput) {
+  if (!toolsInput) return void 0;
+  const list = [];
+  if (Array.isArray(toolsInput)) {
+    for (const t of toolsInput) {
+      if (t && t.name) {
+        list.push({
+          name: t.name,
+          description: t.description || "",
+          parameters: t.parameters || { type: "object", properties: {} }
+        });
+      }
+    }
+  } else if (typeof toolsInput === "object") {
+    for (const [key, t] of Object.entries(toolsInput)) {
+      if (t) {
+        list.push({
+          name: t.name || key,
+          description: t.description || "",
+          parameters: t.parameters || { type: "object", properties: {} }
+        });
+      }
+    }
+  }
+  return list.length > 0 ? list : void 0;
+}
+export function useAgent(agentName, id = "default", event) {
+  const stub = getAgentDurableObject(agentName, id, "QARPEO_AGENT_DO", event);
+  const def = getAgentDefinition(agentName);
+  return {
+    async chat(message, options) {
+      const toolSchemas = serializeToolSchemas(options?.tools || def?.tools);
+      const response = await stub.fetch(
+        new Request("http://agent/chat", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            agentName,
+            message,
+            system: options?.system || def?.system,
+            model: options?.model || def?.model,
+            maxSteps: options?.maxSteps ?? def?.maxSteps,
+            maxTokens: options?.maxTokens ?? def?.maxTokens,
+            temperature: options?.temperature ?? def?.temperature,
+            tools: toolSchemas,
+            ...options
+          })
+        })
+      );
+      return response;
+    },
+    async history() {
+      const response = await stub.fetch(new Request("http://agent/history"));
+      const data = await response.json();
+      return data.messages || [];
+    },
+    async clear() {
+      await stub.fetch(new Request("http://agent/clear", { method: "POST" }));
+    },
+    async getState() {
+      const response = await stub.fetch(new Request("http://agent/state"));
+      const data = await response.json();
+      return data.state || {};
+    },
+    async setState(state) {
+      await stub.fetch(
+        new Request("http://agent/state", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(state)
+        })
+      );
+    }
+  };
+}
+export async function embedText(text, options) {
+  const model = options?.model || "@cf/baai/bge-base-en-v1.5";
+  const ai = getAIBinding(options?.binding, options?.event);
+  const texts = Array.isArray(text) ? text : [text];
+  const result = await ai.run(model, { text: texts });
+  if (Array.isArray(result?.data)) {
+    return result.data;
+  }
+  if (Array.isArray(result)) {
+    return result;
+  }
+  return [];
+}
+export async function similaritySearch(indexName, query, options) {
+  const embeddings = await embedText(query, options);
+  const vector = embeddings[0];
+  if (!vector) return [];
+  const vectorize = getVectorizeBinding(options?.binding, options?.event);
+  const queryOpts = {
+    topK: options?.topK || 5,
+    returnMetadata: options?.returnMetadata ?? true
+  };
+  if (options?.namespace) queryOpts.namespace = options.namespace;
+  if (options?.filter) queryOpts.filter = options.filter;
+  if (options?.returnValues !== void 0) queryOpts.returnValues = options.returnValues;
+  const results = await vectorize.query(vector, queryOpts);
+  return results.matches || [];
+}
+export async function generateText(options) {
+  const model = options.model || "@cf/meta/llama-3.3-70b-instruct";
+  const ai = getAIBinding(options.binding, options.event);
+  const messages = [];
+  if (options.system) {
+    messages.push({ role: "system", content: options.system });
+  }
+  if (options.messages) {
+    messages.push(...options.messages.map((m) => ({ role: m.role, content: m.content })));
+  } else if (options.prompt) {
+    messages.push({ role: "user", content: options.prompt });
+  }
+  const result = await ai.run(model, {
+    messages,
+    temperature: options.temperature
+  });
+  return result?.response || String(result || "");
+}
+export async function streamText(options) {
+  const model = options.model || "@cf/meta/llama-3.3-70b-instruct";
+  const ai = getAIBinding(options.binding, options.event);
+  const messages = [];
+  if (options.system) {
+    messages.push({ role: "system", content: options.system });
+  }
+  if (options.messages) {
+    messages.push(...options.messages.map((m) => ({ role: m.role, content: m.content })));
+  } else if (options.prompt) {
+    messages.push({ role: "user", content: options.prompt });
+  }
+  const { readable, writable } = new TransformStream();
+  const writer = writable.getWriter();
+  const encoder = new TextEncoder();
+  (async () => {
+    try {
+      const aiStream = await ai.run(model, {
+        messages,
+        temperature: options.temperature,
+        stream: true
+      });
+      if (aiStream && typeof aiStream.getReader === "function") {
+        const reader = aiStream.getReader();
+        const decoder = new TextDecoder();
+        let sseBuffer = "";
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) {
+            if (sseBuffer.trim().startsWith("data: ")) {
+              const dataStr = sseBuffer.trim().slice(6).trim();
+              if (dataStr !== "[DONE]") {
+                try {
+                  const parsed = JSON.parse(dataStr);
+                  const delta = parsed.response || parsed.delta?.content || "";
+                  if (delta) {
+                    await writer.write(
+                      encoder.encode(`event: text-delta
+data: ${JSON.stringify({ delta })}
+
+`)
+                    );
+                  }
+                } catch {
+                }
+              }
+            }
+            break;
+          }
+          sseBuffer += decoder.decode(value, { stream: true });
+          const lines = sseBuffer.split("\n");
+          sseBuffer = lines.pop() || "";
+          for (const line of lines) {
+            if (line.startsWith("data: ")) {
+              const dataStr = line.slice(6).trim();
+              if (dataStr === "[DONE]") continue;
+              try {
+                const parsed = JSON.parse(dataStr);
+                const delta = parsed.response || parsed.delta?.content || "";
+                if (delta) {
+                  await writer.write(
+                    encoder.encode(`event: text-delta
+data: ${JSON.stringify({ delta })}
+
+`)
+                  );
+                }
+              } catch {
+              }
+            }
+          }
+        }
+      } else if (aiStream?.response) {
+        await writer.write(
+          encoder.encode(
+            `event: text-delta
+data: ${JSON.stringify({ delta: aiStream.response })}
+
+`
+          )
+        );
+      }
+      await writer.write(encoder.encode(`event: done
+data: {}
+
+`));
+    } catch (err) {
+      await writer.write(
+        encoder.encode(
+          `event: error
+data: ${JSON.stringify({ message: err?.message || "Stream error" })}
+
+`
+        )
+      );
+    } finally {
+      await writer.close();
+    }
+  })();
+  return new Response(readable, {
+    headers: {
+      "Content-Type": "text/event-stream; charset=utf-8",
+      "Cache-Control": "no-cache, no-transform",
+      Connection: "keep-alive"
+    }
+  });
+}
+async function toUint8Array(input) {
+  if (!input) return new Uint8Array(0);
+  if (input instanceof Uint8Array) return input;
+  if (input instanceof ArrayBuffer) return new Uint8Array(input);
+  if (ArrayBuffer.isView(input)) {
+    return new Uint8Array(input.buffer, input.byteOffset, input.byteLength);
+  }
+  if (Array.isArray(input)) return new Uint8Array(input);
+  if (typeof Blob !== "undefined" && input instanceof Blob) {
+    const ab = await input.arrayBuffer();
+    return new Uint8Array(ab);
+  }
+  if (typeof Response !== "undefined" && input instanceof Response) {
+    const ab = await input.arrayBuffer();
+    return new Uint8Array(ab);
+  }
+  if (input && typeof input.getReader === "function") {
+    const reader = input.getReader();
+    const chunks = [];
+    let totalLength = 0;
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (value) {
+        const chunk = value instanceof Uint8Array ? value : new Uint8Array(value);
+        chunks.push(chunk);
+        totalLength += chunk.byteLength;
+      }
+    }
+    const combined = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+      combined.set(chunk, offset);
+      offset += chunk.byteLength;
+    }
+    return combined;
+  }
+  if (typeof input === "string") {
+    const base64Match = input.match(/^data:.*?;base64,(.*)$/);
+    const rawStr = base64Match ? base64Match[1] : input;
+    try {
+      const binary = atob(rawStr);
+      const bytes = new Uint8Array(binary.length);
+      for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+      }
+      return bytes;
+    } catch {
+      return new TextEncoder().encode(input);
+    }
+  }
+  return new Uint8Array(0);
+}
+function uint8ArrayToBase64(bytes) {
+  let binary = "";
+  const len = bytes.byteLength;
+  for (let i = 0; i < len; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
+function createDevMockImageBytes(_prompt, _format = "png") {
+  return new Uint8Array([
+    137,
+    80,
+    78,
+    71,
+    13,
+    10,
+    26,
+    10,
+    0,
+    0,
+    0,
+    13,
+    73,
+    72,
+    68,
+    82,
+    0,
+    0,
+    0,
+    1,
+    0,
+    0,
+    0,
+    1,
+    8,
+    6,
+    0,
+    0,
+    0,
+    31,
+    21,
+    196,
+    137,
+    0,
+    0,
+    0,
+    10,
+    73,
+    68,
+    65,
+    84,
+    120,
+    156,
+    99,
+    0,
+    1,
+    0,
+    0,
+    5,
+    0,
+    1,
+    13,
+    10,
+    45,
+    180,
+    0,
+    0,
+    0,
+    0,
+    73,
+    69,
+    78,
+    68,
+    174,
+    66,
+    96,
+    130
+  ]);
+}
+function createDevMockWavBytes(_text) {
+  return new Uint8Array([
+    82,
+    73,
+    70,
+    70,
+    36,
+    0,
+    0,
+    0,
+    87,
+    65,
+    86,
+    69,
+    102,
+    109,
+    116,
+    32,
+    16,
+    0,
+    0,
+    0,
+    1,
+    0,
+    1,
+    0,
+    64,
+    31,
+    0,
+    0,
+    128,
+    62,
+    0,
+    0,
+    2,
+    0,
+    16,
+    0,
+    100,
+    97,
+    116,
+    97,
+    0,
+    0,
+    0,
+    0
+  ]);
+}
+export async function generateImage(options) {
+  const opts = typeof options === "string" ? { prompt: options } : options;
+  const prompt = opts.prompt;
+  const model = opts.model || "@cf/black-forest-labs/flux-1-schnell";
+  let uint8Array;
+  const mimeType = opts.format === "jpeg" ? "image/jpeg" : opts.format === "webp" ? "image/webp" : "image/png";
+  try {
+    const ai = getAIBinding(opts.binding, opts.event);
+    const inputs = { prompt };
+    if (opts.negativePrompt) inputs.negative_prompt = opts.negativePrompt;
+    if (opts.steps !== void 0) inputs.num_steps = opts.steps;
+    if (opts.width !== void 0) inputs.width = opts.width;
+    if (opts.height !== void 0) inputs.height = opts.height;
+    if (opts.guidance !== void 0) inputs.guidance = opts.guidance;
+    if (opts.seed !== void 0) inputs.seed = opts.seed;
+    if (opts.strength !== void 0) inputs.strength = opts.strength;
+    if (opts.image) {
+      const imgBytes = await toUint8Array(opts.image);
+      inputs.image = Array.from(imgBytes);
+    }
+    const aiOptions = opts.gateway ? { gateway: opts.gateway } : void 0;
+    const rawResult = await ai.run(model, inputs, aiOptions);
+    if (rawResult?.image && typeof rawResult.image === "string") {
+      uint8Array = await toUint8Array(rawResult.image);
+    } else {
+      uint8Array = await toUint8Array(rawResult);
+    }
+  } catch (err) {
+    if (err?.message?.includes("was not found")) {
+      uint8Array = createDevMockImageBytes(prompt, opts.format);
+    } else {
+      throw err;
+    }
+  }
+  const base64 = uint8ArrayToBase64(uint8Array);
+  const dataUrl = `data:${mimeType};base64,${base64}`;
+  return {
+    uint8Array,
+    arrayBuffer: uint8Array.buffer.slice(
+      uint8Array.byteOffset,
+      uint8Array.byteOffset + uint8Array.byteLength
+    ),
+    base64,
+    dataUrl,
+    mimeType,
+    width: opts.width,
+    height: opts.height,
+    toResponse(headers) {
+      return new Response(uint8Array, {
+        headers: {
+          "Content-Type": mimeType,
+          "Content-Length": String(uint8Array.byteLength),
+          "Cache-Control": "public, max-age=31536000, immutable",
+          ...headers
+        }
+      });
+    },
+    async saveToBlob(key, saveOpts) {
+      const r2 = getR2Binding(saveOpts?.binding, saveOpts?.event || opts.event);
+      return await r2.put(key, uint8Array, {
+        httpMetadata: {
+          contentType: saveOpts?.contentType || mimeType
+        }
+      });
+    }
+  };
+}
+export const textToImage = generateImage;
+export async function generateSpeech(options) {
+  const opts = typeof options === "string" ? { text: options } : options;
+  const text = opts.text;
+  const model = opts.model || "@cf/meta/mms-tts-eng";
+  const mimeType = "audio/wav";
+  let uint8Array;
+  try {
+    const ai = getAIBinding(opts.binding, opts.event);
+    const inputs = { text };
+    if (opts.lang) inputs.lang = opts.lang;
+    const aiOptions = opts.gateway ? { gateway: opts.gateway } : void 0;
+    const rawResult = await ai.run(model, inputs, aiOptions);
+    uint8Array = await toUint8Array(rawResult);
+  } catch (err) {
+    if (err?.message?.includes("was not found")) {
+      uint8Array = createDevMockWavBytes(text);
+    } else {
+      throw err;
+    }
+  }
+  const base64 = uint8ArrayToBase64(uint8Array);
+  const dataUrl = `data:${mimeType};base64,${base64}`;
+  return {
+    uint8Array,
+    arrayBuffer: uint8Array.buffer.slice(
+      uint8Array.byteOffset,
+      uint8Array.byteOffset + uint8Array.byteLength
+    ),
+    base64,
+    dataUrl,
+    mimeType,
+    toResponse(headers) {
+      return new Response(uint8Array, {
+        headers: {
+          "Content-Type": mimeType,
+          "Content-Length": String(uint8Array.byteLength),
+          "Cache-Control": "no-cache",
+          ...headers
+        }
+      });
+    },
+    async saveToBlob(key, saveOpts) {
+      const r2 = getR2Binding(saveOpts?.binding, saveOpts?.event || opts.event);
+      return await r2.put(key, uint8Array, {
+        httpMetadata: {
+          contentType: saveOpts?.contentType || mimeType
+        }
+      });
+    }
+  };
+}
+export const textToSpeech = generateSpeech;
+export async function transcribeAudio(options) {
+  const opts = typeof options === "object" && options !== null && "audio" in options && !ArrayBuffer.isView(options) && !(options instanceof ArrayBuffer) && !(typeof Blob !== "undefined" && options instanceof Blob) ? options : { audio: options };
+  const model = opts.model || "@cf/openai/whisper";
+  const audioBytes = await toUint8Array(opts.audio);
+  try {
+    const ai = getAIBinding(opts.binding, opts.event);
+    const inputs = {
+      audio: Array.from(audioBytes)
+    };
+    if (opts.language) inputs.language = opts.language;
+    if (opts.task) inputs.task = opts.task;
+    const aiOptions = opts.gateway ? { gateway: opts.gateway } : void 0;
+    const rawResult = await ai.run(model, inputs, aiOptions);
+    const text = rawResult?.text || "";
+    const wordCount = rawResult?.word_count || (text ? text.trim().split(/\s+/).length : 0);
+    return {
+      text,
+      wordCount,
+      words: rawResult?.words,
+      vtt: rawResult?.vtt,
+      language: opts.language,
+      raw: rawResult
+    };
+  } catch (err) {
+    if (err?.message?.includes("was not found")) {
+      const wordCount = 5;
+      const text = `[Dev Mock] Transcribed audio (${audioBytes.byteLength} bytes)`;
+      return {
+        text,
+        wordCount,
+        raw: { text, word_count: wordCount }
+      };
+    }
+    throw err;
+  }
+}
+export const speechToText = transcribeAudio;

package/dist/runtime/server/utils/analytics-query.d.ts

@@ -0,0 +1,109 @@
+/**
+ * @file Analytics-query.ts Tier 2 Analytics — Cloudflare Analytics Engine SQL API query wrapper.
+ *   Provides pre-built dashboard metric helpers backed by the CF AE HTTP SQL API. CF AE SQL API
+ *   endpoint: GET https://api.cloudflare.com/client/v4/accounts/{account_id}/analytics_engine/sql
+ *   ?query=SELECT ... Data point schema used by tracker.ts: blob1 = event type ("pageview" | custom
+ *   name) blob2 = path blob3 = referrer blob4 = country blob5 = device type blob6 = user agent
+ *   blob7 = session fingerprint blob8 = user ID blob9 = metadata JSON (events only) double1 =
+ *   response time ms double2 = HTTP status code index1 = site ID
+ */
+import type { AnalyticsRange, AnalyticsSummary, PageviewSummary, AnalyticsEventRecord } from "../../../types";
+export interface QueryAnalyticsOptions {
+    /** Cloudflare Account ID. Falls back to env `CLOUDFLARE_ACCOUNT_ID`. */
+    accountId?: string;
+    /** Cloudflare API token with AE read. Falls back to env `CLOUDFLARE_API_TOKEN`. */
+    apiToken?: string;
+    /** Dataset / table name to query (the wrangler dataset name). */
+    dataset?: string;
+}
+export interface DashboardOptions extends QueryAnalyticsOptions {
+    /** Site ID filter (index1). If omitted, queries across all sites in the dataset. */
+    siteId?: string;
+}
+/**
+ * Execute a raw SQL query against the Cloudflare Analytics Engine SQL API.
+ *
+ * @param sql SQL string (supports AE SQL dialect)
+ * @param options Account credentials and dataset name
+ * @returns Parsed rows as plain objects
+ */
+export declare function queryAnalytics<T = Record<string, unknown>>(sql: string, options?: QueryAnalyticsOptions): Promise<T[]>;
+/**
+ * Creates a set of pre-built analytics dashboard metric helpers. All queries target the fixed
+ * schema written by `trackPageview()` / `trackEvent()`.
+ *
+ * @example
+ *   ;```ts
+ *   const dash = useAnalyticsDashboard({ accountId, apiToken, dataset: "analytics-prod" })
+ *   const { total, series } = await dash.pageviews("7d")
+ *   ```
+ */
+export declare function useAnalyticsDashboard(options?: DashboardOptions): {
+    /**
+     * Total pageviews and time-series breakdown.
+     *
+     * @param range Time range (default: '7d')
+     */
+    pageviews(range?: AnalyticsRange): Promise<PageviewSummary>;
+    /**
+     * Unique visitor count (unique session fingerprints).
+     *
+     * @param range Time range (default: '7d')
+     */
+    visitors(range?: AnalyticsRange): Promise<number>;
+    /**
+     * Top pages by pageview count.
+     *
+     * @param limit Max results (default: 10)
+     * @param range Time range (default: '7d')
+     */
+    topPages(limit?: number, range?: AnalyticsRange): Promise<Array<{
+        path: string;
+        views: number;
+    }>>;
+    /**
+     * Top referrers by visit count.
+     *
+     * @param limit Max results (default: 10)
+     * @param range Time range (default: '7d')
+     */
+    topReferrers(limit?: number, range?: AnalyticsRange): Promise<Array<{
+        referrer: string;
+        count: number;
+    }>>;
+    /**
+     * Pageview breakdown by country.
+     *
+     * @param limit Max results (default: 10)
+     * @param range Time range (default: '7d')
+     */
+    countries(limit?: number, range?: AnalyticsRange): Promise<Array<{
+        country: string;
+        count: number;
+    }>>;
+    /**
+     * Device type breakdown.
+     *
+     * @param range Time range (default: '7d')
+     */
+    devices(range?: AnalyticsRange): Promise<{
+        mobile: number;
+        desktop: number;
+        bot: number;
+    }>;
+    /**
+     * Custom event breakdown.
+     *
+     * @param name Filter to a specific event name. If omitted, returns all events.
+     * @param limit Max results (default: 20)
+     * @param range Time range (default: '7d')
+     */
+    events(name?: string, limit?: number, range?: AnalyticsRange): Promise<AnalyticsEventRecord[]>;
+    /**
+     * Returns a full KPI summary object — useful for the dashboard overview card. Runs multiple
+     * queries in parallel.
+     *
+     * @param range Time range (default: '7d')
+     */
+    summary(range?: AnalyticsRange): Promise<AnalyticsSummary>;
+};