@spacelr/sdk 0.2.0 → 0.2.2

package/dist/index.d.mts

@@ -381,28 +381,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;
@@ -825,6 +803,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;
@@ -892,6 +935,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.
      *

package/dist/index.d.ts

@@ -381,28 +381,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;
@@ -825,6 +803,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;
@@ -892,6 +935,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.
      *

package/dist/index.js

@@ -412,7 +412,9 @@ var TokenManager = class {
     return tokens.accessToken;
   }
   async setTokens(tokens) {
-    await this.storage.setTokens(tokens);
+    const needsDefault = tokens.expiresAt === void 0 && !!tokens.refreshToken;
+    const normalised = needsDefault ? { ...tokens, expiresAt: Math.floor(Date.now() / 1e3) } : tokens;
+    await this.storage.setTokens(normalised);
     this.authLostEmitted = false;
   }
   async clearTokens() {
@@ -1674,6 +1676,68 @@ var StorageModule = class {
 };
 
 // libs/sdk/src/modules/database.module.ts
+var Paginator = class {
+  constructor(http, basePath, opts) {
+    this.http = http;
+    this.basePath = basePath;
+    this._exhausted = false;
+    /**
+     * 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.
+     */
+    this.chain = Promise.resolve({
+      documents: [],
+      hasMore: false
+    });
+    this.cursor = opts.cursor;
+    this.direction = opts.sort?._id ?? -1;
+    this.pageSize = opts.limit ?? 50;
+    this.where = opts.where;
+  }
+  /**
+   * 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() {
+    return this._exhausted;
+  }
+  next() {
+    const run = this.chain.then(
+      () => this.fetchNextPage(),
+      () => this.fetchNextPage()
+    );
+    this.chain = run;
+    return run;
+  }
+  async fetchNextPage() {
+    if (this._exhausted) return { documents: [], hasMore: false };
+    const builder = new QueryBuilder(this.http, this.basePath, this.where).sort({ _id: this.direction }).limit(this.pageSize);
+    let result;
+    if (this.cursor !== void 0) {
+      const cursorBuilder = this.direction === -1 ? builder.before(this.cursor) : builder.after(this.cursor);
+      result = await cursorBuilder.execute();
+    } else {
+      result = await builder.execute();
+    }
+    if (result.documents.length === 0) {
+      this._exhausted = true;
+      return { documents: [], hasMore: false };
+    }
+    this.cursor = result.documents[result.documents.length - 1]._id;
+    const hasMore = result.mode === "cursor" ? result.hasMore : result.documents.length < result.total;
+    return { documents: result.documents, hasMore };
+  }
+};
 var QueryBuilder = class {
   constructor(http, basePath, filter) {
     this.http = http;
@@ -1790,6 +1854,20 @@ var CollectionRef = class {
   find(filter) {
     return new QueryBuilder(this.http, this.basePath, filter);
   }
+  /**
+   * 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 = {}) {
+    return new Paginator(this.http, this.basePath, opts);
+  }
   /**
    * Server-side substring search across the specified fields.
    *