@aurabase/aurabase-js 0.3.0

package/packages/aurabase/src/AuraClient.ts

@@ -0,0 +1,237 @@
+import { BaseAuthStore, LocalAuthStore, DEFAULT_MAX_RETRIES } from '@aurabase/core'
+import type { AuraClientLike, ChannelConfig, AuraClientOptions, AuraObservabilityEvent } from '@aurabase/core'
+import { AuthService, AuthAdminService } from '@aurabase/auth'
+import { DatabaseService } from '@aurabase/db'
+import { StorageService } from '@aurabase/storage'
+import { RealtimeService } from '@aurabase/realtime'
+import type { AuraChannel } from '@aurabase/realtime'
+import { FunctionsService } from '@aurabase/functions'
+import { AiService } from '@aurabase/ai'
+import { NotificationsService } from '@aurabase/notifications'
+
+/**
+ * Détecte un contexte d'exécution CLIENT navigateur où une clé service_role ne doit
+ * jamais figurer : thread principal (`window`) ET Web Workers navigateur (dedicated/
+ * shared). On EXCLUT volontairement `ServiceWorkerGlobalScope` — utilisé par des
+ * runtimes SERVEUR/edge légitimes (Cloudflare Workers) où service_role est valide —
+ * pour éviter tout faux positif qui casserait un usage serveur légitime.
+ */
+export function isBrowserContext(): boolean {
+  if (typeof window !== 'undefined') return true
+  const g = globalThis as Record<string, unknown>
+  if (typeof g.DedicatedWorkerGlobalScope !== 'undefined') return true
+  if (typeof g.SharedWorkerGlobalScope !== 'undefined') return true
+  return false
+}
+
+/** Préfixe des clés service_role (backend : `generate_api_key("service_role")`). */
+const SERVICE_ROLE_KEY_PREFIX = 'aura_sk_'
+
+/**
+ * Main Aurabase client.
+ *
+ * @example
+ * ```ts
+ * import { createClient } from 'aurabase'
+ * const aura = createClient('http://localhost:8080', 'my-project-id')
+ * const { data } = await aura.db.from('posts').eq('published', true)
+ * ```
+ */
+export class AuraClient<Database = any> implements AuraClientLike {
+  readonly baseUrl: string
+  readonly projectId: string
+  readonly apiKey: string | null
+  readonly fetchFn: typeof globalThis.fetch
+  readonly authStore: BaseAuthStore
+  readonly retryConfig: { enabled: boolean; maxRetries: number }
+  /** Timeout par défaut (ms) des requêtes JSON sans signal. `undefined` → défaut core (30s). */
+  readonly requestTimeoutMs?: number
+  /** Hook d'observabilité (LOT 3) — voir `AuraClientOptions.onEvent`. */
+  readonly onEvent?: (event: AuraObservabilityEvent) => void
+  /** Journalise chaque `AuraObservabilityEvent` via `console.debug` — voir `AuraClientOptions.debug`. */
+  readonly debug?: boolean
+
+  // Lazy-initialised service instances
+  private _auth: AuthService | null = null
+  private _db: DatabaseService<Database> | null = null
+  private _storage: StorageService | null = null
+  private _realtime: RealtimeService | null = null
+  private _functions: FunctionsService | null = null
+  private _ai: AiService | null = null
+  private _notifications: NotificationsService | null = null
+  private _authAdmin: AuthAdminService | null = null
+  private _disposed = false
+  private readonly _persistSession: boolean
+  private readonly _autoRefresh: boolean
+  private readonly _detectSessionInUrl: boolean | undefined
+
+  constructor(
+    baseUrl: string,
+    projectId: string,
+    apiKeyOrOptions?: string | AuraClientOptions,
+    options?: AuraClientOptions,
+  ) {
+    // Normalise: strip trailing slash
+    this.baseUrl = baseUrl.replace(/\/+$/, '')
+    this.projectId = projectId
+
+    // Support both: createClient(url, pid, apiKey, opts?) or createClient(url, pid, opts?)
+    const resolvedOptions = typeof apiKeyOrOptions === 'string' ? options : apiKeyOrOptions
+    this.apiKey = typeof apiKeyOrOptions === 'string' ? apiKeyOrOptions : (apiKeyOrOptions?.apiKey ?? null)
+    this.fetchFn = resolvedOptions?.fetch ?? globalThis.fetch.bind(globalThis)
+
+    // Retry transitoire : activé par défaut, désactivable/ajustable via l'option `retry`.
+    const r = resolvedOptions?.retry
+    this.retryConfig =
+      r === false
+        ? { enabled: false, maxRetries: 0 }
+        : r === undefined || r === true
+          ? { enabled: true, maxRetries: DEFAULT_MAX_RETRIES }
+          : { enabled: r.enabled ?? true, maxRetries: r.maxRetries ?? DEFAULT_MAX_RETRIES }
+
+    // Timeout par défaut des requêtes (pass-through : undefined → défaut appliqué par le core).
+    this.requestTimeoutMs = resolvedOptions?.requestTimeoutMs
+
+    // Observabilité (LOT 3) : pass-through direct, consommé par fetchWithAuth/refreshOnce
+    // (core) et par AuthService (jwks-fetch-failed). `undefined` par défaut → aucune émission.
+    this.onEvent = resolvedOptions?.onEvent
+    this.debug = resolvedOptions?.debug
+
+    if (!this.apiKey && typeof console !== 'undefined') {
+      console.warn(
+        '[aurabase] No API key provided. Most operations require an API key (apikey header). ' +
+        'Only public auth routes (register, login, refresh) will work without one.',
+      )
+    }
+
+    // SEC-F5 : une clé service_role (aura_sk_) embarquée côté client fuite dans le
+    // bundle JS = compromission totale du projet (BYPASSRLS). En contexte navigateur,
+    // on ÉCHOUE la construction par défaut (throw) — un simple warn se contourne/
+    // s'ignore. `refuseServiceRoleInBrowser: false` rétrograde en warn (échappatoire
+    // explicite). createAdminClient() couvre le cas serveur légitime.
+    if (this.apiKey?.startsWith(SERVICE_ROLE_KEY_PREFIX) && isBrowserContext()) {
+      const refuse = resolvedOptions?.refuseServiceRoleInBrowser ?? true
+      const message =
+        '[aurabase] SÉCURITÉ : une clé service_role (aura_sk_…) est fournie à createClient() ' +
+        'dans un contexte navigateur. Cette clé à privilèges élevés NE DOIT JAMAIS être exposée ' +
+        'côté client (elle fuiterait dans le bundle). Utilisez une clé anon (aura_anon_…) côté ' +
+        "client, et createAdminClient() côté serveur pour les opérations d'administration."
+      if (refuse) {
+        throw new Error(message)
+      } else if (typeof console !== 'undefined') {
+        console.warn(message)
+      }
+    }
+
+    // Auth store: use provided store, or LocalAuthStore in browser, or BaseAuthStore in Node
+    if (resolvedOptions?.auth?.storage) {
+      this.authStore = resolvedOptions.auth.storage
+    } else if (resolvedOptions?.auth?.persistSession === false) {
+      this.authStore = new BaseAuthStore()
+    } else if (typeof localStorage !== 'undefined') {
+      this.authStore = new LocalAuthStore()
+    } else {
+      this.authStore = new BaseAuthStore()
+    }
+    // Câble le hook d'observabilité sur le store (LOT 3) : `storage-blocked` est émis
+    // depuis les catch `localStorage` de `LocalAuthStore` (quota dépassé, navigation
+    // privée Safari, storage désactivé…). Câblé même si un store custom est fourni via
+    // `auth.storage` (méthode héritée de `BaseAuthStore`, no-op si jamais appelée).
+    this.authStore.setObservabilityHook(this.onEvent, this.debug)
+
+    this._persistSession = resolvedOptions?.auth?.persistSession !== false
+    this._autoRefresh = resolvedOptions?.auth?.autoRefresh ?? true
+    this._detectSessionInUrl = resolvedOptions?.auth?.detectSessionInUrl
+
+    // Démarre le refresh proactif sans attendre un accès à `aura.auth`.
+    if (this._autoRefresh && this._persistSession && typeof window !== 'undefined') {
+      void this.auth
+    }
+  }
+
+  /**
+   * Démonte le client : arrête le refresh proactif (ticker + visibilité + BroadcastChannel),
+   * déconnecte le realtime, vide les listeners d'auth. Idempotent. À appeler en teardown
+   * (React Strict Mode / HMR / tests).
+   */
+  dispose(): void {
+    if (this._disposed) return
+    this._disposed = true
+    this._auth?.dispose()
+    this._realtime?.disconnect()
+  }
+
+  // -- Lazy service getters ---------------------------------------------------
+
+  get auth(): AuthService {
+    if (!this._auth) {
+      this._auth = new AuthService(this, {
+        autoRefresh: this._autoRefresh,
+        persistSession: this._persistSession,
+        detectSessionInUrl: this._detectSessionInUrl,
+      })
+    }
+    return this._auth
+  }
+
+  get authAdmin(): AuthAdminService {
+    // E21 (durci) : l'API admin exige une clé à privilèges élevés (service_role).
+    // L'utiliser côté navigateur implique d'embarquer cette clé dans le bundle JS =
+    // compromission totale du projet. On THROW (plus de simple warn : un warn se
+    // contourne/s'ignore ; l'accès admin côté client doit échouer franchement).
+    if (isBrowserContext()) {
+      throw new Error(
+        '[aurabase] SÉCURITÉ : authAdmin est inaccessible dans un contexte navigateur. ' +
+        "L'API admin requiert une clé service_role qui ne doit JAMAIS être exposée côté " +
+        'client (elle fuiterait dans le bundle). Utilisez createAdminClient() côté serveur uniquement.',
+      )
+    }
+    if (!this._authAdmin) this._authAdmin = new AuthAdminService(this)
+    return this._authAdmin
+  }
+
+  get db(): DatabaseService<Database> {
+    if (!this._db) this._db = new DatabaseService<Database>(this)
+    return this._db
+  }
+
+  get storage(): StorageService {
+    if (!this._storage) this._storage = new StorageService(this)
+    return this._storage
+  }
+
+  get realtime(): RealtimeService {
+    if (!this._realtime) this._realtime = new RealtimeService(this)
+    return this._realtime
+  }
+
+  get functions(): FunctionsService {
+    if (!this._functions) this._functions = new FunctionsService(this)
+    return this._functions
+  }
+
+  get ai(): AiService {
+    if (!this._ai) this._ai = new AiService(this)
+    return this._ai
+  }
+
+  get notifications(): NotificationsService {
+    if (!this._notifications) this._notifications = new NotificationsService(this)
+    return this._notifications
+  }
+
+  /**
+   * Shortcut: create a realtime channel with Supabase-compatible API.
+   * Equivalent to `aura.realtime.channel(name)`.
+   *
+   * @example
+   * ```ts
+   * const channel = aura.channel('room-1')
+   *   .on('postgres_changes', { event: 'INSERT', schema: 'public', table: 'messages' }, cb)
+   *   .subscribe()
+   * ```
+   */
+  channel(name: string, options?: ChannelConfig): AuraChannel {
+    return this.realtime.channel(name, options)
+  }
+}

package/packages/aurabase/src/index.ts

@@ -0,0 +1,152 @@
+export { AuraClient } from './AuraClient'
+export { AuraError, isAuraError } from '@aurabase/core'
+export { BaseAuthStore } from '@aurabase/core'
+export { LocalAuthStore } from '@aurabase/core'
+export { QueryBuilder } from '@aurabase/db'
+
+// Services (for advanced usage / typing)
+export { AuthService, isMfaChallenge } from '@aurabase/auth'
+export { AuthAdminService } from '@aurabase/auth'
+export { DatabaseService } from '@aurabase/db'
+export { StorageService } from '@aurabase/storage'
+export { RealtimeService } from '@aurabase/realtime'
+export { AuraChannel } from '@aurabase/realtime'
+export { FunctionsService } from '@aurabase/functions'
+export { AiService } from '@aurabase/ai'
+export { NotificationsService, NotificationsAdminService } from '@aurabase/notifications'
+
+// Types
+export type {
+  AuraResponse,
+  AuraErrorCode,
+  AuraObservabilityEvent,
+  AuraClientOptions,
+  Meta,
+  User,
+  TokenPair,
+  LoginResponse,
+  MfaChallenge,
+  AuthEvent,
+  AuthChangePayload,
+  SignUpRequest,
+  SignInRequest,
+  MagicLinkRequest,
+  OAuthSignInOptions,
+  PasswordResetRequest,
+  UpdateUserRequest,
+  MfaEnrollResponse,
+  MfaVerifyRequest,
+  SessionInfo,
+  FilterOp,
+  QueryFilter,
+  CountMode,
+  QueryOptions,
+  SchemaColumn,
+  SchemaTable,
+  StorageBucket,
+  UploadResult,
+  FileEntry,
+  RealtimeEvent,
+  RealtimeListenType,
+  RealtimeSubscribeStatus,
+  PostgresChangesFilter,
+  BroadcastFilter,
+  PresenceFilter,
+  PresenceState,
+  PresenceInfo,
+  ChannelConfig,
+  BroadcastPayload,
+  ChatMessage,
+  ChatResponse,
+  EmbedRequest,
+  EmbedResponse,
+  RagRequest,
+  RagResponse,
+  RagIngestRequest,
+  RagIngestResponse,
+  SemanticSearchResult,
+  FunctionDef,
+  Job,
+  CronJob,
+  Notification,
+  NotificationTemplate,
+  SendNotificationRequest,
+  BatchSendResponse,
+  NotificationRule,
+  NotificationSettings,
+  NotificationStats,
+  NotificationAttempt,
+  NotificationDeadLetter,
+  NotificationEvent,
+  NotificationProviderLog,
+  NotificationQueueStats,
+  NotificationTemplatePreview,
+  IdentityInfo,
+  AdminUser,
+  AuditLogEntry,
+  AuthSettings,
+  EmailTemplateUpdate,
+  AdminCreateUserRequest,
+  AdminUpdateUserRequest,
+} from '@aurabase/core'
+
+import { AuraClient, isBrowserContext } from './AuraClient'
+import type { AuraClientOptions } from '@aurabase/core'
+
+/**
+ * Create a new Aurabase client instance.
+ *
+ * @example
+ * ```ts
+ * // With API key (recommended — like Supabase)
+ * const aura = createClient('http://localhost:8080', 'project-uuid', 'aura_anon_xxx')
+ *
+ * // With options
+ * const aura = createClient('http://localhost:8080', 'project-uuid', 'aura_anon_xxx', {
+ *   auth: { persistSession: true }
+ * })
+ *
+ * // Without API key (backward compatible)
+ * const aura = createClient('http://localhost:8080', 'project-uuid')
+ * ```
+ */
+export function createClient<Database = any>(
+  baseUrl: string,
+  projectId: string,
+  apiKeyOrOptions?: string | AuraClientOptions,
+  options?: AuraClientOptions,
+): AuraClient<Database> {
+  return new AuraClient<Database>(baseUrl, projectId, apiKeyOrOptions, options)
+}
+
+/**
+ * Crée un client à usage **SERVEUR uniquement** pour les opérations d'administration
+ * (`client.authAdmin` : lister/créer/bannir des utilisateurs, lire l'audit). Exige une
+ * clé `service_role`. Lève une erreur si appelé dans un navigateur — cette clé ne doit
+ * jamais être embarquée dans un bundle client (E21). Équivalent du séparateur
+ * Admin SDK de Firebase / `service_role` server-side de Supabase.
+ *
+ * @example
+ * ```ts
+ * // server-side only (API route, edge function, backend)
+ * const admin = createAdminClient(url, projectId, process.env.SERVICE_ROLE_KEY!)
+ * await admin.authAdmin.listUsers()
+ * ```
+ */
+export function createAdminClient<Database = any>(
+  baseUrl: string,
+  projectId: string,
+  serviceRoleKey: string,
+  options?: AuraClientOptions,
+): AuraClient<Database> {
+  // Garde étendue au-delà de `window` : couvre aussi les Web Workers navigateur
+  // (dedicated/shared) via isBrowserContext(). ServiceWorkerGlobalScope (Cloudflare
+  // Workers = serveur) est volontairement exclu pour ne pas casser un usage serveur.
+  if (isBrowserContext()) {
+    throw new Error(
+      '[aurabase] createAdminClient() ne doit jamais être appelé côté navigateur : ' +
+      'la clé service_role serait exposée dans le bundle. À utiliser uniquement côté serveur.',
+    )
+  }
+  return new AuraClient<Database>(baseUrl, projectId, serviceRoleKey, options)
+}

package/packages/aurabase/src/ssr.ts

@@ -0,0 +1,156 @@
+/**
+ * Server-side rendering helpers for Aurabase.
+ *
+ * @example Next.js middleware
+ * ```ts
+ * import { createServerClient } from 'aurabase/ssr'
+ *
+ * export async function middleware(request) {
+ *   let response = NextResponse.next({ request })
+ *   const client = createServerClient(URL, PROJECT_ID, {
+ *     cookies: {
+ *       getAll: () => request.cookies.getAll(),
+ *       setAll: (cookies) => {
+ *         cookies.forEach(({ name, value, options }) => {
+ *           request.cookies.set(name, value)
+ *           response.cookies.set(name, value, options)
+ *         })
+ *       },
+ *     },
+ *   })
+ *   await client.auth.getSession()
+ *   return response
+ * }
+ * ```
+ *
+ * @module
+ */
+
+import { AuraClient } from './AuraClient'
+import type { AuraClientOptions } from '@aurabase/core'
+import { LocalAuthStore } from '@aurabase/core'
+import { parseCookieHeader, serializeCookieHeader } from '@aurabase/core'
+import type { SerializeCookieOptions } from '@aurabase/core'
+
+export interface CookieHandler {
+  /** Return all cookies from the incoming request. */
+  getAll(): Array<{ name: string; value: string }>
+  /** Set cookies on the outgoing response. */
+  setAll(
+    cookies: Array<{
+      name: string
+      value: string
+      options: SerializeCookieOptions
+    }>,
+  ): void
+}
+
+export interface ServerClientOptions {
+  apiKey?: string
+  cookies: CookieHandler
+  cookieOptions?: SerializeCookieOptions
+}
+
+/**
+ * Create an Aurabase client for server-side usage (SSR, API routes, middleware).
+ * Auth state is read from / written to HTTP cookies via the provided handler.
+ */
+/**
+ * Taille max d'un cookie chunk. Les navigateurs limitent un cookie à ~4096 octets
+ * (nom + valeur + attributs) ; on garde une marge confortable, comme `@supabase/ssr`.
+ */
+const MAX_CHUNK_SIZE = 3600
+
+export function createServerClient<Database = any>(
+  baseUrl: string,
+  projectId: string,
+  options: ServerClientOptions,
+): AuraClient<Database> {
+  const cookieName = `aura-${projectId}-auth`
+  const store = new LocalAuthStore(cookieName)
+  // Regex des cookies chunkés `aura-<pid>-auth.<n>` (nom échappé pour la sûreté).
+  const idxRe = new RegExp(`^${cookieName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\.(\\d+)$`)
+
+  // ── Lecture : reconstitue la session depuis le cookie unique OU les chunks ──
+  const incoming = options.cookies.getAll()
+  const numbered = incoming
+    .filter((c) => idxRe.test(c.name))
+    .sort((a, b) => Number(a.name.match(idxRe)![1]) - Number(b.name.match(idxRe)![1]))
+  const base = incoming.find((c) => c.name === cookieName)
+  const decodedValue = numbered.length > 0 ? numbered.map((c) => c.value).join('') : base?.value
+  if (decodedValue) {
+    store.loadFromCookie(`${cookieName}=${encodeURIComponent(decodedValue)}`)
+  }
+  // Noms de cookies auth présents à l'entrée → à expirer s'ils ne sont plus utilisés.
+  const initialNames = incoming
+    .filter((c) => c.name === cookieName || idxRe.test(c.name))
+    .map((c) => c.name)
+
+  // Défaut `secure` calé sur le protocole : `true` en https, `false` en http (dev localhost).
+  // Surchargez via `cookieOptions.secure` si besoin.
+  const defaultCookieOpts: SerializeCookieOptions = {
+    path: '/',
+    secure: baseUrl.startsWith('https://'),
+    sameSite: 'Lax',
+    httpOnly: true,
+    maxAge: 60 * 60 * 24 * 30, // 30 days
+    ...options.cookieOptions,
+  }
+
+  // ── Écriture : propage les changements d'auth vers les cookies de réponse ──
+  store.onChange(() => {
+    const toSet: Array<{ name: string; value: string; options: SerializeCookieOptions }> = []
+    const used = new Set<string>()
+
+    if (store.token) {
+      // Valeur (JSON) décodée à chunker ; le framework ré-encode à la pose.
+      const cookieStr = store.exportToCookie()
+      const eqIdx = cookieStr.indexOf('=')
+      const rawEncoded = eqIdx >= 0 ? cookieStr.slice(eqIdx + 1).split(';')[0] : ''
+      const decoded = rawEncoded ? decodeURIComponent(rawEncoded) : ''
+
+      if (decoded.length <= MAX_CHUNK_SIZE) {
+        toSet.push({ name: cookieName, value: decoded, options: defaultCookieOpts })
+        used.add(cookieName)
+      } else {
+        // Fragmentation : `aura-<pid>-auth.0`, `.1`, … (anti-troncature silencieuse).
+        let idx = 0
+        for (let i = 0; i < decoded.length; i += MAX_CHUNK_SIZE, idx++) {
+          const name = `${cookieName}.${idx}`
+          toSet.push({ name, value: decoded.slice(i, i + MAX_CHUNK_SIZE), options: defaultCookieOpts })
+          used.add(name)
+        }
+      }
+    }
+
+    // Expire tout cookie auth présent avant mais désormais inutilisé (signout, ou
+    // passage de N chunks à moins de chunks) — évite de laisser traîner une session.
+    const expireOpts: SerializeCookieOptions = { ...defaultCookieOpts, maxAge: 0 }
+    for (const name of initialNames) {
+      if (!used.has(name)) toSet.push({ name, value: '', options: expireOpts })
+    }
+
+    if (toSet.length > 0) options.cookies.setAll(toSet)
+  })
+
+  return new AuraClient<Database>(baseUrl, projectId, options.apiKey, {
+    auth: { persistSession: false, storage: store },
+  })
+}
+
+/**
+ * Create an Aurabase client for browser usage.
+ * Thin wrapper around AuraClient with sensible browser defaults.
+ */
+export function createBrowserClient<Database = any>(
+  baseUrl: string,
+  projectId: string,
+  apiKey?: string,
+  options?: AuraClientOptions,
+): AuraClient<Database> {
+  return new AuraClient<Database>(baseUrl, projectId, apiKey, options)
+}
+
+// Re-export cookie utilities
+export { parseCookieHeader, serializeCookieHeader } from '@aurabase/core'
+export type { SerializeCookieOptions } from '@aurabase/core'

package/packages/aurabase/tests/ai-streaming-rag-e2e.test.ts

@@ -0,0 +1,82 @@
+// ---------------------------------------------------------------------------
+// E2E réel (stack live) — Lot sdk-ai / `ai-chat-streaming` + `ai-rag-namespaces-crud`.
+// Réf. : docs/superpowers/specs/2026-07-13-ai-chat-streaming-design.md
+//
+// Vérifie que le CHEMIN SSE de `ai.chatStream` (client.fetchFn brut + parseSSE)
+// atteint le backend `/chat/stream` et livre un flux exploitable, et que le CRUD
+// RAG (`listNamespaces`) est bien câblé. Tolérant à l'absence de provider LLM en
+// local : distingue un flux fonctionnel / une erreur applicative (provider) d'un
+// échec de ROUTE (404) ou d'un timeout, qui eux feraient échouer le test.
+// ---------------------------------------------------------------------------
+
+import { describe, it, expect } from 'vitest'
+import { createAdminClient } from '../src/index'
+
+const URL = process.env.AURA_E2E_URL
+const PROJECT = process.env.AURA_E2E_PROJECT
+const SERVICE = process.env.AURA_E2E_SERVICE_KEY
+const RUN = Boolean(process.env.RUN_E2E && URL && PROJECT && SERVICE)
+const TRANSIENT = new Set([408, 429, 502, 503, 504])
+
+describe.runIf(RUN)('ai chatStream + RAG CRUD E2E réel', () => {
+  it(
+    'chatStream ouvre le flux SSE via /chat/stream (deltas ou erreur applicative, pas 404/timeout)',
+    async () => {
+      const admin = createAdminClient(URL!, PROJECT!, SERVICE!)
+      let deltas = 0
+      let streamErr: { status: number; message?: string } | null = null
+      const ctrl = new AbortController()
+      const cutoff = setTimeout(() => ctrl.abort(), 20_000)
+
+      try {
+        for await (const chunk of admin.ai.chatStream(
+          [{ role: 'user', content: 'Dis simplement bonjour.' }],
+          { model: 'gpt-4o-mini', signal: ctrl.signal },
+        )) {
+          if (chunk.delta) deltas += 1
+          if (deltas >= 3) break // assez pour prouver le streaming
+        }
+      } catch (e) {
+        streamErr = e as { status: number; message?: string }
+      } finally {
+        clearTimeout(cutoff)
+      }
+
+      if (deltas > 0) {
+        // Streaming réel prouvé (provider présent).
+        expect(deltas).toBeGreaterThan(0)
+      } else if (streamErr) {
+        // Pas de provider LLM en local : on DOIT avoir atteint le backend et reçu
+        // une erreur APPLICATIVE (config/provider), PAS un 404 de route ni un
+        // échec transport — cela prouve que le chemin SSE fetchFn+parseSSE marche.
+        expect(
+          streamErr.status,
+          `chatStream a échoué avec un statut de ROUTE/transport (${streamErr.status}: ${streamErr.message}) — ` +
+            `le chemin SSE n'atteint pas le backend`,
+        ).not.toBe(404)
+        expect(TRANSIENT.has(streamErr.status), `statut transitoire ${streamErr.status}`).toBe(false)
+        console.warn(
+          `[ai-streaming-rag-e2e] chatStream : aucun delta mais erreur applicative ${streamErr.status} ` +
+            `(${streamErr.message}) — chemin SSE OK, provider LLM probablement non configuré en local.`,
+        )
+      } else {
+        console.warn('[ai-streaming-rag-e2e] chatStream : ni delta ni erreur (flux vide / annulé) — toléré.')
+      }
+    },
+    45_000,
+  )
+
+  it('listNamespaces (RAG CRUD) est câblé et répond', async () => {
+    const admin = createAdminClient(URL!, PROJECT!, SERVICE!)
+    const res = await admin.ai.listNamespaces()
+    if (res.error && TRANSIENT.has(res.error.status)) {
+      console.warn(`[ai-streaming-rag-e2e] SKIP listNamespaces (${res.error.status}).`)
+      return
+    }
+    // La route doit répondre (pas de 404) et renvoyer une liste (éventuellement vide).
+    expect(res.error?.status, `listNamespaces route absente/erreur: ${JSON.stringify(res.error)}`).not.toBe(404)
+    if (!res.error) {
+      expect(Array.isArray(res.data), 'listNamespaces doit renvoyer un tableau').toBe(true)
+    }
+  })
+})