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

package/dist/keyring.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Phase-2 transitional shim. The implementation lives in
+ * `@drakkar.software/starfish-keyring`. This file is removed in Phase 3.
+ */
+export { KEYRING_WRAP_SALT, KEYRING_WRAP_INFO, KEYRING_IV_BYTES, wrapForRecipient, unwrapFromEntry, verifyEntrySignature, createKeyring, addRecipient, rotateEpoch, createKeyringEncryptor, } from "@drakkar.software/starfish-keyring";
+export type { WrappedKeyEntry, KeyringEpoch, Keyring, KeyringEncryptor, } from "@drakkar.software/starfish-keyring";

package/dist/keyring.js

@@ -0,0 +1,26 @@
+// src/keyring.ts
+import {
+  KEYRING_WRAP_SALT,
+  KEYRING_WRAP_INFO,
+  KEYRING_IV_BYTES,
+  wrapForRecipient,
+  unwrapFromEntry,
+  verifyEntrySignature,
+  createKeyring,
+  addRecipient,
+  rotateEpoch,
+  createKeyringEncryptor
+} from "@drakkar.software/starfish-keyring";
+export {
+  KEYRING_IV_BYTES,
+  KEYRING_WRAP_INFO,
+  KEYRING_WRAP_SALT,
+  addRecipient,
+  createKeyring,
+  createKeyringEncryptor,
+  rotateEpoch,
+  unwrapFromEntry,
+  verifyEntrySignature,
+  wrapForRecipient
+};
+//# sourceMappingURL=keyring.js.map

package/dist/keyring.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/keyring.ts"],
+  "sourcesContent": ["/**\n * Phase-2 transitional shim. The implementation lives in\n * `@drakkar.software/starfish-keyring`. This file is removed in Phase 3.\n */\nexport {\n  KEYRING_WRAP_SALT,\n  KEYRING_WRAP_INFO,\n  KEYRING_IV_BYTES,\n  wrapForRecipient,\n  unwrapFromEntry,\n  verifyEntrySignature,\n  createKeyring,\n  addRecipient,\n  rotateEpoch,\n  createKeyringEncryptor,\n} from \"@drakkar.software/starfish-keyring\"\nexport type {\n  WrappedKeyEntry,\n  KeyringEpoch,\n  Keyring,\n  KeyringEncryptor,\n} from \"@drakkar.software/starfish-keyring\"\n"],
+  "mappings": ";AAIA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;",
+  "names": []
+}

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/mobile-lifecycle.js

@@ -31,13 +31,13 @@ export function createMobileLifecycle(store, deps, options = {}) {
     const appSub = deps.appState.addEventListener("change", (appState) => {
         if (appState === "background" && flushOnBackground) {
             if (store.getState().dirty) {
-                store.getState().flush().catch(() => { });
+                store.getState().flush().catch((err) => { console.error("[Starfish] background flush failed:", err); });
             }
         }
         else if (appState === "active" && pullOnForeground) {
             const { online, syncing } = store.getState();
             if (online && !syncing) {
-                store.getState().pull().catch(() => { });
+                store.getState().pull().catch((err) => { console.error("[Starfish] foreground pull failed:", err); });
             }
         }
         // "inactive" (iOS transition) and other states are intentionally ignored
@@ -53,3 +53,42 @@ export function createMobileLifecycle(store, deps, options = {}) {
         netUnsub?.();
     };
 }
+/**
+ * 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 function createAppendLogMobileLifecycle(store, deps, options = {}) {
+    const { pullOnForeground = true } = options;
+    const appSub = deps.appState.addEventListener("change", (appState) => {
+        if (appState === "active" && pullOnForeground) {
+            const { online, loading } = store.getState();
+            if (online && !loading) {
+                store.getState().pull().catch((err) => { console.error("[Starfish] foreground log pull failed:", err); });
+            }
+        }
+    });
+    let netUnsub = null;
+    if (deps.netInfo) {
+        netUnsub = deps.netInfo.addEventListener(({ isConnected }) => {
+            store.getState().setOnline(!!isConnected);
+        });
+    }
+    return () => {
+        appSub.remove();
+        netUnsub?.();
+    };
+}

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/pairing.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Phase-2 transitional shim. The implementation lives in
+ * `@drakkar.software/starfish-identities`. Removed in Phase 3.
+ */
+export { bootstrapRootIdentity, buildPairingQr, parsePairingQr, assemblePairingBundle, installPairingBundle, deriveCodeKey, buildPairingRequest, readPairingRequest, buildPairingResponse, readPairingResponse, } from "@drakkar.software/starfish-identities";
+export type { DeviceCredentials, PairingQrPayload, PairingBundle, WrappedCekEntry, InstalledPairingResult, AssemblePairingBundleOpts, PairingRequestEncrypted, PairingResponseEncrypted, } from "@drakkar.software/starfish-identities";

package/dist/pairing.js

@@ -0,0 +1,26 @@
+// src/pairing.ts
+import {
+  bootstrapRootIdentity,
+  buildPairingQr,
+  parsePairingQr,
+  assemblePairingBundle,
+  installPairingBundle,
+  deriveCodeKey,
+  buildPairingRequest,
+  readPairingRequest,
+  buildPairingResponse,
+  readPairingResponse
+} from "@drakkar.software/starfish-identities";
+export {
+  assemblePairingBundle,
+  bootstrapRootIdentity,
+  buildPairingQr,
+  buildPairingRequest,
+  buildPairingResponse,
+  deriveCodeKey,
+  installPairingBundle,
+  parsePairingQr,
+  readPairingRequest,
+  readPairingResponse
+};
+//# sourceMappingURL=pairing.js.map

package/dist/pairing.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/pairing.ts"],
+  "sourcesContent": ["/**\n * Phase-2 transitional shim. The implementation lives in\n * `@drakkar.software/starfish-identities`. Removed in Phase 3.\n */\nexport {\n  bootstrapRootIdentity,\n  buildPairingQr,\n  parsePairingQr,\n  assemblePairingBundle,\n  installPairingBundle,\n  deriveCodeKey,\n  buildPairingRequest,\n  readPairingRequest,\n  buildPairingResponse,\n  readPairingResponse,\n} from \"@drakkar.software/starfish-identities\"\nexport type {\n  DeviceCredentials,\n  PairingQrPayload,\n  PairingBundle,\n  WrappedCekEntry,\n  InstalledPairingResult,\n  AssemblePairingBundleOpts,\n  PairingRequestEncrypted,\n  PairingResponseEncrypted,\n} from \"@drakkar.software/starfish-identities\"\n"],
+  "mappings": ";AAIA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;",
+  "names": []
+}

package/dist/polling.js

@@ -14,7 +14,7 @@ export function startPolling(pullFn, getState, intervalMs = 30_000) {
     const timer = setInterval(() => {
         const { online, syncing } = getState();
         if (online && !syncing)
-            pullFn().catch(() => { });
+            pullFn().catch((err) => { console.error("[Starfish] poll failed:", err); });
     }, intervalMs);
     return () => clearInterval(timer);
 }
@@ -42,7 +42,7 @@ export function startAdaptivePolling(pullFn, getState, options) {
             return;
         const { online, syncing } = getState();
         if (online && !syncing)
-            pullFn().catch(() => { });
+            pullFn().catch((err) => { console.error("[Starfish] adaptive poll failed:", err); });
     }, intervalMs);
     return {
         pause: () => { paused = true; },

package/dist/recipients.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Phase-2 transitional shim. The implementation lives in
+ * `@drakkar.software/starfish-keyring`. This file is removed in Phase 3.
+ */
+export { keyringPathFor, addCollectionRecipient, removeRecipient, listRecipients, currentEpoch, } from "@drakkar.software/starfish-keyring";
+export type { RecipientRef, AdderKeys, ListedRecipient, } from "@drakkar.software/starfish-keyring";

package/dist/recipients.js

@@ -0,0 +1,16 @@
+// src/recipients.ts
+import {
+  keyringPathFor,
+  addCollectionRecipient,
+  removeRecipient,
+  listRecipients,
+  currentEpoch
+} from "@drakkar.software/starfish-keyring";
+export {
+  addCollectionRecipient,
+  currentEpoch,
+  keyringPathFor,
+  listRecipients,
+  removeRecipient
+};
+//# sourceMappingURL=recipients.js.map

package/dist/recipients.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/recipients.ts"],
+  "sourcesContent": ["/**\n * Phase-2 transitional shim. The implementation lives in\n * `@drakkar.software/starfish-keyring`. This file is removed in Phase 3.\n */\nexport {\n  keyringPathFor,\n  addCollectionRecipient,\n  removeRecipient,\n  listRecipients,\n  currentEpoch,\n} from \"@drakkar.software/starfish-keyring\"\nexport type {\n  RecipientRef,\n  AdderKeys,\n  ListedRecipient,\n} from \"@drakkar.software/starfish-keyring\"\n"],
+  "mappings": ";AAIA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;",
+  "names": []
+}

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/sync.js

@@ -1,7 +1,13 @@
-import { deepMerge, stableStringify } from "@drakkar.software/starfish-protocol";
+import { AUTHOR_PUBKEY_FIELD, AUTHOR_SIGNATURE_FIELD, deepMerge, docAuthorCanonicalInput, getBase64, } from "@drakkar.software/starfish-protocol";
 import { ConflictError } from "./types.js";
-import { createEncryptor } from "./crypto.js";
+import { stripPushPrefix } from "./client.js";
 import { ValidationError } from "./validate.js";
+export class AbortError extends Error {
+    constructor() {
+        super("SyncManager was aborted");
+        this.name = "AbortError";
+    }
+}
 export class SyncManager {
     client;
     pullPath;
@@ -9,28 +15,31 @@ export class SyncManager {
     onConflict;
     maxRetries;
     encryptor;
-    signData;
+    signer;
     logger;
     loggerName;
     validate;
     lastHash = null;
     lastCheckpoint = 0;
     localData = {};
+    aborted = false;
     constructor(options) {
         this.client = options.client;
         this.pullPath = options.pullPath;
         this.pushPath = options.pushPath;
         this.onConflict = options.onConflict ?? deepMerge;
         this.maxRetries = options.maxRetries ?? 3;
-        this.signData = options.signData;
+        this.signer = options.signer;
         this.logger = options.logger;
         this.loggerName = options.loggerName ?? options.pullPath.split("/").filter(Boolean).pop() ?? options.pullPath;
         this.validate = options.validate;
-        this.encryptor =
-            options.encryptor ??
-                (options.encryptionSecret && options.encryptionSalt
-                    ? createEncryptor(options.encryptionSecret, options.encryptionSalt, options.encryptionInfo)
-                    : null);
+        this.encryptor = options.encryptor ?? null;
+    }
+    abort() {
+        this.aborted = true;
+    }
+    get isAborted() {
+        return this.aborted;
     }
     getData() {
         return { ...this.localData };
@@ -38,16 +47,31 @@ export class SyncManager {
     getHash() {
         return this.lastHash;
     }
+    /** Set the last-known server hash. Used by persistence layers to restore state across restarts. */
+    setHash(hash) {
+        this.lastHash = hash;
+    }
     getCheckpoint() {
         return this.lastCheckpoint;
     }
     async pull() {
+        if (this.aborted)
+            throw new AbortError();
         this.logger?.pullStart(this.loggerName);
         const start = performance.now();
         try {
+            // NOTE: `SyncManager.pull` does NOT auto-enable `withKeyring`. Clients
+            // that drive the keyring helpers from `recipients.ts` and want to save
+            // the cold-start round-trip should call `client.pull(path, {withKeyring: true})`
+            // directly. We keep `SyncManager` keyring-agnostic so it stays usable
+            // for collections that don't use delegated encryption.
             const result = await this.client.pull(this.pullPath, this.lastCheckpoint);
+            if (this.aborted)
+                throw new AbortError();
             if (this.encryptor) {
                 const decrypted = await this.encryptor.decrypt(result.data);
+                if (this.aborted)
+                    throw new AbortError();
                 this.localData = decrypted;
                 result.data = decrypted;
             }
@@ -69,6 +93,8 @@ export class SyncManager {
         }
     }
     async push(data) {
+        if (this.aborted)
+            throw new AbortError();
         if (this.validate) {
             const result = this.validate(data);
             if (result !== true)
@@ -80,13 +106,33 @@ export class SyncManager {
         let pendingData = data;
         while (attempt <= this.maxRetries) {
             try {
-                const payload = this.encryptor
+                const sealed = this.encryptor
                     ? await this.encryptor.encrypt(pendingData)
                     : pendingData;
-                const sig = this.signData
-                    ? await this.signData(stableStringify(payload))
-                    : undefined;
-                const result = await this.client.push(this.pushPath, payload, this.lastHash, sig);
+                if (this.aborted)
+                    throw new AbortError();
+                // v3.0 signer path: sign the document author proof over the doc-author
+                // canonical input (domain-tagged, bound to documentKey) and pass it as
+                // top-level body siblings of `data` (NOT inside `data`), where the server
+                // verifies it and stores the raw author pubkey.
+                let author;
+                if (this.signer) {
+                    const { devEdPubHex, sign } = await this.signer.getSigner();
+                    if (this.aborted)
+                        throw new AbortError();
+                    const documentKey = stripPushPrefix(this.pushPath);
+                    const canonical = docAuthorCanonicalInput(documentKey, sealed);
+                    const sigBytes = await sign(new TextEncoder().encode(canonical));
+                    if (this.aborted)
+                        throw new AbortError();
+                    author = {
+                        [AUTHOR_PUBKEY_FIELD]: devEdPubHex,
+                        [AUTHOR_SIGNATURE_FIELD]: getBase64().encode(sigBytes),
+                    };
+                }
+                const result = await this.client.push(this.pushPath, sealed, this.lastHash, author);
+                if (this.aborted)
+                    throw new AbortError();
                 this.lastHash = result.hash;
                 this.lastCheckpoint = result.timestamp;
                 this.localData = pendingData;
@@ -94,6 +140,8 @@ export class SyncManager {
                 return result;
             }
             catch (err) {
+                if (err instanceof AbortError)
+                    throw err;
                 if (!(err instanceof ConflictError) || attempt >= this.maxRetries) {
                     this.logger?.pushError(this.loggerName, err instanceof Error ? err.message : String(err));
                     throw err;
@@ -101,14 +149,20 @@ export class SyncManager {
                 this.logger?.conflict(this.loggerName, attempt + 1);
                 try {
                     const remote = await this.client.pull(this.pullPath);
+                    if (this.aborted)
+                        throw new AbortError();
                     const remoteData = this.encryptor
                         ? await this.encryptor.decrypt(remote.data)
                         : remote.data;
+                    if (this.aborted)
+                        throw new AbortError();
                     this.lastHash = remote.hash;
                     this.lastCheckpoint = remote.timestamp;
                     pendingData = this.onConflict(pendingData, remoteData);
                 }
                 catch (resolveErr) {
+                    if (resolveErr instanceof AbortError)
+                        throw resolveErr;
                     const msg = resolveErr instanceof Error ? resolveErr.message : String(resolveErr);
                     this.logger?.pushError(this.loggerName, `Conflict resolution failed (attempt ${attempt + 1}): ${msg}`);
                     throw resolveErr;

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.22",
   "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.22"
   },
   "devDependencies": {
     "@legendapp/state": "^2.0.0",

package/dist/append.d.ts

@@ -1,50 +0,0 @@
-import type { StarfishClient } from "./client.js";
-import type { PushSuccess } from "@drakkar.software/starfish-protocol";
-/**
- * Appends `item` to an append-only collection.
- *
- * Sends `{ data: item, baseHash: null }` — the server ignores `baseHash` for
- * append-only collections (conflict detection is disabled or delegated to
- * `checkLastItem` on the server side).
- *
- * ```ts
- * await pushAppend(client, "/push/events", { type: "click", ts: Date.now() })
- * ```
- */
-export declare function pushAppend(client: StarfishClient, path: string, item: Record<string, unknown>): Promise<PushSuccess>;
-export interface PullAppendListOptions {
-    /** Array field name. Defaults to `"items"` (server default). */
-    field?: string;
-    /**
-     * Return only items appended after this timestamp (milliseconds since epoch).
-     * Sent as `?checkpoint=<since>`. Omit for a full pull.
-     */
-    since?: number;
-    /**
-     * Return only the last K items. Applied after the `since` filter.
-     * Useful for "latest N entries" queries without a tracked checkpoint.
-     * Sent as `?last=<K>`.
-     */
-    last?: number;
-}
-/**
- * Pulls the stored item array from an append-only collection.
- *
- * Returns `data[field]` filtered to an array; returns `[]` when the document
- * does not exist yet or the field is absent / not an array.
- *
- * Pass `{ since: ts }` for incremental pulls — only items appended after `ts`
- * are returned (requires per-item timestamps on the server, available from 2.0.0).
- *
- * ```ts
- * // Full pull
- * const events = await pullAppendList(client, "/pull/events")
- *
- * // Incremental pull
- * const newEvents = await pullAppendList(client, "/pull/events", { since: lastSyncTs })
- *
- * // Custom field name
- * const logs = await pullAppendList(client, "/pull/audit", { field: "logs" })
- * ```
- */
-export declare function pullAppendList<T = unknown>(client: StarfishClient, path: string, options?: PullAppendListOptions): Promise<T[]>;