@aurabase/aurabase-js 0.3.0 → 0.4.0

package/packages/core/src/types.ts

@@ -1,1042 +0,0 @@
-// ---------------------------------------------------------------------------
-// Shared TypeScript types for the Aurabase SDK
-// ---------------------------------------------------------------------------
-
-// ---- Generic response wrapper ---------------------------------------------
-
-// E18 : une seule source de vérité pour les erreurs — la CLASSE `AuraError`
-// (avec `status`, `isUnauthorized`, etc.). L'ancienne interface POJO menait à des
-// `error` sans méthodes alors que le type promettait la classe.
-export { AuraError } from './AuraError'
-import type { AuraError } from './AuraError'
-export type { AuraErrorCode } from './AuraError'
-
-export interface Meta {
-  total?: number
-  next_cursor?: string
-}
-
-export interface AuraResponse<T> {
-  data: T | null
-  error: AuraError | null
-  meta?: Meta
-}
-
-// ---- Auth -----------------------------------------------------------------
-
-export interface User {
-  id: string
-  email: string | null
-  phone?: string | null
-  role: string
-  email_verified: boolean
-  is_banned: boolean
-  is_anonymous: boolean
-  mfa_enabled: boolean
-  avatar_url?: string | null
-  name?: string | null
-  user_metadata: Record<string, unknown>
-  app_metadata: Record<string, unknown>
-  created_at: string
-  last_sign_in_at?: string | null
-}
-
-export interface TokenPair {
-  access_token: string
-  refresh_token: string
-  token_type: string
-  expires_in: number
-  user: User
-  provider_token?: string | null
-  provider_refresh_token?: string | null
-}
-
-export interface MfaChallenge {
-  mfa_required: true
-  mfa_token: string
-  mfa_setup_required?: boolean
-}
-
-export type LoginResponse = TokenPair | MfaChallenge
-
-export type AuthEvent =
-  | 'INITIAL_SESSION'
-  | 'SIGNED_IN'
-  | 'SIGNED_OUT'
-  | 'TOKEN_REFRESHED'
-  | 'USER_UPDATED'
-  | 'MFA_CHALLENGE'
-  | 'PASSWORD_RECOVERY'
-
-/**
- * Payload émis par `onAuthStateChange`. NOTE (LOT 3, 3.4) : `mfaToken`/`mfaSetupRequired`
- * ne sont présents QUE lorsque `event === 'MFA_CHALLENGE'` (posés par `AuthService`
- * uniquement sur cet événement — voir `_emitEvent` dans `AuthService.ts`) ; sur tout
- * autre `event`, ces deux champs sont `undefined`. Le type reste une interface plate
- * (pas une union discriminée) pour ne pas casser les consommateurs existants qui
- * déstructurent `{event, user, accessToken}` sans varier selon `event` — mais un
- * consommateur qui lit `mfaToken` DOIT d'abord vérifier `event === 'MFA_CHALLENGE'`.
- */
-export interface AuthChangePayload {
-  event: AuthEvent
-  user: User | null
-  accessToken: string | null
-  /** Présent uniquement si `event === 'MFA_CHALLENGE'`. */
-  mfaToken?: string
-  /** Présent uniquement si `event === 'MFA_CHALLENGE'`. */
-  mfaSetupRequired?: boolean
-  /**
-   * Token de récupération opaque à passer à `resetPassword(token, newPassword)`.
-   * Présent uniquement si `event === 'PASSWORD_RECOVERY'` (extrait du lien email
-   * `?token=…&type=recovery` par `detectSessionInUrl`). `undefined` sur tout autre
-   * événement.
-   */
-  recoveryToken?: string
-}
-
-export interface SignUpRequest {
-  email: string
-  password: string
-  captcha_token?: string
-}
-
-export interface SignInRequest {
-  email: string
-  password: string
-  captcha_token?: string
-}
-
-export interface MagicLinkRequest {
-  email: string
-  create_user?: boolean
-  captcha_token?: string
-  redirect_url?: string
-}
-
-export interface OAuthSignInOptions {
-  redirectTo?: string
-  scopes?: string
-  queryParams?: Record<string, string>
-  /**
-   * Active le flux PKCE (génère + stocke un `code_verifier`, envoie
-   * `code_challenge`/`code_challenge_method=S256` au provider). Opt-in :
-   * absent ou `'implicit'` conserve le comportement existant (aucun
-   * paramètre PKCE) pour ne pas casser silencieusement les consommateurs
-   * actuels du flux implicite.
-   */
-  flowType?: 'pkce' | 'implicit'
-}
-
-export interface PasswordResetRequest {
-  email: string
-}
-
-export interface UpdateUserRequest {
-  email?: string
-  phone?: string
-  password?: string
-  current_password?: string
-  data?: Record<string, unknown>
-}
-
-export interface MfaEnrollResponse {
-  otpauth_url: string
-  secret: string
-}
-
-export interface MfaVerifyRequest {
-  mfa_token: string
-  code: string
-}
-
-export interface SessionInfo {
-  id: string
-  device_info?: string | null
-  ip_address?: string | null
-  created_at: string
-  expires_at: string
-  last_used_at: string
-  is_current: boolean
-}
-
-// ---- Database / Query -----------------------------------------------------
-
-export type FilterOp =
-  | 'eq'
-  | 'neq'
-  | 'gt'
-  | 'gte'
-  | 'lt'
-  | 'lte'
-  | 'in'
-  | 'not_in'
-  | 'like'
-  | 'ilike'
-  | 'is_null'
-  | 'is_not_null'
-  | 'between'
-
-export interface QueryFilter {
-  column: string
-  op: string
-  value: unknown
-}
-
-export type CountMode = 'exact' | 'estimated'
-
-export interface QueryOptions {
-  select?: string[]
-  filters?: QueryFilter[]
-  sort_by?: string
-  sort_order?: 'asc' | 'desc'
-  limit?: number
-  offset?: number
-  count?: CountMode
-}
-
-export interface SchemaColumn {
-  name: string
-  col_type: string
-  nullable: boolean
-  unique: boolean
-  default_val?: string | null
-  references?: { table: string; column: string; constraint_name?: string | null } | null
-}
-
-export interface SchemaIndex {
-  name: string
-  columns: string[]
-  unique: boolean
-}
-
-export interface SchemaTable {
-  name: string
-  columns: SchemaColumn[]
-  primary_key?: string
-  indexes: SchemaIndex[]
-  rls_enabled: boolean
-  realtime_enabled: boolean
-}
-
-export interface SchemaFunctionArg {
-  name: string
-  data_type: string
-  mode: string
-}
-
-export interface SchemaFunction {
-  name: string
-  args: SchemaFunctionArg[]
-  returns: string
-  is_set_returning: boolean
-}
-
-/**
- * Type enum Postgres (`pg_type.typtype='e'`) exposé par `GET /schema` (LOT B).
- * `values` est ordonné (`enumsortorder`). Le générateur SDK (`@aurabase/gen`)
- * en dérive une union de littéraux `Database['public']['Enums'][name]`.
- */
-export interface SchemaEnum {
-  name: string
-  values: string[]
-}
-
-// ---- Storage --------------------------------------------------------------
-
-/**
- * Options de transformation d'image (vocabulaire façon Supabase) appliquées
- * côté rendu backend (`GET /v1/storage/{pid}/{bucket}/{key}?width=&height=&
- * fit=&format=&quality=`). Voir `renderTransformParams` (`@aurabase/storage`)
- * pour le mapping vers les query params du backend.
- */
-export interface ImageTransform {
-  width?: number
-  height?: number
-  resize?: 'cover' | 'contain' | 'fill'
-  quality?: number
-  format?: 'origin' | 'jpeg' | 'png' | 'webp' | 'gif'
-}
-
-export interface StorageBucket {
-  id: string
-  name: string
-  public: boolean
-  file_size_limit?: number | null
-  allowed_mime_types?: string[] | null
-  created_at: string
-  updated_at: string
-}
-
-export interface UploadResult {
-  /** Clé unique de l'objet (`<uuid>.<ext>`) relative au bucket. */
-  key: string
-  url: string
-  size: number
-  mime_type: string
-}
-
-export interface FileEntry {
-  name: string
-  id?: string
-  bucket_id: string
-  size: number
-  mime_type: string
-  created_at: string
-  updated_at: string
-  metadata?: Record<string, unknown>
-}
-
-/** Métadonnées d'un objet storage — forme réelle retournée par getMetadata() */
-export interface ObjectMeta {
-  key: string
-  bucket: string
-  size: number
-  content_type: string
-  etag?: string | null
-  last_modified?: string | null
-  metadata: Record<string, string>
-}
-
-// ---- Realtime -------------------------------------------------------------
-
-/** Événement serveur brut reçu via WebSocket (union discriminée par type) */
-export type ServerMessage =
-  | ServerSubscribedMsg
-  | ServerEventMsg
-  | ServerPongMsg
-  | ServerErrorMsg
-  | ServerTokenRefreshedMsg
-  | ServerPresenceStateMsg
-  | BroadcastAckMessage
-
-export interface ServerSubscribedMsg {
-  type: 'subscribed'
-  channel: string
-  subscription_id?: string
-  history: RealtimeEvent[]
-  ref_id?: string
-}
-
-export interface ServerEventMsg {
-  type: 'event'
-  // Serde flatten : les champs de RealtimeEvent sont au top-level
-  id: string
-  event: 'insert' | 'update' | 'delete' | 'broadcast' | 'presence' | 'system'
-  topic: string
-  payload: Record<string, unknown>
-  timestamp: string
-  allowed_sub_ids?: string[]
-}
-
-export interface ServerPongMsg { type: 'pong' }
-export interface ServerErrorMsg { type: 'error'; message: string }
-export interface ServerTokenRefreshedMsg { type: 'token_refreshed' }
-
-export interface ServerPresenceStateMsg {
-  type: 'presence_state'
-  channel: string
-  presences: PresenceInfo[]
-}
-
-/** Événement realtime (CDC, broadcast, presence) */
-export interface RealtimeEvent<T = Record<string, unknown>> {
-  id: string
-  event: 'insert' | 'update' | 'delete' | 'broadcast' | 'presence' | 'system'
-  topic: string
-  payload: T
-  timestamp: string
-  /** IDs des subscriptions autorisées par RLS. Absent = pas de filtre. */
-  allowed_sub_ids?: string[]
-  /** Ref ID corrélé à la requête client (si fourni) */
-  ref_id?: string
-}
-
-/** Accusé de réception d'un broadcast (envoyé si config.broadcast.ack = true) */
-export interface BroadcastAckMessage {
-  type: 'broadcast_ack'
-  message_id: string
-  ref_id?: string
-}
-
-/** Payload CDC (postgres_changes) avec old_record et type d'operation */
-export interface CdcPayload {
-  schema: string
-  table: string
-  type: 'INSERT' | 'UPDATE' | 'DELETE'
-  record: Record<string, unknown>
-  old_record: Record<string, unknown> | null
-  _truncated?: boolean
-}
-
-/** Status de subscription */
-export type RealtimeSubscribeStatus = 'SUBSCRIBED' | 'CLOSED' | 'CHANNEL_ERROR' | 'TIMED_OUT'
-
-/** Callback de subscription */
-export type SubscribeCallback = (status: RealtimeSubscribeStatus, err?: Error) => void
-
-/** Types d'écoute supportés (pattern Supabase) */
-export type RealtimeListenType = 'postgres_changes' | 'broadcast' | 'presence'
-
-/** Config pour postgres_changes */
-export interface PostgresChangesFilter {
-  event: 'INSERT' | 'UPDATE' | 'DELETE' | '*'
-  schema?: string
-  table?: string
-  /**
-   * Filtre sur colonne, syntaxe PostgREST/Supabase : `"column=operator.value"`.
-   *
-   * **Opérateurs supportés** : `eq, neq, lt, lte, gt, gte, in, like, ilike, is,
-   * match, imatch, isdistinct`.
-   *
-   * - `eq`/`neq` : égalité/inégalité (comparaison textuelle).
-   * - `lt`/`lte`/`gt`/`gte` : comparaison numérique (échoue — pas de match — si
-   *   la valeur n'est pas numérique).
-   * - `in` : appartenance à une liste, `"status=in.(active,pending)"`.
-   * - `like`/`ilike` : motif SQL (`%` = sous-chaîne, `_` = 1 caractère), `ilike`
-   *   insensible à la casse. Ex: `"name=like.jo%"`.
-   * - `is` : `"col=is.null"` / `"col=is.true"` / `"col=is.false"` — compare la
-   *   valeur JSON réelle, pas sa représentation texte.
-   * - `match`/`imatch` : expression régulière (`imatch` insensible à la casse).
-   * - `isdistinct` : distinct au sens SQL — `NULL` est distinct de toute valeur
-   *   non-NULL.
-   *
-   * **Négation** : préfixer l'opérateur par `not.`, ex: `"status=not.eq.done"`.
-   *
-   * **AND** : plusieurs conditions séparées par des virgules, ex:
-   * `"room_id=eq.42,qty=gt.5"` (toutes doivent matcher). Les virgules internes
-   * d'un `in.(a,b,c)` ne séparent PAS les conditions.
-   *
-   * **Où c'est évalué** : le serveur `aura-realtime` filtre ces conditions de
-   * façon **autoritaire** avant l'envoi au client — un `filter` invalide y est
-   * fail-closed (l'event est exclu, jamais laissé passer par défaut). Le SDK
-   * réévalue ensuite la même syntaxe côté client comme second rideau
-   * (defense-in-depth) : il ne peut que sur-filtrer, jamais faire fuiter un
-   * event que le serveur aurait dû exclure.
-   *
-   * **DELETE** : le prédicat est évalué sur l'**ancienne ligne** (`old_record`),
-   * puisque le `record` d'un DELETE est vide côté CDC. Si votre table utilise
-   * `REPLICA IDENTITY DEFAULT`, `old_record` ne contient que la clé primaire —
-   * un filtre sur une autre colonne exclura systématiquement les DELETE, **sauf
-   * `is.null`/`isdistinct`** qui traitent une colonne absente comme `NULL` et
-   * peuvent donc matcher même sans cette colonne dans `old_record`.
-   */
-  filter?: string
-}
-
-/** Config pour broadcast */
-export interface BroadcastFilter {
-  event: string
-}
-
-/** Config pour presence */
-export interface PresenceFilter {
-  event: 'sync' | 'join' | 'leave'
-}
-
-/** Options de channel — compatible Supabase */
-export interface ChannelConfig {
-  private?: boolean
-  /** Configuration broadcast pour ce channel */
-  broadcast?: {
-    /** Si true, le serveur ACK chaque send() (résout la Promise) */
-    ack?: boolean
-    /** Si true, le client reçoit ses propres broadcasts (self-echo) */
-    self?: boolean
-  }
-  /** Configuration présence */
-  config?: {
-    presence?: {
-      /** Clé de présence — permet de regrouper plusieurs onglets/devices du même user */
-      key?: string
-    }
-  }
-}
-
-/** Payload d'un broadcast à envoyer */
-export interface BroadcastPayload {
-  type: 'broadcast'
-  event: string
-  payload: Record<string, unknown>
-  /** Ref ID pour la corrélation request/response (optionnel) */
-  ref_id?: string
-}
-
-/** Presence state (map de key → presences) */
-export type PresenceState = Record<string, PresenceInfo[]>
-
-export interface PresenceInfo {
-  client_id: string
-  user_id?: string | null
-  metadata: Record<string, unknown>
-  joined_at: string
-  last_seen: string
-}
-
-// ---- AI -------------------------------------------------------------------
-
-export interface ChatMessage {
-  role: 'system' | 'user' | 'assistant'
-  content: string
-}
-
-export interface ChatResponse {
-  model: string
-  content: string
-  input_tokens?: number
-  output_tokens?: number
-}
-
-export interface EmbedRequest {
-  text: string
-  namespace: string
-  metadata?: Record<string, unknown>
-}
-
-export interface EmbedResponse {
-  id: string
-  dimensions: number
-}
-
-export interface RagRequest {
-  question: string
-  namespace: string
-  history?: ChatMessage[]
-  system?: string
-}
-
-export interface RagResponse {
-  answer: string
-  sources: Array<{ id: string; content: string; metadata: Record<string, unknown>; similarity: number }>
-  model: string
-  tokens?: number
-}
-
-export interface RagIngestRequest {
-  namespace: string
-  content: string
-  metadata?: Record<string, unknown>
-}
-
-export interface RagIngestResponse {
-  id: string
-  chunks: number
-}
-
-export interface SemanticSearchResult {
-  id: string
-  content: string
-  metadata: Record<string, unknown>
-  similarity: number
-}
-
-// ---- Functions ------------------------------------------------------------
-
-export interface FunctionDef {
-  id: string
-  project_id: string
-  name: string
-  runtime: string
-  code: string
-  code_hash: string
-  env_vars: Record<string, unknown>
-  is_active: boolean
-  created_at: string
-  updated_at: string
-}
-
-export interface Job {
-  id: string
-  project_id: string
-  function_name: string
-  status: 'pending' | 'running' | 'completed' | 'failed' | 'dead'
-  payload: unknown
-  attempts: number
-  max_attempts: number
-  error?: string | null
-  scheduled_at: string
-  started_at?: string | null
-  created_at: string
-  completed_at?: string | null
-}
-
-export interface CronJob {
-  id: string
-  project_id: string
-  name: string
-  schedule: string
-  function_name: string
-  payload: unknown
-  is_active: boolean
-  last_run?: string | null
-  next_run?: string | null
-  created_at: string
-}
-
-// ---- Notifications --------------------------------------------------------
-
-export interface Notification {
-  id: string
-  project_id?: string
-  channel: 'email' | 'sms' | 'push' | 'webhook'
-  recipient: string
-  subject?: string | null
-  body: string
-  status: 'queued' | 'processing' | 'sent' | 'failed' | 'delivered' | 'expired' | 'dead_lettered'
-  error?: string | null
-  metadata?: Record<string, unknown>
-  attempt_count?: number
-  last_attempt_at?: string | null
-  next_attempt_at?: string | null
-  locked_until?: string | null
-  lock_owner?: string | null
-  provider_message_id?: string | null
-  delivered_at?: string | null
-  expires_at?: string | null
-  idempotency_key?: string | null
-  payload_hash?: string | null
-  last_error?: string | null
-  last_error_code?: string | null
-  last_provider_response?: string | null
-  processing_started_at?: string | null
-  completed_at?: string | null
-  updated_at?: string
-  sent_at?: string | null
-  created_at: string
-}
-
-export interface SendNotificationRequest {
-  channel: 'email' | 'sms' | 'push' | 'webhook'
-  recipient: string
-  body?: string
-  subject?: string
-  template_id?: string
-  variables?: Record<string, unknown>
-  metadata?: Record<string, unknown>
-  idempotency_key?: string
-}
-
-export interface BatchSendItemResult {
-  index: number
-  status: 'queued' | 'error'
-  notification?: Notification | null
-  error?: string | null
-}
-
-export interface BatchSendResponse {
-  items: BatchSendItemResult[]
-}
-
-export interface NotificationTemplate {
-  id: string
-  name: string
-  channel: 'email' | 'sms' | 'push' | 'webhook'
-  subject?: string | null
-  body: string
-  variables?: string[]
-  created_at: string
-  updated_at: string
-}
-
-export interface NotificationTemplatePreview {
-  subject?: string | null
-  body: string
-}
-
-export interface NotificationAttempt {
-  id: string
-  notification_id: string
-  project_id: string
-  channel: 'email' | 'sms' | 'push' | 'webhook'
-  provider: string
-  attempt_number: number
-  status: 'processing' | 'sent' | 'failed' | 'retry_scheduled' | 'dead_lettered'
-  started_at: string
-  completed_at?: string | null
-  duration_ms?: number | null
-  error_code?: string | null
-  error_message?: string | null
-  provider_response?: string | null
-  created_at: string
-}
-
-export interface NotificationDeadLetter {
-  id: string
-  notification_id: string
-  project_id: string
-  channel: 'email' | 'sms' | 'push' | 'webhook'
-  recipient: string
-  subject?: string | null
-  body: string
-  metadata?: Record<string, unknown>
-  payload_hash?: string | null
-  idempotency_key?: string | null
-  attempt_count: number
-  last_error: string
-  last_error_code: string
-  last_provider_response?: string | null
-  failed_at: string
-  created_at: string
-}
-
-export interface NotificationEvent {
-  id: string
-  project_id: string
-  subject: string
-  event_type: string
-  status: 'received' | 'matched' | 'ignored' | 'failed' | 'enqueued'
-  rule_id?: string | null
-  notification_id?: string | null
-  error?: string | null
-  metadata?: Record<string, unknown>
-  created_at: string
-}
-
-export interface NotificationProviderLog {
-  timestamp: string
-  notification_id: string
-  channel: 'email' | 'sms' | 'push' | 'webhook'
-  provider: string
-  status: string
-  duration_ms?: number | null
-  error_code?: string | null
-  error_message?: string | null
-  provider_response?: string | null
-  provider_message_id?: string | null
-}
-
-export interface NotificationQueueStats {
-  queued_count: number
-  processing_count: number
-  retry_scheduled_count: number
-  expired_processing_count: number
-  next_retry_at_min?: string | null
-}
-
-export interface NotificationChannelStats {
-  channel: 'email' | 'sms' | 'push' | 'webhook'
-  total: number
-  sent: number
-  delivered: number
-  failed: number
-  dead_lettered: number
-  queued: number
-  processing: number
-  success_rate: number
-  failure_rate: number
-}
-
-export interface NotificationStats {
-  window: string
-  channel?: 'email' | 'sms' | 'push' | 'webhook' | null
-  total: number
-  sent: number
-  delivered: number
-  failed: number
-  dead_lettered: number
-  queued: number
-  processing: number
-  success_rate: number
-  failure_rate: number
-  by_status: Array<{ status: string; count: number }>
-  by_channel: NotificationChannelStats[]
-  timeline: Array<{
-    bucket: string
-    total: number
-    sent: number
-    delivered: number
-    failed: number
-    dead_lettered: number
-  }>
-}
-
-export interface NotificationSettings {
-  project_id: string
-  smtp?: Record<string, unknown>
-  twilio?: Record<string, unknown>
-  fcm?: Record<string, unknown>
-  apns?: Record<string, unknown>
-  webhook?: Record<string, unknown>
-  quotas?: Record<string, unknown>
-  updated_at?: string | null
-}
-
-export interface NotificationRule {
-  id: string
-  project_id: string
-  name: string
-  trigger_type: string
-  condition: Record<string, unknown>
-  template_id?: string | null
-  channel: 'email' | 'sms' | 'push' | 'webhook'
-  recipient_expr: string
-  enabled: boolean
-  delay_seconds: number
-  fire_count: number
-  last_fired_at?: string | null
-  created_at: string
-  updated_at: string
-}
-
-// ---- Observability (LOT 3, finding I8) -------------------------------------
-
-/**
- * Événement d'observabilité interne du SDK. Émis best-effort via le hook `onEvent`
- * (option client) et/ou `console.debug` (option `debug: true`) — voir `emitAuraEvent`.
- * Les erreurs sont massivement avalées ailleurs dans le SDK (`catch {}` JWKS/storage/
- * cookie/subscribers) : ce hook rend visibles les retries, timeouts, refresh
- * silencieux et échecs JWKS/storage sans changer le contrat `AuraResponse`.
- */
-export type AuraObservabilityEvent =
-  | { kind: 'retry'; attempt: number; status?: number; url: string }
-  | { kind: 'timeout'; url: string }
-  | { kind: 'refresh-success' }
-  | { kind: 'refresh-discarded'; reason: string }
-  | { kind: 'jwks-fetch-failed'; baseUrl: string }
-  | { kind: 'storage-blocked'; op: string }
-
-/**
- * Émet un `AuraObservabilityEvent` vers le hook `onEvent` et/ou `console.debug`
- * (si `debug: true`). NE THROW JAMAIS : un hook `onEvent` fourni par le consommateur
- * qui lève une exception ne doit jamais interrompre le flux SDK (retry/refresh/
- * storage restent fonctionnels) — d'où le try/catch autour de l'appel.
- */
-/**
- * Rédige une URL avant journalisation (minor SEC 6a) : retire la query ET le fragment.
- * Ils peuvent porter des CAPACITÉS bearer — `?apikey=`, `?token=`, `?sig=`, une URL
- * signée de storage — qu'on ne doit jamais exposer via l'observabilité (`onEvent`
- * consommateur ou `console.debug`). On ne garde que schéma + host + chemin.
- */
-function redactUrl(u: string): string {
-  const cut = u.search(/[?#]/)
-  return cut === -1 ? u : u.slice(0, cut)
-}
-
-export function emitAuraEvent(
-  onEvent: ((event: AuraObservabilityEvent) => void) | undefined,
-  debug: boolean | undefined,
-  event: AuraObservabilityEvent,
-): void {
-  // Minor SEC 6a : rédige tout champ `url` porteur de query/fragment (retry/timeout)
-  // AVANT de l'émettre. `baseUrl` (jwks-fetch-failed) est déjà une base sans query.
-  const safe: AuraObservabilityEvent =
-    'url' in event && typeof event.url === 'string'
-      ? { ...event, url: redactUrl(event.url) }
-      : event
-  if (debug && typeof console !== 'undefined' && typeof console.debug === 'function') {
-    try {
-      console.debug('[aurabase]', safe)
-    } catch {
-      // ignore — le logging ne doit jamais casser le SDK
-    }
-  }
-  if (!onEvent) return
-  try {
-    onEvent(safe)
-  } catch {
-    // le hook consommateur ne doit JAMAIS throw / casser le SDK
-  }
-}
-
-// ---- Client options -------------------------------------------------------
-
-export interface AuraClientOptions {
-  auth?: {
-    persistSession?: boolean
-    storage?: import('./stores/BaseAuthStore').BaseAuthStore
-    /** Refresh proactif en arrière-plan + synchro multi-onglets (défaut true). */
-    autoRefresh?: boolean
-    /**
-     * Détecte et consomme automatiquement une session présente dans l'URL au boot
-     * du client (callback OAuth) : fragment `#access_token=…` (flux implicit) ou
-     * query `?code=…` (flux PKCE), puis nettoie l'URL via `history.replaceState`.
-     * Défaut : `true` en navigateur, no-op hors navigateur (SSR/Node).
-     */
-    detectSessionInUrl?: boolean
-  }
-  apiKey?: string
-  fetch?: typeof globalThis.fetch
-  /**
-   * SEC-F5 : si une clé `service_role` (`aura_sk_…`) est fournie en contexte NAVIGATEUR
-   * (thread principal ou Web Worker navigateur), `true` (DÉFAUT) fait ÉCHOUER la
-   * construction du client (`throw`) — cette clé à privilèges élevés (BYPASSRLS)
-   * fuiterait dans le bundle JS = compromission totale du projet. `false` rétrograde
-   * en simple `console.warn` (échappatoire explicite, à n'utiliser qu'en connaissance
-   * de cause). Sans effet côté serveur (où service_role est légitime).
-   */
-  refuseServiceRoleInBrowser?: boolean
-  /** Retry transitoire des GET/HEAD (activé par défaut). `false` désactive. */
-  retry?: boolean | { enabled?: boolean; maxRetries?: number }
-  /**
-   * Timeout par défaut (ms) des requêtes JSON sans `signal` fourni (borne un serveur
-   * qui « hang »). N'affecte ni les uploads FormData ni les appels gérant leur propre
-   * annulation (invoke, download). `0` désactive. Défaut : 30 000 ms.
-   */
-  requestTimeoutMs?: number
-  /**
-   * Hook d'observabilité (LOT 3, finding I8) : reçoit chaque `AuraObservabilityEvent`
-   * (retry transitoire, timeout, refresh de session réussi/écarté, échec fetch JWKS,
-   * storage bloqué). Best-effort — le SDK l'appelle dans un try/catch, ce hook ne
-   * peut jamais faire échouer une requête. `undefined` par défaut (aucune émission).
-   */
-  onEvent?: (event: AuraObservabilityEvent) => void
-  /**
-   * Si `true`, chaque `AuraObservabilityEvent` est aussi journalisé via
-   * `console.debug('[aurabase]', event)`, en plus (ou à la place) du hook `onEvent`.
-   * Défaut `false`.
-   */
-  debug?: boolean
-}
-
-// Phase 2 additions
-
-export interface IdentityInfo {
-  id: string
-  provider: string
-  provider_id: string
-  identity_data: Record<string, unknown>
-  auto_linked: boolean
-  created_at: string
-}
-
-// AdminUser : le backend renvoie PublicUser (pas de is_active/password_hash ; a `name`).
-export interface AdminUser extends User {}
-
-export interface AuditLogEntry {
-  id: string
-  user_id?: string | null
-  action: string
-  ip_address?: string | null
-  user_agent?: string | null
-  created_at: string
-}
-
-export interface UserStats {
-  total: number
-  verified: number
-  banned: number
-  mfa_enabled: number
-  new_7d: number
-}
-
-/**
- * Sessions vues depuis l'admin (endpoint `admin/sessions`) : contient `user_id`
- * (toutes sessions, tous utilisateurs) mais pas `is_current` (contrairement à
- * `SessionInfo`, qui décrit les sessions de l'utilisateur courant).
- */
-export interface AdminSessionInfo {
-  id: string
-  user_id: string
-  device_info?: string | null
-  ip_address?: string | null
-  created_at: string
-  expires_at: string
-  last_used_at: string
-}
-
-export interface AuthSettings {
-  allow_signup: boolean
-  email_confirmation_required: boolean
-  password_min_length: number
-  mfa_enabled: boolean
-  allow_anonymous_users: boolean
-  jwt_expiry_seconds: number
-  refresh_token_expiry_days: number
-  site_url?: string | null
-  oauth_providers: Record<string, { enabled?: boolean; client_id?: string; client_secret?: string }>
-  new_device_alerts_enabled: boolean
-  webhook_url?: string | null
-  // SMTP
-  smtp_host?: string | null
-  smtp_port?: number | null
-  smtp_username?: string | null
-  smtp_password_set?: boolean
-  smtp_from_email?: string | null
-  smtp_from_name?: string | null
-  // OAuth credentials (masked)
-  oauth_credentials: Record<string, Record<string, string>>
-  // CAPTCHA
-  captcha_enabled: boolean
-  captcha_provider?: string | null
-  captcha_site_key?: string | null
-  captcha_secret_key_set?: boolean
-  // HaveIBeenPwned
-  password_check_hibp: boolean
-  // SMS
-  sms_provider?: string | null
-  sms_api_key_set?: boolean
-  sms_from_number?: string | null
-  // URLs
-  redirect_urls: string[]
-  // Session
-  session_inactivity_timeout_seconds: number
-  // Hooks
-  hook_send_sms_url?: string | null
-  hook_send_email_url?: string | null
-  hook_mfa_verification_url?: string | null
-  hook_password_verification_url?: string | null
-  auto_link_by_email: boolean
-  // Hardening
-  revoke_on_new_device: boolean
-  enforce_ip_binding: boolean
-  allowed_email_domains: string[]
-  blocked_email_domains: string[]
-  updated_at: string
-}
-
-// Aligné sur UpsertTemplateRequest (backend) : subject + html_body requis.
-export interface EmailTemplateUpdate {
-  subject: string
-  html_body: string
-}
-
-export interface AdminCreateUserRequest {
-  email: string
-  password?: string
-  role?: string
-  email_verified?: boolean
-  user_metadata?: Record<string, unknown>
-}
-
-export interface AdminUpdateUserRequest {
-  password?: string
-  role?: string
-  is_active?: boolean
-  is_banned?: boolean
-  email_verified?: boolean
-  user_metadata?: Record<string, unknown>
-  app_metadata?: Record<string, unknown>
-  mfa_enabled?: boolean
-  revoke_sessions?: boolean
-}
-
-// GenerateLink (admin)
-export type GenerateLinkType = 'magic' | 'recovery' | 'invite'
-
-export interface GenerateLinkResult {
-  link: string
-  token: string
-}
-
-// JwtClaims (getClaims)
-//
-// `exp`/`iat` sont OPTIONNELS (honnêteté de type) : sur le chemin de fallback
-// (`getUser()`, cas HS256/JWKS vide/fetch KO), les claims sont dérivées de
-// l'identité serveur et NE contiennent PAS les champs temporels du JWT. Seul le
-// chemin de vérification LOCALE (RS256/ES256) renseigne `exp`/`iat` réels. Un
-// consommateur doit donc traiter `claims.exp` comme potentiellement `undefined`
-// (pas de `claims.exp * 1000` → `NaN` silencieux).
-export interface JwtClaims {
-  sub: string
-  exp?: number
-  iat?: number
-  nbf?: number
-  iss?: string
-  aud?: string | string[]
-  role?: string
-  [key: string]: unknown
-}
-
-export interface GetClaimsResult {
-  claims: JwtClaims
-  header: { alg: string; kid?: string; typ?: string }
-}