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

package/dist/index.js

@@ -210,6 +210,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")
@@ -524,6 +553,140 @@ var SyncManager = class {
   }
 };
 
+// src/append-log.ts
+import {
+  DEFAULT_ALG as DEFAULT_ALG2,
+  verifyAppendAuthor
+} from "@drakkar.software/starfish-protocol";
+var PULL_PATH_PREFIX = "/pull/";
+function stripPullPrefix(path) {
+  return path.startsWith(PULL_PATH_PREFIX) ? path.slice(PULL_PATH_PREFIX.length) : path;
+}
+var AppendAuthorError = class extends Error {
+  constructor(ts) {
+    super(`append element author verification failed (ts=${ts})`);
+    this.ts = ts;
+    this.name = "AppendAuthorError";
+  }
+};
+function checkpointOf(items) {
+  let max = 0;
+  for (const it of items) if (it.ts > max) max = it.ts;
+  return max;
+}
+var AppendLogCursor = class {
+  client;
+  pullPath;
+  appendField;
+  encryptor;
+  verifyAuthor;
+  documentKey;
+  logger;
+  loggerName;
+  items;
+  lastCheckpoint;
+  constructor(options) {
+    this.client = options.client;
+    this.pullPath = options.pullPath;
+    this.appendField = options.appendField ?? "items";
+    this.encryptor = options.encryptor;
+    this.verifyAuthor = options.verifyAuthor;
+    this.documentKey = stripPullPrefix(options.pullPath);
+    this.logger = options.logger;
+    this.loggerName = options.loggerName ?? options.pullPath.split("/").filter(Boolean).pop() ?? options.pullPath;
+    const seed = options.initialItems ?? [];
+    const seedCheckpoint = checkpointOf(seed);
+    if (options.since != null) {
+      if (options.since < 0) throw new Error("since must be non-negative");
+      if (options.since < seedCheckpoint) {
+        throw new Error("since must be >= the max ts of initialItems");
+      }
+      this.lastCheckpoint = options.since;
+    } else {
+      this.lastCheckpoint = seedCheckpoint;
+    }
+    this.items = [...seed];
+  }
+  /**
+   * 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.
+   */
+  async pull() {
+    this.logger?.pullStart(this.loggerName);
+    const start = performance.now();
+    try {
+      const since = this.lastCheckpoint;
+      const opts = since > 0 ? { appendField: this.appendField, since } : { appendField: this.appendField };
+      const raw = await this.client.pull(this.pullPath, opts);
+      const batch = [];
+      let maxTs = since;
+      for (const el of raw) {
+        if (since > 0 && el.ts <= since) continue;
+        this.verifyOne(el);
+        const data = this.encryptor ? await this.encryptor.decrypt(el.data) : el.data;
+        const out = { ts: el.ts, data };
+        if (el.authorPubkey !== void 0) out.authorPubkey = el.authorPubkey;
+        if (el.authorSignature !== void 0) out.authorSignature = el.authorSignature;
+        batch.push(out);
+        if (el.ts > maxTs) maxTs = el.ts;
+      }
+      this.items.push(...batch);
+      this.lastCheckpoint = maxTs;
+      this.logger?.pullSuccess(this.loggerName, Math.round(performance.now() - start));
+      return batch;
+    } catch (err) {
+      this.logger?.pullError(this.loggerName, err instanceof Error ? err.message : String(err));
+      throw err;
+    }
+  }
+  /** 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. */
+  verifyOne(el) {
+    if (!this.verifyAuthor) return;
+    const policy = typeof this.verifyAuthor === "object" ? this.verifyAuthor : {};
+    const { authorPubkey, authorSignature } = el;
+    if (!authorPubkey || !authorSignature) throw new AppendAuthorError(el.ts);
+    if (policy.expectedAuthorPubkey && authorPubkey.toLowerCase() !== policy.expectedAuthorPubkey.toLowerCase()) {
+      throw new AppendAuthorError(el.ts);
+    }
+    const ok = verifyAppendAuthor(
+      this.documentKey,
+      el.data,
+      authorPubkey,
+      authorSignature,
+      policy.alg ?? DEFAULT_ALG2
+    );
+    if (!ok) throw new AppendAuthorError(el.ts);
+  }
+  /** The full accumulated log (a shallow copy), in `ts` order. */
+  getItems() {
+    return [...this.items];
+  }
+  /** The current checkpoint: the max `ts` held (the next pull's `since`). `0`
+   *  when nothing has been pulled or seeded. */
+  getCheckpoint() {
+    return this.lastCheckpoint;
+  }
+  /** 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) {
+    if (ts < checkpointOf(this.items)) {
+      throw new Error("checkpoint must be >= the max ts already held");
+    }
+    this.lastCheckpoint = ts;
+  }
+};
+
 // src/index.ts
 import { ENCRYPTED_KEY } from "@drakkar.software/starfish-protocol";
 
@@ -1309,6 +1472,29 @@ function createMobileLifecycle(store, deps, options = {}) {
     netUnsub?.();
   };
 }
+function createAppendLogMobileLifecycle(store, deps, options = {}) {
+  const { pullOnForeground = true } = options;
+  const appSub = deps.appState.addEventListener("change", (appState) => {
+    if (appState === "active" && pullOnForeground) {
+      const { online, loading } = store.getState();
+      if (online && !loading) {
+        store.getState().pull().catch((err) => {
+          console.error("[Starfish] foreground log pull failed:", err);
+        });
+      }
+    }
+  });
+  let netUnsub = null;
+  if (deps.netInfo) {
+    netUnsub = deps.netInfo.addEventListener(({ isConnected }) => {
+      store.getState().setOnline(!!isConnected);
+    });
+  }
+  return () => {
+    appSub.remove();
+    netUnsub?.();
+  };
+}
 
 // src/multi-store.ts
 function createMultiStoreSync(options) {
@@ -1361,6 +1547,8 @@ function createMultiStoreSync(options) {
 }
 export {
   AbortError,
+  AppendAuthorError,
+  AppendLogCursor,
   ConflictError,
   ENCRYPTED_KEY,
   SnapshotHistory,
@@ -1369,10 +1557,12 @@ export {
   SyncManager,
   ValidationError,
   buildRevocationList,
+  checkpointOf,
   classifyError,
   computeHash,
   configurePlatform,
   consoleSyncLogger,
+  createAppendLogMobileLifecycle,
   createDebouncedPush,
   createDebouncedSync,
   createDedupFetch,