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

package/dist/sync.d.ts

@@ -70,13 +70,41 @@ export declare class SyncManager {
     private lastCheckpoint;
     private localData;
     private aborted;
+    private lastFromCache;
     constructor(options: SyncManagerOptions);
     abort(): void;
     get isAborted(): boolean;
     getData(): Record<string, unknown>;
+    /**
+     * 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: Record<string, unknown>, remote: Record<string, unknown>): Record<string, unknown>;
     getHash(): string | null;
     /** Set the last-known server hash. Used by persistence layers to restore state across restarts. */
     setHash(hash: string | null): void;
+    /**
+     * 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(): boolean;
+    /**
+     * 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`.
+     */
+    seedFromCache(): Promise<boolean>;
     getCheckpoint(): number;
     pull(): Promise<PullResult>;
     push(data: Record<string, unknown>): Promise<{

package/dist/types.d.ts

@@ -36,6 +36,26 @@ export interface StarfishCapProvider {
         pubHex?: string;
     }>;
 }
+/**
+ * A minimal async key-value store the client uses as a read-through cache for
+ * {@link StarfishClient.pull} (offline-first reads). Host-provided so the SDK
+ * stays storage-agnostic — back it by `localStorage`, `AsyncStorage`, a file,
+ * etc. Shaped like a subset of zustand's `StateStorage` so an existing adapter
+ * fits.
+ *
+ * IMPORTANT — what gets stored: the client caches the RAW server response only
+ * (`data`/`hash`/`timestamp`). For E2E (`delegated`) collections that payload is
+ * the SEALED ciphertext the server holds — never the decrypted form — so this
+ * cache is ciphertext-at-rest by construction. Decryption always happens in
+ * memory on read (see {@link SyncManager}). Public/plaintext collections cache
+ * their plaintext, exactly as the server stores it.
+ */
+export interface PullCache {
+    /** Return the previously-stored string for `key`, or null if absent. Must not throw. */
+    get(key: string): Promise<string | null>;
+    /** Store `value` under `key`. Must not throw (failures are swallowed by the client). */
+    set(key: string, value: string): Promise<void>;
+}
 /** Options for creating a StarfishClient. */
 export interface StarfishClientOptions {
     /** Base URL of the Starfish server (e.g. "https://api.example.com/v1"). */
@@ -66,6 +86,29 @@ export interface StarfishClientOptions {
     capProvider?: StarfishCapProvider;
     /** Optional fetch implementation (defaults to global fetch). */
     fetch?: typeof fetch;
+    /**
+     * Optional read-through cache for {@link StarfishClient.pull} — the basis for
+     * offline-first reads. When set, every successful non-append pull is written
+     * through to the cache (keyed by document path), and a pull that fails because
+     * the TRANSPORT is unreachable (offline / DNS / timeout — `fetch` rejects)
+     * falls back to the cached response, tagged so callers can tell it's stale.
+     *
+     * A real HTTP error (404/403/5xx) is a genuine server answer and always
+     * propagates — the cache is NOT consulted — so "no document yet" and
+     * "access denied" keep their meaning. Caches ciphertext for E2E collections
+     * (the server only ever holds sealed payloads); never decrypted data.
+     */
+    cache?: PullCache;
+    /**
+     * Optional max age (ms) for {@link cache} entries. An entry older than this is
+     * treated as a cache MISS on every read — both cache-first paint and the
+     * offline fallback — so a stale-beyond-policy snapshot is never served (the
+     * pull then goes to the network, or rethrows the transport error offline).
+     * Each cached snapshot records its write time; expiry is `now - cachedAt >
+     * cacheMaxAgeMs`. Omit (default) for entries that never expire — recommended
+     * for an offline-first app where any last-synced data beats none.
+     */
+    cacheMaxAgeMs?: number;
     /**
      * Optional list of client-side plugins. The list is stored on the client
      * instance but does not fire any hooks yet — the contract is plumbed so

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakkar.software/starfish-client",
-  "version": "3.0.0-alpha.13",
+  "version": "3.0.0-alpha.16",
   "repository": {
     "type": "git",
     "url": "https://github.com/Drakkar-Software/starfish.git",
@@ -60,7 +60,7 @@
     }
   },
   "dependencies": {
-    "@drakkar.software/starfish-protocol": "3.0.0-alpha.13"
+    "@drakkar.software/starfish-protocol": "3.0.0-alpha.16"
   },
   "devDependencies": {
     "@legendapp/state": "^2.0.0",