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

package/dist/append.d.ts

@@ -0,0 +1,50 @@
+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[]>;

package/dist/background-sync.js

@@ -0,0 +1,29 @@
+/**
+ * Background Sync API integration for pending changes.
+ * Uses the Web Background Sync API to retry failed sync operations
+ * when connectivity is restored, even if the app is closed.
+ */
+/** Check if the Background Sync API is supported in the current environment. */
+export function isBackgroundSyncSupported() {
+    return (typeof navigator !== "undefined" &&
+        "serviceWorker" in navigator &&
+        "SyncManager" in globalThis);
+}
+/**
+ * Register a background sync event with the active service worker.
+ * Returns true if registration succeeded, false if not supported or no active SW.
+ */
+export async function registerBackgroundSync(opts) {
+    if (!isBackgroundSyncSupported())
+        return false;
+    const tag = opts?.tag ?? "starfish-sync";
+    try {
+        const registration = await navigator.serviceWorker.ready;
+        // @ts-expect-error - SyncManager types may not be available
+        await registration.sync.register(tag);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/bindings/broadcast.d.ts

@@ -0,0 +1,19 @@
+import type { StoreApi } from "zustand/vanilla";
+import type { StarfishStore } from "./zustand.js";
+/**
+ * Syncs a Zustand Starfish store across browser tabs using BroadcastChannel.
+ * Returns a cleanup function that closes the channel.
+ */
+export declare function setupBroadcastSync(store: StoreApi<StarfishStore>, name: string): () => void;
+/**
+ * Syncs a Zustand Starfish store across browser tabs using storage events.
+ * Fallback for environments without BroadcastChannel.
+ * Returns a cleanup function.
+ */
+export declare function setupStorageFallback(store: StoreApi<StarfishStore>, name: string): () => void;
+/**
+ * Auto-detects the best cross-tab sync mechanism and sets it up.
+ * Uses BroadcastChannel when available, falls back to storage events.
+ * Returns a cleanup function.
+ */
+export declare function setupCrossTabSync(store: StoreApi<StarfishStore>, name: string): () => void;

package/dist/bindings/broadcast.js

@@ -0,0 +1,65 @@
+/**
+ * Syncs a Zustand Starfish store across browser tabs using BroadcastChannel.
+ * Returns a cleanup function that closes the channel.
+ */
+export function setupBroadcastSync(store, name) {
+    const channel = new BroadcastChannel(`starfish-${name}`);
+    let lastReceivedData = null;
+    channel.onmessage = (event) => {
+        lastReceivedData = event.data.data;
+        store.setState({ data: event.data.data, dirty: event.data.dirty });
+    };
+    const unsub = store.subscribe((state, prev) => {
+        if (state.data === lastReceivedData)
+            return;
+        if (state.data !== prev.data || state.dirty !== prev.dirty) {
+            channel.postMessage({ data: state.data, dirty: state.dirty });
+        }
+    });
+    return () => {
+        unsub();
+        channel.close();
+    };
+}
+/**
+ * Syncs a Zustand Starfish store across browser tabs using storage events.
+ * Fallback for environments without BroadcastChannel.
+ * Returns a cleanup function.
+ */
+export function setupStorageFallback(store, name) {
+    const storageKey = `starfish-broadcast-${name}`;
+    let lastReceivedData = null;
+    const onStorage = (e) => {
+        if (e.key !== storageKey || !e.newValue)
+            return;
+        const payload = JSON.parse(e.newValue);
+        lastReceivedData = payload.data;
+        store.setState({ data: payload.data, dirty: payload.dirty });
+    };
+    globalThis.addEventListener("storage", onStorage);
+    const unsub = store.subscribe((state, prev) => {
+        if (state.data === lastReceivedData)
+            return;
+        if (state.data !== prev.data || state.dirty !== prev.dirty) {
+            localStorage.setItem(storageKey, JSON.stringify({ data: state.data, dirty: state.dirty }));
+        }
+    });
+    return () => {
+        unsub();
+        globalThis.removeEventListener("storage", onStorage);
+    };
+}
+/**
+ * Auto-detects the best cross-tab sync mechanism and sets it up.
+ * Uses BroadcastChannel when available, falls back to storage events.
+ * Returns a cleanup function.
+ */
+export function setupCrossTabSync(store, name) {
+    if (typeof BroadcastChannel !== "undefined") {
+        return setupBroadcastSync(store, name);
+    }
+    if (typeof globalThis.addEventListener === "function" && typeof localStorage !== "undefined") {
+        return setupStorageFallback(store, name);
+    }
+    return () => { };
+}

package/dist/bindings/react.d.ts

@@ -0,0 +1,12 @@
+import type { StoreApi } from "zustand/vanilla";
+import type { StarfishStore, StarfishState } from "./zustand.js";
+/** Derived sync status for UI display. */
+export type SyncStatus = "synced" | "syncing" | "pending" | "error" | "offline";
+/** Derive a single sync status from store state. */
+export declare function deriveSyncStatus(state: StarfishState): SyncStatus;
+/** Use the full Starfish store state and actions. */
+export declare function useStarfish(store: StoreApi<StarfishStore>): StarfishStore;
+/** Use only the synced data, with an optional selector for fine-grained subscriptions. */
+export declare function useStarfishData<T = Record<string, unknown>>(store: StoreApi<StarfishStore>, selector?: (data: Record<string, unknown>) => T): T;
+/** Use the derived sync status (synced | syncing | pending | error | offline). */
+export declare function useSyncStatus(store: StoreApi<StarfishStore>): SyncStatus;

package/dist/bindings/react.js

@@ -0,0 +1,25 @@
+import { useStore } from "zustand";
+/** Derive a single sync status from store state. */
+export function deriveSyncStatus(state) {
+    if (!state.online)
+        return "offline";
+    if (state.error)
+        return "error";
+    if (state.syncing)
+        return "syncing";
+    if (state.dirty)
+        return "pending";
+    return "synced";
+}
+/** Use the full Starfish store state and actions. */
+export function useStarfish(store) {
+    return useStore(store);
+}
+/** Use only the synced data, with an optional selector for fine-grained subscriptions. */
+export function useStarfishData(store, selector) {
+    return useStore(store, (state) => selector ? selector(state.data) : state.data);
+}
+/** Use the derived sync status (synced | syncing | pending | error | offline). */
+export function useSyncStatus(store) {
+    return useStore(store, deriveSyncStatus);
+}

package/dist/bindings/suspense.js

@@ -0,0 +1,49 @@
+/**
+ * React Suspense integration for Starfish sync data.
+ * Creates resources that throw Promises while loading (Suspense protocol).
+ */
+/**
+ * Create a Suspense-compatible resource from an async fetcher.
+ * The first call to `read()` triggers the fetch. While loading, `read()` throws
+ * a Promise (which React Suspense catches to show a fallback). Once resolved,
+ * `read()` returns the value synchronously.
+ *
+ * @example
+ * ```tsx
+ * const resource = createSuspenseResource(() => syncManager.pull())
+ * function MyComponent() {
+ *   const data = resource.read() // throws while loading, returns data when ready
+ *   return <div>{JSON.stringify(data)}</div>
+ * }
+ * ```
+ */
+export function createSuspenseResource(fetcher) {
+    let status = "pending";
+    let result;
+    let error;
+    let promise = null;
+    function init() {
+        if (promise)
+            return promise;
+        promise = fetcher().then((value) => {
+            status = "resolved";
+            result = value;
+        }, (err) => {
+            status = "rejected";
+            error = err;
+        });
+        return promise;
+    }
+    return {
+        read() {
+            switch (status) {
+                case "pending":
+                    throw init();
+                case "resolved":
+                    return result;
+                case "rejected":
+                    throw error;
+            }
+        },
+    };
+}

package/dist/bindings/zustand.js

@@ -307,7 +307,7 @@ var StarfishClient = class {
    */
   async buildAuthHeaders(method, pathAndQuery, body) {
     if (this.capProvider) {
-      const { cap, devEdPrivHex } = await this.capProvider.getCap();
+      const { cap, devEdPrivHex, pubHex } = await this.capProvider.getCap();
       const req = {
         method,
         pathAndQuery,
@@ -315,12 +315,14 @@ var StarfishClient = class {
         host: this.signingHost()
       };
       const { sig, ts, nonce } = await signRequest(req, devEdPrivHex);
-      return {
+      const headers = {
         Authorization: `Cap ${encodeCapAuth(cap)}`,
         "X-Starfish-Sig": sig,
         "X-Starfish-Ts": String(ts),
         "X-Starfish-Nonce": nonce
       };
+      if (pubHex !== void 0) headers["X-Starfish-Pub"] = pubHex;
+      return headers;
     }
     return {};
   }
@@ -402,6 +404,42 @@ var StarfishClient = class {
     }
     return res.json();
   }
+  /**
+   * Append an element to an appendOnly (`by_timestamp`) collection.
+   *
+   * Unlike {@link push}, appendOnly writes carry no hash/conflict check — an
+   * authorized append is always accepted. Each element is stored server-side as
+   * `{ts, data}` and pulls can filter by `ts` via `since`/`checkpoint`.
+   *
+   * @param path - the push endpoint (e.g. "/push/events")
+   * @param data - the element payload. For a `delegated` collection, encrypt it
+   *   first (e.g. `createKeyringEncryptor(keyring, kem).encrypt(data)`); the
+   *   server stores it opaquely and never reads it.
+   * @param opts.ts - optional client-supplied element timestamp (ms). Must be a
+   *   non-negative integer strictly greater than the latest stored element's ts
+   *   (else the server responds 409). Omit to let the server assign one.
+   * @throws {StarfishHttpError} on a non-2xx response (e.g. 409 for a
+   *   non-monotonic timestamp).
+   */
+  async append(path, data, opts = {}) {
+    const bodyObj = { data };
+    if (opts.ts !== void 0) bodyObj["ts"] = opts.ts;
+    const body = JSON.stringify(bodyObj);
+    const authHeaders = await this.buildAuthHeaders("POST", path, body);
+    const res = await this.fetch(`${this.baseUrl}${path}`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        ...authHeaders
+      },
+      body
+    });
+    if (!res.ok) {
+      throw new StarfishHttpError(res.status, await res.text());
+    }
+    return res.json();
+  }
   /**
    * Pull binary data from a blob collection.
    * Returns raw bytes with the content hash from the ETag header.