@drakkar.software/starfish-client 3.0.0-alpha.29 → 3.0.0-alpha.31

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) {
@@ -762,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.
@@ -1309,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,
@@ -1353,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) => {
@@ -1432,11 +1567,14 @@ function useLogConnectivity(store) {
   }, [store]);
 }
 export {
+  acquireSyncStore,
   aggregateSyncStatus,
+  clearSyncStoreRegistry,
   createStarfishLog,
   createStarfishStore,
   deriveLogStatus,
   deriveSyncStatus,
+  releaseSyncStore,
   subscribeLogStatus,
   subscribeSyncStatus,
   useConnectivity,
@@ -1444,6 +1582,7 @@ export {
   useLastSynced,
   useLogConnectivity,
   useLogStatus,
+  useSharedSyncStore,
   useStarfish,
   useStarfishData,
   useStarfishLog,