@drakkar.software/starfish-client 3.0.0-alpha.13 → 3.0.0-alpha.16

package/README.md

@@ -185,6 +185,8 @@ new StarfishClient({
   baseUrl: "https://api.example.com/v1",
   capProvider,            // v3 — signs every request. Replaces v2 `auth`/`authProvider`.
   fetch,                  // optional custom fetch
+  cache,                  // optional offline-first read-through cache — see below
+  cacheMaxAgeMs,          // optional TTL (ms) for cache entries
 })
 ```
 
@@ -192,6 +194,19 @@ new StarfishClient({
 
 Omit `capProvider` for unauthenticated public reads.
 
+### Offline-first read cache
+
+Pass a `cache` (a `PullCache`: `{ get(k): Promise<string|null>; set(k, v): Promise<void> }`, host-backed by `localStorage`/`AsyncStorage`/etc.) to make every structured `pull()` offline-capable:
+
+- **Write-through:** a successful pull stores the raw `{data, hash, timestamp}` keyed by document path.
+- **Offline fallback:** a pull that fails because the **transport** is unreachable (`fetch` rejects — offline/DNS/timeout) returns the last cached snapshot, tagged so callers can tell it's stale (`pullWasFromCache(result)`).
+- **Real HTTP errors propagate:** 404/403/5xx are genuine server answers — the cache is *not* consulted, so "no document yet" and "access denied" keep their meaning.
+- **`cacheMaxAgeMs`:** an entry older than this is treated as a miss (both cache-first paint and offline fallback); omit for entries that never expire (recommended for offline-first, where any last-synced data beats none).
+- **Ciphertext-at-rest by construction:** the cache stores the raw server payload, which for E2E (`delegated`) collections is the sealed ciphertext the server holds — never the decrypted form. Decryption happens in memory on read (see `SyncManager.seedFromCache`).
+- **`client.peekCache(path)`** reads the cached snapshot *without* a network round-trip — the basis for cache-first paint.
+
+Append collections are not cached here; they own warm-start persistence via `AppendLogCursor` (`persistEncrypted`).
+
 ## `SyncManager`
 
 ```ts
@@ -205,6 +220,8 @@ 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.
+- `onConflict` resolves write conflicts on push *and* reconciles a pull against un-pushed local writes. On a zustand-bound store, a `pull()` while the store is `dirty` merges the fetched snapshot with the local data through this resolver (rather than overwriting it), so an optimistic write isn't lost when a pull races a `set()`. Use a union/CRDT-style resolver (`createUnionMerge`) for append-style collections so both the local and remote writes survive; `SyncManager.resolve(local, remote)` exposes the same merge for callers that need it.
+- **Offline-first (with a client `cache`):** `seedFromCache()` populates `localData` from the client's read-through cache without a network round-trip, decrypting in memory for E2E collections — the merge-doc counterpart to `AppendLogCursor.getDecryptedItems()`. `getLastPullFromCache()` reports whether the latest `pull()`/seed came from cache. On a zustand store these power cache-first paint: `useSyncInit` seeds before the initial pull, and the store exposes a `stale` flag (`seed()` action + `state.stale`) so the UI can show an "offline / showing last-synced data" indicator that clears on the next live pull.
 
 ## `AppendLogCursor`
 

package/dist/bindings/zustand.d.ts

@@ -4,7 +4,7 @@ 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 { StarfishCapProvider, ConflictResolver, PullCache } from "../types.js";
 import type { SyncLogger } from "../logger.js";
 import type { Validator } from "../validate.js";
 export interface StarfishState {
@@ -15,6 +15,14 @@ export interface StarfishState {
     error: string | null;
     /** Last-known server hash, persisted alongside `data`/`dirty`. Restored into the bound SyncManager on hydration. */
     hash: string | null;
+    /**
+     * True when the currently-shown `data` came from the offline read-through
+     * cache (a cache-first {@link StarfishActions.seed} or a {@link StarfishActions.pull}
+     * the client served from cache because the transport was unreachable) rather
+     * than a live server response. A successful live pull/flush clears it. Use it
+     * to drive an "offline / showing last-synced data" indicator.
+     */
+    stale: boolean;
 }
 export interface StarfishActions {
     pull: () => Promise<void>;
@@ -23,6 +31,14 @@ export interface StarfishActions {
     restore: (data: Record<string, unknown>) => void;
     flush: () => Promise<void>;
     setOnline: (online: boolean) => void;
+    /**
+     * Cache-first paint: populate `data` from the client's offline read-through
+     * cache (decrypting in memory for E2E collections) without touching the
+     * network. A no-op when the client has no cache configured or there's no
+     * (unexpired) entry. {@link useSyncInit} calls this once before the initial
+     * pull; the live pull then supersedes the seeded snapshot.
+     */
+    seed: () => Promise<void>;
 }
 export type StarfishStore = StarfishState & StarfishActions;
 export interface CreateStarfishStoreOptions {
@@ -123,6 +139,16 @@ export interface SyncInitConfig {
     storeName?: string;
     storage?: StateStorage | false;
     fetch?: typeof globalThis.fetch;
+    /**
+     * Offline-first read-through cache for the underlying {@link StarfishClient}
+     * (see {@link StarfishClientOptions.cache}). When set, the store seeds from the
+     * last-synced ciphertext on creation (cache-first paint, decrypted in memory)
+     * and the live pull falls back to it when the transport is unreachable; the
+     * store's `stale` flag reflects whether the shown data is from cache.
+     */
+    cache?: PullCache;
+    /** Max age (ms) for {@link cache} entries; see {@link StarfishClientOptions.cacheMaxAgeMs}. */
+    cacheMaxAgeMs?: number;
     logger?: SyncLogger;
     validate?: Validator;
 }

package/dist/bindings/zustand.js

@@ -266,6 +266,13 @@ var StarfishHttpError = class extends Error {
 
 // src/client.ts
 var APPEND_DEFAULT_FIELD = "items";
+function pullCacheKey(pathAndQuery) {
+  const q = pathAndQuery.indexOf("?");
+  return q === -1 ? pathAndQuery : pathAndQuery.slice(0, q);
+}
+function pullWasFromCache(result) {
+  return result.fromCache === true;
+}
 function stripPushPrefix(path) {
   return path.startsWith(PUSH_PATH_PREFIX) ? path.slice(PUSH_PATH_PREFIX.length) : path;
 }
@@ -283,6 +290,8 @@ var StarfishClient = class {
   namespace;
   capProvider;
   fetch;
+  cache;
+  cacheMaxAgeMs;
   /**
    * Installed client-side plugins. Currently stored as inert data; no
    * hooks fire yet. Extensions can inspect this list if needed.
@@ -293,8 +302,19 @@ var StarfishClient = class {
     this.namespace = options.namespace || void 0;
     this.capProvider = options.capProvider;
     this.fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+    this.cache = options.cache;
+    this.cacheMaxAgeMs = options.cacheMaxAgeMs;
     this.plugins = options.plugins ? [...options.plugins] : [];
   }
+  /**
+   * Mark a `PullResult` as having been served from the offline read-through
+   * cache (transport was unreachable). Non-enumerable so it doesn't leak into
+   * JSON / equality / re-caching; read via {@link pullWasFromCache}.
+   */
+  tagFromCache(result) {
+    Object.defineProperty(result, "fromCache", { value: true, enumerable: false });
+    return result;
+  }
   /**
    * Resolve the host portion of the URL the client will send to. The host
    * is folded into the signed canonical input as the `h` field so the
@@ -414,10 +434,20 @@ var StarfishClient = class {
     }
     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 }
-    });
+    const cacheKey = this.cache && appendField === void 0 ? pullCacheKey(pathAndQuery) : void 0;
+    let res;
+    try {
+      res = await this.fetch(url, {
+        method: "GET",
+        headers: { [HEADER_ACCEPT]: "application/json", ...authHeaders }
+      });
+    } catch (err) {
+      if (cacheKey) {
+        const cached = await this.readCache(cacheKey);
+        if (cached) return cached;
+      }
+      throw err;
+    }
     if (!res.ok) {
       throw new StarfishHttpError(res.status, await res.text());
     }
@@ -426,8 +456,46 @@ var StarfishClient = class {
       const list = result.data?.[appendField];
       return Array.isArray(list) ? list : [];
     }
+    if (cacheKey) {
+      const snapshot = {
+        data: result.data,
+        hash: result.hash,
+        timestamp: result.timestamp,
+        cachedAt: Date.now()
+      };
+      void this.cache.set(cacheKey, JSON.stringify(snapshot)).catch(() => {
+      });
+    }
     return result;
   }
+  /**
+   * Read the cached snapshot for a document `path` WITHOUT hitting the network —
+   * the basis for cache-first paint (seed the UI from the last-synced snapshot,
+   * then revalidate with a live {@link pull}). Returns the tagged `PullResult`,
+   * or null when no cache is configured / there's no entry. Namespacing matches
+   * {@link pull}, so the key lines up with whatever `pull` wrote.
+   */
+  async peekCache(path) {
+    if (!this.cache) return null;
+    return this.readCache(pullCacheKey(this.applyNamespace(path)));
+  }
+  /** Read + parse a cached pull snapshot, tagged {@link tagFromCache}. Returns
+   *  null on a miss or an unparseable blob (never throws — a corrupt cache entry
+   *  must not break a pull, just miss). */
+  async readCache(cacheKey) {
+    try {
+      const raw = await this.cache.get(cacheKey);
+      if (!raw) return null;
+      const parsed = JSON.parse(raw);
+      if (!parsed || typeof parsed.hash !== "string") return null;
+      if (this.cacheMaxAgeMs != null && Date.now() - (parsed.cachedAt ?? 0) > this.cacheMaxAgeMs) {
+        return null;
+      }
+      return this.tagFromCache({ data: parsed.data ?? {}, hash: parsed.hash, timestamp: parsed.timestamp ?? 0 });
+    } catch {
+      return null;
+    }
+  }
   /**
    * Pull several documents in one round-trip via `/batch/pull`. `collections` is
    * the list of distinct collection names; `opts.params` supplies, per collection,
@@ -648,6 +716,7 @@ var SyncManager = class {
   lastCheckpoint = 0;
   localData = {};
   aborted = false;
+  lastFromCache = false;
   constructor(options) {
     this.client = options.client;
     this.pullPath = options.pullPath;
@@ -669,6 +738,18 @@ var SyncManager = class {
   getData() {
     return { ...this.localData };
   }
+  /**
+   * Merge a remote snapshot with local (optimistic) data using this manager's
+   * conflict resolver — the same resolver the push-conflict path uses. A plain
+   * {@link pull} overwrites the store's data with the server snapshot, which
+   * would drop un-pushed local writes (they live only in the store, never in
+   * `localData` until a push succeeds). The zustand binding calls this on pull
+   * while the store is dirty so those writes survive. `local` wins by the same
+   * rules as a push conflict.
+   */
+  resolve(local, remote) {
+    return this.onConflict(local, remote);
+  }
   getHash() {
     return this.lastHash;
   }
@@ -676,6 +757,40 @@ var SyncManager = class {
   setHash(hash) {
     this.lastHash = hash;
   }
+  /**
+   * Whether the most recent {@link pull} (or {@link seedFromCache}) was served
+   * from the client's offline read-through cache rather than a live server
+   * response. The binding surfaces this as a `stale` flag so the UI can show an
+   * offline indicator without treating a cache hit as "reachable". Reset to
+   * false by the next successful network pull.
+   */
+  getLastPullFromCache() {
+    return this.lastFromCache;
+  }
+  /**
+   * Cache-first paint: seed `localData` from the client's read-through cache
+   * WITHOUT touching the network, decrypting in memory for E2E collections.
+   * Returns whether anything was seeded (false on a miss, an expired entry, or
+   * a decrypt failure — e.g. keyring skew). Call once on store creation before
+   * the initial live {@link pull}, which then supersedes the seeded snapshot.
+   * Requires the client to have been built with a `cache`.
+   */
+  async seedFromCache() {
+    if (this.aborted) return false;
+    const cached = await this.client.peekCache(this.pullPath);
+    if (!cached) return false;
+    let data;
+    try {
+      data = this.encryptor ? await this.encryptor.decrypt(cached.data) : cached.data;
+    } catch {
+      return false;
+    }
+    if (this.aborted) return false;
+    this.localData = data;
+    this.lastHash = cached.hash;
+    this.lastFromCache = true;
+    return true;
+  }
   getCheckpoint() {
     return this.lastCheckpoint;
   }
@@ -686,6 +801,7 @@ var SyncManager = class {
     try {
       const result = await this.client.pull(this.pullPath, this.lastCheckpoint);
       if (this.aborted) throw new AbortError();
+      this.lastFromCache = pullWasFromCache(result);
       if (this.encryptor) {
         const decrypted = await this.encryptor.decrypt(result.data);
         if (this.aborted) throw new AbortError();
@@ -859,12 +975,25 @@ function createStarfishStore(options) {
       dirty: false,
       error: null,
       hash: null,
+      stale: false,
+      seed: async () => {
+        try {
+          const seeded = await syncManager.seedFromCache();
+          if (!seeded) return;
+          if (get().dirty || Object.keys(get().data).length > 0) return;
+          set({ data: syncManager.getData(), hash: syncManager.getHash(), stale: true }, false, "seed");
+        } catch {
+        }
+      },
       pull: async () => {
         set({ syncing: true, error: null }, false, "pull/start");
         try {
           await syncManager.pull();
-          const newData = syncManager.getData();
-          set({ data: newData, syncing: false, hash: syncManager.getHash() }, false, "pull/success");
+          const remote = syncManager.getData();
+          const newData = get().dirty ? syncManager.resolve(get().data, remote) : remote;
+          set({ data: newData, syncing: false, hash: syncManager.getHash(), stale: syncManager.getLastPullFromCache() }, false, "pull/success");
+          if (get().online && get().dirty) get().flush().catch(() => {
+          });
           options.onRemoteUpdate?.(newData);
         } catch (err) {
           set({ syncing: false, error: err instanceof Error ? err.message : String(err) }, false, "pull/error");
@@ -888,7 +1017,7 @@ function createStarfishStore(options) {
         set({ syncing: true, error: null }, false, "flush/start");
         try {
           await syncManager.push(get().data);
-          set({ data: syncManager.getData(), syncing: false, dirty: false, hash: syncManager.getHash() }, false, "flush/success");
+          set({ data: syncManager.getData(), syncing: false, dirty: false, hash: syncManager.getHash(), stale: false }, false, "flush/success");
         } catch (err) {
           set({ syncing: false, error: err instanceof Error ? err.message : String(err) }, false, "flush/error");
         }
@@ -1013,7 +1142,9 @@ function useSyncInit(config) {
       baseUrl: config.serverUrl,
       namespace: config.namespace,
       capProvider: config.capProvider,
-      fetch: config.fetch
+      fetch: config.fetch,
+      cache: config.cache,
+      cacheMaxAgeMs: config.cacheMaxAgeMs
     });
     const syncManager = new SyncManager({
       client,
@@ -1041,7 +1172,9 @@ function useSyncInit(config) {
       }
     });
     setStore(newStore);
-    newStore.getState().pull().catch(() => {
+    newStore.getState().seed().finally(() => {
+      newStore.getState().pull().catch(() => {
+      });
     });
     return () => {
       setStore(null);