@mitway/sdk 0.2.2 → 0.2.4

package/dist/index.d.cts

@@ -1,3 +1,4 @@
+import { Socket } from 'socket.io-client';
 import * as _supabase_postgrest_js from '@supabase/postgrest-js';
 
 /**
@@ -29,6 +30,301 @@ interface User {
     updated_at: string;
 }
 
+/**
+ * Token Manager for the MITWAY-BaaS SDK.
+ *
+ * In-memory storage for the access token + user. Browser CSRF token lives
+ * in a cookie so the cookie-based refresh flow works across page reloads.
+ */
+
+declare class TokenManager {
+    private accessToken;
+    private user;
+    /** Fired when the access token changes (used by long-lived consumers). */
+    onTokenChange: (() => void) | null;
+    saveSession(session: AuthSession): void;
+    getSession(): AuthSession | null;
+    getAccessToken(): string | null;
+    setAccessToken(token: string): void;
+    getUser(): User | null;
+    setUser(user: User): void;
+    clearSession(): void;
+}
+
+/**
+ * Realtime module — Socket.IO client exposing the channel API.
+ *
+ * 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.
+ */
+
+type PostgresChangesEventSelector = 'INSERT' | 'UPDATE' | 'DELETE' | '*';
+interface PostgresChangesFilter {
+    event: PostgresChangesEventSelector;
+    schema?: string;
+    table: string;
+    /** PostgREST-style filter: `column=op.value` or `column=in.(a,b,c)`. */
+    filter?: string;
+}
+interface PostgresChangesPayload<T = Record<string, unknown>> {
+    type: 'INSERT' | 'UPDATE' | 'DELETE';
+    schema: string;
+    table: string;
+    commit_timestamp: string;
+    columns: Array<{
+        name: string;
+        type: string;
+    }>;
+    record?: T;
+    old_record?: T;
+    errors?: string[];
+}
+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_id?: string;
+    timestamp: 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 true, `channel.send(...)` resolves only after the server
+             *  ack'd the publish — useful if the app wants to know the
+             *  message_id assigned by the server. Default: `false`
+             *  (fire-and-forget). */
+            ack?: boolean;
+            /** 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;
+        };
+    };
+}
+type ChannelStatus = 'SUBSCRIBED' | 'CHANNEL_ERROR' | 'TIMED_OUT' | 'CLOSED';
+type ChannelStatusCallback = (status: ChannelStatus, error?: {
+    code: string;
+    message: string;
+}) => void;
+interface RealtimeOptions {
+    path?: string;
+    transports?: Array<'websocket' | 'polling'>;
+    timeoutMs?: number;
+    extraAuth?: Record<string, string>;
+}
+type PostgresChangesCallback<T = Record<string, unknown>> = (payload: PostgresChangesPayload<T>) => void;
+type BroadcastCallback<T = Record<string, unknown>> = (payload: BroadcastPayload<T>) => void;
+type PresenceCallback<T = Record<string, unknown>> = (payload: PresencePayload<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: PostgresChangesFilter, callback: PostgresChangesCallback<T>): this;
+    on<T = Record<string, unknown>>(type: 'broadcast', filter: BroadcastFilter, callback: BroadcastCallback<T>): this;
+    on<T = Record<string, unknown>>(type: 'presence', filter: PresenceFilter, callback: PresenceCallback<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.
+     */
+    send<T extends Record<string, unknown>>(args: {
+        type: 'broadcast';
+        event: string;
+        payload: T;
+    }): Promise<{
+        ok: true;
+        message_id: string;
+    } | {
+        ok: false;
+        error: {
+            code: string;
+            message: string;
+        };
+    } | void>;
+    /**
+     * 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 readonly baseUrl;
+    private readonly options;
+    private readonly anonKey;
+    private readonly tokenManager;
+    private channels;
+    private connecting;
+    /** 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;
+    /**
+     * 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.ack` — `channel.send()` resolves with the
+     *     server's ack (message_id) instead of fire-and-forget.
+     *   * `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.
+     *
+     * 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>;
+    /**
+     * 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;
+    _getSocket(): Socket | null;
+    _detachChannel(channel: RealtimeChannel): void;
+    private openSocket;
+    private dispatch;
+}
+
 /**
  * MITWAY-BaaS SDK types — only SDK-specific shapes live here.
  * The `User` shape is inlined in `./lib/user` so this package has zero
@@ -89,6 +385,10 @@ interface MitwayBaasConfig {
      * @default true
      */
     autoRefreshToken?: boolean;
+    /**
+     * Realtime transport options. See `RealtimeOptions`.
+     */
+    realtime?: RealtimeOptions;
 }
 /**
  * Active user session in memory. Mirrors what the auth endpoints return.
@@ -146,27 +446,6 @@ declare class Logger {
     logResponse(method: string, url: string, status: number, durationMs: number, body?: any): void;
 }
 
-/**
- * Token Manager for the MITWAY-BaaS SDK.
- *
- * In-memory storage for the access token + user. Browser CSRF token lives
- * in a cookie so the cookie-based refresh flow works across page reloads.
- */
-
-declare class TokenManager {
-    private accessToken;
-    private user;
-    /** Fired when the access token changes (used by long-lived consumers). */
-    onTokenChange: (() => void) | null;
-    saveSession(session: AuthSession): void;
-    getSession(): AuthSession | null;
-    getAccessToken(): string | null;
-    setAccessToken(token: string): void;
-    getUser(): User | null;
-    setUser(user: User): void;
-    clearSession(): void;
-}
-
 /**
  * HttpClient with retry, timeout, abort signal composition, and automatic
  * token refresh on 401 INVALID_TOKEN responses.
@@ -409,6 +688,7 @@ declare class MitwayBaasClient {
     private tokenManager;
     readonly auth: Auth;
     readonly database: Database;
+    readonly realtime: Realtime;
     constructor(config?: MitwayBaasConfig);
     /**
      * Escape hatch for callers that need to make custom requests against the
@@ -423,19 +703,19 @@ declare class MitwayBaasClient {
  * Currently ships:
  *   - auth     (signUp, signInWithPassword, signOut, refreshSession, getSession, getUser)
  *   - database (PostgREST-backed query builder via @supabase/postgrest-js)
+ *   - realtime (Socket.IO transport: subscribe / unsubscribe / publish / on)
  *
  * Not yet included (no backend support):
  *   - storage
  *   - functions
  *   - email
  *   - ai
- *   - realtime
  *
  * @packageDocumentation
  */
 
 /**
- * Factory function for creating SDK clients (Supabase-style).
+ * Factory function for creating SDK clients.
  *
  * @example
  * ```typescript
@@ -449,4 +729,4 @@ declare class MitwayBaasClient {
  */
 declare function createClient(config: MitwayBaasConfig): MitwayBaasClient;
 
-export { type ApiError, Auth, type AuthRefreshResponse, type AuthResponse, type AuthResult, type AuthSession, Database, HttpClient, Logger, MitwayBaasClient, type MitwayBaasConfig, MitwayBaasError, type SignInRequest, type SignUpRequest, 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 PostgresChangesEventSelector, type PostgresChangesFilter, type PostgresChangesPayload, 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 };