@drakkar.software/starfish-client 1.7.0 → 1.11.0

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakkar.software/starfish-client",
-  "version": "1.7.0",
+  "version": "1.11.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/Drakkar-Software/starfish.git",
@@ -64,7 +64,7 @@
     }
   },
   "dependencies": {
-    "@drakkar.software/starfish-protocol": "1.5.0"
+    "@drakkar.software/starfish-protocol": "1.11.0"
   },
   "devDependencies": {
     "@legendapp/state": "^2.0.0",

package/dist/hash.d.ts

@@ -1,10 +0,0 @@
-/**
- * Deterministic JSON serialization with sorted keys (recursive).
- * Must produce identical output to the server's stableStringify.
- */
-export declare function stableStringify(value: unknown): string;
-/**
- * Compute SHA-256 hex digest of the stable-stringified data.
- * Works in both browser (crypto.subtle) and Node.js environments.
- */
-export declare function computeHash(data: Record<string, unknown>): Promise<string>;

package/dist/hash.js

@@ -1,34 +0,0 @@
-import { getCrypto } from "./platform.js";
-/**
- * Deterministic JSON serialization with sorted keys (recursive).
- * Must produce identical output to the server's stableStringify.
- */
-export function stableStringify(value) {
-    if (value === null || value === undefined)
-        return "null";
-    if (typeof value === "boolean" || typeof value === "number")
-        return JSON.stringify(value);
-    if (typeof value === "string")
-        return JSON.stringify(value);
-    if (Array.isArray(value)) {
-        return "[" + value.map(v => stableStringify(v)).join(",") + "]";
-    }
-    if (typeof value === "object") {
-        const obj = value;
-        const keys = Object.keys(obj).sort();
-        const pairs = keys.map(k => JSON.stringify(k) + ":" + stableStringify(obj[k]));
-        return "{" + pairs.join(",") + "}";
-    }
-    return "null";
-}
-/**
- * Compute SHA-256 hex digest of the stable-stringified data.
- * Works in both browser (crypto.subtle) and Node.js environments.
- */
-export async function computeHash(data) {
-    const encoded = new TextEncoder().encode(stableStringify(data));
-    const buf = await getCrypto().subtle.digest("SHA-256", encoded);
-    return Array.from(new Uint8Array(buf))
-        .map(b => b.toString(16).padStart(2, "0"))
-        .join("");
-}

package/dist/platform.d.ts

@@ -1,52 +0,0 @@
-/**
- * Platform abstraction for crypto and base64 operations.
- *
- * Browser and Node.js >= 15 work with zero configuration (globalThis.crypto).
- * React Native users must call configurePlatform() before using the SDK.
- */
-/** Minimal crypto interface required by the SDK (subset of Web Crypto API). */
-export interface CryptoProvider {
-    subtle: {
-        digest(algorithm: string, data: BufferSource): Promise<ArrayBuffer>;
-        importKey(format: "raw", keyData: BufferSource, algorithm: string | Algorithm, extractable: boolean, keyUsages: KeyUsage[]): Promise<CryptoKey>;
-        deriveKey(algorithm: HkdfParams, baseKey: CryptoKey, derivedKeyType: AesKeyGenParams, extractable: boolean, keyUsages: KeyUsage[]): Promise<CryptoKey>;
-        encrypt(algorithm: AesGcmParams, key: CryptoKey, data: BufferSource): Promise<ArrayBuffer>;
-        decrypt(algorithm: AesGcmParams, key: CryptoKey, data: BufferSource): Promise<ArrayBuffer>;
-    };
-    getRandomValues<T extends ArrayBufferView>(array: T): T;
-}
-/** Base64 encode/decode for Uint8Array <-> string. */
-export interface Base64Provider {
-    encode(data: Uint8Array): string;
-    decode(encoded: string): Uint8Array;
-}
-export interface PlatformConfig {
-    crypto?: CryptoProvider;
-    base64?: Base64Provider;
-}
-/**
- * Configure platform-specific providers for environments
- * that lack the Web Crypto API (e.g., React Native).
- *
- * Call once at app startup, before using any SDK functions.
- * Not needed for browser or Node.js >= 15.
- *
- * @example
- * ```ts
- * import { configurePlatform } from "@satellite/client"
- * import QuickCrypto from "react-native-quick-crypto"
- *
- * configurePlatform({
- *   crypto: QuickCrypto,
- *   base64: {
- *     encode: (data) => Buffer.from(data).toString("base64"),
- *     decode: (str) => new Uint8Array(Buffer.from(str, "base64")),
- *   },
- * })
- * ```
- */
-export declare function configurePlatform(config: PlatformConfig): void;
-/** Resolve the active crypto provider. */
-export declare function getCrypto(): CryptoProvider;
-/** Resolve the active base64 provider. */
-export declare function getBase64(): Base64Provider;

package/dist/platform.js

@@ -1,62 +0,0 @@
-/**
- * Platform abstraction for crypto and base64 operations.
- *
- * Browser and Node.js >= 15 work with zero configuration (globalThis.crypto).
- * React Native users must call configurePlatform() before using the SDK.
- */
-let _crypto;
-let _base64;
-/**
- * Configure platform-specific providers for environments
- * that lack the Web Crypto API (e.g., React Native).
- *
- * Call once at app startup, before using any SDK functions.
- * Not needed for browser or Node.js >= 15.
- *
- * @example
- * ```ts
- * import { configurePlatform } from "@satellite/client"
- * import QuickCrypto from "react-native-quick-crypto"
- *
- * configurePlatform({
- *   crypto: QuickCrypto,
- *   base64: {
- *     encode: (data) => Buffer.from(data).toString("base64"),
- *     decode: (str) => new Uint8Array(Buffer.from(str, "base64")),
- *   },
- * })
- * ```
- */
-export function configurePlatform(config) {
-    if (config.crypto)
-        _crypto = config.crypto;
-    if (config.base64)
-        _base64 = config.base64;
-}
-/** Resolve the active crypto provider. */
-export function getCrypto() {
-    if (_crypto)
-        return _crypto;
-    if (typeof globalThis !== "undefined" && globalThis.crypto?.subtle) {
-        return globalThis.crypto;
-    }
-    throw new Error("@satellite/client: No crypto provider available. " +
-        "In React Native, call configurePlatform({ crypto: ... }) before using the SDK.");
-}
-/** Resolve the active base64 provider. */
-export function getBase64() {
-    if (_base64)
-        return _base64;
-    if (typeof globalThis !== "undefined" && typeof globalThis.btoa === "function") {
-        return {
-            encode(data) {
-                return btoa(String.fromCharCode(...data));
-            },
-            decode(encoded) {
-                return Uint8Array.from(atob(encoded), (c) => c.charCodeAt(0));
-            },
-        };
-    }
-    throw new Error("@satellite/client: No base64 provider available. " +
-        "In React Native, call configurePlatform({ base64: ... }) before using the SDK.");
-}