@mitway/sdk 0.2.2 → 0.2.4

package/dist/index.cjs

@@ -26,6 +26,8 @@ __export(index_exports, {
   Logger: () => Logger,
   MitwayBaasClient: () => MitwayBaasClient,
   MitwayBaasError: () => MitwayBaasError,
+  Realtime: () => Realtime,
+  RealtimeChannel: () => RealtimeChannel,
   TokenManager: () => TokenManager,
   createClient: () => createClient,
   default: () => index_default
@@ -888,18 +890,629 @@ 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;
+  channels = /* @__PURE__ */ new Map();
+  connecting = null;
+  /** 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;
+  }
+  get isConnected() {
+    return this.socket?.connected === true;
+  }
+  get socketId() {
+    return this.socket?.id;
+  }
+  /**
+   * 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();
+    }
+    if (this.connecting) {
+      return this.connecting;
+    }
+    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) {
+      const err = new MitwayBaasError(
+        "Realtime requires an access token or anonKey",
+        401,
+        "AUTH_INVALID_API_KEY"
+      );
+      this.connecting = null;
+      return Promise.reject(err);
+    }
+    const timeoutMs = this.options.timeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
+    const socket = (0, import_socket.io)(this.baseUrl, {
+      path: this.options.path,
+      transports: this.options.transports ?? ["websocket"],
+      auth: { token, ...this.options.extraAuth ?? {} },
+      reconnection: true,
+      timeout: timeoutMs
+    });
+    this.socket = socket;
+    socket.onAny((event, ...args) => this.dispatch(event, args));
+    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`,
+            408,
+            "CONNECTION_TIMEOUT"
+          )
+        );
+      }, timeoutMs);
+      const clear = () => {
+        clearTimeout(timer);
+        socket.off("connect", onConnect);
+        socket.off("connect_error", onConnectError);
+      };
+      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"));
+      };
+      socket.once("connect", onConnect);
+      socket.once("connect_error", onConnectError);
+    });
+  }
+  dispatch(event, args) {
+    if (event === "postgres_changes") {
+      const envelope2 = args[0] ?? {};
+      this.channels.forEach((ch) => ch._dispatch("postgres_changes", envelope2));
+      return;
+    }
+    if (event === "connect" || event === "disconnect" || event === "connect_error" || event === "error" || event === "realtime:error" || event === "realtime:shutdown") {
+      return;
+    }
+    const envelope = args[0] ?? {};
+    this.channels.forEach((ch) => ch._dispatch(event, envelope));
+  }
+};
+
 // src/client.ts
 var MitwayBaasClient = class {
   http;
   tokenManager;
   auth;
   database;
+  realtime;
   constructor(config = {}) {
     const logger = new Logger(config.debug);
     this.tokenManager = new TokenManager();
     this.http = new HttpClient(config, this.tokenManager, logger);
     this.auth = new Auth(this.http, this.tokenManager);
     this.database = new Database(this.http, this.tokenManager, config.anonKey);
+    this.realtime = new Realtime(
+      this.http.baseUrl,
+      this.tokenManager,
+      config.anonKey,
+      config.realtime
+    );
   }
   /**
    * Escape hatch for callers that need to make custom requests against the
@@ -923,6 +1536,8 @@ var index_default = MitwayBaasClient;
   Logger,
   MitwayBaasClient,
   MitwayBaasError,
+  Realtime,
+  RealtimeChannel,
   TokenManager,
   createClient
 });