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

package/dist/kv-cache.d.ts

@@ -0,0 +1,63 @@
+/**
+ * KV-backed {@link PullCache} factory.
+ *
+ * {@link createKvPullCache} adapts any {@link AsyncStateStorage} (or any
+ * object with `getItem`/`setItem`) into a {@link PullCache} that the
+ * `StarfishClient` can use as its offline read-through cache.
+ *
+ * Why this matters: the client's `cache` option is ciphertext-at-rest by
+ * construction — it stores the raw sealed server response and only decrypts
+ * in memory on read. Backing the cache with the platform's own KV (AsyncStorage
+ * on React Native, IndexedDB via `createIndexedDBStorage`, a custom adapter)
+ * gives offline-first reads without exposing plaintext to the OS storage layer.
+ *
+ * @example
+ * ```ts
+ * import AsyncStorage from "@react-native-async-storage/async-storage"
+ * import { StarfishClient } from "@drakkar.software/starfish-client"
+ * import { createKvPullCache } from "@drakkar.software/starfish-client"
+ *
+ * const client = new StarfishClient({
+ *   baseUrl: "https://api.example.com",
+ *   cache: createKvPullCache(AsyncStorage, { prefix: "sf:", maxAgeMs: 30 * 24 * 60 * 60 * 1000 }),
+ * })
+ * ```
+ */
+import type { PullCache } from "./types.js";
+/** A storage backend that `createKvPullCache` can wrap. */
+export interface KvStore {
+    getItem(key: string): Promise<string | null> | string | null;
+    setItem(key: string, value: string): Promise<unknown> | unknown;
+    removeItem?: (key: string) => Promise<unknown> | unknown;
+}
+/** Options for {@link createKvPullCache}. */
+export interface KvPullCacheOptions {
+    /**
+     * Key prefix for cache entries (default `"starfish.pullcache."`). Change
+     * when sharing a KV store with other data to avoid key collisions.
+     */
+    prefix?: string;
+    /**
+     * Maximum age in milliseconds for a cached snapshot. When set, an entry
+     * older than `maxAgeMs` is returned as `null` (a cache MISS) so the next
+     * pull goes to the network rather than serving arbitrarily stale data.
+     *
+     * Each entry stores a `_cachedAt` wall-clock timestamp; expiry is checked on
+     * every `get`. Omit (default) for entries that never expire — recommended
+     * for offline-first apps where any last-synced data beats none.
+     */
+    maxAgeMs?: number;
+}
+/**
+ * Adapt a KV store into a {@link PullCache} for `StarfishClient`.
+ *
+ * The adapter serialises the cached pull payload (itself a JSON string) into
+ * an outer JSON envelope that tracks the wall-clock write time for optional
+ * max-age expiry. Reading a legacy entry without `_cachedAt` treats it as
+ * fresh (backward-compatible with plain-string caches).
+ *
+ * All `get`/`set` errors are swallowed (the {@link PullCache} contract
+ * requires implementations not to throw) — a failing KV store simply
+ * degrades to "no cache" without crashing the app.
+ */
+export declare function createKvPullCache(kv: KvStore, opts?: KvPullCacheOptions): PullCache;

package/dist/types.d.ts

@@ -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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakkar.software/starfish-client",
-  "version": "3.0.0-alpha.29",
+  "version": "3.0.0-alpha.30",
   "repository": {
     "type": "git",
     "url": "https://github.com/Drakkar-Software/starfish.git",
@@ -26,6 +26,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"
@@ -60,7 +64,7 @@
     }
   },
   "dependencies": {
-    "@drakkar.software/starfish-protocol": "3.0.0-alpha.29"
+    "@drakkar.software/starfish-protocol": "3.0.0-alpha.30"
   },
   "devDependencies": {
     "@legendapp/state": "^2.0.0",