@aurabase/realtime 0.4.0

package/dist/index.d.cts

@@ -0,0 +1,419 @@
+import { ChannelConfig, PostgresChangesFilter, RealtimeEvent, BroadcastFilter, PresenceFilter, SubscribeCallback, BroadcastPayload, PresenceState, ServerMessage, RealtimeListenType, AuraClientLike, AuraResponse } from '@aurabase/core';
+
+type ListenerCallback = (payload: RealtimeEvent | Record<string, unknown>) => void;
+type ListenerEntry = {
+    type: RealtimeListenType;
+    filter: PostgresChangesFilter | BroadcastFilter | PresenceFilter;
+    callback: ListenerCallback;
+};
+type SendFn = (data: string) => void;
+/**
+ * Délai par défaut d'attente de la confirmation `subscribed` avant d'émettre
+ * `TIMED_OUT`. Aligné sur `DEFAULT_TIMEOUT` de `@supabase/realtime-js`
+ * (`dist/main/lib/constants.js`, 10 000 ms).
+ */
+declare const DEFAULT_SUBSCRIBE_TIMEOUT_MS = 10000;
+/**
+ * A realtime channel with Supabase-compatible chainable API.
+ *
+ * @example
+ * ```ts
+ * const channel = aura.channel('room-1')
+ *   .on('postgres_changes', { event: 'INSERT', schema: 'public', table: 'messages' }, (payload) => {
+ *     console.log('New message:', payload)
+ *   })
+ *   .on('broadcast', { event: 'cursor-pos' }, (payload) => {
+ *     console.log('Cursor:', payload)
+ *   })
+ *   .on('presence', { event: 'sync' }, () => {
+ *     console.log('Presence synced:', channel.presenceState())
+ *   })
+ *   .subscribe((status) => {
+ *     if (status === 'SUBSCRIBED') console.log('Connected!')
+ *   })
+ * ```
+ */
+declare class AuraChannel {
+    readonly name: string;
+    private readonly _projectId;
+    private readonly _listeners;
+    private _subscribed;
+    private _sendFn;
+    private _subscribeCallback;
+    private _presenceState;
+    private _isPrivate;
+    private _broadcastAck;
+    private _broadcastSelf;
+    private _presenceKey;
+    /** ID de subscription retourné par le serveur (utilisé pour le filtre RLS allowed_sub_ids) */
+    private _subscriptionId;
+    /** Compteur pour générer des ref_id uniques par connexion */
+    private _refCounter;
+    /** Dernier event ID recu — utilise pour since_id au reconnect */
+    private _lastEventId;
+    /** Pending ACK callbacks : ref_id → resolve */
+    private _pendingAcks;
+    /**
+     * Timer d'attente de la confirmation `subscribed`. Armé à l'ENVOI effectif du
+     * message subscribe (parité phoenix : `Push#startTimeout` ne démarre qu'au
+     * `send()`), désarmé dès qu'une réponse — `subscribed` ou `error` — arrive.
+     */
+    private _subscribeTimer;
+    /** Délai avant `TIMED_OUT`, surchargeable par `subscribe(cb, timeout)`. */
+    private _subscribeTimeoutMs;
+    /** `CLOSED` n'est émis qu'une fois par cycle de vie du canal (unsubscribe idempotent). */
+    private _closedEmitted;
+    constructor(name: string, projectId: string, options?: ChannelConfig);
+    /** Génère un ref_id unique pour la corrélation request/response. */
+    private _nextRef;
+    /** Full channel name with project prefix (for server protocol) */
+    get fullName(): string;
+    /**
+     * Register a listener for a specific event type.
+     * Returns `this` for chaining.
+     */
+    on(type: 'postgres_changes', filter: PostgresChangesFilter, callback: (payload: RealtimeEvent) => void): this;
+    on(type: 'broadcast', filter: BroadcastFilter, callback: (payload: RealtimeEvent) => void): this;
+    on(type: 'presence', filter: PresenceFilter, callback: (payload: any) => void): this;
+    /**
+     * Subscribe to the channel. Sends the Subscribe message to the server
+     * with the full config (postgres_changes, broadcast, presence).
+     *
+     * Le callback reçoit les mêmes statuts que `@supabase/realtime-js` :
+     * - `SUBSCRIBED`    — le serveur a confirmé l'abonnement ;
+     * - `CHANNEL_ERROR` — refus serveur (RLS, rate limit…), échec de handshake ou
+     *                     coupure inattendue de la connexion ;
+     * - `TIMED_OUT`     — aucune réponse du serveur dans `timeoutMs` après l'envoi ;
+     * - `CLOSED`        — le canal a été fermé volontairement (`unsubscribe()`,
+     *                     `removeChannel()`, `removeAllChannels()`, `disconnect()`).
+     *
+     * @param callback  Callback de statut (optionnel).
+     * @param timeoutMs Délai avant `TIMED_OUT` (défaut 10 s, comme Supabase).
+     */
+    subscribe(callback?: SubscribeCallback, timeoutMs?: number): this;
+    /** Called by RealtimeService once the WS connection is ready. */
+    _bindSend(sendFn: SendFn): void;
+    /** Send the subscribe message to the server. */
+    _doSubscribe(): void;
+    /** (Re)arme le compte à rebours d'attente de la confirmation `subscribed`. */
+    private _armSubscribeTimeout;
+    private _clearSubscribeTimeout;
+    /**
+     * Signale une erreur de transport (échec de handshake, coupure inattendue,
+     * connexion morte) — appelé par `RealtimeService`.
+     *
+     * Émet `CHANNEL_ERROR`, comme `@supabase/realtime-js` : chez Supabase, la
+     * fermeture du socket déclenche `Socket#triggerChanError` (phoenix
+     * `socket.js:550`), qui produit `CHANNEL_ERROR` et **jamais** `CLOSED` —
+     * `CLOSED` reste réservé à la fermeture volontaire du canal.
+     */
+    _signalError(err: Error): void;
+    /** Unsubscribe from the channel. */
+    unsubscribe(): void;
+    /**
+     * Send a broadcast message to the channel.
+     * If broadcast.ack=true, returns a Promise that resolves when the server ACKs.
+     *
+     * @example
+     * ```ts
+     * // Without ACK (fire & forget)
+     * channel.send({ type: 'broadcast', event: 'cursor-pos', payload: { x: 100, y: 200 } })
+     *
+     * // With ACK (wait for server confirmation)
+     * await channel.send({ type: 'broadcast', event: 'cursor-pos', payload: { x: 100 } })
+     * ```
+     */
+    send(message: BroadcastPayload): Promise<'ok' | 'timeout' | 'error'>;
+    /**
+     * Track presence state for this client.
+     * Returns a Promise that resolves with 'ok' once tracked (compatible Supabase).
+     *
+     * @example
+     * ```ts
+     * await channel.track({ user: 'user-1', online_at: new Date().toISOString() })
+     * ```
+     */
+    track(state: Record<string, unknown>): Promise<'ok' | 'error'>;
+    /** Stop tracking presence. */
+    untrack(): Promise<'ok' | 'error'>;
+    /** Get the current presence state for this channel. */
+    presenceState(): PresenceState;
+    /** Called by RealtimeService when a server message arrives for this channel. */
+    _onMessage(msg: ServerMessage): void;
+    /** Dispatch a RealtimeEvent to matching listeners. */
+    private _dispatchEvent;
+    /** Whether this channel has been subscribed. */
+    get isSubscribed(): boolean;
+    /** Get listeners (for re-subscribe after reconnect). */
+    _getListeners(): ListenerEntry[];
+}
+
+/**
+ * Phase du cycle de vie de la connexion WebSocket où l'erreur s'est produite.
+ *
+ * - `handshake`  : la connexion s'est fermée AVANT d'avoir jamais été ouverte.
+ *                  Cause la plus fréquente : refus d'authentification du serveur
+ *                  (HTTP 401/403 sur `GET /v1/realtime/ws`). Peut aussi être un
+ *                  serveur injoignable, un DNS/TLS en échec ou un proxy qui coupe.
+ * - `connection` : la connexion était ouverte et s'est fermée de façon inattendue.
+ * - `liveness`   : la connexion paraît ouverte mais le serveur ne répond plus
+ *                  (aucun message reçu entre deux heartbeats) — TCP à demi-fermé.
+ */
+type RealtimeErrorPhase = 'handshake' | 'connection' | 'liveness';
+/**
+ * Erreur de transport realtime, exploitable par l'appelant.
+ *
+ * ── Ce que cette erreur peut et ne peut PAS dire ─────────────────────────────
+ * La spécification WebSocket **interdit** au client JavaScript de lire le statut
+ * HTTP d'un handshake échoué : l'événement `error` est vide et le `close` porte
+ * systématiquement le code `1006` (« abnormal closure », aucune frame Close reçue).
+ * Vérifié sur la stack Aurabase locale avec Node 26/undici : un refus renvoyé par
+ * `aura-realtime` en `401 Unauthorized` (« Token JWT requis en query param
+ * ?token= ») arrive côté client sous la forme `error {}` puis `close 1006`.
+ *
+ * Cette classe ne fabrique donc jamais de code HTTP. Elle affirme uniquement ce
+ * qui est observable — la phase, le code de fermeture WebSocket, la raison — et
+ * nomme la cause la plus probable pour que l'appelant sache où chercher.
+ */
+declare class RealtimeConnectionError extends Error {
+    /** Phase du cycle de vie où l'échec s'est produit. */
+    readonly phase: RealtimeErrorPhase;
+    /** Code de fermeture WebSocket (RFC 6455 §7.4), si le runtime l'a fourni. */
+    readonly code?: number;
+    /** Raison de fermeture fournie par le serveur, si présente (souvent vide). */
+    readonly reason?: string;
+    constructor(phase: RealtimeErrorPhase, message: string, options?: {
+        code?: number;
+        reason?: string;
+        cause?: unknown;
+    });
+}
+
+/** Connection state machine */
+type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting';
+/**
+ * Période du heartbeat client, en millisecondes.
+ *
+ * Choisie d'après le contrat RÉEL du serveur (`services/aura-realtime/src/handlers/
+ * websocket.rs`) et non d'après une convention supposée :
+ * - le serveur coupe toute connexion dont il n'a RIEN reçu depuis 60 s
+ *   (`heartbeat_timeout`, l.373, évalué à chaque tick de `ping_interval` = 30 s) ;
+ * - il pousse de son côté un `{"type":"pong"}` non sollicité à chaque tick de 30 s
+ *   (l.605), et répond immédiatement à un `{"type":"ping"}` client (l.1027-1030).
+ *
+ * 25 s tient donc largement sous les 60 s serveur, et coïncide avec
+ * `HEARTBEAT_INTERVAL` de `@supabase/realtime-js` (25 000 ms).
+ */
+declare const HEARTBEAT_INTERVAL_MS = 25000;
+/**
+ * Realtime service — manages a single WebSocket connection and multiplexes
+ * channels on top of it. Supabase-compatible API.
+ *
+ * @example
+ * ```ts
+ * const aura = createClient('http://localhost:8080', 'my-project')
+ *
+ * const channel = aura.realtime.channel('room-1')
+ *   .on('postgres_changes', { event: 'INSERT', schema: 'public', table: 'messages' }, (payload) => {
+ *     console.log('New message:', payload)
+ *   })
+ *   .on('broadcast', { event: 'cursor-pos' }, (payload) => {
+ *     console.log('Cursor:', payload)
+ *   })
+ *   .subscribe((status) => {
+ *     if (status === 'SUBSCRIBED') {
+ *       channel.send({ type: 'broadcast', event: 'cursor-pos', payload: { x: 100, y: 200 } })
+ *     }
+ *   })
+ * ```
+ */
+declare class RealtimeService {
+    private readonly client;
+    private _ws;
+    private _channels;
+    private _state;
+    private _stateListeners;
+    private _autoReconnect;
+    private _reconnectAttempts;
+    private _maxReconnectAttempts;
+    private _reconnectTimer;
+    private _intentionalClose;
+    private _heartbeat;
+    private _tokenRefreshTimer;
+    /** Dernier access_token propagé au serveur — évite les pushs redondants (propagation différentielle). */
+    private _lastSentToken;
+    /** Listeners d'erreurs de transport (handshake refusé, coupure, connexion morte). */
+    private _errorListeners;
+    /**
+     * `true` entre l'envoi d'un ping et la réception du message serveur suivant.
+     * S'il est encore `true` au tick de heartbeat suivant, aucun octet applicatif
+     * n'est revenu en 25 s alors que le serveur en pousse au moins un toutes les
+     * 30 s et répond au ping : la connexion est morte (TCP à demi-fermé).
+     */
+    private _awaitingPong;
+    /** Backoff delays in ms: 1s, 2s, 4s, 8s, 16s, 30s (cap) */
+    private static readonly BACKOFF_MS;
+    constructor(client: AuraClientLike);
+    /** Current connection state. */
+    get connectionState(): ConnectionState;
+    /** Listen for connection state changes. */
+    onStateChange(callback: (state: ConnectionState) => void): () => void;
+    private _setState;
+    /**
+     * Écoute les erreurs de transport de la connexion realtime.
+     *
+     * Complète `onStateChange` (qui ne dit que « ça a bougé ») en fournissant la
+     * CAUSE : handshake refusé (typiquement un 401 sur le token/apikey), coupure
+     * inattendue, ou connexion morte détectée par le heartbeat. Sans ce canal,
+     * un refus d'authentification était totalement silencieux — la boucle de
+     * reconnexion tournait indéfiniment sans que l'appelant puisse le savoir.
+     *
+     * @returns Une fonction de désabonnement.
+     *
+     * @example
+     * ```ts
+     * aura.realtime.onError((err) => {
+     *   if (err.phase === 'handshake') {
+     *     // token expiré / apikey invalide → renouveler la session
+     *   }
+     * })
+     * ```
+     */
+    onError(callback: (err: RealtimeConnectionError) => void): () => void;
+    /**
+     * Diffuse une erreur de transport : aux listeners `onError`, puis à tous les
+     * canaux sous forme de `CHANNEL_ERROR` (mécanisme officiel Supabase — chez
+     * phoenix, `Socket#triggerChanError` fait exactement cela).
+     *
+     * Chaque callback est isolé : un listener qui jette ne doit jamais interrompre
+     * la diffusion ni la boucle de reconnexion.
+     */
+    private _emitError;
+    private get _wsUrl();
+    /** Ensure the WebSocket connection is open. */
+    connect(): void;
+    /**
+     * Détache le socket courant et remet à zéro tout ce qui lui était attaché.
+     * Partagé par `onclose` et par la détection de connexion morte (qui ne peut PAS
+     * compter sur un `onclose` : une socket à demi-fermée n'en émet parfois jamais).
+     */
+    private _detachSocket;
+    /**
+     * Un tick de heartbeat : vérifie la liveness du lien puis émet un ping.
+     *
+     * Règle (calquée sur `Socket#sendHeartbeat`/`heartbeatTimeout` de phoenix, que
+     * `@supabase/realtime-js` réutilise) : si le ping du tick précédent n'a été suivi
+     * d'AUCUN message serveur, la connexion est morte. Le contrat serveur rend cette
+     * règle sûre — `aura-realtime` répond au ping immédiatement ET pousse un pong
+     * spontané toutes les 30 s : 25 s de silence total ne peuvent pas être normaux.
+     */
+    private _heartbeatTick;
+    /**
+     * Connexion « zombie » : ouverte du point de vue du système, muette en pratique.
+     *
+     * On ne peut pas se contenter d'appeler `close()` et d'attendre le `onclose` :
+     * sur un TCP à demi-fermé, la frame Close part dans le vide et l'événement peut
+     * n'arriver que bien plus tard (voire jamais). On détache donc le socket
+     * IMMÉDIATEMENT — la garde `ws !== this._ws` neutralisera son `onclose` tardif —
+     * puis on relance le cycle de reconnexion nous-mêmes.
+     */
+    private _handleDeadConnection;
+    /** Send raw data through the WebSocket. */
+    private _send;
+    /** Refresh the JWT token on an existing connection (no disconnect). */
+    refreshToken(token: string): void;
+    /**
+     * Définit/rafraîchit explicitement le token utilisé pour l'autorisation des
+     * canaux privés et broadcast (parité `@supabase/realtime-js` `setAuth`).
+     *
+     * - Avec `token` : utilise ce token. Sinon, reprend `client.authStore.token`.
+     * - Propage via le pipeline existant `refreshToken` (push
+     *   `{ type:'access_token', token }` sur une connexion ouverte, dédupliqué via
+     *   `_lastSentToken`). N'ouvre ni ne ferme aucune connexion WS.
+     * - Hors-ligne : `connect()` lit `client.authStore.token` au moment de l'open,
+     *   donc `setAuth()` doit être appelé avec un token présent dans le store (ou
+     *   après authentification) pour prendre effet sur une future connexion.
+     *
+     * À appeler AVANT de s'abonner à un canal privé (`channel(name,{private:true})`).
+     *
+     * @example
+     * ```ts
+     * aura.realtime.setAuth(session.access_token)
+     * const ch = aura.realtime.channel('secret', { private: true }).subscribe()
+     * ```
+     */
+    setAuth(token?: string): void;
+    /**
+     * Envoie un broadcast par HTTP (REST), sans connexion WebSocket ouverte
+     * (parité `@supabase/realtime-js`). Utile côté serveur/edge.
+     *
+     * POST `/v1/realtime/{projectId}/broadcast` avec le contrat du handler backend
+     * (`broadcast.rs`) : `{ channel, payload }`, `channel` préfixé par le projet,
+     * `event` replié dans `payload` (aligné sur le broadcast WS).
+     *
+     * @param channel Nom du canal (préfixé projet automatiquement si absent).
+     * @param event   Nom de l'événement broadcast.
+     * @param payload Données de l'événement.
+     * @returns `AuraResponse<null>` — `error` non nul en cas de 4xx/rate-limit.
+     *
+     * @example
+     * ```ts
+     * await aura.realtime.httpBroadcast('room-1', 'cursor', { x: 10, y: 20 })
+     * ```
+     */
+    httpBroadcast(channel: string, event: string, payload?: Record<string, unknown>): Promise<AuraResponse<null>>;
+    /**
+     * Schedule proactive token refresh at 80% of the JWT TTL.
+     * Prevents token expiration during an active WebSocket session.
+     */
+    private _scheduleTokenRefresh;
+    /** Schedule a reconnection attempt with exponential backoff + jitter. */
+    private _scheduleReconnect;
+    /** Enable/disable auto-reconnect (enabled by default). */
+    setAutoReconnect(enabled: boolean, maxAttempts?: number): void;
+    /** Disconnect the WebSocket and clean up all channels. */
+    disconnect(): void;
+    /**
+     * Create or retrieve a channel by name.
+     * Returns an `AuraChannel` with chainable `.on()` / `.subscribe()` API.
+     *
+     * @example
+     * ```ts
+     * const channel = aura.realtime.channel('room-1')
+     * ```
+     */
+    channel(name: string, options?: ChannelConfig): AuraChannel;
+    /** Remove a channel. */
+    removeChannel(name: string): void;
+    /** List active channels. */
+    getChannels(): AuraChannel[];
+    /** Remove all channels and subscriptions. */
+    removeAllChannels(): void;
+    /** Route incoming server messages to the correct channel. */
+    private _dispatch;
+    /**
+     * Simple callback-based subscription (legacy API).
+     * Prefer using `.channel().on().subscribe()` instead.
+     *
+     * @deprecated Use `channel().on().subscribe()` instead.
+     */
+    on<T = Record<string, unknown>>(channelName: string, callback: (event: any) => void): {
+        unsubscribe: () => void;
+    };
+}
+
+/**
+ * HeartbeatManager — pings périodiques pour maintenir la connexion WS.
+ * Utilise un Worker dédié (anti-throttle des onglets en arrière-plan) ; fallback setInterval.
+ */
+declare class HeartbeatManager {
+    private _worker;
+    private _workerUrl;
+    private _interval;
+    private _sendFn;
+    start(sendPing: () => void, intervalMs?: number): void;
+    stop(): void;
+    get isActive(): boolean;
+}
+
+export { AuraChannel, type ConnectionState, DEFAULT_SUBSCRIBE_TIMEOUT_MS, HEARTBEAT_INTERVAL_MS, HeartbeatManager, RealtimeConnectionError, type RealtimeErrorPhase, RealtimeService };