@spacelr/sdk 0.1.10 → 0.2.0

package/dist/index.mjs

@@ -543,6 +543,13 @@ async function generatePKCEChallenge() {
 // libs/sdk/src/core/realtime.ts
 import { io } from "socket.io-client";
 var REBUILD_RETRY_DELAY_MS = 5e3;
+var PERMANENT_STREAM_ACK_ERRORS = /* @__PURE__ */ new Set([
+  "not-stream-collection",
+  "Collection not found",
+  "Invalid sinceId format",
+  "Not a member of this project",
+  "Subscribe denied"
+]);
 var RealtimeClient = class {
   constructor(config) {
     this.socket = null;
@@ -563,6 +570,7 @@ var RealtimeClient = class {
     this.rebuildRetryTimer = null;
     this.connectionState = "disconnected";
     this.connectionStateListeners = /* @__PURE__ */ new Set();
+    this.streamSubscriptions = /* @__PURE__ */ new Map();
     this.config = config;
   }
   async subscribe(projectId, collectionName, callback, onError, where) {
@@ -611,6 +619,53 @@ var RealtimeClient = class {
       }
     };
   }
+  /**
+   * Subscribe to a stream-mode collection using Redis Streams replay +
+   * cursor-based delivery. Parallel to `subscribe()` (which targets
+   * pubsub-mode collections). The server validates that the collection is
+   * configured in stream mode and rejects the handshake otherwise.
+   *
+   * The per-subscription cursor (`lastDeliveredId`) advances after each
+   * `onEvent` promise resolves, so reconnects resume from the last delivered
+   * event rather than the originally-subscribed `sinceId`.
+   */
+  async subscribeWithCursor(options) {
+    this.ensureWakeListeners();
+    if (this.connectionState === "disconnected") {
+      this.setConnectionState("reconnecting");
+    }
+    await this.ensureConnected();
+    const streamKey = `stream:${options.projectId}:${options.collectionName}`;
+    const state = {
+      options,
+      lastDeliveredId: options.sinceId ?? null,
+      streamKey,
+      dispatchQueue: Promise.resolve()
+    };
+    const existing = this.streamSubscriptions.get(streamKey);
+    if (existing && existing.size > 0) {
+      existing.add(state);
+      return () => this.unsubscribeStream(state);
+    }
+    const set = /* @__PURE__ */ new Set();
+    set.add(state);
+    this.streamSubscriptions.set(streamKey, set);
+    try {
+      const ack = await this.emitSubscribeEvents(state);
+      if (ack.error) {
+        const message = ack.message ?? ack.error;
+        const err = new Error(message);
+        this.evictStreamKey(streamKey, err, state);
+        options.onError?.(err);
+        throw err;
+      }
+      return () => this.unsubscribeStream(state);
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      this.evictStreamKey(streamKey, error, state);
+      throw error;
+    }
+  }
   /**
    * Tear down the realtime client permanently. After this call the instance
    * is disposed — subsequent `subscribe()` calls will not re-establish a
@@ -635,6 +690,7 @@ var RealtimeClient = class {
     }
     this.subscriptions.clear();
     this.roomWhereMap.clear();
+    this.streamSubscriptions.clear();
     this.connecting = null;
   }
   getConnectionState() {
@@ -716,6 +772,7 @@ var RealtimeClient = class {
           resolve();
         } else {
           this.resubscribeAll();
+          void this.resubscribeAllStreams();
         }
       });
       this.socket.on("connect_error", (err) => {
@@ -748,6 +805,17 @@ var RealtimeClient = class {
           }
         }
       });
+      this.socket.on("event", (payload) => {
+        this.dispatchStreamEvent(payload).catch(() => void 0);
+      });
+      this.socket.on("event-gap", (info) => {
+        const streamKey = `stream:${info.projectId}:${info.collectionName}`;
+        const set = this.streamSubscriptions.get(streamKey);
+        if (!set) return;
+        for (const state of set) {
+          state.options.onGap?.(info);
+        }
+      });
       this.socket.on("disconnect", () => {
         if (!this.disposed) {
           this.setConnectionState("reconnecting");
@@ -805,6 +873,9 @@ var RealtimeClient = class {
     if (this.subscriptions.size > 0) {
       this.resubscribeAll();
     }
+    if (this.streamSubscriptions.size > 0) {
+      void this.resubscribeAllStreams();
+    }
   }
   scheduleRebuildRetry() {
     if (this.disposed || this.rebuildRetryTimer) return;
@@ -864,8 +935,186 @@ var RealtimeClient = class {
       }
     }
   }
+  emitSubscribeEvents(state) {
+    return new Promise((resolve) => {
+      if (!this.socket) {
+        resolve({ error: "disconnected" });
+        return;
+      }
+      const socket = this.socket;
+      const onDisconnect = () => {
+        socket.off("disconnect", onDisconnect);
+        resolve({ error: "disconnected" });
+      };
+      socket.once("disconnect", onDisconnect);
+      socket.emit(
+        "subscribe-events",
+        this.buildStreamPayload(state),
+        (ack) => {
+          socket.off("disconnect", onDisconnect);
+          resolve(ack);
+        }
+      );
+    });
+  }
+  buildStreamPayload(state) {
+    const { projectId, collectionName, where } = state.options;
+    const payload = { projectId, collectionName };
+    if (state.lastDeliveredId) payload["sinceId"] = state.lastDeliveredId;
+    if (where && Object.keys(where).length > 0) payload["where"] = where;
+    return payload;
+  }
+  unsubscribeStream(state) {
+    const set = this.streamSubscriptions.get(state.streamKey);
+    if (!set) return;
+    set.delete(state);
+    if (set.size === 0) {
+      this.streamSubscriptions.delete(state.streamKey);
+      this.socket?.emit("unsubscribe-events", {
+        projectId: state.options.projectId,
+        collectionName: state.options.collectionName
+      });
+    }
+  }
+  dispatchStreamEvent(payload) {
+    if (!payload.eventId) return Promise.resolve();
+    const streamKey = `stream:${payload.projectId}:${payload.collectionName}`;
+    const set = this.streamSubscriptions.get(streamKey);
+    if (!set) return Promise.resolve();
+    const entryId = payload.eventId;
+    for (const state of set) {
+      state.dispatchQueue = state.dispatchQueue.then(async () => {
+        const liveSet = this.streamSubscriptions.get(state.streamKey);
+        if (!liveSet?.has(state)) return;
+        try {
+          await state.options.onEvent({ eventId: entryId, event: payload });
+          state.lastDeliveredId = entryId;
+        } catch (err) {
+          const error = err instanceof Error ? err : new Error(String(err));
+          try {
+            state.options.onError?.(error);
+          } catch {
+          }
+        }
+      });
+    }
+    return Promise.resolve();
+  }
+  async resubscribeAllStreams() {
+    const work = [];
+    for (const set of this.streamSubscriptions.values()) {
+      const states = Array.from(set);
+      if (states.length === 0) continue;
+      const primary = this.pickEarliestCursorState(states);
+      work.push(this.resubscribeOne(primary, set));
+    }
+    try {
+      await Promise.all(work);
+    } catch {
+    }
+  }
+  async resubscribeOne(primary, set) {
+    try {
+      const ack = await this.emitSubscribeEvents(primary);
+      if (ack.error) {
+        const err = new Error(ack.message ?? ack.error);
+        for (const state of [...set]) {
+          state.options.onError?.(err);
+        }
+        if (PERMANENT_STREAM_ACK_ERRORS.has(ack.error)) {
+          this.streamSubscriptions.delete(primary.streamKey);
+        }
+        return;
+      }
+      if (!this.streamSubscriptions.has(primary.streamKey)) {
+        this.socket?.emit("unsubscribe-events", {
+          projectId: primary.options.projectId,
+          collectionName: primary.options.collectionName
+        });
+      }
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      for (const state of [...set]) {
+        state.options.onError?.(error);
+      }
+    }
+  }
+  pickEarliestCursorState(states) {
+    const parse = (id) => {
+      if (!id) return [Number.MAX_SAFE_INTEGER, Number.MAX_SAFE_INTEGER];
+      const [ms, seq = "0"] = id.split("-");
+      return [Number(ms), Number(seq)];
+    };
+    let earliest = states[0];
+    let [eMs, eSeq] = parse(earliest.lastDeliveredId);
+    for (let i = 1; i < states.length; i++) {
+      const [ms, seq] = parse(states[i].lastDeliveredId);
+      if (ms < eMs || ms === eMs && seq < eSeq) {
+        earliest = states[i];
+        eMs = ms;
+        eSeq = seq;
+      }
+    }
+    return earliest;
+  }
+  /**
+   * Evict the primary subscriber AND every sibling that joined the same
+   * streamKey via the dedup path. Fires `onError` on all siblings, then
+   * removes the entire streamKey entry from `streamSubscriptions`.
+   */
+  evictStreamKey(streamKey, err, primary) {
+    const set = this.streamSubscriptions.get(streamKey);
+    if (!set) return;
+    for (const sibling of [...set]) {
+      if (sibling !== primary) {
+        sibling.options.onError?.(err);
+      }
+      set.delete(sibling);
+    }
+    this.streamSubscriptions.delete(streamKey);
+  }
 };
 
+// libs/sdk/src/core/cursor-storage.ts
+function memoryCursorStorage() {
+  const store = /* @__PURE__ */ new Map();
+  return {
+    load(key) {
+      return store.get(key) ?? null;
+    },
+    save(key, cursor) {
+      store.set(key, cursor);
+    }
+  };
+}
+function localStorageCursorStorage(prefix = "spacelr:cursor:") {
+  const storage = (() => {
+    try {
+      const candidate = globalThis.localStorage;
+      return typeof candidate === "undefined" ? null : candidate;
+    } catch {
+      return null;
+    }
+  })();
+  return {
+    load(key) {
+      if (!storage) return null;
+      try {
+        return storage.getItem(prefix + key);
+      } catch {
+        return null;
+      }
+    },
+    save(key, cursor) {
+      if (!storage) return;
+      try {
+        storage.setItem(prefix + key, cursor);
+      } catch {
+      }
+    }
+  };
+}
+
 // libs/sdk/src/modules/auth.module.ts
 var AuthModule = class {
   constructor(http, tokenManager, config) {
@@ -1410,6 +1659,46 @@ var QueryBuilder = class {
     this._offset = offset;
     return this;
   }
+  /**
+   * **Constraint:** the cursor value must be a 24-hex ObjectId string.
+   * Collections using custom non-ObjectId `_id` strings will not work
+   * correctly with cursor pagination — the server's `$lt`/`$gt` comparison
+   * uses BSON type ordering, mixing string `_id`s with ObjectId comparison
+   * produces undefined behaviour. Documented limitation; future work may
+   * add opaque cursor tokens that abstract over `_id` types.
+   *
+   * Switch to cursor-pagination mode: return documents with `_id < id`
+   * (in the sort-defined order). The cursor refers to the cursor *value*,
+   * not visual UI direction. Requires `.sort()` to be `{ _id: 1 }` or
+   * `{ _id: -1 }` (or omitted — server defaults to `{ _id: 1 }`).
+   *
+   * Narrows the builder's mode parameter so subsequent `.execute()` returns
+   * a `CursorResult<T>` instead of `OffsetResult<T>`.
+   *
+   * **For paginating further:** the `nextCursor` field returned by
+   * `execute()` is the `_id` of the last document on the page. To load the
+   * next older page, pass it again to `.before()`. (Do NOT pass it to
+   * `.after()` — that would request docs newer than this page.)
+   *
+   * **Cannot be combined with `.offset()`.** Type system allows the chain
+   * for ergonomics, but the server rejects it with HTTP 400.
+   */
+  before(id) {
+    this._before = id;
+    return this;
+  }
+  /**
+   * Switch to cursor-pagination mode: return documents with `_id > id`.
+   * See `.before()` for full semantics — including the ObjectId-only cursor
+   * constraint and the `.offset()` incompatibility (server-enforced 400).
+   *
+   * **For paginating further:** pass the returned `nextCursor` to
+   * `.after()` again to load the next newer page.
+   */
+  after(id) {
+    this._after = id;
+    return this;
+  }
   select(fields) {
     this._fields = fields;
     return this;
@@ -1424,6 +1713,8 @@ var QueryBuilder = class {
     if (this._sort) query["sort"] = JSON.stringify(this._sort);
     if (this._limit !== void 0) query["limit"] = this._limit;
     if (this._offset !== void 0) query["offset"] = this._offset;
+    if (this._before !== void 0) query["before"] = this._before;
+    if (this._after !== void 0) query["after"] = this._after;
     if (this._fields) query["fields"] = this._fields.join(",");
     if (this._populate.length) {
       query["populate"] = this._populate.map(
@@ -1566,6 +1857,97 @@ var CollectionRef = class {
       }
     };
   }
+  subscribeEvents(handlers) {
+    if (!this.realtime) {
+      throw new Error("Realtime not available: no RealtimeClient configured");
+    }
+    let lastCursor;
+    let unsub = null;
+    let unsubscribed = false;
+    const cursorStorage = handlers.cursorStorage;
+    const cursorKey = handlers.cursorKey ?? `${this.projectId}:${this.collectionName}`;
+    if (cursorStorage && handlers.where && Object.keys(handlers.where).length > 0 && handlers.cursorKey === void 0) {
+      console.warn(
+        `[spacelr] subscribeEvents on ${this.projectId}:${this.collectionName} uses a 'where' filter with cursorStorage but no explicit cursorKey \u2014 filtered subscriptions sharing the default key will silently skip events across reconnects. Pass a unique cursorKey (e.g. include a hash of the filter).`
+      );
+    }
+    const realtime = this.realtime;
+    let lastSavePromise = Promise.resolve();
+    const onEvent = async ({
+      eventId,
+      event
+    }) => {
+      try {
+        if (event.type === "insert" && handlers.onInsert && event.document) {
+          await handlers.onInsert({
+            ...event.document,
+            _eventId: eventId
+          });
+        } else if (event.type === "update" && handlers.onUpdate && event.document) {
+          await handlers.onUpdate({
+            ...event.document,
+            _eventId: eventId
+          });
+        } else if (event.type === "delete" && handlers.onDelete) {
+          await handlers.onDelete(event.documentId, eventId);
+        }
+        lastCursor = eventId;
+        if (cursorStorage) {
+          lastSavePromise = lastSavePromise.then(
+            () => cursorStorage.save(cursorKey, eventId),
+            () => cursorStorage.save(cursorKey, eventId)
+          ).catch((err) => {
+            handlers.onError?.(err instanceof Error ? err : new Error(String(err)));
+          });
+        }
+      } catch (err) {
+        throw err instanceof Error ? err : new Error(String(err));
+      }
+    };
+    const callSubscribe = (sinceId) => realtime.subscribeWithCursor({
+      projectId: this.projectId,
+      collectionName: this.collectionName,
+      sinceId,
+      where: handlers.where,
+      onEvent,
+      onGap: handlers.onGap,
+      onError: handlers.onError
+    });
+    let promise;
+    if (handlers.sinceId !== void 0 || !cursorStorage) {
+      promise = callSubscribe(handlers.sinceId);
+    } else {
+      promise = (async () => {
+        let resumeFrom;
+        try {
+          const loaded = await Promise.resolve(cursorStorage.load(cursorKey));
+          if (loaded) resumeFrom = loaded;
+        } catch (err) {
+          handlers.onError?.(err instanceof Error ? err : new Error(String(err)));
+        }
+        return callSubscribe(resumeFrom);
+      })();
+    }
+    promise.then((u) => {
+      if (unsubscribed) {
+        u();
+      } else {
+        unsub = u;
+      }
+    }).catch(() => void 0);
+    return {
+      unsubscribe() {
+        unsubscribed = true;
+        if (unsub) {
+          unsub();
+          unsub = null;
+        }
+      },
+      getCursor() {
+        return lastCursor;
+      }
+    };
+  }
 };
 var DatabaseModule = class {
   constructor(http, projectId, realtime) {
@@ -1831,6 +2213,8 @@ export {
   SpacelrTimeoutError,
   SpacelrTwoFactorRequiredError,
   createClient,
-  generatePKCEChallenge
+  generatePKCEChallenge,
+  localStorageCursorStorage,
+  memoryCursorStorage
 };
 //# sourceMappingURL=index.mjs.map