@spacelr/sdk 0.1.10 → 0.2.1

package/dist/index.d.mts

@@ -375,6 +375,34 @@ interface DatabaseChangeEvent {
     documentId: string;
     document?: Record<string, unknown>;
     timestamp: number;
+    /**
+     * Redis Stream entry ID (e.g. "1745234123-0") for stream-mode events, or a
+     * synthesised `${projectId}:${collectionName}:${timestamp}-${documentId}`
+     * 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;
@@ -387,6 +415,34 @@ interface RealtimeConfig {
      */
     onTokenRefreshed?: (listener: (accessToken: string) => void) => () => void;
 }
+type GapReason = 'outside-retention-window' | 'redis-unavailable' | 'replay-error' | 'replay-truncated';
+interface StreamGapInfo {
+    projectId: string;
+    collectionName: string;
+    /** Configured retention as a human-readable string (e.g. "maxLen: 10000", "24h", or "unknown"). */
+    retentionWindow: string;
+    reason: GapReason;
+}
+interface StreamSubscriptionOptions {
+    projectId: string;
+    collectionName: string;
+    sinceId?: string;
+    where?: Record<string, string | number | boolean>;
+    /**
+     * Called for each delivered event. Awaited — the cursor does NOT advance
+     * until this resolves. If the callback throws, the cursor is NOT advanced
+     * and `onError` is called; the event is not retried (at-most-once on
+     * handler failure, consistent with the server-side StreamReaderService).
+     */
+    onEvent: (entry: {
+        eventId: string;
+        event: DatabaseChangeEvent;
+    }) => void | Promise<void>;
+    /** Called when the server emits an event-gap. See GapReason for the four codes. */
+    onGap?: (info: StreamGapInfo) => void;
+    /** Called on handshake rejection (not-stream-collection, invalid sinceId, etc.) and handler failures. */
+    onError?: (error: Error) => void;
+}
 declare class RealtimeClient {
     private socket;
     private config;
@@ -400,8 +456,20 @@ declare class RealtimeClient {
     private rebuildRetryTimer;
     private connectionState;
     private connectionStateListeners;
+    private streamSubscriptions;
     constructor(config: RealtimeConfig);
     subscribe(projectId: string, collectionName: string, callback: (event: DatabaseChangeEvent) => void, onError?: (error: Error) => void, where?: Record<string, string | number | boolean>): Promise<() => void>;
+    /**
+     * 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`.
+     */
+    subscribeWithCursor(options: StreamSubscriptionOptions): Promise<() => void>;
     /**
      * Tear down the realtime client permanently. After this call the instance
      * is disposed — subsequent `subscribe()` calls will not re-establish a
@@ -430,7 +498,59 @@ declare class RealtimeClient {
     private ensureWakeListeners;
     private detachWakeListeners;
     private resubscribeAll;
+    private emitSubscribeEvents;
+    private buildStreamPayload;
+    private unsubscribeStream;
+    private dispatchStreamEvent;
+    private resubscribeAllStreams;
+    private resubscribeOne;
+    private pickEarliestCursorState;
+    /**
+     * 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`.
+     */
+    private evictStreamKey;
+}
+
+/**
+ * Persist the stream-mode resume cursor across app restarts and reconnects.
+ *
+ * Pass an implementation to `subscribeEvents({ cursorStorage })` and the SDK
+ * will load the previous cursor before subscribing and save after each event
+ * is handled. All methods may be sync or async — the SDK awaits the returned
+ * value so React Native's AsyncStorage and other async backends work without
+ * extra adapter code.
+ */
+interface CursorStorage {
+    /**
+     * Return the saved cursor for this key, or `null` if none.
+     *
+     * An empty string is also treated as "no cursor" — Redis stream entry ids
+     * are never empty, so an empty value is always the result of a misconfigured
+     * adapter or a zero-length write. Returning `null` is preferred for clarity.
+     */
+    load(key: string): Promise<string | null> | string | null;
+    /** Persist the cursor for this key. Called after each delivered event. */
+    save(key: string, cursor: string): Promise<void> | void;
 }
+/**
+ * In-memory cursor store. Useful for tests and short-lived scripts; state is
+ * lost on process exit. Pass this to `subscribeEvents({ cursorStorage })`
+ * when you want non-persistent in-memory resume behaviour within a single
+ * session — omitting `cursorStorage` entirely disables persistence instead.
+ */
+declare function memoryCursorStorage(): CursorStorage;
+/**
+ * Browser `localStorage`-backed cursor store. Gracefully no-ops in
+ * non-browser environments (Node without a `localStorage` polyfill), so
+ * isomorphic code can use this factory unconditionally.
+ *
+ * @param prefix Key prefix applied to every stored entry. Defaults to
+ *   `spacelr:cursor:` so multiple SDK consumers on the same origin don't
+ *   collide.
+ */
+declare function localStorageCursorStorage(prefix?: string): CursorStorage;
 
 type AuthState = 'authenticated' | 'unauthenticated';
 type AuthStateListener = (state: AuthState) => void | Promise<void>;
@@ -571,7 +691,34 @@ interface PopulateOption {
     collection: string;
     foreignField?: string;
 }
-interface FindResult<T = Record<string, unknown>> {
+interface OffsetResult<T = Record<string, unknown>> {
+    mode: 'offset';
+    documents: (T & {
+        _id: string;
+    })[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+interface CursorResult<T = Record<string, unknown>> {
+    mode: 'cursor';
+    documents: (T & {
+        _id: string;
+    })[];
+    limit: number;
+    /**
+     * `_id` of the last document in `documents`, or `null` if `documents` is empty.
+     * Independent of `hasMore` — the cursor reflects the page contents, not
+     * whether more pages exist.
+     */
+    nextCursor: string | null;
+    /**
+     * True when more documents exist past the returned page. Computed via the
+     * `limit + 1` server-side fetch trick.
+     */
+    hasMore: boolean;
+}
+interface SearchResult<T = Record<string, unknown>> {
     documents: (T & {
         _id: string;
     })[];
@@ -608,6 +755,65 @@ interface SearchOptions {
     offset?: number;
     select?: string[];
 }
+interface SubscribeEventsHandlers<T = Record<string, unknown>> {
+    /** Cursor to resume from. Undefined = fresh subscription, deliver only new events. */
+    sinceId?: string;
+    where?: Record<string, string | number | boolean>;
+    /**
+     * Optional resume-cursor store. When set, the SDK loads the previous cursor
+     * before subscribing and persists the new cursor after each delivered
+     * event. An explicit `sinceId` takes precedence over a loaded cursor —
+     * `load()` is skipped entirely and saves resume from `sinceId` forward,
+     * overwriting any previously persisted cursor.
+     *
+     * Pair `where`-filtered subscriptions with a unique `cursorKey`; subscribers
+     * with different filters must not share a cursor since the stream position
+     * represents "events seen" — filtered-out entries still advance it.
+     */
+    cursorStorage?: CursorStorage;
+    /**
+     * Override the default cursor key. Defaults to `{projectId}:{collectionName}`.
+     * Useful when multiple subscriptions on the same collection (e.g. different
+     * `where` filters or per-user feeds) must persist independent cursors.
+     */
+    cursorKey?: string;
+    /** Called on inserts. Receives the document merged with `_eventId`. */
+    onInsert?: (doc: T & {
+        _id: string;
+        _eventId: string;
+    }) => void | Promise<void>;
+    onUpdate?: (doc: T & {
+        _id: string;
+        _eventId: string;
+    }) => void | Promise<void>;
+    /** Called on deletes. `document` may be absent on tombstones — only documentId + eventId are guaranteed. */
+    onDelete?: (documentId: string, eventId: string) => void | Promise<void>;
+    /** Called when the server emits an event-gap. See GapReason for the four codes. */
+    onGap?: (info: StreamGapInfo) => void;
+    /** Called on handshake rejection (not-stream-collection, invalid sinceId, etc.) and handler failures. */
+    onError?: (error: Error) => void;
+}
+interface StreamSubscription {
+    /**
+     * Stop receiving events and release the server-side reader slot. Idempotent.
+     *
+     * When `cursorStorage` is set, an in-flight async `save()` may still deliver
+     * `onError` asynchronously after `unsubscribe()` returns — the fire-and-forget
+     * save chain is not cancelled. Callers whose `onError` is tied to a component
+     * lifecycle should guard for post-unmount delivery.
+     */
+    unsubscribe(): void;
+    /**
+     * Most recently processed eventId — advances after the subscription's
+     * onEvent pipeline completes for each event, whether or not a user
+     * handler was registered for that event type. `undefined` before any
+     * event arrives.
+     *
+     * Persist this across app restarts and pass it back as `sinceId` on
+     * the next `subscribeEvents()` call to catch up on missed events.
+     */
+    getCursor(): string | undefined;
+}
 interface SubscribeHandlers<T = Record<string, unknown>> {
     where?: Record<string, string | number | boolean>;
     onInsert?: (doc: T & {
@@ -619,22 +825,58 @@ interface SubscribeHandlers<T = Record<string, unknown>> {
     onDelete?: (documentId: string) => void;
     onError?: (error: Error) => void;
 }
-declare class QueryBuilder<T = Record<string, unknown>> {
+declare class QueryBuilder<T = Record<string, unknown>, M extends 'offset' | 'cursor' = 'offset'> {
     private http;
     private basePath;
     private _filter?;
     private _sort?;
     private _limit?;
     private _offset?;
+    private _before?;
+    private _after?;
     private _fields?;
     private _populate;
     constructor(http: HttpClient, basePath: string, filter?: Record<string, unknown>);
-    sort(sort: Record<string, 1 | -1>): QueryBuilder<T>;
-    limit(limit: number): QueryBuilder<T>;
-    offset(offset: number): QueryBuilder<T>;
-    select(fields: string[]): QueryBuilder<T>;
-    populate(field: string, collection: string, foreignField?: string): QueryBuilder<T>;
-    execute(): Promise<FindResult<T>>;
+    sort(sort: Record<string, 1 | -1>): this;
+    limit(limit: number): this;
+    offset(offset: number): 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: string): QueryBuilder<T, 'cursor'>;
+    /**
+     * 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: 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>>;
 }
 declare class CollectionRef<T = Record<string, unknown>> {
     private http;
@@ -661,7 +903,7 @@ declare class CollectionRef<T = Record<string, unknown>> {
      * Limits: `query` 1–200 chars, `fields` 1–10 entries (each matching
      * `/^[a-zA-Z0-9_.]+$/`, max 64 chars), `limit` max 100.
      */
-    search(opts: SearchOptions): Promise<FindResult<T>>;
+    search(opts: SearchOptions): Promise<SearchResult<T>>;
     findById(id: string, options?: FindByIdOptions): Promise<T & {
         _id: string;
     }>;
@@ -669,6 +911,7 @@ declare class CollectionRef<T = Record<string, unknown>> {
     delete(id: string): Promise<DeleteResult>;
     count(filter?: Record<string, unknown>): Promise<number>;
     subscribe(handlers: SubscribeHandlers<T>): () => void;
+    subscribeEvents(handlers: SubscribeEventsHandlers<T>): StreamSubscription;
 }
 declare class DatabaseModule {
     private http;
@@ -839,4 +1082,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 DatabaseChangeEvent, type DownloadUrlResponse, type ExchangeCodeParams, type FileInfo, type FileListResponse, FileVisibility, type FunctionInvokeOptions, type FunctionInvokeResult, 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 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 };
+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 };