@aurabase/aurabase-js 0.3.0

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "@aurabase/aurabase-js",
+  "version": "0.3.0",
+  "description": "aurabase sdk backend service ",
+  "license": "ISC",
+  "author": "Daylami Affane",
+  "type": "module",
+  "main": "index.js",
+  "scripts": {
+    "build": "pnpm -r build",
+    "typecheck": "pnpm -r typecheck",
+    "test": "pnpm -r test",
+    "test:e2e": "pnpm --filter aurabase run test:e2e"
+  },
+  "dependencies": {
+    "acorn": "^8.16.0",
+    "any-promise": "^1.3.0",
+    "assertion-error": "^2.0.1",
+    "bundle-require": "^5.1.0",
+    "cac": "^6.7.14",
+    "chai": "^6.2.2",
+    "chokidar": "^4.0.3",
+    "commander": "^4.1.1",
+    "confbox": "^0.1.8",
+    "consola": "^3.4.2",
+    "convert-source-map": "^2.0.0",
+    "debug": "^4.4.3",
+    "detect-libc": "^2.1.2",
+    "es-module-lexer": "^2.1.0",
+    "esbuild": "^0.28.1",
+    "estree-walker": "^3.0.3",
+    "expect-type": "^1.3.0",
+    "fdir": "^6.5.0",
+    "fix-dts-default-cjs-exports": "^1.0.1",
+    "fsevents": "^2.3.3",
+    "joycon": "^3.1.1",
+    "lightningcss": "^1.32.0",
+    "lightningcss-darwin-arm64": "^1.32.0",
+    "lilconfig": "^3.1.3",
+    "lines-and-columns": "^1.2.4",
+    "load-tsconfig": "^0.2.5",
+    "magic-string": "^0.30.21",
+    "mlly": "^1.8.2",
+    "ms": "^2.1.3",
+    "mz": "^2.7.0",
+    "nanoid": "^3.3.12",
+    "object-assign": "^4.1.1",
+    "obug": "^2.1.1",
+    "pathe": "^2.0.3",
+    "picocolors": "^1.1.1",
+    "picomatch": "^4.0.4",
+    "pirates": "^4.0.7",
+    "pkg-types": "^1.3.1",
+    "postcss": "^8.5.15",
+    "postcss-load-config": "^6.0.1",
+    "readdirp": "^4.1.2",
+    "resolve-from": "^5.0.0",
+    "rolldown": "^1.0.3",
+    "rollup": "^4.60.0",
+    "siginfo": "^2.0.0",
+    "source-map": "^0.7.6",
+    "source-map-js": "^1.2.1",
+    "stackback": "^0.0.2",
+    "std-env": "^4.1.0",
+    "sucrase": "^3.35.1",
+    "thenify": "^3.3.1",
+    "thenify-all": "^1.6.0",
+    "tinybench": "^2.9.0",
+    "tinyexec": "^0.3.2",
+    "tinyglobby": "^0.2.17",
+    "tinyrainbow": "^3.1.0",
+    "tree-kill": "^1.2.2",
+    "ts-interface-checker": "^0.1.13",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "ufo": "^1.6.3",
+    "vite": "^8.0.16",
+    "vitest": "^4.1.9",
+    "why-is-node-running": "^2.3.0"
+  },
+  "devDependencies": {},
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "pnpm": {
+    "overrides": {
+      "esbuild": "^0.28.1"
+    }
+  }
+}

package/packages/ai/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aurabase
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/packages/ai/README.md

@@ -0,0 +1,106 @@
+# @aurabase/ai
+
+Service IA du SDK Aurabase : chat, embeddings, RAG (retrieval-augmented generation), recherche sémantique et conversion langage naturel → SQL.
+
+![npm](https://img.shields.io/npm/v/@aurabase/ai) ![license](https://img.shields.io/badge/license-MIT-blue)
+
+> Pre-release — pas encore publié sur npm.
+
+Fait partie du SDK **[aurabase](../aurabase)**. Installé automatiquement avec `aurabase` ; ce package est publié séparément pour un usage ciblé / tree-shaking.
+
+Sans équivalent 1st-party chez Supabase, Appwrite ou Firebase : `@aurabase/ai` est un **différenciateur** du SDK, pas une simple parité.
+
+## Installation
+
+```bash
+npm i @aurabase/ai
+```
+
+> Ce package dépend de `@aurabase/core` (`workspace:*` en interne, résolu en semver côté npm). Si vous utilisez déjà le package `aurabase`, `@aurabase/ai` est déjà inclus — cette installation ciblée n'est utile que pour composer votre propre client ou limiter la taille du bundle.
+
+## Usage
+
+Dans l'usage courant, `AiService` n'est jamais instancié directement : il est exposé par le client principal sous `aura.ai`.
+
+```ts
+import { createClient } from 'aurabase'
+
+const aura = createClient('http://localhost:8080', 'my-project', 'aura_anon_xxx')
+```
+
+### Chat
+
+Réponse complète en un seul appel — pas de streaming SSE/token-par-token (voir Limitations).
+
+```ts
+const { data, error } = await aura.ai.chat(
+  [{ role: 'user', content: 'Résume ce texte en une phrase.' }],
+  { model: 'gpt-4o-mini', temperature: 0.2, max_tokens: 200 },
+)
+
+if (error) throw error
+console.log(data!.content)
+```
+
+### Embeddings
+
+```ts
+const { data: embedding } = await aura.ai.embed({
+  text: 'Aurabase est une plateforme Backend-as-a-Service.',
+  namespace: 'docs',
+})
+
+console.log(embedding!.dimensions)
+```
+
+### RAG — ingestion puis question/réponse
+
+```ts
+await aura.ai.ragIngest({
+  namespace: 'docs',
+  content: 'Aurabase expose un service de fonctions edge invocables via aura.functions.invoke().',
+})
+
+const { data: answer } = await aura.ai.rag({
+  question: 'Comment invoquer une edge function ?',
+  namespace: 'docs',
+})
+
+console.log(answer!.answer, answer!.sources)
+```
+
+### Recherche sémantique
+
+```ts
+const { data: results } = await aura.ai.semanticSearch('invocation de fonction', 'docs', {
+  top_k: 5,
+  threshold: 0.75,
+})
+
+for (const r of results ?? []) {
+  console.log(r.similarity, r.content)
+}
+```
+
+### NL2SQL
+
+```ts
+const schema = 'CREATE TABLE posts (id uuid, title text, published boolean);'
+
+const { data: query } = await aura.ai.nl2sql('Combien de posts sont publiés ?', schema, {
+  dialect: 'postgres',
+})
+
+console.log(query!.sql, query!.explanation)
+```
+
+## Limitations
+
+- Pas de streaming de chat (SSE / token-par-token) : `chat()` résout une fois la réponse complète générée.
+- Pas de tool/function calling : le modèle ne peut pas invoquer d'outils côté client.
+- Pas de gestion de namespaces RAG (création/liste/suppression) : un namespace existe implicitement dès le premier `ragIngest()`, sans API de cycle de vie dédiée.
+- Pas de suivi d'usage/coût par requête au-delà des champs `input_tokens`/`output_tokens` optionnels de `ChatResponse`.
+
+## Documentation
+
+Référence complète du SDK (tous les services, types partagés, SSR) : [README racine](../../README.md).

package/packages/ai/dist/index.cjs

@@ -0,0 +1,229 @@
+'use strict';
+
+var core = require('@aurabase/core');
+
+// src/AiService.ts
+
+// src/sse.ts
+async function* parseSSE(stream) {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let eventName = "message";
+  let dataLines = [];
+  const consumeLine = (raw) => {
+    const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
+    if (line === "") {
+      if (dataLines.length === 0) {
+        eventName = "message";
+        return null;
+      }
+      const msg = { event: eventName, data: dataLines.join("\n") };
+      eventName = "message";
+      dataLines = [];
+      return msg;
+    }
+    if (line.startsWith(":")) return null;
+    const colon = line.indexOf(":");
+    let field;
+    let value;
+    if (colon === -1) {
+      field = line;
+      value = "";
+    } else {
+      field = line.slice(0, colon);
+      value = line.slice(colon + 1);
+      if (value.startsWith(" ")) value = value.slice(1);
+    }
+    if (field === "event") eventName = value;
+    else if (field === "data") dataLines.push(value);
+    return null;
+  };
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      let idx;
+      while ((idx = buffer.indexOf("\n")) !== -1) {
+        const raw = buffer.slice(0, idx);
+        buffer = buffer.slice(idx + 1);
+        const msg = consumeLine(raw);
+        if (msg) yield msg;
+      }
+    }
+    buffer += decoder.decode();
+    if (buffer.length > 0) {
+      const msg = consumeLine(buffer);
+      if (msg) yield msg;
+    }
+    if (dataLines.length > 0) {
+      yield { event: eventName, data: dataLines.join("\n") };
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+// src/AiService.ts
+var AiService = class extends core.BaseService {
+  constructor(client) {
+    super(client);
+  }
+  get prefix() {
+    return `/v1/ai/${this.client.projectId}`;
+  }
+  /**
+   * Send a chat completion request.
+   */
+  async chat(messages, options) {
+    return this.request("POST", `${this.prefix}/chat`, {
+      messages,
+      ...options
+    });
+  }
+  /**
+   * Chat completion streamé (SSE). Renvoie un `AsyncIterable` de deltas de tokens,
+   * consommable par `for await (const { delta } of ai.chatStream(msgs)) { … }`.
+   *
+   * Court-circuite volontairement le pipeline JSON (`@aurabase/core/fetch.ts`) et
+   * emprunte le chemin transport BRUT `client.fetchFn` (patron `StorageService.download`) :
+   *  - refresh proactif du token expiré (même règle que `download`, marge 30 s) ;
+   *  - pose manuelle de `Authorization: Bearer` + `apikey`, `Accept: text/event-stream` ;
+   *  - lecture de `res.body` via `parseSSE`, mapping des events serveur :
+   *    `delta` (`{ content }`) → `yield { delta }`, `error` (`{ error }`) → lève une
+   *    `AuraError`, `done` → termine l'itération.
+   *
+   * `options.signal` interrompt proprement le flux (annulation du `fetch` + fin
+   * d'itération sans throw). Sur `!res.ok`, lève `AuraError(res.status)`.
+   *
+   * Backend route: POST /v1/ai/{project_id}/chat/stream
+   */
+  async *chatStream(messages, options) {
+    const client = this.client;
+    const store = client.authStore;
+    if (store.token && store.refreshToken && core.isTokenExpired(store.token, 30)) {
+      await core.refreshOnce(client);
+    }
+    const headers = {
+      "Content-Type": "application/json",
+      Accept: "text/event-stream"
+    };
+    if (store.token) headers["Authorization"] = `Bearer ${store.token}`;
+    if (client.apiKey) headers["apikey"] = client.apiKey;
+    const body = JSON.stringify({
+      messages,
+      model: options?.model,
+      temperature: options?.temperature,
+      max_tokens: options?.max_tokens
+    });
+    try {
+      const res = await client.fetchFn(this.url(`${this.prefix}/chat/stream`), {
+        method: "POST",
+        headers,
+        body,
+        signal: options?.signal
+      });
+      if (!res.ok) {
+        let parsed = null;
+        try {
+          parsed = await res.json();
+        } catch {
+        }
+        throw new core.AuraError(res.status, parsed);
+      }
+      if (!res.body) {
+        throw new core.AuraError(0, {
+          error: { code: "invalid_response", message: "chatStream: la r\xE9ponse SSE n'a pas de corps lisible" }
+        });
+      }
+      for await (const msg of parseSSE(res.body)) {
+        if (msg.event === "delta") {
+          let content = "";
+          try {
+            content = JSON.parse(msg.data).content ?? "";
+          } catch {
+            content = "";
+          }
+          if (content) yield { delta: content };
+        } else if (msg.event === "error") {
+          let message = "AI stream error";
+          try {
+            message = JSON.parse(msg.data).error ?? message;
+          } catch {
+          }
+          throw new core.AuraError(0, { error: { code: "ai_stream_error", message } });
+        } else if (msg.event === "done") {
+          return;
+        }
+      }
+    } catch (err) {
+      if (options?.signal?.aborted || core.isAbortError(err)) return;
+      throw err;
+    }
+  }
+  /**
+   * Generate embeddings for the given input(s).
+   */
+  async embed(req) {
+    return this.request("POST", `${this.prefix}/embed`, req);
+  }
+  /**
+   * Retrieval-Augmented Generation: query a collection and get an answer.
+   */
+  async rag(req) {
+    return this.request("POST", `${this.prefix}/rag/query`, req);
+  }
+  /**
+   * Ingest a document into a RAG namespace.
+   */
+  async ragIngest(req) {
+    return this.request("POST", `${this.prefix}/rag/ingest`, req);
+  }
+  /**
+   * Liste les namespaces RAG du projet.
+   * Backend route: GET /v1/ai/{project_id}/rag/namespaces (→ `Vec<String>`).
+   */
+  async listNamespaces() {
+    return this.request("GET", `${this.prefix}/rag/namespaces`);
+  }
+  /**
+   * Supprime un namespace RAG (et son corpus). Le segment `namespace` est
+   * URL-encodé (anti-injection de chemin).
+   * Backend route: DELETE /v1/ai/{project_id}/rag/{namespace} (→ `{ deleted }`).
+   */
+  async deleteNamespace(namespace) {
+    return this.request("DELETE", `${this.prefix}/rag/${encodeURIComponent(namespace)}`);
+  }
+  /**
+   * Ré-indexe un namespace RAG avec le modèle d'embedding courant (remédiation
+   * après un changement de modèle/dimension). Le segment `namespace` est URL-encodé.
+   * Backend route: POST /v1/ai/{project_id}/rag/{namespace}/reindex (→ `ReindexResponse`).
+   */
+  async reindexNamespace(namespace) {
+    return this.request("POST", `${this.prefix}/rag/${encodeURIComponent(namespace)}/reindex`);
+  }
+  /**
+   * Semantic search over an embedding namespace.
+   */
+  async semanticSearch(query, namespace, options) {
+    const params = new URLSearchParams({ query, namespace });
+    if (options?.top_k !== void 0) params.set("top_k", String(options.top_k));
+    if (options?.threshold !== void 0) params.set("threshold", String(options.threshold));
+    return this.request("GET", `${this.prefix}/search?${params.toString()}`);
+  }
+  /**
+   * Natural-language to SQL: convert a question into a SQL query.
+   */
+  async nl2sql(question, schema, options) {
+    return this.request("POST", `${this.prefix}/nl2sql`, {
+      question,
+      schema,
+      dialect: options?.dialect,
+      examples: options?.examples
+    });
+  }
+};
+
+exports.AiService = AiService;
+exports.parseSSE = parseSSE;

package/packages/ai/dist/index.d.cts

@@ -0,0 +1,139 @@
+import { BaseService, AuraClientLike, ChatMessage, AuraResponse, ChatResponse, EmbedRequest, EmbedResponse, RagRequest, RagResponse, RagIngestRequest, RagIngestResponse, SemanticSearchResult } from '@aurabase/core';
+export { AuraResponse, ChatMessage, ChatResponse, EmbedRequest, EmbedResponse, RagIngestRequest, RagIngestResponse, RagRequest, RagResponse, SemanticSearchResult } from '@aurabase/core';
+
+/** Un message SSE dispatché : nom d'event (`message` par défaut) + données jointes. */
+interface SSEMessage {
+    event: string;
+    data: string;
+}
+/** Chunk de streaming de chat : un delta de tokens incrémental. */
+interface ChatStreamChunk {
+    delta: string;
+}
+/**
+ * Parse un flux SSE en `AsyncGenerator<SSEMessage>`.
+ *
+ * Conforme au protocole EventSource :
+ *  - événements séparés par une ligne vide (`\n\n`) ;
+ *  - champs `event:` / `data:` (espace optionnel après le `:`), autres champs ignorés ;
+ *  - plusieurs `data:` d'un même event sont jointes par `\n` ;
+ *  - lignes commençant par `:` = commentaires/keep-alive → ignorées ;
+ *  - CRLF toléré (le `\r` de fin de ligne est retiré).
+ *
+ * Gère les trames partielles : un event scindé sur plusieurs chunks est
+ * bufferisé jusqu'à réception de la ligne vide. Un éventuel event final non
+ * terminé par une ligne vide est tout de même livré à la fermeture du flux.
+ */
+declare function parseSSE(stream: ReadableStream<Uint8Array>): AsyncGenerator<SSEMessage>;
+
+/**
+ * Un namespace RAG. Le backend (`GET /rag/namespaces` → `Vec<String>`) renvoie
+ * de simples chaînes ; le type reste un alias pour documenter l'intention et
+ * autoriser une évolution ultérieure vers un objet sans casser les appelants.
+ */
+type RagNamespace = string;
+/**
+ * Réponse de `DELETE /rag/{namespace}` — forme réelle du handler
+ * (`rag_delete_namespace` → `{ "deleted": <count> }`).
+ */
+interface RagDeleteResponse {
+    /** Nombre d'entrées supprimées du namespace. */
+    deleted: number;
+}
+/**
+ * Réponse de `POST /rag/{namespace}/reindex` — forme réelle du handler
+ * (`ReindexResponse` dans `services/aura-ai/src/rag/mod.rs`).
+ */
+interface RagReindexResponse {
+    /** Nombre de chunks ré-embeddés sous le modèle courant. */
+    reindexed: number;
+    /** Modèle d'embedding désormais appliqué au namespace. */
+    embedding_model: string;
+}
+
+declare class AiService extends BaseService {
+    constructor(client: AuraClientLike);
+    private get prefix();
+    /**
+     * Send a chat completion request.
+     */
+    chat(messages: ChatMessage[], options?: {
+        model?: string;
+        temperature?: number;
+        max_tokens?: number;
+    }): Promise<AuraResponse<ChatResponse>>;
+    /**
+     * Chat completion streamé (SSE). Renvoie un `AsyncIterable` de deltas de tokens,
+     * consommable par `for await (const { delta } of ai.chatStream(msgs)) { … }`.
+     *
+     * Court-circuite volontairement le pipeline JSON (`@aurabase/core/fetch.ts`) et
+     * emprunte le chemin transport BRUT `client.fetchFn` (patron `StorageService.download`) :
+     *  - refresh proactif du token expiré (même règle que `download`, marge 30 s) ;
+     *  - pose manuelle de `Authorization: Bearer` + `apikey`, `Accept: text/event-stream` ;
+     *  - lecture de `res.body` via `parseSSE`, mapping des events serveur :
+     *    `delta` (`{ content }`) → `yield { delta }`, `error` (`{ error }`) → lève une
+     *    `AuraError`, `done` → termine l'itération.
+     *
+     * `options.signal` interrompt proprement le flux (annulation du `fetch` + fin
+     * d'itération sans throw). Sur `!res.ok`, lève `AuraError(res.status)`.
+     *
+     * Backend route: POST /v1/ai/{project_id}/chat/stream
+     */
+    chatStream(messages: ChatMessage[], options?: {
+        model?: string;
+        temperature?: number;
+        max_tokens?: number;
+        signal?: AbortSignal;
+    }): AsyncGenerator<ChatStreamChunk>;
+    /**
+     * Generate embeddings for the given input(s).
+     */
+    embed(req: EmbedRequest): Promise<AuraResponse<EmbedResponse>>;
+    /**
+     * Retrieval-Augmented Generation: query a collection and get an answer.
+     */
+    rag(req: RagRequest): Promise<AuraResponse<RagResponse>>;
+    /**
+     * Ingest a document into a RAG namespace.
+     */
+    ragIngest(req: RagIngestRequest): Promise<AuraResponse<RagIngestResponse>>;
+    /**
+     * Liste les namespaces RAG du projet.
+     * Backend route: GET /v1/ai/{project_id}/rag/namespaces (→ `Vec<String>`).
+     */
+    listNamespaces(): Promise<AuraResponse<RagNamespace[]>>;
+    /**
+     * Supprime un namespace RAG (et son corpus). Le segment `namespace` est
+     * URL-encodé (anti-injection de chemin).
+     * Backend route: DELETE /v1/ai/{project_id}/rag/{namespace} (→ `{ deleted }`).
+     */
+    deleteNamespace(namespace: string): Promise<AuraResponse<RagDeleteResponse>>;
+    /**
+     * Ré-indexe un namespace RAG avec le modèle d'embedding courant (remédiation
+     * après un changement de modèle/dimension). Le segment `namespace` est URL-encodé.
+     * Backend route: POST /v1/ai/{project_id}/rag/{namespace}/reindex (→ `ReindexResponse`).
+     */
+    reindexNamespace(namespace: string): Promise<AuraResponse<RagReindexResponse>>;
+    /**
+     * Semantic search over an embedding namespace.
+     */
+    semanticSearch(query: string, namespace: string, options?: {
+        top_k?: number;
+        threshold?: number;
+    }): Promise<AuraResponse<SemanticSearchResult[]>>;
+    /**
+     * Natural-language to SQL: convert a question into a SQL query.
+     */
+    nl2sql(question: string, schema: string, options?: {
+        dialect?: string;
+        examples?: Array<{
+            question: string;
+            sql: string;
+        }>;
+    }): Promise<AuraResponse<{
+        sql: string;
+        explanation: string;
+    }>>;
+}
+
+export { AiService, type ChatStreamChunk, type RagDeleteResponse, type RagNamespace, type RagReindexResponse, type SSEMessage, parseSSE };