@drakkar.software/starfish-client 3.0.0-alpha.28 → 3.0.0-alpha.30

package/README.md

@@ -198,10 +198,18 @@ 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:
+**Persist-backed Zustand stores are offline-first for reads without a client `cache`.** When
+`createStarfishStore` is used with a `storage`, the persisted `starfish-{name}` entry rehydrates
+`data` on cold start. If the first `pull()` then fails because the transport is unreachable (offline /
+DNS / timeout), `pull()` preserves the already-shown data and sets `stale: true` — no error, no empty
+screen. HTTP errors (4xx/5xx), aborts, and decrypt failures still set `error` as usual.
+
+The client `cache` (`PullCache`) remains available for additional capabilities:
+
+Pass a `cache` (a `PullCache`: `{ get(k): Promise<string|null>; set(k, v): Promise<void> }`, host-backed by `localStorage`/`AsyncStorage`/etc.) to the client for:
 
 - **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)`).
+- **Offline fallback (without a persist-backed store):** a pull that fails because the **transport** is unreachable returns the last cached snapshot, tagged so callers can tell it's stale (`pullWasFromCache(result)`).
 - **Real HTTP errors propagate:** 404/403 are genuine server answers — the cache is *not* consulted, so "no document yet" and "access denied" keep their meaning. 429 and 5xx can optionally be caught via `cacheFallbackStatuses` (see below).
 - **Stale-while-revalidate:** set `cacheFallbackStatuses: [429, 500, 502, 503, 504]` to make transient server failures serve the last-synced snapshot immediately and retry in the background (honoring `Retry-After`). When the live response arrives, the cache is updated and `onRevalidated` fires. No snapshot → the error propagates as usual. Do NOT include 403/404 — they are genuine answers, not transient failures.
 - **`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).
@@ -224,7 +232,7 @@ 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.
+- **Offline-first:** Zustand stores backed by `storage` are offline-first without any client `cache` — a transport failure during `pull()` preserves the persisted data and sets `stale: true` on the store. When a client `cache` is also configured, `seedFromCache()` additionally populates `localData` from the ciphertext cache without a network round-trip (decrypting in memory for E2E collections); `getLastPullFromCache()` reports whether the latest `pull()`/seed came from that cache. On a zustand store, the `stale` flag tracks both sources: it is set by an offline `pull()` (no cache needed) and by `seed()` (cache-first paint before the initial 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, PullCache } from "../types.js";
+import type { StarfishClientOptions, StarfishCapProvider, ConflictResolver, PullCache } from "../types.js";
 import type { SyncLogger } from "../logger.js";
 import type { Validator } from "../validate.js";
 export interface StarfishState {
@@ -163,6 +163,19 @@ export interface SyncInitConfig {
     cache?: PullCache;
     /** Max age (ms) for {@link cache} entries; see {@link StarfishClientOptions.cacheMaxAgeMs}. */
     cacheMaxAgeMs?: number;
+    /**
+     * HTTP status codes for which pulls fall back to the last-cached snapshot rather than
+     * throwing — stale-while-revalidate for transient server failures.
+     * See {@link StarfishClientOptions.cacheFallbackStatuses}.
+     * Recommended set for offline-first apps: `[429, 500, 502, 503, 504]`.
+     */
+    cacheFallbackStatuses?: number[];
+    /**
+     * Called after a background revalidation following a {@link cacheFallbackStatuses} hit:
+     * the server returned a live response and the fresh snapshot has been written through.
+     * See {@link StarfishClientOptions.onRevalidated}.
+     */
+    onRevalidated?: StarfishClientOptions["onRevalidated"];
     logger?: SyncLogger;
     validate?: Validator;
 }
@@ -176,6 +189,59 @@ export interface SyncInitConfig {
  * Pass `null` to disable sync (returns `null`).
  */
 export declare function useSyncInit(config: SyncInitConfig | null): StoreApi<StarfishStore> | null;
+/**
+ * Config for a shared sync store — identical to {@link SyncInitConfig} EXCEPT:
+ *  - `onData` is omitted: it is not safe to fan out a single `onRemoteUpdate`
+ *    callback to multiple independent subscribers. Consumers should instead
+ *    subscribe to the returned store via `store.subscribe(...)`.
+ *  - `storeName` is REQUIRED: it is the registry key, not an optional label.
+ */
+export type SharedSyncConfig = Omit<SyncInitConfig, "onData" | "storeName"> & {
+    /** Registry key AND store persistence label. Required; there is no default. */
+    storeName: string;
+};
+/**
+ * Return (or create) the shared zustand store for `config.storeName`.
+ *
+ * On the **first** acquire, constructs `StarfishClient` → `SyncManager` → store
+ * (forwarding all config fields, including `cacheFallbackStatuses` and `onRevalidated`
+ * for native stale-while-revalidate), then fires `seed().finally(pull())`. On every
+ * subsequent acquire of the same `storeName`, the existing store is returned — **no**
+ * new pull fires.
+ *
+ * Always pair with {@link releaseSyncStore}. Call {@link clearSyncStoreRegistry}
+ * on account switch / sign-out.
+ */
+export declare function acquireSyncStore(config: SharedSyncConfig): StoreApi<StarfishStore>;
+/**
+ * Release a previously acquired store. Decrements the refCount; on 0 the entry is
+ * evicted — the store, client, and sync manager are dropped and GC'd (mirrors
+ * `useSyncInit`'s own teardown, which simply drops the local store reference).
+ */
+export declare function releaseSyncStore(storeName: string): void;
+/**
+ * Clear all registry entries.
+ *
+ * Call on account switch or sign-out alongside any other per-session cache clears.
+ * An identity guard inside {@link acquireSyncStore} prevents any in-flight pull from
+ * firing against the old session's cap after this is called.
+ */
+export declare function clearSyncStoreRegistry(): void;
+/**
+ * React hook that returns (or creates) the shared zustand store for
+ * `config.storeName` — a drop-in replacement for {@link useSyncInit} when the
+ * same logical document is consumed from multiple components.
+ *
+ * **Key design decision — effect deps include only `storeName`:** config identity
+ * churn (fresh `capProvider`/`encryptor` refs per render) is intentionally ignored.
+ * For a given `(user, space)` the cap and keyring are functionally equivalent across
+ * refs, and no `onData` fan-out is needed, so the shared store never needs to rebuild
+ * on churn. The `configRef` pattern ensures the latest config values are captured at
+ * acquire-time without re-running the effect.
+ *
+ * Pass `null` to disable sync (returns `null`).
+ */
+export declare function useSharedSyncStore(config: SharedSyncConfig | null): StoreApi<StarfishStore> | null;
 export interface StarfishLogState {
     /** The full accumulated log, newest appended last. */
     items: AppendElement[];

package/dist/bindings/zustand.js

@@ -263,6 +263,13 @@ var StarfishHttpError = class extends Error {
     this.name = "StarfishHttpError";
   }
 };
+var AppendHttpError = class extends Error {
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+    this.name = "AppendHttpError";
+  }
+};
 
 // src/fetch.ts
 function parseRetryAfterMs(header, opts) {
@@ -276,6 +283,20 @@ function parseRetryAfterMs(header, opts) {
   }
   return Math.min(fallbackMs, maxMs);
 }
+function classifyError(err) {
+  if (err instanceof Response || err && typeof err === "object" && "status" in err) {
+    const status = err.status;
+    if (typeof status !== "number" || isNaN(status)) return "unknown";
+    if (status === 0) return "network";
+    if (status === 401 || status === 403) return "auth";
+    if (status === 409) return "conflict";
+    if (status === 429) return "rate-limited";
+    if (status >= 500) return "server";
+    if (status >= 400) return "client";
+  }
+  if (err instanceof Error && /failed to fetch|fetch failed|network|load failed|ECONNREFUSED|ENOTFOUND/i.test(err.message)) return "network";
+  return "unknown";
+}
 
 // src/client.ts
 var APPEND_DEFAULT_FIELD = "items";
@@ -748,6 +769,62 @@ var StarfishClient = class {
     }
     return res.json();
   }
+  /**
+   * Append one element to a **public-write** append-only collection with an
+   * Ed25519 author proof but **no cap `Authorization` header**.
+   *
+   * Unlike {@link append}, which always attaches a cap-signed `Authorization`
+   * header from the configured `capProvider`, this method signs only the
+   * append-author proof (binding the element to the writer's Ed25519 key) and
+   * sends the request without authentication headers. This is required for
+   * collections with `writeRoles: ["public"]` — the server's cap-scope check
+   * would reject a request carrying a cap whose scope does not cover the path.
+   *
+   * Typical use-case: writing a sealed invitation to another user's
+   * public-write inbox collection without needing a cap scoped to the
+   * recipient's namespace. The author proof is optional on the server side
+   * (`requireAuthorSignature: false` for a public inbox), but signing anyway
+   * binds the stored element to the sender's Ed25519 key for verification in
+   * the receive path.
+   *
+   * The element is sent as `{ data, authorPubkey, authorSignature }`.
+   *
+   * @param path    The push path, e.g. `/push/inbox/{userId}/{shard}`.
+   * @param element The JSON element to append.
+   * @param signer  The sender's Ed25519 keypair (signs the author proof).
+   *
+   * @throws {AppendHttpError} on a non-2xx response.
+   */
+  async appendAnonymous(path, element, signer) {
+    const sendPath = this.applyNamespace(path);
+    const documentKey = stripPushPrefix(path);
+    const { authorPubkey, authorSignature } = signAppendAuthor(
+      documentKey,
+      element,
+      signer.edPubHex,
+      signer.edPrivHex
+    );
+    const body = JSON.stringify({
+      [DATA_FIELD]: element,
+      [AUTHOR_PUBKEY_FIELD]: authorPubkey,
+      [AUTHOR_SIGNATURE_FIELD]: authorSignature
+    });
+    const res = await this.fetch(`${this.baseUrl}${sendPath}`, {
+      method: "POST",
+      headers: {
+        [HEADER_CONTENT_TYPE]: "application/json",
+        [HEADER_ACCEPT]: "application/json"
+      },
+      body
+    });
+    if (!res.ok) {
+      const detail = await res.text().catch(() => "");
+      throw new AppendHttpError(
+        res.status,
+        `anonymous append failed: HTTP ${res.status} ${detail}`.trim()
+      );
+    }
+  }
   /**
    * Pull binary data from a blob collection.
    * Returns raw bytes with the content hash from the ETag header.
@@ -1134,6 +1211,10 @@ function createStarfishStore(options) {
           });
           options.onRemoteUpdate?.(newData);
         } catch (err) {
+          if (classifyError(err) === "network") {
+            set({ syncing: false, stale: true }, false, "pull/offline");
+            return;
+          }
           set({ syncing: false, error: err instanceof Error ? err.message : String(err) }, false, "pull/error");
         }
       },
@@ -1291,7 +1372,9 @@ function useSyncInit(config) {
       capProvider: config.capProvider,
       fetch: config.fetch,
       cache: config.cache,
-      cacheMaxAgeMs: config.cacheMaxAgeMs
+      cacheMaxAgeMs: config.cacheMaxAgeMs,
+      cacheFallbackStatuses: config.cacheFallbackStatuses,
+      onRevalidated: config.onRevalidated
     });
     const syncManager = new SyncManager({
       client,
@@ -1335,6 +1418,76 @@ function useSyncInit(config) {
   ]);
   return store;
 }
+var _syncStoreRegistry = /* @__PURE__ */ new Map();
+function acquireSyncStore(config) {
+  const existing = _syncStoreRegistry.get(config.storeName);
+  if (existing) {
+    existing.refCount += 1;
+    return existing.store;
+  }
+  const client = new StarfishClient({
+    baseUrl: config.serverUrl,
+    namespace: config.namespace,
+    capProvider: config.capProvider,
+    fetch: config.fetch,
+    cache: config.cache,
+    cacheMaxAgeMs: config.cacheMaxAgeMs,
+    cacheFallbackStatuses: config.cacheFallbackStatuses,
+    onRevalidated: config.onRevalidated
+  });
+  const syncManager = new SyncManager({
+    client,
+    pullPath: config.pullPath,
+    pushPath: config.pushPath,
+    encryptor: config.encryptor,
+    onConflict: config.onConflict,
+    logger: config.logger,
+    validate: config.validate
+  });
+  const store = createStarfishStore({
+    name: config.storeName,
+    syncManager,
+    storage: config.storage
+    // No onRemoteUpdate: consumers subscribe via store.subscribe() — see module comment.
+  });
+  const entry = { store, refCount: 1 };
+  _syncStoreRegistry.set(config.storeName, entry);
+  store.getState().seed().finally(() => {
+    if (_syncStoreRegistry.get(config.storeName) === entry) {
+      store.getState().pull().catch(() => {
+      });
+    }
+  });
+  return store;
+}
+function releaseSyncStore(storeName) {
+  const entry = _syncStoreRegistry.get(storeName);
+  if (!entry) return;
+  entry.refCount -= 1;
+  if (entry.refCount <= 0) _syncStoreRegistry.delete(storeName);
+}
+function clearSyncStoreRegistry() {
+  _syncStoreRegistry.clear();
+}
+function useSharedSyncStore(config) {
+  const [store, setStore] = useState(null);
+  const storeName = config?.storeName ?? null;
+  const configRef = useRef(config);
+  configRef.current = config;
+  useEffect(() => {
+    if (!storeName) {
+      setStore(null);
+      return;
+    }
+    const acquired = acquireSyncStore(configRef.current);
+    setStore(acquired);
+    return () => {
+      releaseSyncStore(storeName);
+      setStore(null);
+    };
+  }, [storeName]);
+  return store;
+}
 function createStarfishLog(options) {
   const { cursor } = options;
   const storeCreator = (rawSet, get) => {
@@ -1414,11 +1567,14 @@ function useLogConnectivity(store) {
   }, [store]);
 }
 export {
+  acquireSyncStore,
   aggregateSyncStatus,
+  clearSyncStoreRegistry,
   createStarfishLog,
   createStarfishStore,
   deriveLogStatus,
   deriveSyncStatus,
+  releaseSyncStore,
   subscribeLogStatus,
   subscribeSyncStatus,
   useConnectivity,
@@ -1426,6 +1582,7 @@ export {
   useLastSynced,
   useLogConnectivity,
   useLogStatus,
+  useSharedSyncStore,
   useStarfish,
   useStarfishData,
   useStarfishLog,