@drakkar.software/starfish-client 3.0.0-alpha.2 → 3.0.0-alpha.21

package/dist/logger.d.ts

@@ -5,6 +5,9 @@ export interface SyncMetrics {
     conflictCount?: number;
     retryCount?: number;
     cacheHit?: boolean;
+    /** Elements an append-log pull dropped under `onElementError: "skip"`
+     *  (failed verification/decryption). Omitted when none were skipped. */
+    skippedCount?: number;
 }
 /** Structured logger for sync operations. */
 export interface SyncLogger {

package/dist/mobile-lifecycle.d.ts

@@ -1,5 +1,5 @@
 import type { StoreApi } from "zustand/vanilla";
-import type { StarfishStore } from "./bindings/zustand.js";
+import type { StarfishStore, StarfishLogStore } from "./bindings/zustand.js";
 /**
  * Minimal interface matching React Native's `AppState` module.
  * Pass `AppState` from `react-native` directly.
@@ -69,3 +69,30 @@ export interface MobileLifecycleOptions {
  * @returns A cleanup function that removes all event listeners.
  */
 export declare function createMobileLifecycle(store: StoreApi<StarfishStore>, deps: MobileLifecycleDeps, options?: MobileLifecycleOptions): () => void;
+export interface AppendLogLifecycleOptions {
+    /**
+     * Pull new elements when the app returns to the foreground.
+     * Only pulls if the store is online and not already loading.
+     * Default: `true`.
+     */
+    pullOnForeground?: boolean;
+}
+/**
+ * Wires React Native app lifecycle events to an append-log store
+ * (`createStarfishLog`). A log is read-only, so this only pulls on foreground
+ * (there is nothing to flush on background). NetInfo connectivity changes are
+ * forwarded to `store.getState().setOnline()`.
+ *
+ * ```ts
+ * import { AppState } from "react-native"
+ * import NetInfo from "@react-native-community/netinfo"
+ * import { createStarfishLog, createAppendLogMobileLifecycle } from "@drakkar.software/starfish-client"
+ *
+ * const store = createStarfishLog({ cursor })
+ * const cleanup = createAppendLogMobileLifecycle(store, { appState: AppState, netInfo: NetInfo })
+ * useEffect(() => cleanup, [])
+ * ```
+ *
+ * @returns A cleanup function that removes all event listeners.
+ */
+export declare function createAppendLogMobileLifecycle(store: StoreApi<StarfishLogStore>, deps: MobileLifecycleDeps, options?: AppendLogLifecycleOptions): () => void;

package/dist/mutate.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Read-modify-write a document with hash-CAS conflict retry.
+ *
+ * The everyday way to atomically edit a synced document: pull the current
+ * version, apply a pure `mutator` to its data, push the result with the read
+ * hash, and retry on a {@link ConflictError} (a concurrent writer moved the hash)
+ * by re-reading FRESH server state and re-applying the mutator. A missing
+ * document (404) is surfaced to the mutator as `{ data: null, hash: null }` so it
+ * can create the doc on first write.
+ *
+ * This replaces the ad-hoc `for (attempt…) { pull; mutate; try push catch
+ * ConflictError }` loop that applications otherwise hand-roll around every
+ * editable doc. The `mutator` MUST be idempotent — it re-runs on each retry — and
+ * returns `null` to signal a no-op (nothing changed; skip the write).
+ */
+import { StarfishClient } from "./client.js";
+/** The current state handed to a {@link DocMutator}: the document data (or `null`
+ *  when the doc does not exist yet) and the hash to base the next push on. */
+export interface DocState<T> {
+    data: T | null;
+    hash: string | null;
+}
+/**
+ * Pure transform from the current document to the next. Return the full next
+ * document body to write, or `null` for a no-op (the write is skipped). Runs once
+ * per attempt on freshly-pulled state, so it must be idempotent.
+ */
+export type DocMutator<T> = (cur: DocState<T>) => T | null;
+export interface MutateDocOptions {
+    /** Max push attempts before a persistent conflict propagates. Default 3. */
+    maxAttempts?: number;
+}
+/**
+ * Atomically read-modify-write the document at `path`. Returns the document that
+ * was written, or `null` if the mutator signalled a no-op. Throws the underlying
+ * error on a non-conflict failure, or a {@link ConflictError} if every attempt
+ * raced and lost.
+ */
+export declare function mutateDoc<T extends Record<string, unknown> = Record<string, unknown>>(client: StarfishClient, path: string, mutator: DocMutator<T>, options?: MutateDocOptions): Promise<T | null>;

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,10 +36,49 @@ 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"). */
     baseUrl: string;
+    /**
+     * Optional namespace for a namespace-mounted server. When set, every request
+     * path `/{action}/…` is rewritten to `/v1/{namespace}/{action}/…` for BOTH the
+     * URL the client hits AND the canonical path it signs, so the signature the
+     * server reconstructs from the namespaced URL verifies (no rewrite layer
+     * needed). Mirrors the Python client's `namespace` parameter.
+     *
+     * Crucially this also rewrites the paths that namespace-unaware SDK helpers
+     * build internally (e.g. `starfish-keyring`'s `addCollectionRecipient`, blob
+     * uploads), so consumers no longer hand-prefix paths or wrap the client to
+     * reach a namespaced deployment. Leave unset (default) for a root-mounted
+     * server — paths pass through unchanged, byte-identical to before.
+     *
+     * Pass the bare namespace name (e.g. `"octochat"`); `baseUrl` then carries only
+     * the origin (and any reverse-proxy mount the proxy strips), not the `/v1`
+     * version segment. Must match `[A-Za-z0-9_-]+` and not be a reserved route name
+     * (`pull`, `push`, `health`, `batch`).
+     */
+    namespace?: string;
     /**
      * Cap-cert provider. When set, requests are signed with Ed25519 and carry
      * `Authorization: Cap <…>`. Omit for unauthenticated public-read collections.
@@ -47,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.2",
+  "version": "3.0.0-alpha.21",
   "repository": {
     "type": "git",
     "url": "https://github.com/Drakkar-Software/starfish.git",
@@ -60,7 +60,7 @@
     }
   },
   "dependencies": {
-    "@drakkar.software/starfish-protocol": "3.0.0-alpha.2"
+    "@drakkar.software/starfish-protocol": "3.0.0-alpha.21"
   },
   "devDependencies": {
     "@legendapp/state": "^2.0.0",