@spacelr/sdk 0.10.0 → 0.10.2

package/dist/index.d.mts

@@ -62,6 +62,12 @@ interface RegisterResponse {
     access_token?: string;
     /** Omitted by the server when `emailVerificationRequired` is true. */
     refresh_token?: string;
+    /**
+     * Access-token lifetime in seconds. Present whenever tokens are issued
+     * (i.e. not when email verification is required). Lets the SDK store an
+     * expiry and refresh proactively instead of on the first request.
+     */
+    expires_in?: number;
     emailVerificationRequired?: boolean;
 }
 interface TokenResponse {
@@ -597,6 +603,10 @@ declare class RealtimeClient {
     private subscriptions;
     private connecting;
     private roomWhereMap;
+    private roomErrorMap;
+    private roomGeneration;
+    private subEpoch;
+    private resubscribingRooms;
     private unsubscribeFromTokenRefreshed;
     private onVisibilityChange;
     private onOnline;
@@ -606,7 +616,9 @@ declare class RealtimeClient {
     private connectionStateListeners;
     private streamSubscriptions;
     constructor(config: RealtimeConfig);
-    subscribe(projectId: string, collectionName: string, callback: (event: DatabaseChangeEvent) => void, onError?: (error: Error) => void, where?: WhereFilter): Promise<() => void>;
+    subscribe(projectId: string, collectionName: string, callback: (event: DatabaseChangeEvent) => void, onError?: (error: Error & {
+        code?: string;
+    }) => void, where?: WhereFilter): Promise<() => void>;
     /**
      * Subscribe to a stream-mode collection using Redis Streams replay +
      * cursor-based delivery. Parallel to `subscribe()` (which targets
@@ -698,6 +710,31 @@ declare class RealtimeClient {
     private ensureWakeListeners;
     private detachWakeListeners;
     private resubscribeAll;
+    /**
+     * Parse a pubsub room key back into its projectId + collectionName.
+     * Room format: `db:{projectId}:{collectionName}` or that base plus `?filter`.
+     * Returns null for anything that isn't a well-formed `db:` room.
+     */
+    private parseRoom;
+    /** Build an Error carrying the gateway's typed `errorCode` (if any) as `.code`. */
+    private toSubscribeError;
+    /** Call every subscriber's error handler registered for `room` (#661). */
+    private notifyRoomError;
+    /**
+     * Re-run the subscribe handshake for one already-tracked room. Shared by
+     * reconnect resubscription (`resubscribeAll`) and the #661
+     * `subscription-invalidated` handler.
+     *
+     * - Deduped per room via `resubscribingRooms` so the duplicate invalidation
+     *   events the gateway emits (one per evicted room) collapse to one handshake.
+     * - Snapshots the room's generation; the ack acts only if it is still current,
+     *   so a late ack cannot clobber an unsubscribe/re-subscribe that happened in
+     *   the meantime — and a success that arrives after the room was removed emits
+     *   a compensating `unsubscribe` so no ghost server room is left behind.
+     * - On a genuine denial the subscription is evicted and its stored `onError`
+     *   is called (with the typed `.code`), instead of silently going quiet.
+     */
+    private resubscribeRoom;
     private emitSubscribeEvents;
     private buildStreamPayload;
     private unsubscribeStream;

package/dist/index.d.ts

@@ -62,6 +62,12 @@ interface RegisterResponse {
     access_token?: string;
     /** Omitted by the server when `emailVerificationRequired` is true. */
     refresh_token?: string;
+    /**
+     * Access-token lifetime in seconds. Present whenever tokens are issued
+     * (i.e. not when email verification is required). Lets the SDK store an
+     * expiry and refresh proactively instead of on the first request.
+     */
+    expires_in?: number;
     emailVerificationRequired?: boolean;
 }
 interface TokenResponse {
@@ -597,6 +603,10 @@ declare class RealtimeClient {
     private subscriptions;
     private connecting;
     private roomWhereMap;
+    private roomErrorMap;
+    private roomGeneration;
+    private subEpoch;
+    private resubscribingRooms;
     private unsubscribeFromTokenRefreshed;
     private onVisibilityChange;
     private onOnline;
@@ -606,7 +616,9 @@ declare class RealtimeClient {
     private connectionStateListeners;
     private streamSubscriptions;
     constructor(config: RealtimeConfig);
-    subscribe(projectId: string, collectionName: string, callback: (event: DatabaseChangeEvent) => void, onError?: (error: Error) => void, where?: WhereFilter): Promise<() => void>;
+    subscribe(projectId: string, collectionName: string, callback: (event: DatabaseChangeEvent) => void, onError?: (error: Error & {
+        code?: string;
+    }) => void, where?: WhereFilter): Promise<() => void>;
     /**
      * Subscribe to a stream-mode collection using Redis Streams replay +
      * cursor-based delivery. Parallel to `subscribe()` (which targets
@@ -698,6 +710,31 @@ declare class RealtimeClient {
     private ensureWakeListeners;
     private detachWakeListeners;
     private resubscribeAll;
+    /**
+     * Parse a pubsub room key back into its projectId + collectionName.
+     * Room format: `db:{projectId}:{collectionName}` or that base plus `?filter`.
+     * Returns null for anything that isn't a well-formed `db:` room.
+     */
+    private parseRoom;
+    /** Build an Error carrying the gateway's typed `errorCode` (if any) as `.code`. */
+    private toSubscribeError;
+    /** Call every subscriber's error handler registered for `room` (#661). */
+    private notifyRoomError;
+    /**
+     * Re-run the subscribe handshake for one already-tracked room. Shared by
+     * reconnect resubscription (`resubscribeAll`) and the #661
+     * `subscription-invalidated` handler.
+     *
+     * - Deduped per room via `resubscribingRooms` so the duplicate invalidation
+     *   events the gateway emits (one per evicted room) collapse to one handshake.
+     * - Snapshots the room's generation; the ack acts only if it is still current,
+     *   so a late ack cannot clobber an unsubscribe/re-subscribe that happened in
+     *   the meantime — and a success that arrives after the room was removed emits
+     *   a compensating `unsubscribe` so no ghost server room is left behind.
+     * - On a genuine denial the subscription is evicted and its stored `onError`
+     *   is called (with the typed `.code`), instead of silently going quiet.
+     */
+    private resubscribeRoom;
     private emitSubscribeEvents;
     private buildStreamPayload;
     private unsubscribeStream;

package/dist/index.js

@@ -715,6 +715,21 @@ var RealtimeClient = class {
     this.connecting = null;
     // Store original where objects per room for reconnect resubscription
     this.roomWhereMap = /* @__PURE__ */ new Map();
+    // Per-room, per-callback error handlers so EVERY subscriber to a room (not
+    // just the first) is notified on a denial, and a departed subscriber's handler
+    // is never left dangling for its still-active siblings (#661).
+    this.roomErrorMap = /* @__PURE__ */ new Map();
+    // Per-room generation stamp, taken from a global monotonic counter each time a
+    // room becomes active. A re-subscribe snapshots the room's stamp and acts on
+    // the ack only if it is still current — so a late ack cannot notify or clean
+    // up after the app has unsubscribed/re-subscribed (#661). Entries are deleted
+    // on last-unsubscribe (bounded); the global counter guarantees a re-subscribe
+    // always gets a strictly higher stamp, so there is no ABA hole.
+    this.roomGeneration = /* @__PURE__ */ new Map();
+    this.subEpoch = 0;
+    // Rooms with a re-subscribe handshake in flight — dedupes the duplicate
+    // `subscription-invalidated` events the gateway emits per evicted room (#661).
+    this.resubscribingRooms = /* @__PURE__ */ new Set();
     this.unsubscribeFromTokenRefreshed = null;
     // Wake-up listeners (browser only) — recover from long OS suspends where
     // socket.io's internal reconnect loop may have already given up.
@@ -743,7 +758,17 @@ var RealtimeClient = class {
     }
     const callbacks = this.subscriptions.get(room);
     callbacks?.add(callback);
+    if (onError) {
+      let handlers = this.roomErrorMap.get(room);
+      if (!handlers) {
+        handlers = /* @__PURE__ */ new Map();
+        this.roomErrorMap.set(room, handlers);
+      }
+      handlers.set(callback, onError);
+    }
     if (callbacks?.size === 1) {
+      const generation = ++this.subEpoch;
+      this.roomGeneration.set(room, generation);
       if (where && Object.keys(where).length > 0) {
         this.roomWhereMap.set(room, where);
       }
@@ -755,8 +780,8 @@ var RealtimeClient = class {
         "subscribe",
         payload,
         (response) => {
-          if (response.error && onError) {
-            onError(new Error(response.error));
+          if (response.error && this.roomGeneration.get(room) === generation) {
+            this.notifyRoomError(room, this.toSubscribeError(response));
           }
         }
       );
@@ -765,9 +790,12 @@ var RealtimeClient = class {
       const callbacks2 = this.subscriptions.get(room);
       if (callbacks2) {
         callbacks2.delete(callback);
+        this.roomErrorMap.get(room)?.delete(callback);
         if (callbacks2.size === 0) {
           this.subscriptions.delete(room);
           this.roomWhereMap.delete(room);
+          this.roomErrorMap.delete(room);
+          this.roomGeneration.delete(room);
           const payload = { projectId, collectionName };
           if (where && Object.keys(where).length > 0) {
             payload["where"] = where;
@@ -920,6 +948,9 @@ var RealtimeClient = class {
     }
     this.subscriptions.clear();
     this.roomWhereMap.clear();
+    this.roomErrorMap.clear();
+    this.roomGeneration.clear();
+    this.resubscribingRooms.clear();
     this.streamSubscriptions.clear();
     this.connecting = null;
   }
@@ -1069,6 +1100,18 @@ var RealtimeClient = class {
           }
         }
       });
+      this.socket.on(
+        "subscription-invalidated",
+        (payload) => {
+          if (!payload?.projectId || !payload?.collectionName) return;
+          const base = `db:${payload.projectId}:${payload.collectionName}`;
+          for (const room of this.subscriptions.keys()) {
+            if (room === base || room.startsWith(`${base}?`)) {
+              this.resubscribeRoom(room);
+            }
+          }
+        }
+      );
       this.socket.on("event", (payload) => {
         this.dispatchStreamEvent(payload).catch(() => void 0);
       });
@@ -1170,31 +1213,88 @@ var RealtimeClient = class {
     this.onOnline = null;
   }
   resubscribeAll() {
+    this.resubscribingRooms.clear();
     for (const [room] of this.subscriptions) {
-      const queryIdx = room.indexOf("?");
-      const basePart = queryIdx >= 0 ? room.substring(0, queryIdx) : room;
-      const parts = basePart.split(":");
-      if (parts.length >= 3) {
-        const projectId = parts[1];
-        const collectionName = parts.slice(2).join(":");
-        const payload = { projectId, collectionName };
-        const where = this.roomWhereMap.get(room);
-        if (where) {
-          payload["where"] = where;
-        }
-        this.socket?.emit(
-          "subscribe",
-          payload,
-          (response) => {
-            if (response?.error) {
-              this.subscriptions.delete(room);
-              this.roomWhereMap.delete(room);
-            }
-          }
-        );
+      this.resubscribeRoom(room);
+    }
+  }
+  /**
+   * Parse a pubsub room key back into its projectId + collectionName.
+   * Room format: `db:{projectId}:{collectionName}` or that base plus `?filter`.
+   * Returns null for anything that isn't a well-formed `db:` room.
+   */
+  parseRoom(room) {
+    const queryIdx = room.indexOf("?");
+    const basePart = queryIdx >= 0 ? room.substring(0, queryIdx) : room;
+    const parts = basePart.split(":");
+    if (parts.length < 3 || parts[0] !== "db") return null;
+    return { projectId: parts[1], collectionName: parts.slice(2).join(":") };
+  }
+  /** Build an Error carrying the gateway's typed `errorCode` (if any) as `.code`. */
+  toSubscribeError(response) {
+    const err = new Error(response.error ?? "Subscribe denied");
+    if (response.errorCode) err.code = response.errorCode;
+    return err;
+  }
+  /** Call every subscriber's error handler registered for `room` (#661). */
+  notifyRoomError(room, error) {
+    const handlers = this.roomErrorMap.get(room);
+    if (!handlers) return;
+    for (const handler of handlers.values()) {
+      try {
+        handler(error);
+      } catch {
       }
     }
   }
+  /**
+   * Re-run the subscribe handshake for one already-tracked room. Shared by
+   * reconnect resubscription (`resubscribeAll`) and the #661
+   * `subscription-invalidated` handler.
+   *
+   * - Deduped per room via `resubscribingRooms` so the duplicate invalidation
+   *   events the gateway emits (one per evicted room) collapse to one handshake.
+   * - Snapshots the room's generation; the ack acts only if it is still current,
+   *   so a late ack cannot clobber an unsubscribe/re-subscribe that happened in
+   *   the meantime — and a success that arrives after the room was removed emits
+   *   a compensating `unsubscribe` so no ghost server room is left behind.
+   * - On a genuine denial the subscription is evicted and its stored `onError`
+   *   is called (with the typed `.code`), instead of silently going quiet.
+   */
+  resubscribeRoom(room) {
+    if (!this.socket) return;
+    if (this.resubscribingRooms.has(room)) return;
+    if (!this.subscriptions.has(room)) return;
+    const parsed = this.parseRoom(room);
+    if (!parsed) return;
+    const { projectId, collectionName } = parsed;
+    const where = this.roomWhereMap.get(room);
+    const generation = this.roomGeneration.get(room) ?? 0;
+    const payload = { projectId, collectionName };
+    if (where) payload["where"] = where;
+    this.resubscribingRooms.add(room);
+    this.socket.emit(
+      "subscribe",
+      payload,
+      (response) => {
+        this.resubscribingRooms.delete(room);
+        if ((this.roomGeneration.get(room) ?? 0) !== generation) {
+          if (!this.subscriptions.has(room) && !response?.error) {
+            this.socket?.emit("unsubscribe", payload);
+          }
+          return;
+        }
+        if (response?.error) {
+          const error = this.toSubscribeError(response);
+          this.notifyRoomError(room, error);
+          this.subscriptions.delete(room);
+          this.roomWhereMap.delete(room);
+          this.roomErrorMap.delete(room);
+          this.roomGeneration.delete(room);
+        }
+      }
+    );
+  }
   emitSubscribeEvents(state) {
     return new Promise((resolve) => {
       if (!this.socket) {
@@ -1770,9 +1870,11 @@ var AuthModule = class {
   }
   async storeTokensFromRegister(response) {
     if (!response.access_token) return;
+    const expiresAt = response.expires_in ? Math.floor(Date.now() / 1e3) + response.expires_in : void 0;
     await this.tokenManager.setTokens({
       accessToken: response.access_token,
-      refreshToken: response.refresh_token
+      refreshToken: response.refresh_token,
+      expiresAt
     });
     this.emitState("authenticated");
   }