@aurabase/aurabase-js 0.3.0

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

@@ -0,0 +1,1137 @@
+/**
+ * Codes d'erreur produits par le SDK (LOT 3, finding I4 : taxonomie ad hoc non
+ * typée). Union fermée de tous les codes émis SDK-side (`grep new AuraError` sur
+ * `packages/*\/src`) + les codes backend usuels rencontrés (`PGRST116`), plus
+ * `(string & {})` pour rester ouvert à tout code backend arbitraire (`error.error.code`)
+ * sans perdre l'autocomplétion sur les codes connus (pattern "LiteralUnion").
+ *
+ * Provenance des codes SDK-side :
+ *  - fetch.ts (core)   : no_session, network_error, invalid_response, refresh_discarded, timeout
+ *  - AuthService.ts    : no_session, pkce_generation_failed, no_code_verifier, missing_email,
+ *                        unverifiable_token, invalid_issuer, invalid_audience
+ *  - jwks.ts            : jwks_fetch_failed, no_matching_key, signature_invalid, token_expired,
+ *                        token_not_yet_valid, invalid_jwt, unsupported_alg
+ *  - storage/path.ts   : invalid_path
+ *  - db/QueryBuilder.ts: PGRST116 (parité PostgREST : `.single()` sur 0/plusieurs lignes)
+ */
+type AuraErrorCode = 'no_session' | 'timeout' | 'network_error' | 'invalid_response' | 'refresh_discarded' | 'unverifiable_token' | 'no_code_verifier' | 'pkce_generation_failed' | 'missing_email' | 'jwks_fetch_failed' | 'signature_invalid' | 'token_expired' | 'token_not_yet_valid' | 'invalid_jwt' | 'unsupported_alg' | 'no_matching_key' | 'invalid_issuer' | 'invalid_audience' | 'invalid_path' | 'PGRST116' | (string & {});
+/**
+ * Structured error thrown/returned by the Aurabase SDK.
+ * Mirrors the backend's `AuraError` JSON shape.
+ */
+declare class AuraError extends Error {
+    readonly status: number;
+    readonly code: AuraErrorCode;
+    readonly details: unknown;
+    /** Marqueur runtime pour `isAuraError` (détection cross-realm/cross-bundle). */
+    protected readonly __isAuraError = true;
+    constructor(status: number, body?: {
+        error?: {
+            code?: string;
+            message?: string;
+        };
+        message?: string;
+    } | null);
+    get isNotFound(): boolean;
+    get isUnauthorized(): boolean;
+    get isForbidden(): boolean;
+    get isRateLimited(): boolean;
+}
+declare function isAuraError(error: unknown): error is AuraError;
+
+interface Meta {
+    total?: number;
+    next_cursor?: string;
+}
+interface AuraResponse<T> {
+    data: T | null;
+    error: AuraError | null;
+    meta?: Meta;
+}
+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;
+}
+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;
+}
+interface MfaChallenge {
+    mfa_required: true;
+    mfa_token: string;
+    mfa_setup_required?: boolean;
+}
+type LoginResponse = TokenPair | MfaChallenge;
+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'`.
+ */
+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;
+}
+interface SignUpRequest {
+    email: string;
+    password: string;
+    captcha_token?: string;
+}
+interface SignInRequest {
+    email: string;
+    password: string;
+    captcha_token?: string;
+}
+interface MagicLinkRequest {
+    email: string;
+    create_user?: boolean;
+    captcha_token?: string;
+    redirect_url?: string;
+}
+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';
+}
+interface PasswordResetRequest {
+    email: string;
+}
+interface UpdateUserRequest {
+    email?: string;
+    phone?: string;
+    password?: string;
+    current_password?: string;
+    data?: Record<string, unknown>;
+}
+interface MfaEnrollResponse {
+    otpauth_url: string;
+    secret: string;
+}
+interface MfaVerifyRequest {
+    mfa_token: string;
+    code: string;
+}
+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;
+}
+type FilterOp = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'like' | 'ilike' | 'is_null' | 'is_not_null' | 'between';
+interface QueryFilter {
+    column: string;
+    op: string;
+    value: unknown;
+}
+type CountMode = 'exact' | 'estimated';
+interface QueryOptions {
+    select?: string[];
+    filters?: QueryFilter[];
+    sort_by?: string;
+    sort_order?: 'asc' | 'desc';
+    limit?: number;
+    offset?: number;
+    count?: CountMode;
+}
+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;
+}
+interface SchemaIndex {
+    name: string;
+    columns: string[];
+    unique: boolean;
+}
+interface SchemaTable {
+    name: string;
+    columns: SchemaColumn[];
+    primary_key?: string;
+    indexes: SchemaIndex[];
+    rls_enabled: boolean;
+    realtime_enabled: boolean;
+}
+interface SchemaFunctionArg {
+    name: string;
+    data_type: string;
+    mode: string;
+}
+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]`.
+ */
+interface SchemaEnum {
+    name: string;
+    values: string[];
+}
+/**
+ * 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.
+ */
+interface ImageTransform {
+    width?: number;
+    height?: number;
+    resize?: 'cover' | 'contain' | 'fill';
+    quality?: number;
+    format?: 'origin' | 'jpeg' | 'png' | 'webp' | 'gif';
+}
+interface StorageBucket {
+    id: string;
+    name: string;
+    public: boolean;
+    file_size_limit?: number | null;
+    allowed_mime_types?: string[] | null;
+    created_at: string;
+    updated_at: string;
+}
+interface UploadResult {
+    /** Clé unique de l'objet (`<uuid>.<ext>`) relative au bucket. */
+    key: string;
+    url: string;
+    size: number;
+    mime_type: string;
+}
+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() */
+interface ObjectMeta {
+    key: string;
+    bucket: string;
+    size: number;
+    content_type: string;
+    etag?: string | null;
+    last_modified?: string | null;
+    metadata: Record<string, string>;
+}
+/** Événement serveur brut reçu via WebSocket (union discriminée par type) */
+type ServerMessage = ServerSubscribedMsg | ServerEventMsg | ServerPongMsg | ServerErrorMsg | ServerTokenRefreshedMsg | ServerPresenceStateMsg | BroadcastAckMessage;
+interface ServerSubscribedMsg {
+    type: 'subscribed';
+    channel: string;
+    subscription_id?: string;
+    history: RealtimeEvent[];
+    ref_id?: string;
+}
+interface ServerEventMsg {
+    type: 'event';
+    id: string;
+    event: 'insert' | 'update' | 'delete' | 'broadcast' | 'presence' | 'system';
+    topic: string;
+    payload: Record<string, unknown>;
+    timestamp: string;
+    allowed_sub_ids?: string[];
+}
+interface ServerPongMsg {
+    type: 'pong';
+}
+interface ServerErrorMsg {
+    type: 'error';
+    message: string;
+}
+interface ServerTokenRefreshedMsg {
+    type: 'token_refreshed';
+}
+interface ServerPresenceStateMsg {
+    type: 'presence_state';
+    channel: string;
+    presences: PresenceInfo[];
+}
+/** Événement realtime (CDC, broadcast, presence) */
+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) */
+interface BroadcastAckMessage {
+    type: 'broadcast_ack';
+    message_id: string;
+    ref_id?: string;
+}
+/** Payload CDC (postgres_changes) avec old_record et type d'operation */
+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 */
+type RealtimeSubscribeStatus = 'SUBSCRIBED' | 'CLOSED' | 'CHANNEL_ERROR' | 'TIMED_OUT';
+/** Callback de subscription */
+type SubscribeCallback = (status: RealtimeSubscribeStatus, err?: Error) => void;
+/** Types d'écoute supportés (pattern Supabase) */
+type RealtimeListenType = 'postgres_changes' | 'broadcast' | 'presence';
+/** Config pour postgres_changes */
+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 */
+interface BroadcastFilter {
+    event: string;
+}
+/** Config pour presence */
+interface PresenceFilter {
+    event: 'sync' | 'join' | 'leave';
+}
+/** Options de channel — compatible Supabase */
+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 */
+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) */
+type PresenceState = Record<string, PresenceInfo[]>;
+interface PresenceInfo {
+    client_id: string;
+    user_id?: string | null;
+    metadata: Record<string, unknown>;
+    joined_at: string;
+    last_seen: string;
+}
+interface ChatMessage {
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+}
+interface ChatResponse {
+    model: string;
+    content: string;
+    input_tokens?: number;
+    output_tokens?: number;
+}
+interface EmbedRequest {
+    text: string;
+    namespace: string;
+    metadata?: Record<string, unknown>;
+}
+interface EmbedResponse {
+    id: string;
+    dimensions: number;
+}
+interface RagRequest {
+    question: string;
+    namespace: string;
+    history?: ChatMessage[];
+    system?: string;
+}
+interface RagResponse {
+    answer: string;
+    sources: Array<{
+        id: string;
+        content: string;
+        metadata: Record<string, unknown>;
+        similarity: number;
+    }>;
+    model: string;
+    tokens?: number;
+}
+interface RagIngestRequest {
+    namespace: string;
+    content: string;
+    metadata?: Record<string, unknown>;
+}
+interface RagIngestResponse {
+    id: string;
+    chunks: number;
+}
+interface SemanticSearchResult {
+    id: string;
+    content: string;
+    metadata: Record<string, unknown>;
+    similarity: number;
+}
+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;
+}
+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;
+}
+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;
+}
+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;
+}
+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;
+}
+interface BatchSendItemResult {
+    index: number;
+    status: 'queued' | 'error';
+    notification?: Notification | null;
+    error?: string | null;
+}
+interface BatchSendResponse {
+    items: BatchSendItemResult[];
+}
+interface NotificationTemplate {
+    id: string;
+    name: string;
+    channel: 'email' | 'sms' | 'push' | 'webhook';
+    subject?: string | null;
+    body: string;
+    variables?: string[];
+    created_at: string;
+    updated_at: string;
+}
+interface NotificationTemplatePreview {
+    subject?: string | null;
+    body: string;
+}
+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;
+}
+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;
+}
+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;
+}
+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;
+}
+interface NotificationQueueStats {
+    queued_count: number;
+    processing_count: number;
+    retry_scheduled_count: number;
+    expired_processing_count: number;
+    next_retry_at_min?: string | null;
+}
+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;
+}
+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;
+    }>;
+}
+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;
+}
+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;
+}
+/**
+ * É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`.
+ */
+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;
+};
+declare function emitAuraEvent(onEvent: ((event: AuraObservabilityEvent) => void) | undefined, debug: boolean | undefined, event: AuraObservabilityEvent): void;
+interface AuraClientOptions {
+    auth?: {
+        persistSession?: boolean;
+        storage?: 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;
+}
+interface IdentityInfo {
+    id: string;
+    provider: string;
+    provider_id: string;
+    identity_data: Record<string, unknown>;
+    auto_linked: boolean;
+    created_at: string;
+}
+interface AdminUser extends User {
+}
+interface AuditLogEntry {
+    id: string;
+    user_id?: string | null;
+    action: string;
+    ip_address?: string | null;
+    user_agent?: string | null;
+    created_at: string;
+}
+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).
+ */
+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;
+}
+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_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: Record<string, Record<string, string>>;
+    captcha_enabled: boolean;
+    captcha_provider?: string | null;
+    captcha_site_key?: string | null;
+    captcha_secret_key_set?: boolean;
+    password_check_hibp: boolean;
+    sms_provider?: string | null;
+    sms_api_key_set?: boolean;
+    sms_from_number?: string | null;
+    redirect_urls: string[];
+    session_inactivity_timeout_seconds: number;
+    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;
+    revoke_on_new_device: boolean;
+    enforce_ip_binding: boolean;
+    allowed_email_domains: string[];
+    blocked_email_domains: string[];
+    updated_at: string;
+}
+interface EmailTemplateUpdate {
+    subject: string;
+    html_body: string;
+}
+interface AdminCreateUserRequest {
+    email: string;
+    password?: string;
+    role?: string;
+    email_verified?: boolean;
+    user_metadata?: Record<string, unknown>;
+}
+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;
+}
+type GenerateLinkType = 'magic' | 'recovery' | 'invite';
+interface GenerateLinkResult {
+    link: string;
+    token: string;
+}
+interface JwtClaims {
+    sub: string;
+    exp?: number;
+    iat?: number;
+    nbf?: number;
+    iss?: string;
+    aud?: string | string[];
+    role?: string;
+    [key: string]: unknown;
+}
+interface GetClaimsResult {
+    claims: JwtClaims;
+    header: {
+        alg: string;
+        kid?: string;
+        typ?: string;
+    };
+}
+
+type AuthChangeCallback = (token: string | null, user: User | null) => void;
+/**
+ * Check whether a JWT has expired (or will expire within `marginSec` seconds).
+ */
+declare function isTokenExpired(token: string, marginSec?: number): boolean;
+/**
+ * In-memory auth store with an event-emitter pattern.
+ * Can be extended (see LocalAuthStore) for persistence.
+ */
+declare class BaseAuthStore {
+    /**
+     * True si le store survit à un redirect pleine page (persistance disque, ex.
+     * localStorage). Le store de base est en mémoire → non persistant. Exploité par
+     * le flux PKCE : le `code_verifier` doit survivre au redirect OAuth.
+     */
+    readonly persistent: boolean;
+    private _token;
+    private _refreshToken;
+    private _user;
+    private _listeners;
+    private _removalEpoch;
+    /** Stockage générique clé/valeur (ex: PKCE `code_verifier`). En mémoire par défaut. */
+    private _kv;
+    /** Hook d'observabilité (LOT 3) — câblé par `AuraClient` via `setObservabilityHook`. */
+    private _onEvent?;
+    private _debug;
+    /** Compteur incrémenté à chaque `clear()` — sert au commit-guard anti-race du refresh. */
+    get removalEpoch(): number;
+    get token(): string | null;
+    get refreshToken(): string | null;
+    get user(): User | null;
+    /** True if a non-expired access token is present. */
+    get isValid(): boolean;
+    save(token: string, refreshToken: string, user: User): void;
+    clear(): void;
+    setItem(key: string, value: string): void;
+    getItem(key: string): string | null;
+    removeItem(key: string): void;
+    /**
+     * Câble le hook d'observabilité (appelé par `AuraClient` à la construction).
+     * Permet à `LocalAuthStore` d'émettre `storage-blocked` quand `localStorage` est
+     * indisponible (navigation privée Safari, quota dépassé, storage désactivé…).
+     * Sans effet sur `BaseAuthStore` elle-même (en mémoire, jamais "bloquée").
+     */
+    setObservabilityHook(onEvent: ((event: AuraObservabilityEvent) => void) | undefined, debug: boolean | undefined): void;
+    /** Émet `{kind:'storage-blocked', op}` — ne throw jamais (voir `emitAuraEvent`). */
+    protected _emitStorageBlocked(op: string): void;
+    /**
+     * Register a callback that fires whenever the auth state changes.
+     * Returns an unsubscribe function.
+     */
+    onChange(callback: AuthChangeCallback): () => void;
+    protected _triggerChange(): void;
+}
+
+/**
+ * Forme minimale du client consommée par `fetchWithAuth`, `BaseService`,
+ * le `QueryBuilder` et les services. Le `AuraClient` concret (meta-package)
+ * satisfait cette interface structurellement — ce qui casse le cycle de
+ * dépendance core → meta (les services n'importent plus la classe concrète).
+ */
+interface AuraClientLike {
+    readonly baseUrl: string;
+    readonly projectId: string;
+    readonly apiKey: string | null;
+    readonly fetchFn: typeof globalThis.fetch;
+    readonly authStore: BaseAuthStore;
+    /** Consommé uniquement par le service realtime (refresh proactif du token). */
+    readonly auth: {
+        refreshSession(): Promise<AuraResponse<TokenPair>>;
+    };
+    /** Config du retry transitoire. Défauts appliqués si absent : enabled=true, maxRetries=3. */
+    readonly retryConfig?: {
+        enabled: boolean;
+        maxRetries: number;
+    };
+    /**
+     * Timeout par défaut (ms) des requêtes HTTP. Appliqué UNIQUEMENT aux requêtes
+     * JSON sans `signal` fourni (donc pas aux uploads FormData ni aux appels qui
+     * gèrent déjà leur propre annulation). `0` désactive. Défaut : 30 000 ms.
+     */
+    readonly requestTimeoutMs?: number;
+    /**
+     * Hook d'observabilité (LOT 3, finding I8), optionnel — n'importe quelle implémentation
+     * structurelle de `AuraClientLike` reste compatible sans le fournir (pas de breaking
+     * change). Consommé par `fetchWithAuth`/`refreshOnce` pour émettre retry/timeout/refresh.
+     */
+    readonly onEvent?: (event: AuraObservabilityEvent) => void;
+    /** Si `true`, chaque `AuraObservabilityEvent` est aussi journalisé via `console.debug`. */
+    readonly debug?: boolean;
+}
+
+/** Point d'entrée unique du refresh, dédupliqué par client (single-flight). */
+declare function refreshOnce(client: AuraClientLike): Promise<AuraResponse<TokenPair>>;
+interface FetchInit {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+    signal?: AbortSignal;
+    skipAuthRefresh?: boolean;
+    /**
+     * Override explicite du `Authorization: Bearer` (LOT D). S'il est fourni, il
+     * GAGNE sur `store.token` — permet de valider un token ARBITRAIRE (foreign)
+     * plutôt que celui de la session courante (ex. `getUser(jwt)`). Sans lui, le
+     * comportement historique s'applique (`Authorization = Bearer store.token`).
+     */
+    authToken?: string;
+    /** Désactive le retry transitoire pour cette requête (override). */
+    skipRetry?: boolean;
+    /** Interne (E19) : marque une requête déjà rejouée après refresh pour borner la récursion. */
+    _retried?: boolean;
+}
+/**
+ * Core fetch wrapper that handles:
+ * - Lazy token refresh before expiry
+ * - Authorization / API key injection
+ * - Content-Type defaulting
+ * - Structured AuraResponse parsing
+ */
+declare function fetchWithAuth<T>(url: string, init: FetchInit, client: AuraClientLike): Promise<AuraResponse<T>>;
+
+/**
+ * Abstract base class for all service modules.
+ * Provides the shared HTTP helper and URL builder.
+ */
+declare abstract class BaseService {
+    protected readonly client: AuraClientLike;
+    constructor(client: AuraClientLike);
+    /** Build a full URL for the given path. */
+    protected url(path: string): string;
+    /** Convenience HTTP helper that delegates to fetchWithAuth. */
+    protected request<T>(method: string, path: string, body?: unknown, options?: {
+        headers?: Record<string, string>;
+        signal?: AbortSignal;
+        skipAuthRefresh?: boolean;
+        /** Override explicite du Bearer (LOT D) — valide un token arbitraire. */
+        authToken?: string;
+    }): Promise<AuraResponse<T>>;
+}
+
+interface CookieOptions {
+    path?: string;
+    domain?: string;
+    maxAge?: number;
+    secure?: boolean;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+    httpOnly?: boolean;
+}
+/**
+ * Auth store backed by `localStorage` (browser) with cookie helpers for SSR.
+ */
+declare class LocalAuthStore extends BaseAuthStore {
+    /** Persiste en localStorage → survit au redirect pleine page (cf. PKCE). */
+    readonly persistent = true;
+    private readonly key;
+    constructor(key?: string);
+    save(token: string, refreshToken: string, user: User): void;
+    clear(): void;
+    /**
+     * Supprime de localStorage tous les artefacts d'auth éphémères sur disque :
+     *  - `code_verifier` PKCE (`aura-<projectId>-pkce-code-verifier`),
+     *  - marqueur d'initiation OAuth implicit (`aura-<projectId>-oauth-implicit-initiated`,
+     *    SEC-F3). Un `signOut`/`clear()` ne doit laisser aucun résidu réutilisable (parité
+     * `@supabase/ssr` : ces artefacts sont éphémères). On itère les clés préfixées pour
+     * couvrir un store partagé entre plusieurs projets, sans dépendre du `projectId` courant.
+     */
+    private _removePkceVerifiers;
+    setItem(key: string, value: string): void;
+    getItem(key: string): string | null;
+    removeItem(key: string): void;
+    /**
+     * Populate the store from a raw `Cookie` header string (server-side).
+     * Looks for the key matching `this.key`.
+     */
+    loadFromCookie(cookieString: string): void;
+    /**
+     * Serialize current auth state into a `Set-Cookie` value.
+     */
+    exportToCookie(options?: CookieOptions): string;
+    private _loadFromStorage;
+    private _persist;
+    private _removeStorage;
+}
+
+/** JSON.stringify avec support des bigint (sérialisés en string). */
+declare function serializeBody(body: unknown): string;
+
+/**
+ * Parse a raw Cookie header string into key-value pairs.
+ */
+declare function parseCookieHeader(header: string): Record<string, string>;
+interface SerializeCookieOptions {
+    path?: string;
+    domain?: string;
+    maxAge?: number;
+    secure?: boolean;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+    httpOnly?: boolean;
+}
+/**
+ * Serialize a cookie name + value + options into a Set-Cookie header value.
+ */
+declare function serializeCookieHeader(name: string, value: string, options?: SerializeCookieOptions): string;
+
+/**
+ * Primitives de résilience réseau (module pur, sans I/O).
+ * `Math.random`/`Date.now` sont injectables pour des tests déterministes.
+ */
+declare const RETRYABLE_STATUS: Set<number>;
+declare const RETRYABLE_METHODS: Set<string>;
+declare const DEFAULT_MAX_RETRIES = 3;
+declare function isRetryableStatus(status: number): boolean;
+declare function isRetryableMethod(method: string): boolean;
+/** Full jitter : random(0, min(BASE·2^attempt, CAP)). `attempt` commence à 0. */
+declare function computeBackoff(attempt: number, rand?: () => number): number;
+/** Parse un header `Retry-After` (secondes OU HTTP-date) → délai en ms, ou null. */
+declare function parseRetryAfter(header: string | null, now?: number): number | null;
+/** `sleep(ms)` qui résout tôt (sans rejeter) si `signal` s'annule. */
+declare function abortableSleep(ms: number, signal?: AbortSignal): Promise<void>;
+/** True si l'erreur `fetch` est une annulation utilisateur (jamais rejouée). */
+declare function isAbortError(err: unknown): boolean;
+
+export { type AdminCreateUserRequest, type AdminSessionInfo, type AdminUpdateUserRequest, type AdminUser, type AuditLogEntry, type AuraClientLike, type AuraClientOptions, AuraError, type AuraErrorCode, type AuraObservabilityEvent, type AuraResponse, type AuthChangePayload, type AuthEvent, type AuthSettings, BaseAuthStore, BaseService, type BatchSendItemResult, type BatchSendResponse, type BroadcastAckMessage, type BroadcastFilter, type BroadcastPayload, type CdcPayload, type ChannelConfig, type ChatMessage, type ChatResponse, type CountMode, type CronJob, DEFAULT_MAX_RETRIES, type EmailTemplateUpdate, type EmbedRequest, type EmbedResponse, type FetchInit, type FileEntry, type FilterOp, type FunctionDef, type GenerateLinkResult, type GenerateLinkType, type GetClaimsResult, type IdentityInfo, type ImageTransform, type Job, type JwtClaims, LocalAuthStore, type LoginResponse, type MagicLinkRequest, type Meta, type MfaChallenge, type MfaEnrollResponse, type MfaVerifyRequest, type Notification, type NotificationAttempt, type NotificationChannelStats, type NotificationDeadLetter, type NotificationEvent, type NotificationProviderLog, type NotificationQueueStats, type NotificationRule, type NotificationSettings, type NotificationStats, type NotificationTemplate, type NotificationTemplatePreview, type OAuthSignInOptions, type ObjectMeta, type PasswordResetRequest, type PostgresChangesFilter, type PresenceFilter, type PresenceInfo, type PresenceState, type QueryFilter, type QueryOptions, RETRYABLE_METHODS, RETRYABLE_STATUS, type RagIngestRequest, type RagIngestResponse, type RagRequest, type RagResponse, type RealtimeEvent, type RealtimeListenType, type RealtimeSubscribeStatus, type SchemaColumn, type SchemaEnum, type SchemaFunction, type SchemaFunctionArg, type SchemaIndex, type SchemaTable, type SemanticSearchResult, type SendNotificationRequest, type SerializeCookieOptions, type ServerErrorMsg, type ServerEventMsg, type ServerMessage, type ServerPongMsg, type ServerPresenceStateMsg, type ServerSubscribedMsg, type ServerTokenRefreshedMsg, type SessionInfo, type SignInRequest, type SignUpRequest, type StorageBucket, type SubscribeCallback, type TokenPair, type UpdateUserRequest, type UploadResult, type User, type UserStats, abortableSleep, computeBackoff, emitAuraEvent, fetchWithAuth, isAbortError, isAuraError, isRetryableMethod, isRetryableStatus, isTokenExpired, parseCookieHeader, parseRetryAfter, refreshOnce, serializeBody, serializeCookieHeader };