@spacelr/sdk 0.2.2 → 0.4.0

package/dist/index.d.mts

@@ -296,6 +296,15 @@ interface HttpRequestOptions {
     query?: Record<string, string | number | undefined>;
     /** Send cookies cross-origin (credentials: 'include'). Defaults to true for /auth/ paths. */
     withCredentials?: boolean;
+    /**
+     * External AbortSignal that lets callers cancel an in-flight request before
+     * the configured timeout elapses (e.g. `subscribeWithSnapshot` aborting its
+     * snapshot find() when the user calls unsubscribe()). Forwarded into the
+     * internal AbortController so cancellation surfaces as a DOMException with
+     * name 'AbortError' — the caller is responsible for distinguishing it from
+     * the timeout-driven abort if it matters.
+     */
+    signal?: AbortSignal;
 }
 declare class HttpClient {
     private config;
@@ -362,6 +371,19 @@ declare class SpacelrTwoFactorRequiredError extends SpacelrError {
     readonly twoFactorToken: string;
     constructor(twoFactorToken: string, details?: Record<string, unknown>);
 }
+/**
+ * Thrown when `collection.search()` is called without the pre-filter the
+ * collection requires (issue #165). `details.missingFields` lists the
+ * top-level filter keys the server expected.
+ *
+ * Required filters protect against unindexable full-collection regex
+ * scans on large collections — see the collection's `searchConfig` for
+ * which fields are required.
+ */
+declare class SpacelrSearchFilterRequiredError extends SpacelrError {
+    readonly missingFields: string[];
+    constructor(message: string, details?: Record<string, unknown>);
+}
 declare class SpacelrEmailVerificationRequiredError extends SpacelrError {
     readonly emailSent: boolean;
     constructor(emailSent: boolean, details?: Record<string, unknown>);
@@ -448,6 +470,58 @@ declare class RealtimeClient {
      * event rather than the originally-subscribed `sinceId`.
      */
     subscribeWithCursor(options: StreamSubscriptionOptions): Promise<() => void>;
+    /**
+     * 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.
+     */
+    subscribeWithCursorWithMeta(options: StreamSubscriptionOptions): Promise<{
+        unsubscribe: () => void;
+        realtimeMode: 'pubsub' | 'stream';
+        latestStreamId: string | 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.
+     */
+    private _subscribeInternal;
     /**
      * Tear down the realtime client permanently. After this call the instance
      * is disposed — subsequent `subscribe()` calls will not re-establish a
@@ -733,6 +807,98 @@ interface SearchOptions {
     offset?: number;
     select?: string[];
 }
+/**
+ * Options for `CollectionRef.subscribeWithSnapshot()` — see #99.
+ *
+ * The helper combines an initial query, a live stream subscription,
+ * and outside-retention-window gap recovery into one idempotent
+ * contract. Apps must implement `onChange` as state mutation keyed
+ * by `_id` (Map/Set semantics): events MAY arrive twice (snapshot
+ * vs stream overlap, gap recovery replay window, reconnect replay
+ * from persisted cursor).
+ *
+ * Performance: `onChange` is awaited; a slow handler stalls the
+ * stream for THIS subscriber. Keep it fast (synchronous state
+ * updates only).
+ *
+ * Requires a stream-mode collection. Calling on a pubsub collection
+ * throws SpacelrError with code SUBSCRIBE_WITH_SNAPSHOT_REQUIRES_STREAM
+ * BEFORE any find() runs.
+ */
+interface SubscribeWithSnapshotOptions<T> {
+    /**
+     * Filter for both the initial snapshot AND the live `onChange` stream.
+     *
+     * **Snapshot semantics** (full MongoDB query): supports operators like
+     * `{ status: { $in: [...] } }`, `{ ts: { $gt: ... } }`, etc.
+     *
+     * **Live-stream semantics** (gateway-side equality only): the stream
+     * filter only honours top-level primitive equality
+     * (`string | number | boolean` values). Operator-shaped values are
+     * silently dropped from the stream filter at handshake time — the
+     * remaining primitive entries still apply, so a typical chat-style
+     * `{ chatId: 'c1' }` filter works identically on both sides. If you
+     * pass a mixed `{ chatId: 'c1', status: { $in: [...] } }`, the
+     * snapshot is fully filtered but the live stream filters by `chatId`
+     * only; you may receive `onChange` events for documents whose `status`
+     * is outside your `$in` set. Re-check in the handler if needed.
+     */
+    where?: Record<string, unknown>;
+    sort?: Record<string, 1 | -1>;
+    limit?: number;
+    select?: string[];
+    /**
+     * Called with the full snapshot:
+     *   - once after the initial find()
+     *   - again after every gap-exceeded recovery
+     * `cursor` is the stream position at the moment the snapshot was
+     * taken — opaque, may be persisted, may be passed to a later
+     * subscribeWithCursor as sinceId. Never compare cursor strings.
+     *
+     * Note on shared readers: when another subscriber on the SAME
+     * client+collection is already active, this subscriber piggy-backs
+     * on that reader. The returned `cursor` reflects the stream tip at
+     * THIS handshake; the shared reader may already have advanced past
+     * it, so the duplicate-delivery window between this `cursor` and
+     * the next `onChange` event can be wider than a fresh single-
+     * subscriber attach. The at-least-once contract still holds —
+     * idempotent `onChange` handlers absorb the extra duplicates.
+     */
+    onSnapshot: (docs: (T & {
+        _id: string;
+    })[], cursor: string | null) => void | Promise<void>;
+    /**
+     * Per-event callback. Awaited; cursor advances after this resolves.
+     * State mutations MUST be idempotent by `_id`.
+     */
+    onChange: (event: DatabaseChangeEvent) => void | Promise<void>;
+    /**
+     * Fatal stream/subscription errors AFTER the initial handshake has
+     * resolved. Subscription is torn down. Pre-handshake failures (e.g.
+     * pubsub-mode collection, ack-error from the gateway) DO NOT fire
+     * this callback — they reject the helper's promise instead, with a
+     * typed `SpacelrError` carrying a discriminator code.
+     *
+     * If this callback itself throws, the gap-recovery state machine
+     * still resets to `'idle'`, but `onError` may be invoked a second
+     * time (with the same error) by the dispatch IIFE's safety-net
+     * catch. Keep the callback total: log, set state, return.
+     */
+    onError?: (err: Error) => void;
+    /**
+     * Snapshot read (`find()`) failed. Default: forwards to `onError`.
+     * Aborted reads (caused by `unsubscribe()`) NEVER call this — they
+     * silently reject the helper's promise with `AbortError`.
+     *
+     * **Dual-notification on non-abort failures**: a snapshot failure
+     * fires this callback AND rejects the helper's outer promise with
+     * the same error. Callers that handle both `await ...catch()` AND
+     * register `onSnapshotError` will receive the error twice — pick
+     * one path. The dual surface is intentional so apps using fire-and-
+     * forget callback handlers don't need to also wrap the await.
+     */
+    onSnapshotError?: (err: Error) => void;
+}
 interface SubscribeEventsHandlers<T = Record<string, unknown>> {
     /** Cursor to resume from. Undefined = fresh subscription, deliver only new events. */
     sinceId?: string;
@@ -919,7 +1085,13 @@ declare class QueryBuilder<T = Record<string, unknown>, M extends 'offset' | 'cu
     after(id: string): QueryBuilder<T, 'cursor'>;
     select(fields: string[]): this;
     populate(field: string, collection: string, foreignField?: string): this;
-    execute(): Promise<M extends 'cursor' ? CursorResult<T> : OffsetResult<T>>;
+    /**
+     * `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.
+     */
+    execute(signal?: AbortSignal): Promise<M extends 'cursor' ? CursorResult<T> : OffsetResult<T>>;
 }
 declare class CollectionRef<T = Record<string, unknown>> {
     private http;
@@ -955,6 +1127,13 @@ declare class CollectionRef<T = Record<string, unknown>> {
      * 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.
      */
@@ -967,6 +1146,16 @@ declare class CollectionRef<T = Record<string, unknown>> {
     count(filter?: Record<string, unknown>): Promise<number>;
     subscribe(handlers: SubscribeHandlers<T>): () => void;
     subscribeEvents(handlers: SubscribeEventsHandlers<T>): StreamSubscription;
+    /**
+     * 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.
+     */
+    subscribeWithSnapshot(opts: SubscribeWithSnapshotOptions<T>): Promise<() => void>;
 }
 declare class DatabaseModule {
     private http;
@@ -1137,4 +1326,4 @@ interface SpacelrClient {
 }
 declare function createClient(config: SpacelrClientConfig): SpacelrClient;
 
-export { type ApiResponse, type AuthLostReason, type AuthState, type AuthStateListener, type AuthorizationUrlParams, BrowserTokenStorage, CodeChallengeMethod, type ConnectionState, type CursorStorage, type DatabaseChangeEvent, type DownloadUrlResponse, type ExchangeCodeParams, type FileInfo, type FileListResponse, FileVisibility, type FunctionInvokeOptions, type FunctionInvokeResult, type GapReason, GrantType, type InitMultipartUploadParams, type InitMultipartUploadResponse, type JWK, type JWKSResponse, type ListFilesParams, type LoginParams, type LoginResponse, MemoryTokenStorage, type OpenIDConfiguration, type PKCEChallenge, type PartEtag, type PushSubscriptionInfo, type QuotaInfo, type RegisterParams, type RegisterResponse, type SearchOptions, type ShareFileParams, SharePermission, SpacelrAuthError, type SpacelrClient, type SpacelrClientConfig, SpacelrEmailVerificationRequiredError, SpacelrError, SpacelrNetworkError, SpacelrTimeoutError, SpacelrTwoFactorRequiredError, type StoredTokens, type StreamGapInfo, type StreamSubscription, type SubscribeEventsHandlers, type SubscribeHandlers, type TokenResponse, type TokenStorage, type TwoFactorResponse, type TwoFactorVerifyParams, type UnshareFileParams, type UploadFileParams, type UploadLargeFileParams, type UploadProgress, type UserInfo, type UserProfile, type VapidKeyResponse, createClient, generatePKCEChallenge, localStorageCursorStorage, memoryCursorStorage };
+export { type ApiResponse, type AuthLostReason, type AuthState, type AuthStateListener, type AuthorizationUrlParams, BrowserTokenStorage, CodeChallengeMethod, type ConnectionState, type CursorStorage, type DatabaseChangeEvent, type DownloadUrlResponse, type ExchangeCodeParams, type FileInfo, type FileListResponse, FileVisibility, type FunctionInvokeOptions, type FunctionInvokeResult, type GapReason, GrantType, type InitMultipartUploadParams, type InitMultipartUploadResponse, type JWK, type JWKSResponse, type ListFilesParams, type LoginParams, type LoginResponse, MemoryTokenStorage, type OpenIDConfiguration, type PKCEChallenge, type PartEtag, type PushSubscriptionInfo, type QuotaInfo, type RegisterParams, type RegisterResponse, type SearchOptions, type ShareFileParams, SharePermission, SpacelrAuthError, type SpacelrClient, type SpacelrClientConfig, SpacelrEmailVerificationRequiredError, SpacelrError, SpacelrNetworkError, SpacelrSearchFilterRequiredError, SpacelrTimeoutError, SpacelrTwoFactorRequiredError, type StoredTokens, type StreamGapInfo, type StreamSubscription, type SubscribeEventsHandlers, type SubscribeHandlers, type SubscribeWithSnapshotOptions, type TokenResponse, type TokenStorage, type TwoFactorResponse, type TwoFactorVerifyParams, type UnshareFileParams, type UploadFileParams, type UploadLargeFileParams, type UploadProgress, type UserInfo, type UserProfile, type VapidKeyResponse, createClient, generatePKCEChallenge, localStorageCursorStorage, memoryCursorStorage };

package/dist/index.d.ts

@@ -296,6 +296,15 @@ interface HttpRequestOptions {
     query?: Record<string, string | number | undefined>;
     /** Send cookies cross-origin (credentials: 'include'). Defaults to true for /auth/ paths. */
     withCredentials?: boolean;
+    /**
+     * External AbortSignal that lets callers cancel an in-flight request before
+     * the configured timeout elapses (e.g. `subscribeWithSnapshot` aborting its
+     * snapshot find() when the user calls unsubscribe()). Forwarded into the
+     * internal AbortController so cancellation surfaces as a DOMException with
+     * name 'AbortError' — the caller is responsible for distinguishing it from
+     * the timeout-driven abort if it matters.
+     */
+    signal?: AbortSignal;
 }
 declare class HttpClient {
     private config;
@@ -362,6 +371,19 @@ declare class SpacelrTwoFactorRequiredError extends SpacelrError {
     readonly twoFactorToken: string;
     constructor(twoFactorToken: string, details?: Record<string, unknown>);
 }
+/**
+ * Thrown when `collection.search()` is called without the pre-filter the
+ * collection requires (issue #165). `details.missingFields` lists the
+ * top-level filter keys the server expected.
+ *
+ * Required filters protect against unindexable full-collection regex
+ * scans on large collections — see the collection's `searchConfig` for
+ * which fields are required.
+ */
+declare class SpacelrSearchFilterRequiredError extends SpacelrError {
+    readonly missingFields: string[];
+    constructor(message: string, details?: Record<string, unknown>);
+}
 declare class SpacelrEmailVerificationRequiredError extends SpacelrError {
     readonly emailSent: boolean;
     constructor(emailSent: boolean, details?: Record<string, unknown>);
@@ -448,6 +470,58 @@ declare class RealtimeClient {
      * event rather than the originally-subscribed `sinceId`.
      */
     subscribeWithCursor(options: StreamSubscriptionOptions): Promise<() => void>;
+    /**
+     * 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.
+     */
+    subscribeWithCursorWithMeta(options: StreamSubscriptionOptions): Promise<{
+        unsubscribe: () => void;
+        realtimeMode: 'pubsub' | 'stream';
+        latestStreamId: string | 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.
+     */
+    private _subscribeInternal;
     /**
      * Tear down the realtime client permanently. After this call the instance
      * is disposed — subsequent `subscribe()` calls will not re-establish a
@@ -733,6 +807,98 @@ interface SearchOptions {
     offset?: number;
     select?: string[];
 }
+/**
+ * Options for `CollectionRef.subscribeWithSnapshot()` — see #99.
+ *
+ * The helper combines an initial query, a live stream subscription,
+ * and outside-retention-window gap recovery into one idempotent
+ * contract. Apps must implement `onChange` as state mutation keyed
+ * by `_id` (Map/Set semantics): events MAY arrive twice (snapshot
+ * vs stream overlap, gap recovery replay window, reconnect replay
+ * from persisted cursor).
+ *
+ * Performance: `onChange` is awaited; a slow handler stalls the
+ * stream for THIS subscriber. Keep it fast (synchronous state
+ * updates only).
+ *
+ * Requires a stream-mode collection. Calling on a pubsub collection
+ * throws SpacelrError with code SUBSCRIBE_WITH_SNAPSHOT_REQUIRES_STREAM
+ * BEFORE any find() runs.
+ */
+interface SubscribeWithSnapshotOptions<T> {
+    /**
+     * Filter for both the initial snapshot AND the live `onChange` stream.
+     *
+     * **Snapshot semantics** (full MongoDB query): supports operators like
+     * `{ status: { $in: [...] } }`, `{ ts: { $gt: ... } }`, etc.
+     *
+     * **Live-stream semantics** (gateway-side equality only): the stream
+     * filter only honours top-level primitive equality
+     * (`string | number | boolean` values). Operator-shaped values are
+     * silently dropped from the stream filter at handshake time — the
+     * remaining primitive entries still apply, so a typical chat-style
+     * `{ chatId: 'c1' }` filter works identically on both sides. If you
+     * pass a mixed `{ chatId: 'c1', status: { $in: [...] } }`, the
+     * snapshot is fully filtered but the live stream filters by `chatId`
+     * only; you may receive `onChange` events for documents whose `status`
+     * is outside your `$in` set. Re-check in the handler if needed.
+     */
+    where?: Record<string, unknown>;
+    sort?: Record<string, 1 | -1>;
+    limit?: number;
+    select?: string[];
+    /**
+     * Called with the full snapshot:
+     *   - once after the initial find()
+     *   - again after every gap-exceeded recovery
+     * `cursor` is the stream position at the moment the snapshot was
+     * taken — opaque, may be persisted, may be passed to a later
+     * subscribeWithCursor as sinceId. Never compare cursor strings.
+     *
+     * Note on shared readers: when another subscriber on the SAME
+     * client+collection is already active, this subscriber piggy-backs
+     * on that reader. The returned `cursor` reflects the stream tip at
+     * THIS handshake; the shared reader may already have advanced past
+     * it, so the duplicate-delivery window between this `cursor` and
+     * the next `onChange` event can be wider than a fresh single-
+     * subscriber attach. The at-least-once contract still holds —
+     * idempotent `onChange` handlers absorb the extra duplicates.
+     */
+    onSnapshot: (docs: (T & {
+        _id: string;
+    })[], cursor: string | null) => void | Promise<void>;
+    /**
+     * Per-event callback. Awaited; cursor advances after this resolves.
+     * State mutations MUST be idempotent by `_id`.
+     */
+    onChange: (event: DatabaseChangeEvent) => void | Promise<void>;
+    /**
+     * Fatal stream/subscription errors AFTER the initial handshake has
+     * resolved. Subscription is torn down. Pre-handshake failures (e.g.
+     * pubsub-mode collection, ack-error from the gateway) DO NOT fire
+     * this callback — they reject the helper's promise instead, with a
+     * typed `SpacelrError` carrying a discriminator code.
+     *
+     * If this callback itself throws, the gap-recovery state machine
+     * still resets to `'idle'`, but `onError` may be invoked a second
+     * time (with the same error) by the dispatch IIFE's safety-net
+     * catch. Keep the callback total: log, set state, return.
+     */
+    onError?: (err: Error) => void;
+    /**
+     * Snapshot read (`find()`) failed. Default: forwards to `onError`.
+     * Aborted reads (caused by `unsubscribe()`) NEVER call this — they
+     * silently reject the helper's promise with `AbortError`.
+     *
+     * **Dual-notification on non-abort failures**: a snapshot failure
+     * fires this callback AND rejects the helper's outer promise with
+     * the same error. Callers that handle both `await ...catch()` AND
+     * register `onSnapshotError` will receive the error twice — pick
+     * one path. The dual surface is intentional so apps using fire-and-
+     * forget callback handlers don't need to also wrap the await.
+     */
+    onSnapshotError?: (err: Error) => void;
+}
 interface SubscribeEventsHandlers<T = Record<string, unknown>> {
     /** Cursor to resume from. Undefined = fresh subscription, deliver only new events. */
     sinceId?: string;
@@ -919,7 +1085,13 @@ declare class QueryBuilder<T = Record<string, unknown>, M extends 'offset' | 'cu
     after(id: string): QueryBuilder<T, 'cursor'>;
     select(fields: string[]): this;
     populate(field: string, collection: string, foreignField?: string): this;
-    execute(): Promise<M extends 'cursor' ? CursorResult<T> : OffsetResult<T>>;
+    /**
+     * `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.
+     */
+    execute(signal?: AbortSignal): Promise<M extends 'cursor' ? CursorResult<T> : OffsetResult<T>>;
 }
 declare class CollectionRef<T = Record<string, unknown>> {
     private http;
@@ -955,6 +1127,13 @@ declare class CollectionRef<T = Record<string, unknown>> {
      * 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.
      */
@@ -967,6 +1146,16 @@ declare class CollectionRef<T = Record<string, unknown>> {
     count(filter?: Record<string, unknown>): Promise<number>;
     subscribe(handlers: SubscribeHandlers<T>): () => void;
     subscribeEvents(handlers: SubscribeEventsHandlers<T>): StreamSubscription;
+    /**
+     * 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.
+     */
+    subscribeWithSnapshot(opts: SubscribeWithSnapshotOptions<T>): Promise<() => void>;
 }
 declare class DatabaseModule {
     private http;
@@ -1137,4 +1326,4 @@ interface SpacelrClient {
 }
 declare function createClient(config: SpacelrClientConfig): SpacelrClient;
 
-export { type ApiResponse, type AuthLostReason, type AuthState, type AuthStateListener, type AuthorizationUrlParams, BrowserTokenStorage, CodeChallengeMethod, type ConnectionState, type CursorStorage, type DatabaseChangeEvent, type DownloadUrlResponse, type ExchangeCodeParams, type FileInfo, type FileListResponse, FileVisibility, type FunctionInvokeOptions, type FunctionInvokeResult, type GapReason, GrantType, type InitMultipartUploadParams, type InitMultipartUploadResponse, type JWK, type JWKSResponse, type ListFilesParams, type LoginParams, type LoginResponse, MemoryTokenStorage, type OpenIDConfiguration, type PKCEChallenge, type PartEtag, type PushSubscriptionInfo, type QuotaInfo, type RegisterParams, type RegisterResponse, type SearchOptions, type ShareFileParams, SharePermission, SpacelrAuthError, type SpacelrClient, type SpacelrClientConfig, SpacelrEmailVerificationRequiredError, SpacelrError, SpacelrNetworkError, SpacelrTimeoutError, SpacelrTwoFactorRequiredError, type StoredTokens, type StreamGapInfo, type StreamSubscription, type SubscribeEventsHandlers, type SubscribeHandlers, type TokenResponse, type TokenStorage, type TwoFactorResponse, type TwoFactorVerifyParams, type UnshareFileParams, type UploadFileParams, type UploadLargeFileParams, type UploadProgress, type UserInfo, type UserProfile, type VapidKeyResponse, createClient, generatePKCEChallenge, localStorageCursorStorage, memoryCursorStorage };
+export { type ApiResponse, type AuthLostReason, type AuthState, type AuthStateListener, type AuthorizationUrlParams, BrowserTokenStorage, CodeChallengeMethod, type ConnectionState, type CursorStorage, type DatabaseChangeEvent, type DownloadUrlResponse, type ExchangeCodeParams, type FileInfo, type FileListResponse, FileVisibility, type FunctionInvokeOptions, type FunctionInvokeResult, type GapReason, GrantType, type InitMultipartUploadParams, type InitMultipartUploadResponse, type JWK, type JWKSResponse, type ListFilesParams, type LoginParams, type LoginResponse, MemoryTokenStorage, type OpenIDConfiguration, type PKCEChallenge, type PartEtag, type PushSubscriptionInfo, type QuotaInfo, type RegisterParams, type RegisterResponse, type SearchOptions, type ShareFileParams, SharePermission, SpacelrAuthError, type SpacelrClient, type SpacelrClientConfig, SpacelrEmailVerificationRequiredError, SpacelrError, SpacelrNetworkError, SpacelrSearchFilterRequiredError, SpacelrTimeoutError, SpacelrTwoFactorRequiredError, type StoredTokens, type StreamGapInfo, type StreamSubscription, type SubscribeEventsHandlers, type SubscribeHandlers, type SubscribeWithSnapshotOptions, type TokenResponse, type TokenStorage, type TwoFactorResponse, type TwoFactorVerifyParams, type UnshareFileParams, type UploadFileParams, type UploadLargeFileParams, type UploadProgress, type UserInfo, type UserProfile, type VapidKeyResponse, createClient, generatePKCEChallenge, localStorageCursorStorage, memoryCursorStorage };