@mitway/sdk 0.2.3 → 0.2.4

package/dist/index.cjs

@@ -27,6 +27,7 @@ __export(index_exports, {
   MitwayBaasClient: () => MitwayBaasClient,
   MitwayBaasError: () => MitwayBaasError,
   Realtime: () => Realtime,
+  RealtimeChannel: () => RealtimeChannel,
   TokenManager: () => TokenManager,
   createClient: () => createClient,
   default: () => index_default
@@ -891,40 +892,497 @@ var Database = class {
 
 // src/modules/realtime.ts
 var import_socket = require("socket.io-client");
+var PRESENCE_HEARTBEAT_MS = 2e4;
 var DEFAULT_CONNECT_TIMEOUT_MS = 1e4;
+var RealtimeChannel = class {
+  constructor(topic, realtime, options = {}) {
+    this.topic = topic;
+    this.realtime = realtime;
+    this.options = options;
+  }
+  topic;
+  realtime;
+  bindings = [];
+  state = "closed";
+  statusCallback = null;
+  /** Local presence state mirror — populated from `presence_state` /
+   *  `presence_join` / `presence_leave` events. Read via `presenceState()`. */
+  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. */
+  trackedState = null;
+  presenceHeartbeat = null;
+  /** Timestamp of the most recently received broadcast on this channel —
+   *  used as the `since` anchor on replay after reconnect. ISO-8601. */
+  lastBroadcastTimestamp = null;
+  /** Configuration from `channel(topic, opts)`. Frozen at construction. */
+  options;
+  /** Whether this channel was opened as `private: true`. */
+  get isPrivate() {
+    return this.options.config?.private === true;
+  }
+  /** The user-supplied presence key, if any. */
+  get presenceKey() {
+    return this.options.config?.presence?.key;
+  }
+  /** Internal — exposed for Realtime to drive resubscription after a
+   *  network hiccup. Returns the current lifecycle state. */
+  _state() {
+    return this.state;
+  }
+  /** 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. */
+  async _rejoinAfterReconnect() {
+    if (this.state === "closed") {
+      return;
+    }
+    for (const b of this.bindings) {
+      if (b.type === "postgres_changes") {
+        b.subscriptionId = void 0;
+      }
+    }
+    this.state = "joining";
+    try {
+      await this.registerAllBindings();
+      if (this.trackedState) {
+        const socket = this.realtime._getSocket();
+        const key = this.presenceKey;
+        socket?.emit(
+          "realtime:presence:track",
+          key !== void 0 ? { channel: this.topic, state: this.trackedState, key } : { channel: this.topic, state: this.trackedState }
+        );
+      }
+      if (this.lastBroadcastTimestamp && this.bindings.some((b) => b.type === "broadcast")) {
+        void this.replay({ since: this.lastBroadcastTimestamp }).catch(() => void 0);
+      }
+      this.state = "joined";
+      this.statusCallback?.("SUBSCRIBED");
+    } catch (err) {
+      this.state = "errored";
+      this.statusCallback?.("CHANNEL_ERROR", {
+        code: "REJOIN_FAILED",
+        message: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
+  on(type, filter, callback) {
+    if (type === "postgres_changes") {
+      this.bindings.push({
+        type: "postgres_changes",
+        filter,
+        callback
+      });
+    } else if (type === "broadcast") {
+      this.bindings.push({
+        type: "broadcast",
+        filter,
+        callback
+      });
+    } else {
+      this.bindings.push({
+        type: "presence",
+        filter,
+        callback
+      });
+    }
+    return this;
+  }
+  // -------------------------------------------------------------------------
+  // Presence — track / untrack / state accessor
+  // -------------------------------------------------------------------------
+  /**
+   * 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).
+   */
+  async track(state) {
+    const socket = this.realtime._getSocket();
+    if (!socket) {
+      throw new MitwayBaasError("Socket not connected", 503, "NOT_CONNECTED");
+    }
+    this.trackedState = state;
+    const key = this.presenceKey;
+    socket.emit(
+      "realtime:presence:track",
+      key !== void 0 ? { channel: this.topic, state, key } : { channel: this.topic, state }
+    );
+    if (!this.presenceHeartbeat) {
+      this.presenceHeartbeat = setInterval(() => {
+        const s = this.realtime._getSocket();
+        if (s && this.trackedState) {
+          s.emit(
+            "realtime:presence:track",
+            key !== void 0 ? { channel: this.topic, state: this.trackedState, key } : { channel: this.topic, state: this.trackedState }
+          );
+        }
+      }, PRESENCE_HEARTBEAT_MS);
+      const h = this.presenceHeartbeat;
+      h.unref?.();
+    }
+  }
+  /**
+   * Remove this client's presence entry immediately, stopping the
+   * heartbeat. Safe if the client never called `track`.
+   */
+  untrack() {
+    this.trackedState = null;
+    if (this.presenceHeartbeat) {
+      clearInterval(this.presenceHeartbeat);
+      this.presenceHeartbeat = null;
+    }
+    const socket = this.realtime._getSocket();
+    socket?.emit("realtime:presence:untrack", { channel: this.topic });
+  }
+  /** 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() {
+    return this.presence;
+  }
+  /**
+   * 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) {
+    this.statusCallback = statusCallback ?? null;
+    if (this.state === "joining" || this.state === "joined") {
+      return this;
+    }
+    this.state = "joining";
+    void this.realtime.connect().then(
+      async () => {
+        try {
+          await this.registerAllBindings();
+          this.state = "joined";
+          this.statusCallback?.("SUBSCRIBED");
+        } catch (err) {
+          this.state = "errored";
+          const message = err instanceof Error ? err.message : String(err);
+          this.statusCallback?.("CHANNEL_ERROR", {
+            code: "SUBSCRIBE_FAILED",
+            message
+          });
+        }
+      },
+      (err) => {
+        this.state = "errored";
+        this.statusCallback?.("CHANNEL_ERROR", {
+          code: "CONNECT_FAILED",
+          message: err.message
+        });
+      }
+    );
+    return 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.
+   */
+  async unsubscribe() {
+    if (this.state === "closed") {
+      return;
+    }
+    const socket = this.realtime._getSocket();
+    if (this.presenceHeartbeat) {
+      clearInterval(this.presenceHeartbeat);
+      this.presenceHeartbeat = null;
+    }
+    if (!socket) {
+      this.trackedState = null;
+      this.state = "closed";
+      return;
+    }
+    if (this.trackedState) {
+      socket.emit("realtime:presence:untrack", { channel: this.topic });
+      this.trackedState = null;
+    }
+    const pcBindings = this.bindings.filter(
+      (b) => b.type === "postgres_changes"
+    );
+    for (const b of pcBindings) {
+      if (b.subscriptionId) {
+        socket.emit("realtime:postgres_changes:unsubscribe", {
+          subscription_id: b.subscriptionId
+        });
+        b.subscriptionId = void 0;
+      }
+    }
+    if (this.bindings.some((b) => b.type === "broadcast" || b.type === "presence")) {
+      socket.emit("realtime:unsubscribe", { channel: this.topic });
+    }
+    this.realtime._detachChannel(this);
+    this.state = "closed";
+    this.statusCallback?.("CLOSED");
+  }
+  /**
+   * 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.
+   */
+  async send(args) {
+    if (args.type !== "broadcast") {
+      throw new MitwayBaasError(
+        'Only "broadcast" sends are supported \u2014 DB changes flow via your DB writes, not channel.send()',
+        400,
+        "UNSUPPORTED_SEND_TYPE"
+      );
+    }
+    const RESERVED_BROADCAST_NAMES = /* @__PURE__ */ new Set([
+      "postgres_changes",
+      "presence_state",
+      "presence_join",
+      "presence_leave"
+    ]);
+    if (RESERVED_BROADCAST_NAMES.has(args.event)) {
+      throw new MitwayBaasError(
+        `"${args.event}" is a reserved event name \u2014 pick a different name for broadcast events`,
+        400,
+        "RESERVED_EVENT_NAME"
+      );
+    }
+    const socket = this.realtime._getSocket();
+    if (!socket) {
+      throw new MitwayBaasError("Socket not connected", 503, "NOT_CONNECTED");
+    }
+    const broadcastCfg = this.options.config?.broadcast;
+    const wantAck = broadcastCfg?.ack === true;
+    const self = broadcastCfg?.self;
+    const wirePayload = {
+      channel: this.topic,
+      event: args.event,
+      payload: args.payload
+    };
+    if (self === false) {
+      wirePayload.self = false;
+    }
+    if (!wantAck) {
+      socket.emit("realtime:publish", wirePayload);
+      return;
+    }
+    return await new Promise((resolve) => {
+      socket.emit(
+        "realtime:publish",
+        wirePayload,
+        (ack) => {
+          resolve(ack);
+        }
+      );
+    });
+  }
+  /**
+   * 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.
+   */
+  async replay(args) {
+    const socket = this.realtime._getSocket();
+    if (!socket) {
+      throw new MitwayBaasError("Socket not connected", 503, "NOT_CONNECTED");
+    }
+    socket.emit("realtime:broadcast:replay", {
+      channel: this.topic,
+      since: args.since,
+      limit: args.limit,
+      private: this.isPrivate
+    });
+  }
+  /** Internal — called by Realtime's event router on every incoming event. */
+  _dispatch(event, envelope) {
+    if (event === "postgres_changes") {
+      const pcEvent = envelope;
+      for (const b of this.bindings) {
+        if (b.type !== "postgres_changes") {
+          continue;
+        }
+        if (!b.subscriptionId || !pcEvent.ids.includes(b.subscriptionId)) {
+          continue;
+        }
+        const matchesEvent = b.filter.event === "*" || b.filter.event === pcEvent.data.type;
+        if (!matchesEvent) {
+          continue;
+        }
+        try {
+          b.callback(pcEvent.data);
+        } catch {
+        }
+      }
+      return;
+    }
+    if (event === "presence_state" || event === "presence_join" || event === "presence_leave") {
+      const e = envelope;
+      if (e.channel !== this.topic) {
+        return;
+      }
+      if (event === "presence_state" && e.state) {
+        this.presence = { ...e.state };
+        this.firePresence({ event: "sync", state: this.presence });
+      } else if (event === "presence_join" && e.joins) {
+        Object.assign(this.presence, e.joins);
+        this.firePresence({ event: "join", joins: e.joins });
+      } else if (event === "presence_leave" && e.leaves) {
+        for (const key of Object.keys(e.leaves)) {
+          delete this.presence[key];
+        }
+        this.firePresence({ event: "leave", leaves: e.leaves });
+      }
+      return;
+    }
+    const meta = envelope.meta;
+    if (meta?.timestamp) {
+      if (!this.lastBroadcastTimestamp || meta.timestamp > this.lastBroadcastTimestamp) {
+        this.lastBroadcastTimestamp = meta.timestamp;
+      }
+    }
+    for (const b of this.bindings) {
+      if (b.type !== "broadcast") {
+        continue;
+      }
+      if (b.filter.event !== event) {
+        continue;
+      }
+      const { meta: _meta, ...payload } = envelope;
+      try {
+        b.callback({ type: "broadcast", event, payload });
+      } catch {
+      }
+    }
+  }
+  firePresence(payload) {
+    for (const b of this.bindings) {
+      if (b.type !== "presence") {
+        continue;
+      }
+      if (b.filter.event !== payload.event) {
+        continue;
+      }
+      try {
+        b.callback(payload);
+      } catch {
+      }
+    }
+  }
+  async registerAllBindings() {
+    const socket = this.realtime._getSocket();
+    if (!socket) {
+      throw new Error("Socket not available");
+    }
+    const needsRoomJoin = this.bindings.some(
+      (b) => b.type === "broadcast" || b.type === "presence"
+    );
+    if (needsRoomJoin) {
+      await new Promise((resolve, reject) => {
+        socket.emit(
+          "realtime:subscribe",
+          { channel: this.topic, private: this.isPrivate },
+          (ack) => {
+            if (ack.ok) {
+              resolve();
+            } else {
+              reject(new Error(ack.error?.message ?? "subscribe failed"));
+            }
+          }
+        );
+      });
+    }
+    const pcBindings = this.bindings.filter(
+      (b) => b.type === "postgres_changes"
+    );
+    await Promise.all(
+      pcBindings.map(
+        (b) => new Promise((resolve, reject) => {
+          socket.emit(
+            "realtime:postgres_changes:subscribe",
+            {
+              event: b.filter.event,
+              schema: b.filter.schema ?? "public",
+              table: b.filter.table,
+              filter: b.filter.filter
+            },
+            (ack) => {
+              if (ack.ok && ack.subscription_id) {
+                b.subscriptionId = ack.subscription_id;
+                resolve();
+              } else {
+                reject(
+                  new Error(ack.error?.message ?? "postgres_changes subscribe failed")
+                );
+              }
+            }
+          );
+        })
+      )
+    );
+  }
+};
 var Realtime = class {
   socket = null;
   baseUrl;
   options;
   anonKey;
   tokenManager;
-  listeners = /* @__PURE__ */ new Map();
-  reserved = {
-    connect: /* @__PURE__ */ new Set(),
-    disconnect: /* @__PURE__ */ new Set(),
-    connect_error: /* @__PURE__ */ new Set(),
-    error: /* @__PURE__ */ new Set()
-  };
+  channels = /* @__PURE__ */ new Map();
   connecting = null;
-  subscribedChannels = /* @__PURE__ */ new Set();
+  /** 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). */
+  firstConnected = false;
   constructor(baseUrl, tokenManager, anonKey, options = {}) {
     this.baseUrl = baseUrl;
     this.tokenManager = tokenManager;
     this.anonKey = anonKey;
     this.options = options;
   }
-  // -----------------------------------------------------------------
-  // Connection lifecycle
-  // -----------------------------------------------------------------
   get isConnected() {
     return this.socket?.connected === true;
   }
   get socketId() {
     return this.socket?.id;
   }
-  /** 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.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, opts) {
+    const existing = this.channels.get(topic);
+    if (existing) {
+      return existing;
+    }
+    const channel = new RealtimeChannel(topic, this, opts);
+    this.channels.set(topic, channel);
+    return channel;
+  }
   connect() {
     if (this.isConnected) {
       return Promise.resolve();
@@ -935,6 +1393,28 @@ var Realtime = class {
     this.connecting = this.openSocket();
     return this.connecting;
   }
+  /**
+   * Close the socket. Channels are left as-is so they can re-subscribe
+   * on the next `connect()` — useful for auth token refresh flows.
+   */
+  disconnect() {
+    if (!this.socket) {
+      return;
+    }
+    this.socket.disconnect();
+    this.socket = null;
+    this.firstConnected = false;
+  }
+  // -------------------------------------------------------------------------
+  // internals used by RealtimeChannel
+  // -------------------------------------------------------------------------
+  /* istanbul ignore next — tested via channel integration */
+  _getSocket() {
+    return this.socket;
+  }
+  _detachChannel(channel) {
+    this.channels.delete(channel.topic);
+  }
   openSocket() {
     const token = this.tokenManager.getAccessToken() ?? this.anonKey;
     if (!token) {
@@ -956,13 +1436,22 @@ var Realtime = class {
     });
     this.socket = socket;
     socket.onAny((event, ...args) => this.dispatch(event, args));
-    socket.on("connect", () => this.emitReserved("connect"));
-    socket.on("disconnect", (reason) => this.emitReserved("disconnect", reason));
-    socket.on("connect_error", (err) => this.emitReserved("connect_error", err));
+    socket.on("connect", () => {
+      if (!this.firstConnected) {
+        return;
+      }
+      for (const channel of this.channels.values()) {
+        const state = channel._state();
+        if (state === "joined" || state === "errored") {
+          void channel._rejoinAfterReconnect();
+        }
+      }
+    });
     return new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
         socket.off("connect", onConnect);
         socket.off("connect_error", onConnectError);
+        this.connecting = null;
         reject(
           new MitwayBaasError(
             `Realtime connection timeout after ${timeoutMs}ms`,
@@ -970,7 +1459,6 @@ var Realtime = class {
             "CONNECTION_TIMEOUT"
           )
         );
-        this.connecting = null;
       }, timeoutMs);
       const clear = () => {
         clearTimeout(timer);
@@ -980,128 +1468,31 @@ var Realtime = class {
       const onConnect = () => {
         clear();
         this.connecting = null;
+        this.firstConnected = true;
         resolve();
       };
       const onConnectError = (err) => {
         clear();
         this.connecting = null;
-        reject(
-          new MitwayBaasError(err.message, 0, "CONNECTION_FAILED")
-        );
+        reject(new MitwayBaasError(err.message, 0, "CONNECTION_FAILED"));
       };
       socket.once("connect", onConnect);
       socket.once("connect_error", onConnectError);
     });
   }
-  /** Close the socket and clear in-memory subscription state. Reserved
-   *  listeners survive so callers can reconnect later via `connect()`. */
-  disconnect() {
-    if (!this.socket) {
-      return;
-    }
-    this.socket.disconnect();
-    this.socket = null;
-    this.subscribedChannels.clear();
-  }
-  // -----------------------------------------------------------------
-  // Subscribe / Unsubscribe / Publish
-  // -----------------------------------------------------------------
-  async subscribe(channel) {
-    await this.connect();
-    const socket = this.socket;
-    if (!socket) {
-      return {
-        ok: false,
-        channel,
-        error: { code: "NOT_CONNECTED", message: "Socket is not connected" }
-      };
-    }
-    const result = await new Promise((resolve) => {
-      socket.emit("realtime:subscribe", { channel }, (ack) => {
-        resolve(ack);
-      });
-    });
-    if (result.ok) {
-      this.subscribedChannels.add(channel);
-    }
-    return result;
-  }
-  /** Fire-and-forget. No ack from the server. */
-  unsubscribe(channel) {
-    this.subscribedChannels.delete(channel);
-    this.socket?.emit("realtime:unsubscribe", { channel });
-  }
-  /** 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, event, payload) {
-    this.socket?.emit("realtime:publish", { channel, event, payload });
-  }
-  // TypeScript overload impl signature must be assignable from every
-  // public overload. The public overloads take arg lists of different
-  // shapes (ConnectionListener: 0 args, DisconnectListener: 1 string
-  // arg, RealtimeListener: 2 args), so the implementation uses the
-  // widest possible signature. This matches the pattern in socket.io
-  // itself and is the standard TypeScript overload idiom.
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  on(event, cb) {
-    if (isReserved(event)) {
-      this.reserved[event].add(cb);
-      return;
-    }
-    if (!this.listeners.has(event)) {
-      this.listeners.set(event, /* @__PURE__ */ new Set());
-    }
-    this.listeners.get(event).add(cb);
-  }
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  off(event, cb) {
-    if (isReserved(event)) {
-      this.reserved[event].delete(cb);
-      return;
-    }
-    this.listeners.get(event)?.delete(cb);
-  }
-  // -----------------------------------------------------------------
-  // Internals
-  // -----------------------------------------------------------------
   dispatch(event, args) {
-    if (isReserved(event)) {
+    if (event === "postgres_changes") {
+      const envelope2 = args[0] ?? {};
+      this.channels.forEach((ch) => ch._dispatch("postgres_changes", envelope2));
       return;
     }
-    if (event === "realtime:error") {
-      const err = args[0] ?? {};
-      this.reserved.error.forEach(
-        (cb) => cb(err, {
-          message_id: "",
-          sender_type: "system",
-          timestamp: (/* @__PURE__ */ new Date()).toISOString()
-        })
-      );
-      return;
-    }
-    const set = this.listeners.get(event);
-    if (!set || set.size === 0) {
+    if (event === "connect" || event === "disconnect" || event === "connect_error" || event === "error" || event === "realtime:error" || event === "realtime:shutdown") {
       return;
     }
     const envelope = args[0] ?? {};
-    const { meta, ...payload } = envelope;
-    const metaOrStub = meta ?? {
-      message_id: "",
-      sender_type: "system",
-      timestamp: (/* @__PURE__ */ new Date()).toISOString()
-    };
-    set.forEach((cb) => cb(payload, metaOrStub));
-  }
-  emitReserved(event, ...args) {
-    const set = this.reserved[event];
-    set.forEach((cb) => cb(...args));
+    this.channels.forEach((ch) => ch._dispatch(event, envelope));
   }
 };
-function isReserved(event) {
-  return event === "connect" || event === "disconnect" || event === "connect_error" || event === "error";
-}
 
 // src/client.ts
 var MitwayBaasClient = class {
@@ -1146,6 +1537,7 @@ var index_default = MitwayBaasClient;
   MitwayBaasClient,
   MitwayBaasError,
   Realtime,
+  RealtimeChannel,
   TokenManager,
   createClient
 });