@drakkar.software/starfish-client 1.4.1 → 1.6.0

package/dist/platform.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 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

@@ -0,0 +1,62 @@
+/**
+ * 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.");
+}

package/dist/resolvers.d.ts

@@ -1,4 +1,23 @@
 import type { ConflictResolver } from "./types.js";
+/** Metadata about which fields were affected during conflict resolution. */
+export interface ConflictMeta {
+    /** Field names that differed between local and remote. */
+    conflictedFields: string[];
+    /** How the conflict was resolved. */
+    resolvedBy: "local" | "remote" | "merged";
+    /** Timestamp of resolution. */
+    timestamp: number;
+}
+/** Conflict resolver that also returns metadata about the resolution. */
+export type ConflictResolverWithMeta = (local: Record<string, unknown>, remote: Record<string, unknown>) => {
+    data: Record<string, unknown>;
+    meta: ConflictMeta;
+};
+/**
+ * Wrap a standard ConflictResolver to also return metadata about which fields conflicted.
+ * Compares local and remote keys to detect differing fields.
+ */
+export declare function withConflictMeta(resolver: ConflictResolver): ConflictResolverWithMeta;
 /**
  * Creates a conflict resolver that merges arrays by ID with per-item
  * timestamp comparison, and uses document-level timestamp for scalars.

package/dist/resolvers.js

@@ -1,3 +1,60 @@
+/** Shallow structural comparison of two values. Handles objects, arrays, and primitives. */
+function shallowEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a == null || b == null)
+        return a === b;
+    if (typeof a !== typeof b)
+        return false;
+    if (typeof a !== "object")
+        return false;
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    if (Array.isArray(a) && Array.isArray(b)) {
+        if (a.length !== b.length)
+            return false;
+        return a.every((v, i) => shallowEqual(v, b[i]));
+    }
+    const aObj = a;
+    const bObj = b;
+    const aKeys = Object.keys(aObj);
+    const bKeys = Object.keys(bObj);
+    if (aKeys.length !== bKeys.length)
+        return false;
+    return aKeys.every((k) => shallowEqual(aObj[k], bObj[k]));
+}
+/**
+ * Wrap a standard ConflictResolver to also return metadata about which fields conflicted.
+ * Compares local and remote keys to detect differing fields.
+ */
+export function withConflictMeta(resolver) {
+    return (local, remote) => {
+        const conflictedFields = [];
+        const allKeys = new Set([...Object.keys(local), ...Object.keys(remote)]);
+        for (const key of allKeys) {
+            const lv = local[key];
+            const rv = remote[key];
+            if (!shallowEqual(lv, rv)) {
+                conflictedFields.push(key);
+            }
+        }
+        const data = resolver(local, remote);
+        // Determine how it was resolved using structural comparison
+        let resolvedBy = "merged";
+        if (shallowEqual(data, local))
+            resolvedBy = "local";
+        else if (shallowEqual(data, remote))
+            resolvedBy = "remote";
+        return {
+            data,
+            meta: {
+                conflictedFields,
+                resolvedBy,
+                timestamp: Date.now(),
+            },
+        };
+    };
+}
 /** Compare two timestamp values. Handles both numeric (epoch) and string (ISO-8601) timestamps. */
 function compareTimestamps(a, b) {
     if (typeof a === "number" && typeof b === "number")

package/dist/service-worker.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Service Worker utilities for offline support and PWA functionality.
+ */
+export interface ServiceWorkerOptions {
+    /** Scope for the service worker registration. */
+    scope?: string;
+    /** Called when an updated service worker is available. */
+    onUpdate?: (registration: ServiceWorkerRegistration) => void;
+}
+/** Check if service workers are supported in the current environment. */
+export declare function isServiceWorkerSupported(): boolean;
+/**
+ * Register a service worker for offline support.
+ * Returns the registration, or null if not supported.
+ */
+export declare function registerServiceWorker(scriptUrl: string, opts?: ServiceWorkerOptions): Promise<ServiceWorkerRegistration | null>;
+/** Unregister all service worker registrations. Returns true if any were unregistered. */
+export declare function unregisterServiceWorkers(): Promise<boolean>;

package/dist/service-worker.js

@@ -0,0 +1,55 @@
+/**
+ * Service Worker utilities for offline support and PWA functionality.
+ */
+/** Check if service workers are supported in the current environment. */
+export function isServiceWorkerSupported() {
+    return typeof navigator !== "undefined" && "serviceWorker" in navigator;
+}
+/**
+ * Register a service worker for offline support.
+ * Returns the registration, or null if not supported.
+ */
+export async function registerServiceWorker(scriptUrl, opts) {
+    if (!isServiceWorkerSupported())
+        return null;
+    try {
+        const registration = await navigator.serviceWorker.register(scriptUrl, {
+            scope: opts?.scope,
+        });
+        if (opts?.onUpdate) {
+            registration.onupdatefound = () => {
+                const installingWorker = registration.installing;
+                if (installingWorker) {
+                    installingWorker.onstatechange = () => {
+                        if (installingWorker.state === "installed" &&
+                            navigator.serviceWorker.controller) {
+                            opts.onUpdate(registration);
+                        }
+                    };
+                }
+            };
+        }
+        return registration;
+    }
+    catch {
+        return null;
+    }
+}
+/** Unregister all service worker registrations. Returns true if any were unregistered. */
+export async function unregisterServiceWorkers() {
+    if (!isServiceWorkerSupported())
+        return false;
+    try {
+        const registrations = await navigator.serviceWorker.getRegistrations();
+        let unregistered = false;
+        for (const registration of registrations) {
+            const result = await registration.unregister();
+            if (result)
+                unregistered = true;
+        }
+        return unregistered;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/storage/indexeddb.d.ts

@@ -0,0 +1,17 @@
+/**
+ * IndexedDB-based storage adapter for Zustand persistence.
+ * Implements the same interface as Zustand's StateStorage (getItem/setItem/removeItem).
+ * Supports larger data than localStorage (typically 50MB+).
+ */
+export interface IndexedDBStorageOptions {
+    /** Database name. Default: "starfish" */
+    dbName?: string;
+    /** Object store name. Default: "state" */
+    storeName?: string;
+}
+export interface AsyncStateStorage {
+    getItem: (name: string) => Promise<string | null>;
+    setItem: (name: string, value: string) => Promise<void>;
+    removeItem: (name: string) => Promise<void>;
+}
+export declare function createIndexedDBStorage(opts?: IndexedDBStorageOptions): AsyncStateStorage;

package/dist/storage/indexeddb.js

@@ -0,0 +1,59 @@
+/**
+ * IndexedDB-based storage adapter for Zustand persistence.
+ * Implements the same interface as Zustand's StateStorage (getItem/setItem/removeItem).
+ * Supports larger data than localStorage (typically 50MB+).
+ */
+function openDB(dbName, storeName) {
+    return new Promise((resolve, reject) => {
+        const request = indexedDB.open(dbName, 1);
+        request.onupgradeneeded = () => {
+            const db = request.result;
+            if (!db.objectStoreNames.contains(storeName)) {
+                db.createObjectStore(storeName);
+            }
+        };
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error);
+    });
+}
+function idbRequest(request) {
+    return new Promise((resolve, reject) => {
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error);
+    });
+}
+export function createIndexedDBStorage(opts) {
+    const dbName = opts?.dbName ?? "starfish";
+    const storeName = opts?.storeName ?? "state";
+    let dbPromise = null;
+    function getDB() {
+        if (!dbPromise) {
+            dbPromise = openDB(dbName, storeName).catch((err) => {
+                dbPromise = null; // Reset so next call retries
+                throw err;
+            });
+        }
+        return dbPromise;
+    }
+    return {
+        async getItem(name) {
+            const db = await getDB();
+            const tx = db.transaction(storeName, "readonly");
+            const store = tx.objectStore(storeName);
+            const result = await idbRequest(store.get(name));
+            return result ?? null;
+        },
+        async setItem(name, value) {
+            const db = await getDB();
+            const tx = db.transaction(storeName, "readwrite");
+            const store = tx.objectStore(storeName);
+            await idbRequest(store.put(value, name));
+        },
+        async removeItem(name) {
+            const db = await getDB();
+            const tx = db.transaction(storeName, "readwrite");
+            const store = tx.objectStore(storeName);
+            await idbRequest(store.delete(name));
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakkar.software/starfish-client",
-  "version": "1.4.1",
+  "version": "1.6.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/Drakkar-Software/starfish.git",
@@ -37,6 +37,10 @@
     "./testing": {
       "types": "./dist/testing.d.ts",
       "import": "./dist/testing.js"
+    },
+    "./identity": {
+      "types": "./dist/identity.d.ts",
+      "import": "./dist/identity.js"
     }
   },
   "peerDependencies": {
@@ -60,7 +64,7 @@
     }
   },
   "dependencies": {
-    "@drakkar.software/starfish-protocol": "1.4.1"
+    "@drakkar.software/starfish-protocol": "1.5.0"
   },
   "devDependencies": {
     "@legendapp/state": "^2.0.0",

package/dist/bindings/broadcast.d.ts

@@ -1,19 +0,0 @@
-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

@@ -1,65 +0,0 @@
-/**
- * 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

@@ -1,12 +0,0 @@
-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

@@ -1,25 +0,0 @@
-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);
-}