@drakkar.software/starfish-client 1.19.1 → 2.0.0

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

@@ -1,11 +1,231 @@
 // src/bindings/zustand.ts
 import { createStore } from "zustand/vanilla";
 import { useStore } from "zustand";
-import {
-  persist,
-  subscribeWithSelector,
-  createJSONStorage
-} from "zustand/middleware";
+
+// ../../../node_modules/.pnpm/zustand@5.0.11_@types+react@19.2.14_immer@11.1.4_react@19.2.4_use-sync-external-store@1.6.0_react@19.2.4_/node_modules/zustand/esm/middleware.mjs
+var subscribeWithSelectorImpl = (fn) => (set, get, api) => {
+  const origSubscribe = api.subscribe;
+  api.subscribe = ((selector, optListener, options) => {
+    let listener = selector;
+    if (optListener) {
+      const equalityFn = (options == null ? void 0 : options.equalityFn) || Object.is;
+      let currentSlice = selector(api.getState());
+      listener = (state) => {
+        const nextSlice = selector(state);
+        if (!equalityFn(currentSlice, nextSlice)) {
+          const previousSlice = currentSlice;
+          optListener(currentSlice = nextSlice, previousSlice);
+        }
+      };
+      if (options == null ? void 0 : options.fireImmediately) {
+        optListener(currentSlice, currentSlice);
+      }
+    }
+    return origSubscribe(listener);
+  });
+  const initialState = fn(set, get, api);
+  return initialState;
+};
+var subscribeWithSelector = subscribeWithSelectorImpl;
+function createJSONStorage(getStorage, options) {
+  let storage;
+  try {
+    storage = getStorage();
+  } catch (e) {
+    return;
+  }
+  const persistStorage = {
+    getItem: (name) => {
+      var _a;
+      const parse = (str2) => {
+        if (str2 === null) {
+          return null;
+        }
+        return JSON.parse(str2, options == null ? void 0 : options.reviver);
+      };
+      const str = (_a = storage.getItem(name)) != null ? _a : null;
+      if (str instanceof Promise) {
+        return str.then(parse);
+      }
+      return parse(str);
+    },
+    setItem: (name, newValue) => storage.setItem(name, JSON.stringify(newValue, options == null ? void 0 : options.replacer)),
+    removeItem: (name) => storage.removeItem(name)
+  };
+  return persistStorage;
+}
+var toThenable = (fn) => (input) => {
+  try {
+    const result = fn(input);
+    if (result instanceof Promise) {
+      return result;
+    }
+    return {
+      then(onFulfilled) {
+        return toThenable(onFulfilled)(result);
+      },
+      catch(_onRejected) {
+        return this;
+      }
+    };
+  } catch (e) {
+    return {
+      then(_onFulfilled) {
+        return this;
+      },
+      catch(onRejected) {
+        return toThenable(onRejected)(e);
+      }
+    };
+  }
+};
+var persistImpl = (config, baseOptions) => (set, get, api) => {
+  let options = {
+    storage: createJSONStorage(() => window.localStorage),
+    partialize: (state) => state,
+    version: 0,
+    merge: (persistedState, currentState) => ({
+      ...currentState,
+      ...persistedState
+    }),
+    ...baseOptions
+  };
+  let hasHydrated = false;
+  let hydrationVersion = 0;
+  const hydrationListeners = /* @__PURE__ */ new Set();
+  const finishHydrationListeners = /* @__PURE__ */ new Set();
+  let storage = options.storage;
+  if (!storage) {
+    return config(
+      (...args) => {
+        console.warn(
+          `[zustand persist middleware] Unable to update item '${options.name}', the given storage is currently unavailable.`
+        );
+        set(...args);
+      },
+      get,
+      api
+    );
+  }
+  const setItem = () => {
+    const state = options.partialize({ ...get() });
+    return storage.setItem(options.name, {
+      state,
+      version: options.version
+    });
+  };
+  const savedSetState = api.setState;
+  api.setState = (state, replace) => {
+    savedSetState(state, replace);
+    return setItem();
+  };
+  const configResult = config(
+    (...args) => {
+      set(...args);
+      return setItem();
+    },
+    get,
+    api
+  );
+  api.getInitialState = () => configResult;
+  let stateFromStorage;
+  const hydrate = () => {
+    var _a, _b;
+    if (!storage) return;
+    const currentVersion = ++hydrationVersion;
+    hasHydrated = false;
+    hydrationListeners.forEach((cb) => {
+      var _a2;
+      return cb((_a2 = get()) != null ? _a2 : configResult);
+    });
+    const postRehydrationCallback = ((_b = options.onRehydrateStorage) == null ? void 0 : _b.call(options, (_a = get()) != null ? _a : configResult)) || void 0;
+    return toThenable(storage.getItem.bind(storage))(options.name).then((deserializedStorageValue) => {
+      if (deserializedStorageValue) {
+        if (typeof deserializedStorageValue.version === "number" && deserializedStorageValue.version !== options.version) {
+          if (options.migrate) {
+            const migration = options.migrate(
+              deserializedStorageValue.state,
+              deserializedStorageValue.version
+            );
+            if (migration instanceof Promise) {
+              return migration.then((result) => [true, result]);
+            }
+            return [true, migration];
+          }
+          console.error(
+            `State loaded from storage couldn't be migrated since no migrate function was provided`
+          );
+        } else {
+          return [false, deserializedStorageValue.state];
+        }
+      }
+      return [false, void 0];
+    }).then((migrationResult) => {
+      var _a2;
+      if (currentVersion !== hydrationVersion) {
+        return;
+      }
+      const [migrated, migratedState] = migrationResult;
+      stateFromStorage = options.merge(
+        migratedState,
+        (_a2 = get()) != null ? _a2 : configResult
+      );
+      set(stateFromStorage, true);
+      if (migrated) {
+        return setItem();
+      }
+    }).then(() => {
+      if (currentVersion !== hydrationVersion) {
+        return;
+      }
+      postRehydrationCallback == null ? void 0 : postRehydrationCallback(stateFromStorage, void 0);
+      stateFromStorage = get();
+      hasHydrated = true;
+      finishHydrationListeners.forEach((cb) => cb(stateFromStorage));
+    }).catch((e) => {
+      if (currentVersion !== hydrationVersion) {
+        return;
+      }
+      postRehydrationCallback == null ? void 0 : postRehydrationCallback(void 0, e);
+    });
+  };
+  api.persist = {
+    setOptions: (newOptions) => {
+      options = {
+        ...options,
+        ...newOptions
+      };
+      if (newOptions.storage) {
+        storage = newOptions.storage;
+      }
+    },
+    clearStorage: () => {
+      storage == null ? void 0 : storage.removeItem(options.name);
+    },
+    getOptions: () => options,
+    rehydrate: () => hydrate(),
+    hasHydrated: () => hasHydrated,
+    onHydrate: (cb) => {
+      hydrationListeners.add(cb);
+      return () => {
+        hydrationListeners.delete(cb);
+      };
+    },
+    onFinishHydration: (cb) => {
+      finishHydrationListeners.add(cb);
+      return () => {
+        finishHydrationListeners.delete(cb);
+      };
+    }
+  };
+  if (!options.skipHydration) {
+    hydrate();
+  }
+  return stateFromStorage || configResult;
+};
+var persist = persistImpl;
+
+// src/bindings/zustand.ts
 import { useEffect, useRef, useState, useCallback } from "react";
 
 // src/types.ts
@@ -25,6 +245,7 @@ var StarfishHttpError = class extends Error {
 };
 
 // src/client.ts
+var APPEND_DEFAULT_FIELD = "items";
 var StarfishClient = class {
   baseUrl;
   auth;
@@ -34,13 +255,24 @@ var StarfishClient = class {
     this.auth = options.auth;
     this.fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
   }
-  /**
-   * Pull synced data from the server.
-   * @param path - The pull endpoint path (e.g. "/pull/users/abc/settings")
-   * @param checkpoint - Only return data updated after this timestamp (0 = full pull)
-   */
-  async pull(path, checkpoint) {
-    const url = checkpoint ? `${this.baseUrl}${path}?checkpoint=${checkpoint}` : `${this.baseUrl}${path}`;
+  async pull(path, checkpointOrOptions) {
+    let url = `${this.baseUrl}${path}`;
+    let appendField;
+    if (typeof checkpointOrOptions === "number") {
+      if (checkpointOrOptions) url += `?checkpoint=${checkpointOrOptions}`;
+    } else if (checkpointOrOptions != null) {
+      appendField = checkpointOrOptions.appendField ?? APPEND_DEFAULT_FIELD;
+      const params = new URLSearchParams();
+      if (checkpointOrOptions.since != null) {
+        if (checkpointOrOptions.since < 0) throw new Error("since must be non-negative");
+        params.set("checkpoint", String(checkpointOrOptions.since));
+      }
+      if (checkpointOrOptions.last != null) {
+        if (checkpointOrOptions.last < 0) throw new Error("last must be non-negative");
+        params.set("last", String(checkpointOrOptions.last));
+      }
+      if (params.size > 0) url += `?${params.toString()}`;
+    }
     const authHeaders = this.auth ? await this.auth({ method: "GET", path, body: null }) : {};
     const res = await this.fetch(url, {
       method: "GET",
@@ -49,7 +281,12 @@ var StarfishClient = class {
     if (!res.ok) {
       throw new StarfishHttpError(res.status, await res.text());
     }
-    return res.json();
+    const result = await res.json();
+    if (appendField !== void 0) {
+      const list = result.data?.[appendField];
+      return Array.isArray(list) ? list : [];
+    }
+    return result;
   }
   /**
    * Push synced data to the server.