@aurabase/aurabase-js 0.3.0 → 0.4.0

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

@@ -1,259 +0,0 @@
-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

@@ -1,259 +0,0 @@
-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 };