@spacelr/sdk 0.2.2 → 0.3.0

package/dist/index.js

@@ -30,6 +30,7 @@ __export(index_exports, {
   SpacelrEmailVerificationRequiredError: () => SpacelrEmailVerificationRequiredError,
   SpacelrError: () => SpacelrError,
   SpacelrNetworkError: () => SpacelrNetworkError,
+  SpacelrSearchFilterRequiredError: () => SpacelrSearchFilterRequiredError,
   SpacelrTimeoutError: () => SpacelrTimeoutError,
   SpacelrTwoFactorRequiredError: () => SpacelrTwoFactorRequiredError,
   createClient: () => createClient,
@@ -84,6 +85,14 @@ var SpacelrTwoFactorRequiredError = class extends SpacelrError {
     this.twoFactorToken = twoFactorToken;
   }
 };
+var SpacelrSearchFilterRequiredError = class extends SpacelrError {
+  constructor(message, details) {
+    super(message, "SEARCH_FILTER_REQUIRED", 400, details);
+    this.name = "SpacelrSearchFilterRequiredError";
+    const fields = details?.["missingFields"];
+    this.missingFields = Array.isArray(fields) ? fields.filter((f) => typeof f === "string") : [];
+  }
+};
 var SpacelrEmailVerificationRequiredError = class extends SpacelrError {
   constructor(emailSent, details) {
     super(
@@ -112,7 +121,25 @@ var HttpClient = class {
     const timeout = this.config.timeout ?? 3e4;
     const includeCredentials = options.withCredentials ?? options.path.startsWith("/auth/");
     const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    let timeoutFired = false;
+    const timeoutId = setTimeout(() => {
+      timeoutFired = true;
+      controller.abort();
+    }, timeout);
+    let externalAbort = false;
+    let onExternalAbort;
+    if (options.signal) {
+      if (options.signal.aborted) {
+        externalAbort = true;
+        controller.abort();
+      } else {
+        onExternalAbort = () => {
+          externalAbort = true;
+          controller.abort();
+        };
+        options.signal.addEventListener("abort", onExternalAbort);
+      }
+    }
     try {
       const response = await fetch(url, {
         method: options.method,
@@ -134,6 +161,7 @@ var HttpClient = class {
     } catch (error) {
       if (error instanceof SpacelrError) throw error;
       if (error instanceof DOMException && error.name === "AbortError") {
+        if (externalAbort && !timeoutFired) throw error;
         throw new SpacelrTimeoutError(timeout);
       }
       throw new SpacelrNetworkError(
@@ -141,6 +169,9 @@ var HttpClient = class {
       );
     } finally {
       clearTimeout(timeoutId);
+      if (options.signal && onExternalAbort) {
+        options.signal.removeEventListener("abort", onExternalAbort);
+      }
     }
   }
   async uploadForm(path, formData, onProgress) {
@@ -311,6 +342,12 @@ var HttpClient = class {
     const message = apiBody.error?.message ?? `HTTP ${statusCode}`;
     const code = apiBody.error?.code ?? `HTTP_${statusCode}`;
     const details = apiBody.error?.details;
+    const flatBody = body;
+    if (statusCode === 400 && flatBody["errorCode"] === "SEARCH_FILTER_REQUIRED") {
+      const flatMessage = typeof flatBody["message"] === "string" ? flatBody["message"] : message;
+      const missingFields = Array.isArray(flatBody["missingFields"]) ? flatBody["missingFields"] : [];
+      throw new SpacelrSearchFilterRequiredError(flatMessage, { missingFields });
+    }
     if (statusCode === 401 || statusCode === 403) {
       throw new SpacelrAuthError(message, statusCode, details);
     }
@@ -666,6 +703,67 @@ var RealtimeClient = class {
    * event rather than the originally-subscribed `sinceId`.
    */
   async subscribeWithCursor(options) {
+    const { unsubscribe } = await this._subscribeInternal(options);
+    return unsubscribe;
+  }
+  /**
+   * Metadata-aware variant of `subscribeWithCursor()` — see #99.
+   *
+   * Identical to `subscribeWithCursor` except it also returns the
+   * `realtimeMode` and `latestStreamId` from the server's
+   * subscribe-events ack so callers (notably `subscribeWithSnapshot`)
+   * can fail-fast on pubsub-mode collections and anchor the snapshot
+   * baseline atomically with the reader-attach.
+   *
+   * Defaults: if the server didn't send `realtimeMode` (older
+   * gateway), the SDK treats the collection as pubsub-mode so
+   * downstream fail-fasts still fire correctly. `latestStreamId`
+   * defaults to `null` when absent.
+   *
+   * Dedup-path note: when a sibling local subscription already holds
+   * the server-side reader slot for this streamKey, no new handshake
+   * is emitted — the SDK piggy-backs on the existing slot. In that
+   * case we synthesise `{ realtimeMode: 'stream', latestStreamId: null }`
+   * because the existing slot's prior ack is no longer available.
+   * Callers that need a fresh `latestStreamId` (e.g. snapshot anchor)
+   * MUST handle the `null` case.
+   */
+  async subscribeWithCursorWithMeta(options) {
+    const { unsubscribe, ack } = await this._subscribeInternal(options);
+    return {
+      unsubscribe,
+      // Default to pubsub if the server didn't send the field — older
+      // gateways that haven't been updated yet are treated as pubsub-mode
+      // so the SDK helper's fail-fast still fires correctly.
+      realtimeMode: ack.realtimeMode ?? "pubsub",
+      latestStreamId: ack.latestStreamId ?? null
+    };
+  }
+  /**
+   * Shared body for `subscribeWithCursor` and
+   * `subscribeWithCursorWithMeta`. Owns the handshake, dedup path,
+   * pre-ack registration, and error eviction. Returns the unsubscribe
+   * function plus the subscribe-events ack so metadata-aware callers
+   * can read `realtimeMode` / `latestStreamId`.
+   *
+   * Behaviour-preserving contract — DO NOT change without re-running
+   * the singleflight tests in `realtime.spec.ts`:
+   *
+   * 1. Dedup branch BEFORE registration: if a sibling subscriber for
+   *    this streamKey is already registered, the new caller piggy-backs
+   *    on its server-side slot. Re-emitting the handshake here would
+   *    tear the prior subscriber's reader down.
+   * 2. Registration BEFORE handshake: `streamSubscriptions.set` must
+   *    fire before `emitSubscribeEvents` so replay/event-gap frames
+   *    delivered DURING the handshake fanout find this subscriber.
+   * 3. evictStreamKey on ack-error MUST sweep dedup-path siblings:
+   *    they have no independent server-side state and would silently
+   *    miss every event until the next full reconnect.
+   * 4. The catch block is a safety net for the re-thrown ack-error
+   *    only — `emitSubscribeEvents` itself always resolves, so this
+   *    catch should never fire on the success path.
+   */
+  async _subscribeInternal(options) {
     this.ensureWakeListeners();
     if (this.connectionState === "disconnected") {
       this.setConnectionState("reconnecting");
@@ -681,7 +779,15 @@ var RealtimeClient = class {
     const existing = this.streamSubscriptions.get(streamKey);
     if (existing && existing.size > 0) {
       existing.add(state);
-      return () => this.unsubscribeStream(state);
+      const syntheticAck = {
+        subscribed: streamKey,
+        realtimeMode: "stream",
+        latestStreamId: null
+      };
+      return {
+        unsubscribe: () => this.unsubscribeStream(state),
+        ack: syntheticAck
+      };
     }
     const set = /* @__PURE__ */ new Set();
     set.add(state);
@@ -690,12 +796,15 @@ var RealtimeClient = class {
       const ack = await this.emitSubscribeEvents(state);
       if (ack.error) {
         const message = ack.message ?? ack.error;
-        const err = new Error(message);
+        const err = new SpacelrError(message, ack.error);
         this.evictStreamKey(streamKey, err, state);
         options.onError?.(err);
         throw err;
       }
-      return () => this.unsubscribeStream(state);
+      return {
+        unsubscribe: () => this.unsubscribeStream(state),
+        ack
+      };
     } catch (err) {
       const error = err instanceof Error ? err : new Error(String(err));
       this.evictStreamKey(streamKey, error, state);
@@ -774,6 +883,7 @@ var RealtimeClient = class {
     const wsUrl = this.config.baseUrl.replace(/\/api\/v\d+\/?$/, "");
     return new Promise((resolve, reject) => {
       let initialConnect = true;
+      let onInitialDisconnect = null;
       this.socket = (0, import_socket.io)(`${wsUrl}/database`, {
         auth: async (cb) => {
           try {
@@ -784,8 +894,11 @@ var RealtimeClient = class {
           }
         },
         transports: ["websocket"],
+        // Disable auto-reconnect for the INITIAL connect — caller's promise
+        // rejects on connect_error and they decide whether to retry. Once the
+        // first authentication succeeds we re-enable it via the Manager's
+        // setters (see authenticated handler).
         reconnection: false
-        // Disabled until first successful connect
       });
       this.socket.on("authenticated", () => {
         if (this.disposed) return;
@@ -793,10 +906,32 @@ var RealtimeClient = class {
         if (initialConnect) {
           initialConnect = false;
           if (this.socket) {
-            this.socket.io.opts.reconnection = true;
-            this.socket.io.opts.reconnectionDelay = 1e3;
-            this.socket.io.opts.reconnectionDelayMax = 5e3;
-            this.socket.io.opts.reconnectionAttempts = 50;
+            const manager = this.socket.io;
+            try {
+              manager.reconnection(true);
+              manager.skipReconnect = false;
+              manager.reconnectionDelay(1e3);
+              manager.reconnectionDelayMax(5e3);
+              manager.reconnectionAttempts(50);
+            } catch (err) {
+              if (onInitialDisconnect && this.socket) {
+                this.socket.off("disconnect", onInitialDisconnect);
+                onInitialDisconnect = null;
+              }
+              this.socket?.disconnect();
+              this.socket = null;
+              this.setConnectionState("disconnected");
+              reject(
+                new Error(
+                  `socket.io-client Manager reconnection setters failed \u2014 internal API may have changed; auto-reconnect cannot be enabled. Check socket.io-client version compatibility. Underlying error: ${err instanceof Error ? err.message : String(err)}`
+                )
+              );
+              return;
+            }
+          }
+          if (onInitialDisconnect && this.socket) {
+            this.socket.off("disconnect", onInitialDisconnect);
+            onInitialDisconnect = null;
           }
           if (this.config.onTokenRefreshed && !this.unsubscribeFromTokenRefreshed) {
             this.unsubscribeFromTokenRefreshed = this.config.onTokenRefreshed(
@@ -816,6 +951,14 @@ var RealtimeClient = class {
           reject(new Error(`WebSocket connection failed: ${err.message}`));
         }
       });
+      onInitialDisconnect = (reason) => {
+        if (!initialConnect) return;
+        this.socket?.disconnect();
+        this.socket = null;
+        this.setConnectionState("disconnected");
+        reject(new Error(`WebSocket disconnected during handshake: ${reason}`));
+      };
+      this.socket.on("disconnect", onInitialDisconnect);
       this.socket.io.on("reconnect_failed", () => {
         void this.rebuildSocket();
       });
@@ -853,9 +996,10 @@ var RealtimeClient = class {
         }
       });
       this.socket.on("disconnect", () => {
-        if (!this.disposed) {
-          this.setConnectionState("reconnecting");
-        }
+        if (this.disposed) return;
+        if (initialConnect) return;
+        if (!this.socket) return;
+        this.setConnectionState("reconnecting");
       });
     });
   }
@@ -1053,7 +1197,7 @@ var RealtimeClient = class {
     try {
       const ack = await this.emitSubscribeEvents(primary);
       if (ack.error) {
-        const err = new Error(ack.message ?? ack.error);
+        const err = new SpacelrError(ack.message ?? ack.error, ack.error);
         for (const state of [...set]) {
           state.options.onError?.(err);
         }
@@ -1805,7 +1949,13 @@ var QueryBuilder = class {
     this._populate.push({ field, collection, foreignField });
     return this;
   }
-  async execute() {
+  /**
+   * `signal` is an optional external AbortSignal forwarded into the underlying
+   * HTTP request. Used by `subscribeWithSnapshot` so that an unsubscribe()
+   * call cancels the in-flight snapshot find(); regular callers can leave it
+   * undefined.
+   */
+  async execute(signal) {
     const query = {};
     if (this._filter) query["filter"] = JSON.stringify(this._filter);
     if (this._sort) query["sort"] = JSON.stringify(this._sort);
@@ -1823,7 +1973,8 @@ var QueryBuilder = class {
       method: "GET",
       path: this.basePath,
       query,
-      authenticated: true
+      authenticated: true,
+      signal
     });
   }
 };
@@ -1876,6 +2027,13 @@ var CollectionRef = class {
    * cannot use a standard B-tree index — on very large collections consider
    * narrowing with `filter` to scope the scan.
    *
+   * Required filters: collections may declare `searchConfig.requireFilter`
+   * via the admin API. Calls without those keys at the top level of `filter`
+   * (or inside a top-level `$and`) reject with
+   * `SpacelrSearchFilterRequiredError` carrying `missingFields`. Allowed
+   * shapes: `{ field: value }`, `{ field: { $eq: value } }`,
+   * `{ field: { $in: [...] } }` (non-empty).
+   *
    * Limits: `query` 1–200 chars, `fields` 1–10 entries (each matching
    * `/^[a-zA-Z0-9_.]+$/`, max 64 chars), `limit` max 100.
    */
@@ -2060,6 +2218,291 @@ var CollectionRef = class {
       }
     };
   }
+  /**
+   * Snapshot-aware subscribe — see #99 / SubscribeWithSnapshotOptions.
+   *
+   * Returns a Promise that resolves with the unsubscribe function only
+   * after the first `onSnapshot` has run to completion (initial-load
+   * signal). Calling unsubscribe() while the snapshot find() is in flight
+   * aborts the request and silences the AbortError. Gap-recovery state
+   * machine lands in Task 6.
+   */
+  async subscribeWithSnapshot(opts) {
+    if (!this.realtime) {
+      throw new Error("Realtime not available: no RealtimeClient configured");
+    }
+    let isActive = true;
+    let currentUnsubscribe = null;
+    let snapshotAbort = new AbortController();
+    let recoveryState = "idle";
+    const realtime = this.realtime;
+    const streamWhere = (() => {
+      if (!opts.where) return void 0;
+      const out = {};
+      for (const [k, v] of Object.entries(opts.where)) {
+        if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") {
+          out[k] = v;
+        }
+      }
+      return Object.keys(out).length > 0 ? out : void 0;
+    })();
+    if (opts.where && streamWhere === void 0 && Object.keys(opts.where).length > 0) {
+      console.warn(
+        `[spacelr] subscribeWithSnapshot on ${this.projectId}:${this.collectionName}: 'where' filter contains only operator-shaped values (e.g. $gt, $in) which are not supported by the live stream filter. onChange will receive ALL collection events; snapshot is still filtered.`
+      );
+    }
+    const runRecovery = async () => {
+      currentUnsubscribe?.();
+      currentUnsubscribe = null;
+      if (!isActive) return;
+      let recoveryAckResolved = false;
+      let recoverySnapshotDelivered = false;
+      const pendingRecoveryEvents = [];
+      let next;
+      try {
+        next = await realtime.subscribeWithCursorWithMeta({
+          projectId: this.projectId,
+          collectionName: this.collectionName,
+          sinceId: void 0,
+          where: streamWhere,
+          onEvent: async ({ event }) => {
+            if (!isActive) return;
+            if (!recoverySnapshotDelivered) {
+              pendingRecoveryEvents.push(event);
+              return;
+            }
+            await opts.onChange(event);
+          },
+          onError: (err) => {
+            if (!isActive) return;
+            if (!recoveryAckResolved) return;
+            isActive = false;
+            currentUnsubscribe?.();
+            currentUnsubscribe = null;
+            snapshotAbort.abort();
+            opts.onError?.(err);
+          },
+          onGap: handleGap
+        });
+        recoveryAckResolved = true;
+      } catch (err) {
+        if (!isActive) return;
+        opts.onError?.(err instanceof Error ? err : new Error(String(err)));
+        return;
+      }
+      if (!isActive) {
+        next.unsubscribe();
+        return;
+      }
+      currentUnsubscribe = next.unsubscribe;
+      snapshotAbort = new AbortController();
+      let recoveryDocs;
+      try {
+        const builder = this.find(opts.where);
+        if (opts.sort) builder.sort(opts.sort);
+        if (opts.limit !== void 0) builder.limit(opts.limit);
+        if (opts.select) builder.select(opts.select);
+        const result = await builder.execute(snapshotAbort.signal);
+        recoveryDocs = result.documents;
+      } catch (err) {
+        if (!isActive) return;
+        if (err instanceof DOMException && err.name === "AbortError") return;
+        currentUnsubscribe?.();
+        currentUnsubscribe = null;
+        isActive = false;
+        const error = err instanceof Error ? err : new Error(String(err));
+        if (opts.onSnapshotError) opts.onSnapshotError(error);
+        else opts.onError?.(error);
+        return;
+      }
+      if (!isActive) return;
+      try {
+        await opts.onSnapshot(recoveryDocs, next.latestStreamId);
+      } catch (err) {
+        currentUnsubscribe?.();
+        currentUnsubscribe = null;
+        isActive = false;
+        const error = err instanceof Error ? err : new Error(String(err));
+        opts.onError?.(error);
+        return;
+      }
+      while (true) {
+        if (!isActive) return;
+        if (pendingRecoveryEvents.length === 0) {
+          recoverySnapshotDelivered = true;
+          break;
+        }
+        const ev = pendingRecoveryEvents.shift();
+        if (ev !== void 0) {
+          try {
+            await opts.onChange(ev);
+          } catch (err) {
+            currentUnsubscribe?.();
+            currentUnsubscribe = null;
+            isActive = false;
+            const error = err instanceof Error ? err : new Error(String(err));
+            opts.onError?.(error);
+            return;
+          }
+        }
+      }
+    };
+    const dispatchRecovery = () => {
+      if (!isActive) return;
+      if (recoveryState === "running") {
+        recoveryState = "pending-rerun";
+        return;
+      }
+      if (recoveryState === "pending-rerun") {
+        return;
+      }
+      recoveryState = "running";
+      void (async () => {
+        await Promise.resolve();
+        while (true) {
+          try {
+            await runRecovery();
+          } catch (err) {
+            recoveryState = "idle";
+            if (!isActive) return;
+            const error = err instanceof Error ? err : new Error(String(err));
+            try {
+              opts.onError?.(error);
+            } catch {
+            }
+            return;
+          }
+          if (!isActive) {
+            recoveryState = "idle";
+            return;
+          }
+          if (recoveryState === "pending-rerun") {
+            recoveryState = "running";
+            continue;
+          }
+          recoveryState = "idle";
+          return;
+        }
+      })();
+    };
+    const handleGap = (info) => {
+      if (!isActive) return;
+      if (info.reason !== "outside-retention-window") return;
+      dispatchRecovery();
+    };
+    let subscribeAckResolved = false;
+    let initialSnapshotDelivered = false;
+    const pendingInitialEvents = [];
+    let initial;
+    try {
+      initial = await realtime.subscribeWithCursorWithMeta({
+        projectId: this.projectId,
+        collectionName: this.collectionName,
+        sinceId: void 0,
+        where: streamWhere,
+        onEvent: async ({ event }) => {
+          if (!isActive) return;
+          if (!initialSnapshotDelivered) {
+            pendingInitialEvents.push(event);
+            return;
+          }
+          await opts.onChange(event);
+        },
+        onError: (err) => {
+          if (!isActive) return;
+          if (!subscribeAckResolved) return;
+          isActive = false;
+          snapshotAbort.abort();
+          currentUnsubscribe?.();
+          currentUnsubscribe = null;
+          opts.onError?.(err);
+        },
+        onGap: handleGap
+      });
+      subscribeAckResolved = true;
+    } catch (err) {
+      isActive = false;
+      const code = err instanceof SpacelrError ? err.code : void 0;
+      if (code === "not-stream-collection") {
+        throw new SpacelrError(
+          `subscribeWithSnapshot requires a stream-mode collection. Use subscribe() for pubsub collections.`,
+          "SUBSCRIBE_WITH_SNAPSHOT_REQUIRES_STREAM",
+          void 0,
+          { collectionName: this.collectionName }
+        );
+      }
+      throw err;
+    }
+    if (initial.realtimeMode !== "stream") {
+      isActive = false;
+      initial.unsubscribe();
+      throw new SpacelrError(
+        `subscribeWithSnapshot requires a stream-mode collection. Use subscribe() for pubsub collections.`,
+        "SUBSCRIBE_WITH_SNAPSHOT_REQUIRES_STREAM",
+        void 0,
+        { collectionName: this.collectionName }
+      );
+    }
+    currentUnsubscribe = initial.unsubscribe;
+    let snapshotDocs;
+    try {
+      const builder = this.find(opts.where);
+      if (opts.sort) builder.sort(opts.sort);
+      if (opts.limit !== void 0) builder.limit(opts.limit);
+      if (opts.select) builder.select(opts.select);
+      const result = await builder.execute(snapshotAbort.signal);
+      snapshotDocs = result.documents;
+    } catch (err) {
+      currentUnsubscribe?.();
+      isActive = false;
+      const isAbort = err instanceof DOMException && err.name === "AbortError";
+      if (isAbort) throw err;
+      const error = err instanceof Error ? err : new Error(String(err));
+      if (opts.onSnapshotError) opts.onSnapshotError(error);
+      else opts.onError?.(error);
+      throw error;
+    }
+    if (!isActive) {
+      currentUnsubscribe?.();
+      return () => void 0;
+    }
+    try {
+      await opts.onSnapshot(snapshotDocs, initial.latestStreamId);
+    } catch (err) {
+      currentUnsubscribe?.();
+      currentUnsubscribe = null;
+      isActive = false;
+      const error = err instanceof Error ? err : new Error(String(err));
+      opts.onError?.(error);
+      throw error;
+    }
+    while (true) {
+      if (!isActive) return () => void 0;
+      if (pendingInitialEvents.length === 0) {
+        initialSnapshotDelivered = true;
+        break;
+      }
+      const ev = pendingInitialEvents.shift();
+      if (ev !== void 0) {
+        try {
+          await opts.onChange(ev);
+        } catch (err) {
+          currentUnsubscribe?.();
+          currentUnsubscribe = null;
+          isActive = false;
+          const error = err instanceof Error ? err : new Error(String(err));
+          opts.onError?.(error);
+          throw error;
+        }
+      }
+    }
+    return () => {
+      if (!isActive) return;
+      isActive = false;
+      snapshotAbort.abort();
+      currentUnsubscribe?.();
+    };
+  }
 };
 var DatabaseModule = class {
   constructor(http, projectId, realtime) {
@@ -2323,6 +2766,7 @@ function createClient(config) {
   SpacelrEmailVerificationRequiredError,
   SpacelrError,
   SpacelrNetworkError,
+  SpacelrSearchFilterRequiredError,
   SpacelrTimeoutError,
   SpacelrTwoFactorRequiredError,
   createClient,