@mitway/sdk 0.2.3 → 0.3.0

package/dist/index.d.cts

@@ -1,3 +1,4 @@
+import { Socket } from 'socket.io-client';
 import * as _supabase_postgrest_js from '@supabase/postgrest-js';
 
 /**
@@ -51,111 +52,339 @@ declare class TokenManager {
 }
 
 /**
- * Realtime module — Socket.IO client wrapper for MITWAY-BaaS.
+ * Realtime module — Socket.IO client exposing the channel API.
  *
- * Provides a thin, typed layer over `socket.io-client` so app code can
- * subscribe / publish / listen without dealing with the underlying
- * transport details. The MITWAY-BaaS backend handles auth (JWT / API
- * key), RLS, rate limiting, and fan-out across replicas — the SDK just
- * opens one socket per `MitwayBaasClient` instance and routes events.
+ * Design goals:
+ *   1. `client.realtime.channel(topic).on(type, filter, cb).subscribe()` is
+ *      the single entry point for every primitive.
+ *   2. Three binding types coexist on a channel:
+ *        * `postgres_changes` — WAL-based auto-broadcast of DB events,
+ *          gated by per-subscriber RLS replay in the backend.
+ *        * `broadcast`        — fire-and-forget custom events published
+ *          via `channel.send({...})` (in-memory fan-out) or via the
+ *          server-side `realtime.send()` SQL helper.
+ *        * `presence`         — per-channel live "who's here" state.
+ *   3. One socket per `Realtime` instance. Multiple channels share it.
+ *
+ * The wire protocol is defined in the backend's socket.manager.ts.
  */
 
-/** Standardized meta envelope emitted by the server on every push. */
+type PostgresChangesEventSelector = 'INSERT' | 'UPDATE' | 'DELETE' | '*';
+/** Filter for any event (including the `*` catch-all). */
+interface PostgresChangesFilter {
+    event: PostgresChangesEventSelector;
+    schema?: string;
+    table: string;
+    /** PostgREST-style filter: `column=op.value` or `column=in.(a,b,c)`. */
+    filter?: string;
+}
+/** Common shape shared by every postgres_changes payload variant. */
+interface PostgresChangesPayloadBase {
+    schema: string;
+    table: string;
+    commit_timestamp: string;
+    columns: Array<{
+        name: string;
+        type: string;
+    }>;
+    errors?: string[];
+}
+/** INSERT: the new row is in `new`. `old` is kept as an empty object so
+ *  code that accesses both fields never needs optional chaining. */
+interface PostgresChangesInsertPayload<T = Record<string, unknown>> extends PostgresChangesPayloadBase {
+    eventType: 'INSERT';
+    new: T;
+    old: Record<string, never>;
+}
+/** UPDATE: both `new` and `old` are populated. `old` is `Partial<T>`
+ *  because RLS / REPLICA IDENTITY may strip columns the subscriber can't
+ *  see. */
+interface PostgresChangesUpdatePayload<T = Record<string, unknown>> extends PostgresChangesPayloadBase {
+    eventType: 'UPDATE';
+    new: T;
+    old: Partial<T>;
+}
+/** DELETE: the deleted row is in `old`. On RLS-enabled tables only
+ *  primary-key columns are populated. `new` is always an empty object. */
+interface PostgresChangesDeletePayload<T = Record<string, unknown>> extends PostgresChangesPayloadBase {
+    eventType: 'DELETE';
+    new: Record<string, never>;
+    old: Partial<T>;
+}
+/** Discriminated union — what the `'*'` overload of `on('postgres_changes',
+ *  ...)` passes to the callback. */
+type PostgresChangesPayload<T = Record<string, unknown>> = PostgresChangesInsertPayload<T> | PostgresChangesUpdatePayload<T> | PostgresChangesDeletePayload<T>;
+interface BroadcastFilter {
+    event: string;
+}
+interface BroadcastPayload<T = Record<string, unknown>> {
+    type: 'broadcast';
+    event: string;
+    payload: T;
+}
+/** Presence event selector used with `.on('presence', { event }, cb)`. */
+type PresenceEventSelector = 'sync' | 'join' | 'leave';
+interface PresenceFilter {
+    event: PresenceEventSelector;
+}
+/** State map keyed by opaque client key (the socket id on our server side).
+ *  The client treats these keys as blackboxes — just compare across sync /
+ *  join / leave deltas to track which participants appeared or departed. */
+type PresenceState<T = Record<string, unknown>> = Record<string, T>;
+interface PresenceSyncPayload<T = Record<string, unknown>> {
+    event: 'sync';
+    state: PresenceState<T>;
+}
+interface PresenceJoinPayload<T = Record<string, unknown>> {
+    event: 'join';
+    /** One-entry map `{ [key]: state }` with the new or updated state. */
+    joins: PresenceState<T>;
+}
+interface PresenceLeavePayload<T = Record<string, unknown>> {
+    event: 'leave';
+    /** One-entry map `{ [key]: state }` with the state just before leaving. */
+    leaves: PresenceState<T>;
+}
+type PresencePayload<T = Record<string, unknown>> = PresenceSyncPayload<T> | PresenceJoinPayload<T> | PresenceLeavePayload<T>;
 interface RealtimeMessageMeta {
     channel?: string;
     message_id: string;
-    sender_type: 'system' | 'user';
     sender_id?: string;
     timestamp: string;
 }
-/** Subscribe ack returned by the server. */
-type SubscribeResult = {
-    ok: true;
-    channel: string;
-} | {
-    ok: false;
-    channel: string;
-    error: {
-        code: string;
-        message: string;
+/**
+ * Channel configuration — passed to `client.realtime.channel(topic, opts)`.
+ * Every option has a safe default so apps can omit `opts` entirely for the
+ * common case.
+ */
+interface ChannelOptions {
+    config?: {
+        /** When true, subscribe is gated on `realtime.authorize_subscribe(role,
+         *  claims, topic)` at the server side. Replay is also gated if
+         *  requested on a private channel. Default: `false` (open topic). */
+        private?: boolean;
+        broadcast?: {
+            /** When `false`, the sending socket is excluded from the fan-out.
+             *  Default: `true` (sender also receives its own broadcasts). */
+            self?: boolean;
+        };
+        presence?: {
+            /** Optional stable key that replaces the socket id in the presence
+             *  hash. Useful to group multiple tabs of the same user under one
+             *  entry. Default: socket id (each tab is a separate entry). */
+            key?: string;
+        };
     };
-};
-/** Server-pushed unsolicited error. */
-interface RealtimeErrorPayload {
-    channel?: string;
-    code: string;
-    message: string;
-}
-interface RealtimeListener<T = unknown> {
-    (payload: T, meta: RealtimeMessageMeta): void;
 }
-type ConnectionListener = () => void;
-type DisconnectListener = (reason: string) => void;
-type ConnectErrorListener = (error: Error) => void;
+type ChannelStatus = 'SUBSCRIBED' | 'CHANNEL_ERROR' | 'TIMED_OUT' | 'CLOSED';
+/** Callback invoked for every channel status transition. The second
+ *  argument is a standard `Error` (so consumers can annotate it as
+ *  `err: Error` out of the box) with a non-standard `.code` string
+ *  attached for programmatic discrimination (`SUBSCRIBE_FAILED`,
+ *  `CONNECT_FAILED`, `REJOIN_FAILED`, …). */
+type ChannelStatusCallback = (status: ChannelStatus, error?: Error & {
+    code?: string;
+}) => void;
 interface RealtimeOptions {
-    /** Override the path on the server. Defaults to the Socket.IO default. */
     path?: string;
-    /** Transport strategy. Defaults to `['websocket']` — modern browsers
-     *  and Node always support it, no need for the long-polling fallback. */
     transports?: Array<'websocket' | 'polling'>;
-    /** Handshake timeout in ms. */
     timeoutMs?: number;
-    /** Extra fields merged into socket.handshake.auth. Advanced usage. */
     extraAuth?: Record<string, string>;
 }
-/**
- * MITWAY-BaaS realtime client.
- *
- * Public API mirrors the InsForge realtime SDK for familiarity, but the
- * wire protocol follows our backend (see
- * `MITWAY-BaaS/backend/src/infra/socket/socket.manager.ts`):
- *
- *   - Handshake auth uses `auth.token` containing the JWT (preferred)
- *     or an opaque API key string.
- *   - `realtime:subscribe` / `realtime:unsubscribe` / `realtime:publish`
- *     are the client-to-server events.
- *   - Server pushes the user-defined `event` name with `{ ...payload,
- *     meta }` shape.
- *   - `realtime:error` is the unsolicited error channel for publish
- *     failures and similar.
- */
+type BroadcastCallback<T = Record<string, unknown>> = (payload: BroadcastPayload<T>) => void;
+type PresenceSyncCallback = () => void;
+type PresenceJoinCallback<T = Record<string, unknown>> = (payload: PresenceJoinPayload<T>) => void;
+type PresenceLeaveCallback<T = Record<string, unknown>> = (payload: PresenceLeavePayload<T>) => void;
+declare class RealtimeChannel {
+    readonly topic: string;
+    private readonly realtime;
+    private bindings;
+    private state;
+    private statusCallback;
+    /** Local presence state mirror — populated from `presence_state` /
+     *  `presence_join` / `presence_leave` events. Read via `presenceState()`. */
+    private presence;
+    /** Latest state this client has tracked. Non-null means the heartbeat
+     *  timer is active and we'll re-emit this state every TTL/2. */
+    private trackedState;
+    private presenceHeartbeat;
+    /** Timestamp of the most recently received broadcast on this channel —
+     *  used as the `since` anchor on replay after reconnect. ISO-8601. */
+    private lastBroadcastTimestamp;
+    /** Configuration from `channel(topic, opts)`. Frozen at construction. */
+    private readonly options;
+    constructor(topic: string, realtime: Realtime, options?: ChannelOptions);
+    /** Whether this channel was opened as `private: true`. */
+    private get isPrivate();
+    /** The user-supplied presence key, if any. */
+    private get presenceKey();
+    /** Internal — exposed for Realtime to drive resubscription after a
+     *  network hiccup. Returns the current lifecycle state. */
+    _state(): 'closed' | 'joining' | 'joined' | 'errored';
+    /** Internal — called by `Realtime` when Socket.IO reconnects after a
+     *  drop. Re-runs the registration flow; the backend assigns fresh
+     *  subscription_ids and Socket.IO rejoins the per-subscription rooms,
+     *  so events resume without developer intervention. The user-provided
+     *  statusCallback (from the original subscribe()) fires again with
+     *  'SUBSCRIBED' or 'CHANNEL_ERROR' so the app can reflect state. */
+    _rejoinAfterReconnect(): Promise<void>;
+    on<T = Record<string, unknown>>(type: 'postgres_changes', filter: {
+        event: 'INSERT';
+        schema?: string;
+        table: string;
+        filter?: string;
+    }, callback: (payload: PostgresChangesInsertPayload<T>) => void): this;
+    on<T = Record<string, unknown>>(type: 'postgres_changes', filter: {
+        event: 'UPDATE';
+        schema?: string;
+        table: string;
+        filter?: string;
+    }, callback: (payload: PostgresChangesUpdatePayload<T>) => void): this;
+    on<T = Record<string, unknown>>(type: 'postgres_changes', filter: {
+        event: 'DELETE';
+        schema?: string;
+        table: string;
+        filter?: string;
+    }, callback: (payload: PostgresChangesDeletePayload<T>) => void): this;
+    on<T = Record<string, unknown>>(type: 'postgres_changes', filter: {
+        event: '*';
+        schema?: string;
+        table: string;
+        filter?: string;
+    }, callback: (payload: PostgresChangesPayload<T>) => void): this;
+    on<T = Record<string, unknown>>(type: 'broadcast', filter: BroadcastFilter, callback: BroadcastCallback<T>): this;
+    on(type: 'presence', filter: {
+        event: 'sync';
+    }, callback: PresenceSyncCallback): this;
+    on<T = Record<string, unknown>>(type: 'presence', filter: {
+        event: 'join';
+    }, callback: PresenceJoinCallback<T>): this;
+    on<T = Record<string, unknown>>(type: 'presence', filter: {
+        event: 'leave';
+    }, callback: PresenceLeaveCallback<T>): this;
+    /**
+     * Register or refresh this client's presence entry on the channel. Safe
+     * to call many times — state replaces (not merges). Starts a heartbeat
+     * timer at TTL/2 so the entry stays alive while the socket is open.
+     * The channel must be `subscribe()`d first (the server enforces this).
+     */
+    track(state: Record<string, unknown>): Promise<void>;
+    /**
+     * Remove this client's presence entry immediately, stopping the
+     * heartbeat. Safe if the client never called `track`.
+     */
+    untrack(): void;
+    /** Snapshot of the current presence state on this channel. Keys are
+     *  opaque client identifiers (server-assigned). Re-read inside your
+     *  `.on('presence', { event: 'sync' }, ...)` handler. */
+    presenceState<T = Record<string, unknown>>(): PresenceState<T>;
+    /**
+     * Register all bindings with the server:
+     *   * For each `broadcast` binding, ensure we're subscribed to the topic
+     *     (one `realtime:subscribe` for the channel as a whole).
+     *   * For each `postgres_changes` binding, emit
+     *     `realtime:postgres_changes:subscribe` and record the assigned
+     *     subscription_id.
+     *
+     * `statusCallback` is invoked with `'SUBSCRIBED'` when every binding
+     * has ack'd, or with `'CHANNEL_ERROR' | 'TIMED_OUT'` on failure.
+     */
+    subscribe(statusCallback?: ChannelStatusCallback): this;
+    /**
+     * Tear down every binding: unsubscribe from the broadcast topic (if
+     * any broadcast bindings exist) and remove every postgres_changes
+     * subscription by id. Safe to call when state is already closed.
+     */
+    unsubscribe(): Promise<void>;
+    /**
+     * Publish a broadcast event to the topic. Broadcasts are always
+     * ephemeral — the server fans out to every subscribed socket in memory,
+     * with no DB persistence or webhook fan-out. For audited / durable
+     * events, write to your own application table and enable
+     * `postgres_changes` on it; the SDK will surface the INSERT as a
+     * `postgres_changes` event without a separate channel.send call.
+     *
+     * The returned promise always resolves with the server ack, so callers
+     * can `await channel.send(...)` to confirm delivery + get the server-
+     * assigned `message_id`. There's no performance cost — Socket.IO piggy-
+     * backs the ack on the same frame. Callers that don't need it just
+     * don't await.
+     */
+    send<T extends Record<string, unknown>>(args: {
+        type: 'broadcast';
+        event: string;
+        payload: T;
+    }): Promise<{
+        status: 'ok';
+        message_id: string;
+    } | {
+        status: 'error';
+        error: {
+            code: string;
+            message: string;
+        };
+    }>;
+    /**
+     * Replay SQL-originated broadcasts on this topic since the given
+     * timestamp. Delivered only to this socket (same envelope format as
+     * live broadcasts; the SDK routes them through `.on('broadcast', ...)`
+     * bindings just like the real-time path). Backend caps the window at
+     * 24 h and the limit at 1000.
+     */
+    replay(args: {
+        since: string;
+        limit?: number;
+    }): Promise<void>;
+    /** Internal — called by Realtime's event router on every incoming event. */
+    _dispatch(event: string, envelope: Record<string, unknown>): void;
+    private firePresence;
+    private registerAllBindings;
+}
 declare class Realtime {
     private socket;
-    private baseUrl;
-    private options;
-    private anonKey;
-    private tokenManager;
-    private listeners;
-    private reserved;
+    private readonly baseUrl;
+    private readonly options;
+    private readonly anonKey;
+    private readonly tokenManager;
+    private channels;
     private connecting;
-    private subscribedChannels;
+    /** Flips to `true` once the initial handshake resolves. Differentiates
+     *  the first `connect` event (part of `openSocket`) from subsequent
+     *  reconnect events (which should trigger auto-resubscribe). */
+    private firstConnected;
     constructor(baseUrl: string, tokenManager: TokenManager, anonKey: string | undefined, options?: RealtimeOptions);
     get isConnected(): boolean;
     get socketId(): string | undefined;
-    /** Explicitly open the connection. Safe to call multiple times; only
-     *  opens one socket per instance. Subsequent calls during connection
-     *  return the same in-flight promise. */
+    /**
+     * Get (or create) a channel for `topic`. Channels are cached so multiple
+     * `.channel('same')` calls return the same instance.
+     *
+     * The optional `opts` argument lets the caller configure the channel:
+     *   * `config.private` — enable subscribe-side authorization against
+     *     `realtime.authorize_subscribe(...)` on the tenant DB.
+     *   * `config.broadcast.self` — `false` excludes the sender from the
+     *     fan-out (defaults to `true`).
+     *   * `config.presence.key` — stable presence key to group multiple
+     *     tabs of the same user under one entry.
+     *
+     * `channel.send()` always resolves with the server ack (see its own
+     * docstring); there is no separate opt-in needed.
+     *
+     * Options are locked in when the channel is first created; subsequent
+     * `.channel('same')` calls with different opts are ignored. Pass a
+     * different topic to get a different-configured channel.
+     */
+    channel(topic: string, opts?: ChannelOptions): RealtimeChannel;
     connect(): Promise<void>;
-    private openSocket;
-    /** Close the socket and clear in-memory subscription state. Reserved
-     *  listeners survive so callers can reconnect later via `connect()`. */
+    /**
+     * Close the socket. Channels are left as-is so they can re-subscribe
+     * on the next `connect()` — useful for auth token refresh flows.
+     */
     disconnect(): void;
-    subscribe(channel: string): Promise<SubscribeResult>;
-    /** Fire-and-forget. No ack from the server. */
-    unsubscribe(channel: string): void;
-    /** Publish via the Socket.IO transport. Subject to RLS INSERT policy
-     *  on `realtime.messages` (disabled by default — the developer must
-     *  add a policy before clients can publish). Returns immediately; any
-     *  server rejection comes through the `error` reserved event. */
-    publish(channel: string, event: string, payload: Record<string, unknown>): void;
-    on(event: 'connect', cb: ConnectionListener): void;
-    on(event: 'disconnect', cb: DisconnectListener): void;
-    on(event: 'connect_error', cb: ConnectErrorListener): void;
-    on(event: 'error', cb: RealtimeListener<RealtimeErrorPayload>): void;
-    on<T = unknown>(event: string, cb: RealtimeListener<T>): void;
-    off(event: string, cb: (...args: any[]) => void): void;
+    _getSocket(): Socket | null;
+    _detachChannel(channel: RealtimeChannel): void;
+    private openSocket;
     private dispatch;
-    private emitReserved;
 }
 
 /**
@@ -548,7 +777,7 @@ declare class MitwayBaasClient {
  */
 
 /**
- * Factory function for creating SDK clients (Supabase-style).
+ * Factory function for creating SDK clients.
  *
  * @example
  * ```typescript
@@ -562,4 +791,4 @@ declare class MitwayBaasClient {
  */
 declare function createClient(config: MitwayBaasConfig): MitwayBaasClient;
 
-export { type ApiError, Auth, type AuthRefreshResponse, type AuthResponse, type AuthResult, type AuthSession, type ConnectErrorListener, type ConnectionListener, Database, type DisconnectListener, HttpClient, Logger, MitwayBaasClient, type MitwayBaasConfig, MitwayBaasError, Realtime, type RealtimeErrorPayload, type RealtimeListener, type RealtimeMessageMeta, type RealtimeOptions, type SignInRequest, type SignUpRequest, type SubscribeResult, TokenManager, type User, createClient, MitwayBaasClient as default };
+export { type ApiError, Auth, type AuthRefreshResponse, type AuthResponse, type AuthResult, type AuthSession, type BroadcastFilter, type BroadcastPayload, type ChannelOptions, type ChannelStatus, type ChannelStatusCallback, Database, HttpClient, Logger, MitwayBaasClient, type MitwayBaasConfig, MitwayBaasError, type PostgresChangesDeletePayload, type PostgresChangesEventSelector, type PostgresChangesFilter, type PostgresChangesInsertPayload, type PostgresChangesPayload, type PostgresChangesUpdatePayload, type PresenceEventSelector, type PresenceFilter, type PresenceJoinPayload, type PresenceLeavePayload, type PresencePayload, type PresenceState, type PresenceSyncPayload, Realtime, RealtimeChannel, type RealtimeMessageMeta, type RealtimeOptions, type SignInRequest, type SignUpRequest, TokenManager, type User, createClient, MitwayBaasClient as default };