@drakkar.software/starfish-client 2.0.0 → 2.2.0

package/dist/mobile-lifecycle.js

@@ -31,13 +31,13 @@ export function createMobileLifecycle(store, deps, options = {}) {
     const appSub = deps.appState.addEventListener("change", (appState) => {
         if (appState === "background" && flushOnBackground) {
             if (store.getState().dirty) {
-                store.getState().flush().catch(() => { });
+                store.getState().flush().catch((err) => { console.error("[Starfish] background flush failed:", err); });
             }
         }
         else if (appState === "active" && pullOnForeground) {
             const { online, syncing } = store.getState();
             if (online && !syncing) {
-                store.getState().pull().catch(() => { });
+                store.getState().pull().catch((err) => { console.error("[Starfish] foreground pull failed:", err); });
             }
         }
         // "inactive" (iOS transition) and other states are intentionally ignored

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

@@ -14,7 +14,7 @@ export function startPolling(pullFn, getState, intervalMs = 30_000) {
     const timer = setInterval(() => {
         const { online, syncing } = getState();
         if (online && !syncing)
-            pullFn().catch(() => { });
+            pullFn().catch((err) => { console.error("[Starfish] poll failed:", err); });
     }, intervalMs);
     return () => clearInterval(timer);
 }
@@ -42,7 +42,7 @@ export function startAdaptivePolling(pullFn, getState, options) {
             return;
         const { online, syncing } = getState();
         if (online && !syncing)
-            pullFn().catch(() => { });
+            pullFn().catch((err) => { console.error("[Starfish] adaptive poll failed:", err); });
     }, intervalMs);
     return {
         pause: () => { paused = true; },

package/dist/sync.d.ts

@@ -4,6 +4,9 @@ import { StarfishClient } from "./client.js";
 import type { Encryptor } from "./crypto.js";
 import type { SyncLogger } from "./logger.js";
 import type { Validator } from "./validate.js";
+export declare class AbortError extends Error {
+    constructor();
+}
 export interface SyncManagerOptions {
     client: StarfishClient;
     pullPath: string;
@@ -42,9 +45,14 @@ export declare class SyncManager {
     private lastHash;
     private lastCheckpoint;
     private localData;
+    private aborted;
     constructor(options: SyncManagerOptions);
+    abort(): void;
+    get isAborted(): boolean;
     getData(): Record<string, unknown>;
     getHash(): string | null;
+    /** Set the last-known server hash. Used by persistence layers to restore state across restarts. */
+    setHash(hash: string | null): void;
     getCheckpoint(): number;
     pull(): Promise<PullResult>;
     push(data: Record<string, unknown>): Promise<{

package/package.json

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

package/dist/append.d.ts

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

@@ -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);
-}