@drakkar.software/starfish-client 3.0.0-alpha.8 → 3.0.0-alpha.9

package/README.md

@@ -206,6 +206,27 @@ new SyncManager({
 - `signer.getSigner()` returns `{ devEdPubHex, sign(payload) }`. When set, every push attaches `authorPubkey = cap.sub` and `authorSignature = base64(Ed25519(payload))` over the encrypted payload (without the author fields).
 - `encryptor` is the only encryption option — the v2 single-secret `encryptionSecret`/`encryptionSalt` shorthand was removed in v3.
 
+## `AppendLogCursor`
+
+Incremental, stateful cursor over an append-only collection — the log counterpart to `SyncManager`. It owns the accumulated array and pulls only what's new; the checkpoint is **derived from the last element it holds**, so it resumes from persisted data on a fresh page.
+
+```ts
+const log = new AppendLogCursor({
+  client, pullPath: "/pull/events",
+  appendField,            // default "items"
+  initialItems,           // warm-start seed (raw {ts,data} envelopes) — or pass `since`
+  encryptor,              // optional: decrypt each element's data (ts/author preserved)
+  verifyAuthor,           // optional: true | { expectedAuthorPubkey?, alg? }
+})
+const fresh = await log.pull()  // only elements newer than the last held
+log.getItems()                  // full accumulated log
+log.getCheckpoint()             // max ts held — persist, and restore via setCheckpoint()
+```
+
+- Cold start (no seed) → first `pull()` fetches the whole collection; warm start (seeded) → resumes incrementally.
+- `verifyAuthor` verifies each element's author signature over the stored (pre-decryption) data and throws `AppendAuthorError` atomically on any failure (nothing is appended, checkpoint unchanged).
+- **Reactive bindings:** `createStarfishLog` (Zustand, `./zustand`) + hooks `useStarfishLog` / `useStarfishLogItems` / `useLogStatus` / `useLogConnectivity`; `createStarfishLogObservable` (Legend, `./legend`); `createAppendLogMobileLifecycle` (pull on app foreground). `startPolling` and `createSuspenseResource` work with `cursor.pull()` directly.
+
 ## Other utilities
 
 The package also re-exports the v2 ergonomics that survived intact: `consoleSyncLogger`, `noopSyncLogger`, `createMetricsCollector`, `createMigrator`, `createSchemaValidator`, `classifyError`, conflict resolvers (`createUnionMerge`, `createSoftDeleteResolver`, `timestampWinner`, `pruneTombstones`), `SnapshotHistory`, `startPolling`/`startAdaptivePolling`, `createDedupFetch`, `fetchServerConfig`, `pullEntitlements`, `createIndexedDBStorage`, `exportData`/`importData`, `createDebouncedSync`/`createDebouncedPush`, `createMultiStoreSync`, `createMobileLifecycle`, and the Zustand/Legend bindings via the `./zustand` and `./legend` subpaths.

package/dist/append-log.d.ts

@@ -0,0 +1,158 @@
+import { type Alg, type Encryptor } from "@drakkar.software/starfish-protocol";
+import type { StarfishClient } from "./client.js";
+import type { SyncLogger } from "./logger.js";
+/**
+ * A single stored element of an append-only collection, exactly as returned by
+ * `client.pull(path, { appendField })`. `ts` is the server-assigned, strictly
+ * increasing element timestamp; `data` is the payload (plaintext under the
+ * `"none"` encryption mode, the opaque encryptor wrapper under `"delegated"`).
+ *
+ * When an {@link AppendLogCursor} is given an `encryptor`, the elements it
+ * stores and returns carry the **decrypted** `data` while preserving `ts` and
+ * the author fields — so the shape is uniform and re-seedable.
+ */
+export interface AppendElement {
+    ts: number;
+    data: Record<string, unknown>;
+    authorPubkey?: string;
+    authorSignature?: string;
+}
+/** Per-element author-signature verification policy for {@link AppendLogCursor}. */
+export interface AuthorVerifier {
+    /** If set, every element's `authorPubkey` MUST equal this key (compared as
+     *  case-insensitive hex), else the pull fails. Omit to accept any signing key
+     *  (verify only that the signature is valid for the element's self-declared
+     *  `authorPubkey` — see the `verifyAuthor` note on restricting authors). */
+    expectedAuthorPubkey?: string;
+    /** Signing suite the signatures were produced under. Defaults to `DEFAULT_ALG`. */
+    alg?: Alg;
+}
+export interface AppendLogCursorOptions {
+    client: StarfishClient;
+    /** Pull endpoint path, e.g. `"/pull/events"`. */
+    pullPath: string;
+    /** Array field name in the pulled document. Defaults to `"items"`. */
+    appendField?: string;
+    /**
+     * Warm-start seed: raw envelopes the caller persisted last session. The
+     * cursor adopts them verbatim (never re-decrypts/re-verifies them) and
+     * derives its initial checkpoint from their max `ts`.
+     */
+    initialItems?: AppendElement[];
+    /**
+     * Explicit checkpoint-only seed (ms). Resume incrementally without
+     * rehydrating history. When given together with `initialItems`, it must be
+     * `>= max(ts of initialItems)` (a lower value would re-fetch held items).
+     */
+    since?: number;
+    /**
+     * When set, each freshly-pulled element's `.data` is decrypted via this
+     * encryptor (the `ts`/author fields are preserved). Author verification, when
+     * enabled, runs over the original (pre-decryption) `data`.
+     *
+     * Caveat: a returned / `getItems()` element then holds DECRYPTED `data` but an
+     * `authorSignature` computed over the stored CIPHERTEXT — they no longer match,
+     * so do NOT re-verify a decrypted element with `verifyAppendAuthor`. The cursor
+     * already verified it (over the ciphertext) at pull time when `verifyAuthor` is
+     * on; `authorPubkey` is retained for identity.
+     */
+    encryptor?: Encryptor;
+    /**
+     * `true` to verify every element's author signature, or a policy object.
+     *
+     * This verifies the signature is valid for the element's self-declared
+     * `authorPubkey` — it does NOT by itself restrict WHICH authors are accepted.
+     * To restrict authorship, set `expectedAuthorPubkey` (single author), or check
+     * each `el.authorPubkey` against your own authorization source (keyring /
+     * member list / cap allow-list) after pull — for a multi-writer log, the
+     * authorized set lives there and changes over time, not here.
+     *
+     * The signature covers `data` + the document key, but NOT `ts`: a malicious
+     * server cannot forge content, but can reorder or re-timestamp authentic
+     * elements, so trust `ts` only as far as you trust the server.
+     */
+    verifyAuthor?: boolean | AuthorVerifier;
+    /** Structured logger for pull events. */
+    logger?: SyncLogger;
+    /** Name passed to logger methods (default: derived from `pullPath`). */
+    loggerName?: string;
+}
+/** Thrown when an append element's author signature fails verification. */
+export declare class AppendAuthorError extends Error {
+    readonly ts: number;
+    constructor(ts: number);
+}
+/** Largest `ts` among `items`, or `0` when empty. The checkpoint for an
+ *  append-only log is exactly this — the server returns elements with
+ *  `ts > checkpoint`, and element timestamps are strictly increasing. */
+export declare function checkpointOf(items: readonly {
+    ts: number;
+}[]): number;
+/**
+ * A stateful cursor over an append-only collection. It owns the accumulated
+ * array of elements and pulls only what is new: each {@link pull} derives the
+ * checkpoint from the last element it holds and asks the server for elements
+ * with a greater `ts`.
+ *
+ * This is the incremental, stateful counterpart to the deliberately stateless
+ * `client.pull(path, { appendField, since })`, and the sibling of
+ * {@link SyncManager} for append-only logs (no merge / push-conflict
+ * machinery — a log only grows).
+ *
+ * The cursor accumulates every pulled element in memory; for an unboundedly
+ * large log, pull a bounded window with raw `client.pull(path, { last })` instead.
+ *
+ * Cold start (nothing persisted) — first `pull()` fetches the whole collection:
+ * ```ts
+ * const log = new AppendLogCursor({ client, pullPath: "/pull/events" })
+ * const all = await log.pull()
+ * ```
+ * Warm start (resume from persisted data) — first `pull()` fetches only newer
+ * elements; persistence is a round-trip of `getItems()` (see the `encryptor`
+ * caveat when decrypting):
+ * ```ts
+ * const log = new AppendLogCursor({ client, pullPath: "/pull/events",
+ *   initialItems: await store.load() })
+ * const fresh = await log.pull()
+ * await store.save(log.getItems())
+ * ```
+ */
+export declare class AppendLogCursor {
+    private readonly client;
+    private readonly pullPath;
+    private readonly appendField;
+    private readonly encryptor?;
+    private readonly verifyAuthor?;
+    private readonly documentKey;
+    private readonly logger?;
+    private readonly loggerName;
+    private readonly items;
+    private lastCheckpoint;
+    constructor(options: AppendLogCursorOptions);
+    /**
+     * Fetch elements newer than the current checkpoint, verify + decrypt them,
+     * append them to the local log, and return ONLY the newly-fetched batch.
+     *
+     * Atomic: the batch is fully verified and decrypted into a local before any
+     * state mutation, so a verify/decrypt failure throws without advancing the
+     * checkpoint past elements that could never be re-fetched.
+     *
+     * Not safe to call concurrently: like `SyncManager.pull`, overlapping calls
+     * read the same checkpoint and would fetch — and append — the same window twice.
+     */
+    pull(): Promise<AppendElement[]>;
+    /** Verify a single element's author signature over its RAW (pre-decryption)
+     *  `data`. Throws {@link AppendAuthorError} on any failure. No-op when
+     *  verification is disabled. */
+    private verifyOne;
+    /** The full accumulated log (a shallow copy), in `ts` order. */
+    getItems(): AppendElement[];
+    /** The current checkpoint: the max `ts` held (the next pull's `since`). `0`
+     *  when nothing has been pulled or seeded. */
+    getCheckpoint(): number;
+    /** Restore the checkpoint without seeding items — for persistence layers that
+     *  store only the checkpoint. Used to resume incrementally across restarts.
+     *  Rejects a value below the max `ts` already held: rewinding would make the
+     *  next pull re-deliver, and duplicate, elements the cursor already has. */
+    setCheckpoint(ts: number): void;
+}

package/dist/bindings/legend.d.ts

@@ -1,5 +1,6 @@
 import type { Observable } from "@legendapp/state";
 import type { SyncManager } from "../sync.js";
+import type { AppendLogCursor, AppendElement } from "../append-log.js";
 export interface StarfishLegendState {
     data: Record<string, unknown>;
     syncing: boolean;
@@ -23,3 +24,25 @@ export interface CreateStarfishObservableOptions {
     produce?: <T>(base: T, recipe: (draft: T) => T | void) => T;
 }
 export declare function createStarfishObservable(options: CreateStarfishObservableOptions): StarfishLegendStore;
+export interface StarfishLogObservableState {
+    /** The full accumulated log, newest appended last. */
+    items: AppendElement[];
+    /** A `pull()` is in flight. */
+    loading: boolean;
+    online: boolean;
+    error: string | null;
+    /** The cursor's checkpoint (max `ts` held). */
+    checkpoint: number;
+}
+export interface StarfishLogObservableStore {
+    /** The observable state tree — read fields with `.get()` inside `observer` components. */
+    state: Observable<StarfishLogObservableState>;
+    /** Pull elements newer than the checkpoint, append them, return the new batch.
+     *  Errors are captured into `state.error`. */
+    pull: () => Promise<AppendElement[]>;
+    setOnline: (online: boolean) => void;
+}
+export interface CreateStarfishLogObservableOptions {
+    cursor: AppendLogCursor;
+}
+export declare function createStarfishLogObservable(options: CreateStarfishLogObservableOptions): StarfishLogObservableStore;

package/dist/bindings/legend.js

@@ -57,7 +57,39 @@ function createStarfishObservable(options) {
   };
   return { state, pull, set, flush, setOnline };
 }
+function createStarfishLogObservable(options) {
+  const { cursor } = options;
+  const state = observable({
+    // Seed from the cursor so a warm-started cursor's items show immediately.
+    items: cursor.getItems(),
+    loading: false,
+    online: true,
+    error: null,
+    checkpoint: cursor.getCheckpoint()
+  });
+  const pull = async () => {
+    if (state.loading.get()) return [];
+    state.loading.set(true);
+    state.error.set(null);
+    try {
+      const batch = await cursor.pull();
+      state.items.set(cursor.getItems());
+      state.checkpoint.set(cursor.getCheckpoint());
+      return batch;
+    } catch (err) {
+      state.error.set(err instanceof Error ? err.message : String(err));
+      return [];
+    } finally {
+      state.loading.set(false);
+    }
+  };
+  const setOnline = (online) => {
+    state.online.set(online);
+  };
+  return { state, pull, setOnline };
+}
 export {
+  createStarfishLogObservable,
   createStarfishObservable
 };
 //# sourceMappingURL=legend.js.map

package/dist/bindings/legend.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/bindings/legend.ts"],
-  "sourcesContent": ["import { observable } from \"@legendapp/state\"\nimport type { Observable } from \"@legendapp/state\"\nimport type { SyncManager } from \"../sync.js\"\n\nexport interface StarfishLegendState {\n  data: Record<string, unknown>\n  syncing: boolean\n  online: boolean\n  dirty: boolean\n  error: string | null\n}\n\nexport interface StarfishLegendStore {\n  /** The observable state tree \u2014 read fields with `.get()` inside `observer` components. */\n  state: Observable<StarfishLegendState>\n  pull: () => Promise<void>\n  set: (modifier: (current: Record<string, unknown>) => Record<string, unknown>) => void\n  flush: () => Promise<void>\n  setOnline: (online: boolean) => void\n}\n\nexport interface CreateStarfishObservableOptions {\n  /** Unique name for this collection (used for persistence keys when applicable). */\n  name: string\n  syncManager: SyncManager\n  /** Pass `produce` from `immer` to enable draft-based mutations in `set()`. */\n  produce?: <T>(base: T, recipe: (draft: T) => T | void) => T\n}\n\nexport function createStarfishObservable(\n  options: CreateStarfishObservableOptions,\n): StarfishLegendStore {\n  const state = observable<StarfishLegendState>({\n    data: {},\n    syncing: false,\n    online: true,\n    dirty: false,\n    error: null,\n  })\n\n  const flush = async (): Promise<void> => {\n    if (state.syncing.get() || !state.dirty.get()) return\n    state.syncing.set(true)\n    state.error.set(null)\n    try {\n      await options.syncManager.push(state.data.get())\n      state.data.set(options.syncManager.getData())\n      state.dirty.set(false)\n    } catch (err) {\n      state.error.set(err instanceof Error ? err.message : String(err))\n    } finally {\n      state.syncing.set(false)\n    }\n  }\n\n  const pull = async (): Promise<void> => {\n    state.syncing.set(true)\n    state.error.set(null)\n    try {\n      await options.syncManager.pull()\n      state.data.set(options.syncManager.getData())\n    } catch (err) {\n      state.error.set(err instanceof Error ? err.message : String(err))\n    } finally {\n      state.syncing.set(false)\n    }\n  }\n\n  const set = (\n    modifier: (current: Record<string, unknown>) => Record<string, unknown>,\n  ): void => {\n    try {\n      const current = state.data.get()\n      const next = options.produce\n        ? options.produce(\n            current,\n            modifier as (draft: Record<string, unknown>) => Record<string, unknown> | void,\n          )\n        : modifier(current)\n      state.data.set(next)\n      state.dirty.set(true)\n      state.error.set(null)\n      if (state.online.get()) flush().catch(() => {})\n    } catch (err) {\n      state.error.set(err instanceof Error ? err.message : String(err))\n    }\n  }\n\n  const setOnline = (online: boolean): void => {\n    state.online.set(online)\n    if (online && state.dirty.get()) flush().catch(() => {})\n  }\n\n  return { state, pull, set, flush, setOnline }\n}\n"],
-  "mappings": ";AAAA,SAAS,kBAAkB;AA6BpB,SAAS,yBACd,SACqB;AACrB,QAAM,QAAQ,WAAgC;AAAA,IAC5C,MAAM,CAAC;AAAA,IACP,SAAS;AAAA,IACT,QAAQ;AAAA,IACR,OAAO;AAAA,IACP,OAAO;AAAA,EACT,CAAC;AAED,QAAM,QAAQ,YAA2B;AACvC,QAAI,MAAM,QAAQ,IAAI,KAAK,CAAC,MAAM,MAAM,IAAI,EAAG;AAC/C,UAAM,QAAQ,IAAI,IAAI;AACtB,UAAM,MAAM,IAAI,IAAI;AACpB,QAAI;AACF,YAAM,QAAQ,YAAY,KAAK,MAAM,KAAK,IAAI,CAAC;AAC/C,YAAM,KAAK,IAAI,QAAQ,YAAY,QAAQ,CAAC;AAC5C,YAAM,MAAM,IAAI,KAAK;AAAA,IACvB,SAAS,KAAK;AACZ,YAAM,MAAM,IAAI,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG,CAAC;AAAA,IAClE,UAAE;AACA,YAAM,QAAQ,IAAI,KAAK;AAAA,IACzB;AAAA,EACF;AAEA,QAAM,OAAO,YAA2B;AACtC,UAAM,QAAQ,IAAI,IAAI;AACtB,UAAM,MAAM,IAAI,IAAI;AACpB,QAAI;AACF,YAAM,QAAQ,YAAY,KAAK;AAC/B,YAAM,KAAK,IAAI,QAAQ,YAAY,QAAQ,CAAC;AAAA,IAC9C,SAAS,KAAK;AACZ,YAAM,MAAM,IAAI,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG,CAAC;AAAA,IAClE,UAAE;AACA,YAAM,QAAQ,IAAI,KAAK;AAAA,IACzB;AAAA,EACF;AAEA,QAAM,MAAM,CACV,aACS;AACT,QAAI;AACF,YAAM,UAAU,MAAM,KAAK,IAAI;AAC/B,YAAM,OAAO,QAAQ,UACjB,QAAQ;AAAA,QACN;AAAA,QACA;AAAA,MACF,IACA,SAAS,OAAO;AACpB,YAAM,KAAK,IAAI,IAAI;AACnB,YAAM,MAAM,IAAI,IAAI;AACpB,YAAM,MAAM,IAAI,IAAI;AACpB,UAAI,MAAM,OAAO,IAAI,EAAG,OAAM,EAAE,MAAM,MAAM;AAAA,MAAC,CAAC;AAAA,IAChD,SAAS,KAAK;AACZ,YAAM,MAAM,IAAI,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG,CAAC;AAAA,IAClE;AAAA,EACF;AAEA,QAAM,YAAY,CAAC,WAA0B;AAC3C,UAAM,OAAO,IAAI,MAAM;AACvB,QAAI,UAAU,MAAM,MAAM,IAAI,EAAG,OAAM,EAAE,MAAM,MAAM;AAAA,IAAC,CAAC;AAAA,EACzD;AAEA,SAAO,EAAE,OAAO,MAAM,KAAK,OAAO,UAAU;AAC9C;",
+  "sourcesContent": ["import { observable } from \"@legendapp/state\"\nimport type { Observable } from \"@legendapp/state\"\nimport type { SyncManager } from \"../sync.js\"\nimport type { AppendLogCursor, AppendElement } from \"../append-log.js\"\n\nexport interface StarfishLegendState {\n  data: Record<string, unknown>\n  syncing: boolean\n  online: boolean\n  dirty: boolean\n  error: string | null\n}\n\nexport interface StarfishLegendStore {\n  /** The observable state tree \u2014 read fields with `.get()` inside `observer` components. */\n  state: Observable<StarfishLegendState>\n  pull: () => Promise<void>\n  set: (modifier: (current: Record<string, unknown>) => Record<string, unknown>) => void\n  flush: () => Promise<void>\n  setOnline: (online: boolean) => void\n}\n\nexport interface CreateStarfishObservableOptions {\n  /** Unique name for this collection (used for persistence keys when applicable). */\n  name: string\n  syncManager: SyncManager\n  /** Pass `produce` from `immer` to enable draft-based mutations in `set()`. */\n  produce?: <T>(base: T, recipe: (draft: T) => T | void) => T\n}\n\nexport function createStarfishObservable(\n  options: CreateStarfishObservableOptions,\n): StarfishLegendStore {\n  const state = observable<StarfishLegendState>({\n    data: {},\n    syncing: false,\n    online: true,\n    dirty: false,\n    error: null,\n  })\n\n  const flush = async (): Promise<void> => {\n    if (state.syncing.get() || !state.dirty.get()) return\n    state.syncing.set(true)\n    state.error.set(null)\n    try {\n      await options.syncManager.push(state.data.get())\n      state.data.set(options.syncManager.getData())\n      state.dirty.set(false)\n    } catch (err) {\n      state.error.set(err instanceof Error ? err.message : String(err))\n    } finally {\n      state.syncing.set(false)\n    }\n  }\n\n  const pull = async (): Promise<void> => {\n    state.syncing.set(true)\n    state.error.set(null)\n    try {\n      await options.syncManager.pull()\n      state.data.set(options.syncManager.getData())\n    } catch (err) {\n      state.error.set(err instanceof Error ? err.message : String(err))\n    } finally {\n      state.syncing.set(false)\n    }\n  }\n\n  const set = (\n    modifier: (current: Record<string, unknown>) => Record<string, unknown>,\n  ): void => {\n    try {\n      const current = state.data.get()\n      const next = options.produce\n        ? options.produce(\n            current,\n            modifier as (draft: Record<string, unknown>) => Record<string, unknown> | void,\n          )\n        : modifier(current)\n      state.data.set(next)\n      state.dirty.set(true)\n      state.error.set(null)\n      if (state.online.get()) flush().catch(() => {})\n    } catch (err) {\n      state.error.set(err instanceof Error ? err.message : String(err))\n    }\n  }\n\n  const setOnline = (online: boolean): void => {\n    state.online.set(online)\n    if (online && state.dirty.get()) flush().catch(() => {})\n  }\n\n  return { state, pull, set, flush, setOnline }\n}\n\n// \u2500\u2500 Append-only log binding \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n//\n// The reactive counterpart for an append-only collection, backed by an\n// `AppendLogCursor`. Read-only (a log only grows): no `set`/`flush`/`dirty`.\n// The cursor owns the items + checkpoint; persist via `getItems()` and\n// rehydrate by constructing the cursor with `initialItems`.\n//\n// The store assumes it is the SOLE driver of its cursor (it seeds from\n// `cursor.getItems()` at construction and updates only via its own `pull()`);\n// don't also call `cursor.pull()` directly, or the observable will go stale.\n\nexport interface StarfishLogObservableState {\n  /** The full accumulated log, newest appended last. */\n  items: AppendElement[]\n  /** A `pull()` is in flight. */\n  loading: boolean\n  online: boolean\n  error: string | null\n  /** The cursor's checkpoint (max `ts` held). */\n  checkpoint: number\n}\n\nexport interface StarfishLogObservableStore {\n  /** The observable state tree \u2014 read fields with `.get()` inside `observer` components. */\n  state: Observable<StarfishLogObservableState>\n  /** Pull elements newer than the checkpoint, append them, return the new batch.\n   *  Errors are captured into `state.error`. */\n  pull: () => Promise<AppendElement[]>\n  setOnline: (online: boolean) => void\n}\n\nexport interface CreateStarfishLogObservableOptions {\n  cursor: AppendLogCursor\n}\n\nexport function createStarfishLogObservable(\n  options: CreateStarfishLogObservableOptions,\n): StarfishLogObservableStore {\n  const { cursor } = options\n  const state = observable<StarfishLogObservableState>({\n    // Seed from the cursor so a warm-started cursor's items show immediately.\n    items: cursor.getItems(),\n    loading: false,\n    online: true,\n    error: null,\n    checkpoint: cursor.getCheckpoint(),\n  })\n\n  const pull = async (): Promise<AppendElement[]> => {\n    if (state.loading.get()) return []\n    state.loading.set(true)\n    state.error.set(null)\n    try {\n      const batch = await cursor.pull()\n      state.items.set(cursor.getItems())\n      state.checkpoint.set(cursor.getCheckpoint())\n      return batch\n    } catch (err) {\n      state.error.set(err instanceof Error ? err.message : String(err))\n      return []\n    } finally {\n      state.loading.set(false)\n    }\n  }\n\n  const setOnline = (online: boolean): void => {\n    state.online.set(online)\n  }\n\n  return { state, pull, setOnline }\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/dist/bindings/zustand.d.ts

@@ -3,6 +3,7 @@ import { type StateStorage } from "zustand/middleware";
 import type { DevtoolsOptions } from "zustand/middleware";
 import type { Encryptor } from "@drakkar.software/starfish-protocol";
 import { SyncManager } from "../sync.js";
+import { AppendLogCursor, type AppendElement } from "../append-log.js";
 import type { StarfishCapProvider, ConflictResolver } from "../types.js";
 import type { SyncLogger } from "../logger.js";
 import type { Validator } from "../validate.js";
@@ -135,3 +136,40 @@ export interface SyncInitConfig {
  * Pass `null` to disable sync (returns `null`).
  */
 export declare function useSyncInit(config: SyncInitConfig | null): StoreApi<StarfishStore> | null;
+export interface StarfishLogState {
+    /** The full accumulated log, newest appended last. */
+    items: AppendElement[];
+    /** A `pull()` is in flight. */
+    loading: boolean;
+    online: boolean;
+    error: string | null;
+    /** The cursor's checkpoint (max `ts` held). */
+    checkpoint: number;
+}
+export interface StarfishLogActions {
+    /** Pull elements newer than the checkpoint, append them, and return the new
+     *  batch. Errors are captured into `error` (mirroring the SyncManager store). */
+    pull: () => Promise<AppendElement[]>;
+    setOnline: (online: boolean) => void;
+}
+export type StarfishLogStore = StarfishLogState & StarfishLogActions;
+export interface CreateStarfishLogOptions {
+    cursor: AppendLogCursor;
+    devtools?: (storeCreator: any) => any;
+}
+export declare function createStarfishLog(options: CreateStarfishLogOptions): StoreApi<StarfishLogStore>;
+/** Derived status for an append-log store. */
+export type LogStatus = "idle" | "loading" | "error" | "offline";
+/** Derive a single status from log store state. */
+export declare function deriveLogStatus(state: StarfishLogState): LogStatus;
+/** Use the full append-log store state and actions. */
+export declare function useStarfishLog(store: StoreApi<StarfishLogStore>): StarfishLogStore;
+/** Use only the accumulated items, with an optional selector for fine-grained subscriptions. */
+export declare function useStarfishLogItems<T = AppendElement[]>(store: StoreApi<StarfishLogStore>, selector?: (items: AppendElement[]) => T): T;
+/** Use the derived log status (idle | loading | error | offline). */
+export declare function useLogStatus(store: StoreApi<StarfishLogStore>): LogStatus;
+/** Subscribe to log status changes outside of React. Invoked immediately with the
+ *  current status, then on every change. Returns an unsubscribe function. */
+export declare function subscribeLogStatus(store: StoreApi<StarfishLogStore>, callback: (status: LogStatus) => void): () => void;
+/** Binds browser online/offline events to the log store's setOnline action. Cleans up on unmount. */
+export declare function useLogConnectivity(store: StoreApi<StarfishLogStore>): void;

package/dist/bindings/zustand.js

@@ -435,6 +435,35 @@ var StarfishClient = class {
     }
     return result;
   }
+  /**
+   * Pull several collections in one round-trip via `/batch/pull`. `collections`
+   * is the list of collection names; `opts.params` supplies path params per
+   * collection (serialized to a URL-encoded JSON `params` query). The server
+   * auto-fills the `{identity}` param from the authenticated caller, so per-user
+   * collections need no params. Returns a map of collection name → its pulled
+   * document or a per-collection `{ error }`. Honors the configured namespace.
+   *
+   * Note: not append/checkpoint-aware — for incremental append-only reads use
+   * `pull(path, { since })` (or `AppendLogCursor`) per collection.
+   */
+  async batchPull(collections, opts = {}) {
+    const search = new URLSearchParams();
+    search.set("collections", collections.join(","));
+    if (opts.params && Object.keys(opts.params).length > 0) {
+      search.set("params", JSON.stringify(opts.params));
+    }
+    const pathAndQuery = `${this.applyNamespace("/batch/pull")}?${search.toString()}`;
+    const url = `${this.baseUrl}${pathAndQuery}`;
+    const authHeaders = await this.buildAuthHeaders("GET", pathAndQuery, void 0);
+    const res = await this.fetch(url, {
+      method: "GET",
+      headers: { [HEADER_ACCEPT]: "application/json", ...authHeaders }
+    });
+    if (!res.ok) {
+      throw new StarfishHttpError(res.status, await res.text());
+    }
+    return await res.json();
+  }
   /**
    * Push synced data to the server.
    * @param path - The push endpoint path (e.g. "/push/users/abc/settings")
@@ -1018,16 +1047,101 @@ function useSyncInit(config) {
   ]);
   return store;
 }
+function createStarfishLog(options) {
+  const { cursor } = options;
+  const storeCreator = (rawSet, get) => {
+    const set = rawSet;
+    return {
+      // Seed from the cursor so a warm-started cursor's items show immediately.
+      items: cursor.getItems(),
+      loading: false,
+      online: true,
+      error: null,
+      checkpoint: cursor.getCheckpoint(),
+      pull: async () => {
+        if (get().loading) return [];
+        set({ loading: true, error: null }, false, "log/pull/start");
+        try {
+          const batch = await cursor.pull();
+          set(
+            { items: cursor.getItems(), checkpoint: cursor.getCheckpoint(), loading: false },
+            false,
+            "log/pull/success"
+          );
+          return batch;
+        } catch (err) {
+          set({ loading: false, error: err instanceof Error ? err.message : String(err) }, false, "log/pull/error");
+          return [];
+        }
+      },
+      setOnline: (online) => {
+        set({ online }, false, "log/setOnline");
+      }
+    };
+  };
+  const withSelector = subscribeWithSelector(storeCreator);
+  return createStore()(
+    options.devtools ? options.devtools(withSelector) : withSelector
+  );
+}
+function deriveLogStatus(state) {
+  if (!state.online) return "offline";
+  if (state.error) return "error";
+  if (state.loading) return "loading";
+  return "idle";
+}
+function useStarfishLog(store) {
+  return useStore(store);
+}
+function useStarfishLogItems(store, selector) {
+  return useStore(
+    store,
+    (state) => selector ? selector(state.items) : state.items
+  );
+}
+function useLogStatus(store) {
+  return useStore(store, deriveLogStatus);
+}
+function subscribeLogStatus(store, callback) {
+  let prev = deriveLogStatus(store.getState());
+  callback(prev);
+  return store.subscribe((state) => {
+    const next = deriveLogStatus(state);
+    if (next !== prev) {
+      prev = next;
+      callback(next);
+    }
+  });
+}
+function useLogConnectivity(store) {
+  useEffect(() => {
+    const handleOnline = () => store.getState().setOnline(true);
+    const handleOffline = () => store.getState().setOnline(false);
+    window.addEventListener("online", handleOnline);
+    window.addEventListener("offline", handleOffline);
+    return () => {
+      window.removeEventListener("online", handleOnline);
+      window.removeEventListener("offline", handleOffline);
+    };
+  }, [store]);
+}
 export {
   aggregateSyncStatus,
+  createStarfishLog,
   createStarfishStore,
+  deriveLogStatus,
   deriveSyncStatus,
+  subscribeLogStatus,
   subscribeSyncStatus,
   useConnectivity,
   useCrossTabSync,
   useLastSynced,
+  useLogConnectivity,
+  useLogStatus,
   useStarfish,
   useStarfishData,
+  useStarfishLog,
+  useStarfishLogItems,
   useSyncInit,
   useSyncStatus
 };