@spacelr/sdk 0.2.1 → 0.3.0

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>);
@@ -381,28 +403,6 @@ interface DatabaseChangeEvent {
      * for pubsub-mode events. Used by function triggers as an idempotency key.
      */
     eventId?: string;
-    /**
-     * Identifies the origin of the write. Stamped on the envelope (never in the
-     * document body) so function-service can run a tamper-resistant recursion guard
-     * (internal TCP caller can spoof — see PR notes). Absent on legacy events
-     * published before this field existed.
-     */
-    _source?: 'user' | 'function';
-    /**
-     * When `_source === 'function'`, the id of the function whose runtime wrote
-     * the document. Used to skip self-chain events without blocking legitimate
-     * cross-function chains.
-     */
-    _sourceFunctionId?: string;
-    /**
-     * Hop-counter on function-originated events. User writes have no value.
-     * Each function-write increments the incoming envelope's depth by one,
-     * so an A→B→A loop bumps the counter on every hop. The reader rejects
-     * dispatch when depth >= MAX_CHAIN_DEPTH so mutual chains terminate
-     * deterministically rather than relying on the bounded queue to drop
-     * events.
-     */
-    _chainDepth?: number;
 }
 interface RealtimeConfig {
     baseUrl: string;
@@ -470,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
@@ -755,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;
@@ -825,6 +969,71 @@ interface SubscribeHandlers<T = Record<string, unknown>> {
     onDelete?: (documentId: string) => void;
     onError?: (error: Error) => void;
 }
+interface PaginateOptions {
+    where?: Record<string, unknown>;
+    /** Sort direction by `_id`. Defaults to -1 (newest first — chat scroll-back). */
+    sort?: {
+        _id: 1 | -1;
+    };
+    /** Page size. Default 50. Server typically caps at 100. */
+    limit?: number;
+    /**
+     * Optional initial cursor — paginate from this `_id` exclusively. Useful
+     * when the caller already holds a boundary document (e.g. the oldest
+     * message currently rendered in a chat view paired with `subscribeEvents`).
+     */
+    cursor?: string;
+}
+interface PaginatorPage<T = Record<string, unknown>> {
+    documents: (T & {
+        _id: string;
+    })[];
+    /**
+     * True when more documents exist past this page. The paginator also flips
+     * `exhausted` to true when this returns false, so callers can poll either
+     * `page.hasMore` after each call or `paginator.exhausted` between calls.
+     */
+    hasMore: boolean;
+}
+/**
+ * Cursor-based scroll helper around `find()`. Tracks the last-seen `_id`
+ * across calls and applies it as `.before()` (descending sort) or
+ * `.after()` (ascending sort) on the next page so the keyset stays stable
+ * under concurrent inserts. Use `subscribeEvents` for new docs and
+ * `paginate` for older — the two compose into a chat-style timeline.
+ */
+declare class Paginator<T = Record<string, unknown>> {
+    private readonly http;
+    private readonly basePath;
+    private cursor?;
+    private _exhausted;
+    private readonly direction;
+    private readonly pageSize;
+    private readonly where?;
+    /**
+     * Tail of the serialized `next()` chain. Each call appends to this so
+     * concurrent invocations from a UI scroll handler (e.g. user spam-tapping
+     * "load more") don't issue parallel requests with the same cursor — which
+     * would return duplicate pages and clobber the cursor based on whichever
+     * response settles last. Calls execute strictly in invocation order.
+     */
+    private chain;
+    constructor(http: HttpClient, basePath: string, opts: PaginateOptions);
+    /**
+     * True once a `next()` call has returned an empty page. Subsequent
+     * `next()` calls return an empty page without hitting the server.
+     *
+     * Note: only the empty-page signal flips this flag; a server response
+     * that returns documents but `hasMore: false` does NOT exhaust. This
+     * lets ascending paginators (`sort: { _id: 1 }`) keep polling for
+     * documents inserted after the caller caught up to the current tail —
+     * the next `.after(lastSeen)` call will simply return zero documents
+     * until something new lands.
+     */
+    get exhausted(): boolean;
+    next(): Promise<PaginatorPage<T>>;
+    private fetchNextPage;
+}
 declare class QueryBuilder<T = Record<string, unknown>, M extends 'offset' | 'cursor' = 'offset'> {
     private http;
     private basePath;
@@ -876,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;
@@ -892,6 +1107,18 @@ declare class CollectionRef<T = Record<string, unknown>> {
         _id?: string;
     })[]): Promise<InsertResult>;
     find(filter?: Record<string, unknown>): QueryBuilder<T>;
+    /**
+     * Cursor-based scroll-back helper. Returns a `Paginator` whose `.next()`
+     * yields successive pages and tracks the last-seen `_id` internally.
+     * Defaults to descending sort and 50 docs per page (chat scroll-back is
+     * the canonical use case). See `PaginateOptions` for tuning.
+     *
+     * **Cursor constraint:** uses `_id` keyset pagination, which requires
+     * 24-hex ObjectId `_id`s. Collections with custom string `_id` schemes
+     * fall back to comparing strings as ObjectIds — the server's handler
+     * documents this limitation on `before` / `after` directly.
+     */
+    paginate(opts?: PaginateOptions): Paginator<T>;
     /**
      * Server-side substring search across the specified fields.
      *
@@ -900,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.
      */
@@ -912,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;
@@ -1082,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 };