@aurabase/aurabase-js 0.3.0

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

@@ -0,0 +1,259 @@
+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;
+/**
+ * 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;
+    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).
+     */
+    subscribe(callback?: SubscribeCallback): this;
+    /** Called by RealtimeService once the WS connection is ready. */
+    _bindSend(sendFn: SendFn): void;
+    /** Send the subscribe message to the server. */
+    _doSubscribe(): 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[];
+}
+
+/** Connection state machine */
+type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting';
+/**
+ * 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;
+    /** 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;
+    private get _wsUrl();
+    /** Ensure the WebSocket connection is open. */
+    connect(): void;
+    /** 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, HeartbeatManager, RealtimeService };

package/packages/realtime/dist/index.d.ts

@@ -0,0 +1,259 @@
+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;
+/**
+ * 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;
+    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).
+     */
+    subscribe(callback?: SubscribeCallback): this;
+    /** Called by RealtimeService once the WS connection is ready. */
+    _bindSend(sendFn: SendFn): void;
+    /** Send the subscribe message to the server. */
+    _doSubscribe(): 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[];
+}
+
+/** Connection state machine */
+type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting';
+/**
+ * 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;
+    /** 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;
+    private get _wsUrl();
+    /** Ensure the WebSocket connection is open. */
+    connect(): void;
+    /** 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, HeartbeatManager, RealtimeService };