@drakkar.software/starfish-client 3.0.0-alpha.4 → 3.0.0-alpha.40

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import type { Alg, CapCert } from "@drakkar.software/starfish-protocol";
+import type { CapCert, PullResult } from "@drakkar.software/starfish-protocol";
 /** Push conflict error (HTTP 409). */
 export declare class ConflictError extends Error {
     constructor();
@@ -9,6 +9,20 @@ export declare class StarfishHttpError extends Error {
     readonly body: string;
     constructor(status: number, body: string);
 }
+/**
+ * Non-2xx HTTP error from an anonymous (cap-less) append call.
+ *
+ * Distinct from {@link StarfishHttpError} so callers can distinguish "the
+ * anonymous write was rejected" (e.g. auth required, payload too large) from
+ * other client errors without pattern-matching on the error message.
+ */
+export declare class AppendHttpError extends Error {
+    /** HTTP status returned by the server. */
+    readonly status: number;
+    constructor(
+    /** HTTP status returned by the server. */
+    status: number, message: string);
+}
 /**
  * v3.0 cap-cert provider for `StarfishClient`. Returns the device's cap-cert and
  * the matching Ed25519 private key (hex). The client calls `getCap()` once per
@@ -29,25 +43,56 @@ export interface StarfishCapProvider {
      * The client then sends it as `X-Starfish-Pub` so the server can verify the
      * request signature against it and check the cap's `aud` allow-list. Omit
      * `pubHex` for device/member caps (the server uses `cap.sub`).
-     *
-     * `presenterAlg` is the crypto suite of `devEdPrivHex` (the key that signs
-     * the request). It matters only for `audience` caps, where the presenter is
-     * an arbitrary redeemer whose suite is unrelated to the cap's `issAlg`; the
-     * client sends it as `X-Starfish-Alg`. For device/member caps the subject's
-     * suite is taken authoritatively from the verified cert, so this is ignored.
-     * Defaults to `"ed25519"` when omitted.
      */
     getCap(): Promise<{
         cap: CapCert;
         devEdPrivHex: string;
         pubHex?: string;
-        presenterAlg?: Alg;
     }>;
 }
+/**
+ * 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.
@@ -55,6 +100,67 @@ 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;
+    /**
+     * HTTP status codes for which a structured `pull()` falls back to the
+     * last-synced cached snapshot rather than throwing `StarfishHttpError` —
+     * a **stale-while-revalidate** strategy for transient server failures.
+     *
+     * When a pull returns one of these statuses AND a {@link cache} is configured
+     * AND a cached snapshot exists for the document, `pull()` returns the cached
+     * result immediately (tagged stale via `pullWasFromCache`) and spawns a
+     * background revalidation loop that retries until it gets a live response.
+     * On success the fresh snapshot is written through and {@link onRevalidated}
+     * fires. When no cached snapshot exists the error propagates as usual.
+     *
+     * Applies only to structured (non-append) pulls. Do NOT include `403` or `404`
+     * — they are genuine server answers (access denied / no document yet).
+     *
+     * Default `undefined` — every non-2xx status throws as before.
+     *
+     * Recommended set for offline-first apps: `[429, 500, 502, 503, 504]`.
+     */
+    cacheFallbackStatuses?: number[];
+    /**
+     * Called after a background revalidation delivers a fresh snapshot to the
+     * cache. Fires for two revalidation paths:
+     *
+     * 1. **Error-triggered** ({@link cacheFallbackStatuses} hit): the server
+     *    returned a transient error (429/5xx), `pull()` served the stale cache,
+     *    and the background retry loop eventually got a live response.
+     * 2. **SWR-on-read** ({@link PullOptions.staleWhileRevalidate}): `pull()`
+     *    served the cache immediately and the background fetch completed.
+     *
+     * In both cases `result` is the fresh `PullResult` just written to cache.
+     * Use this to signal reachability recovery and/or push the fresh data into
+     * any store that is showing the stale snapshot.
+     *
+     * `path` is the namespaced document path (namespace prefix + path + query
+     * string, matching the cache key written by {@link StarfishClient.pull}).
+     */
+    onRevalidated?: (path: string, result: PullResult) => void;
     /**
      * 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/dist/types.js

@@ -0,0 +1,18 @@
+/** Push conflict error (HTTP 409). */
+export class ConflictError extends Error {
+    constructor() {
+        super("hash_mismatch");
+        this.name = "ConflictError";
+    }
+}
+/** HTTP error from the Starfish server. */
+export class StarfishHttpError extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        super(`HTTP ${status}: ${body}`);
+        this.status = status;
+        this.body = body;
+        this.name = "StarfishHttpError";
+    }
+}

package/dist/validate.js

@@ -0,0 +1,28 @@
+/** Error thrown when pre-push validation fails. */
+export class ValidationError extends Error {
+    errors;
+    constructor(errors) {
+        super(`Validation failed: ${errors.join("; ")}`);
+        this.errors = errors;
+        this.name = "ValidationError";
+    }
+}
+/**
+ * Creates a validator from a JSON Schema object.
+ * Requires an Ajv-compatible validate function.
+ *
+ * @example
+ * ```ts
+ * import Ajv from "ajv"
+ * const ajv = new Ajv()
+ * const validator = createSchemaValidator(ajv, mySchema)
+ * ```
+ */
+export function createSchemaValidator(ajv, schema) {
+    const validate = ajv.compile(schema);
+    return (data) => {
+        if (validate(data))
+            return true;
+        return [ajv.errorsText(validate.errors)];
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakkar.software/starfish-client",
-  "version": "3.0.0-alpha.4",
+  "version": "3.0.0-alpha.40",
   "repository": {
     "type": "git",
     "url": "https://github.com/Drakkar-Software/starfish.git",
@@ -11,6 +11,7 @@
   },
   "description": "TypeScript client SDK for the Starfish sync protocol",
   "type": "module",
+  "sideEffects": false,
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -26,6 +27,10 @@
       "types": "./dist/bindings/legend.d.ts",
       "import": "./dist/bindings/legend.js"
     },
+    "./events": {
+      "types": "./dist/events.d.ts",
+      "import": "./dist/events.js"
+    },
     "./fetch": {
       "types": "./dist/fetch.d.ts",
       "import": "./dist/fetch.js"
@@ -37,6 +42,10 @@
     "./testing": {
       "types": "./dist/testing.d.ts",
       "import": "./dist/testing.js"
+    },
+    "./suspense": {
+      "types": "./dist/bindings/suspense.d.ts",
+      "import": "./dist/bindings/suspense.js"
     }
   },
   "peerDependencies": {
@@ -60,7 +69,7 @@
     }
   },
   "dependencies": {
-    "@drakkar.software/starfish-protocol": "3.0.0-alpha.4"
+    "@drakkar.software/starfish-protocol": "3.0.0-alpha.40"
   },
   "devDependencies": {
     "@legendapp/state": "^2.0.0",
@@ -74,7 +83,7 @@
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
     "typescript": "^5.5.0",
-    "vitest": "^3.0.0",
+    "vitest": "^3.2.6",
     "zustand": "^5.0.11"
   },
   "files": [