@drakkar.software/starfish-client 1.4.1 → 1.5.0

package/dist/background-sync.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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.
+ */
+export interface BackgroundSyncOptions {
+    /** Sync event tag. Default: "starfish-sync" */
+    tag?: string;
+}
+/** Check if the Background Sync API is supported in the current environment. */
+export declare function isBackgroundSyncSupported(): boolean;
+/**
+ * Register a background sync event with the active service worker.
+ * Returns true if registration succeeded, false if not supported or no active SW.
+ */
+export declare function registerBackgroundSync(opts?: BackgroundSyncOptions): Promise<boolean>;

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/suspense.d.ts

@@ -0,0 +1,25 @@
+/**
+ * React Suspense integration for Starfish sync data.
+ * Creates resources that throw Promises while loading (Suspense protocol).
+ */
+interface SuspenseResource<T> {
+    /** Read the resource value. Throws a Promise while pending (Suspense protocol). */
+    read(): T;
+}
+/**
+ * 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 declare function createSuspenseResource<T>(fetcher: () => Promise<T>): SuspenseResource<T>;
+export {};

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/dedup.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Request deduplication: prevents multiple concurrent identical GET requests.
+ * If a GET request is in-flight for a URL, subsequent identical GET requests
+ * return the same Promise. POST/PUT/DELETE/PATCH are never deduped.
+ */
+export declare function createDedupFetch(baseFetch?: typeof globalThis.fetch): typeof globalThis.fetch;

package/dist/dedup.js

@@ -0,0 +1,35 @@
+/**
+ * Request deduplication: prevents multiple concurrent identical GET requests.
+ * If a GET request is in-flight for a URL, subsequent identical GET requests
+ * return the same Promise. POST/PUT/DELETE/PATCH are never deduped.
+ */
+export function createDedupFetch(baseFetch = globalThis.fetch.bind(globalThis)) {
+    const inflightGets = new Map();
+    return (async (input, init) => {
+        const method = (init?.method ?? "GET").toUpperCase();
+        // Only dedup GET requests
+        if (method !== "GET") {
+            return baseFetch(input, init);
+        }
+        const url = typeof input === "string"
+            ? input
+            : input instanceof URL
+                ? input.toString()
+                : input.url;
+        const existing = inflightGets.get(url);
+        if (existing) {
+            // Return a clone — the original is reserved for cloning only
+            return existing.then((res) => res.clone());
+        }
+        // Store a promise that resolves to a response we keep solely for cloning.
+        // The first caller also gets a clone, ensuring the "master" body is never consumed.
+        const promise = baseFetch(input, init)
+            .then((res) => res)
+            .finally(() => {
+            inflightGets.delete(url);
+        });
+        inflightGets.set(url, promise);
+        // First caller also gets a clone so the cached response body stays unconsumed
+        return promise.then((res) => res.clone());
+    });
+}

package/dist/export.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Data export/import helpers for Starfish sync data.
+ * Supports JSON and CSV formats.
+ */
+export interface ExportOptions {
+    /** Output format. Default: "json" */
+    format?: "json" | "csv";
+    /** Pretty-print JSON output. Default: false */
+    pretty?: boolean;
+}
+/**
+ * Export data to a string representation.
+ * JSON: serializes the full object.
+ * CSV: flattens top-level keys into columns. Array values are JSON-encoded.
+ */
+export declare function exportData(data: Record<string, unknown>, opts?: ExportOptions): string;
+/**
+ * Import data from a string representation.
+ */
+export declare function importData(raw: string, format?: "json" | "csv"): Record<string, unknown>;
+/**
+ * Export data to a Blob suitable for download.
+ */
+export declare function exportToBlob(data: Record<string, unknown>, opts?: ExportOptions): Blob;

package/dist/export.js

@@ -0,0 +1,115 @@
+/**
+ * Data export/import helpers for Starfish sync data.
+ * Supports JSON and CSV formats.
+ */
+/**
+ * Export data to a string representation.
+ * JSON: serializes the full object.
+ * CSV: flattens top-level keys into columns. Array values are JSON-encoded.
+ */
+export function exportData(data, opts) {
+    const format = opts?.format ?? "json";
+    if (format === "json") {
+        return opts?.pretty
+            ? JSON.stringify(data, null, 2)
+            : JSON.stringify(data);
+    }
+    // CSV export: each top-level key becomes a column
+    return toCsv(data);
+}
+/**
+ * Import data from a string representation.
+ */
+export function importData(raw, format = "json") {
+    if (format === "json") {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            throw new Error("Expected a JSON object");
+        }
+        return parsed;
+    }
+    return fromCsv(raw);
+}
+/**
+ * Export data to a Blob suitable for download.
+ */
+export function exportToBlob(data, opts) {
+    const format = opts?.format ?? "json";
+    const content = exportData(data, opts);
+    const mimeType = format === "csv" ? "text/csv;charset=utf-8" : "application/json;charset=utf-8";
+    return new Blob([content], { type: mimeType });
+}
+function toCsv(data) {
+    const keys = Object.keys(data);
+    const header = keys.map(escapeCsvField).join(",");
+    const values = keys.map((k) => {
+        const v = data[k];
+        if (v === null || v === undefined)
+            return "";
+        if (typeof v === "object")
+            return escapeCsvField(JSON.stringify(v));
+        return escapeCsvField(String(v));
+    });
+    return `${header}\n${values.join(",")}`;
+}
+function fromCsv(raw) {
+    const lines = raw.trim().split("\n");
+    if (lines.length < 2) {
+        throw new Error("CSV must have at least a header row and a data row");
+    }
+    const headers = parseCsvLine(lines[0]);
+    const values = parseCsvLine(lines[1]);
+    const result = {};
+    for (let i = 0; i < headers.length; i++) {
+        const key = headers[i];
+        const val = values[i] ?? "";
+        // Try to parse JSON values
+        try {
+            result[key] = JSON.parse(val);
+        }
+        catch {
+            result[key] = val;
+        }
+    }
+    return result;
+}
+function escapeCsvField(field) {
+    if (field.includes(",") || field.includes('"') || field.includes("\n")) {
+        return `"${field.replace(/"/g, '""')}"`;
+    }
+    return field;
+}
+function parseCsvLine(line) {
+    const result = [];
+    let current = "";
+    let inQuotes = false;
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        if (inQuotes) {
+            if (ch === '"' && line[i + 1] === '"') {
+                current += '"';
+                i++;
+            }
+            else if (ch === '"') {
+                inQuotes = false;
+            }
+            else {
+                current += ch;
+            }
+        }
+        else {
+            if (ch === '"') {
+                inQuotes = true;
+            }
+            else if (ch === ",") {
+                result.push(current);
+                current = "";
+            }
+            else {
+                current += ch;
+            }
+        }
+    }
+    result.push(current);
+    return result;
+}

package/dist/hash.d.ts

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

@@ -0,0 +1,34 @@
+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/index.d.ts

@@ -10,16 +10,27 @@ export { createEncryptor, ENCRYPTED_KEY } from "./crypto.js";
 export type { Encryptor } from "./crypto.js";
 export { ConflictError, StarfishHttpError, } from "./types.js";
 export type { StarfishClientOptions, AuthProvider, ConflictResolver, } from "./types.js";
-export { consoleSyncLogger, noopSyncLogger } from "./logger.js";
-export type { SyncLogger } from "./logger.js";
+export { consoleSyncLogger, noopSyncLogger, createMetricsCollector } from "./logger.js";
+export type { SyncLogger, SyncMetrics, MetricsCollector } from "./logger.js";
 export { createMigrator } from "./migrate.js";
 export type { MigrationFn, MigrationConfig } from "./migrate.js";
 export { ValidationError, createSchemaValidator } from "./validate.js";
 export type { Validator, ValidationResult } from "./validate.js";
 export { classifyError } from "./fetch.js";
 export type { ErrorCategory } from "./fetch.js";
-export { createUnionMerge, createSoftDeleteResolver, timestampWinner, pruneTombstones, } from "./resolvers.js";
+export { createUnionMerge, createSoftDeleteResolver, timestampWinner, pruneTombstones, withConflictMeta, } from "./resolvers.js";
+export type { ConflictMeta, ConflictResolverWithMeta } from "./resolvers.js";
 export { SnapshotHistory } from "./history.js";
 export type { Snapshot, SnapshotHistoryOptions } from "./history.js";
 export { startPolling, startAdaptivePolling } from "./polling.js";
 export type { PollableState, AdaptivePollingOptions, AdaptivePollingControls } from "./polling.js";
+export { createDedupFetch } from "./dedup.js";
+export { createIndexedDBStorage } from "./storage/indexeddb.js";
+export type { IndexedDBStorageOptions, AsyncStateStorage } from "./storage/indexeddb.js";
+export { exportData, importData, exportToBlob } from "./export.js";
+export type { ExportOptions } from "./export.js";
+export { isBackgroundSyncSupported, registerBackgroundSync } from "./background-sync.js";
+export type { BackgroundSyncOptions } from "./background-sync.js";
+export { isServiceWorkerSupported, registerServiceWorker, unregisterServiceWorkers } from "./service-worker.js";
+export type { ServiceWorkerOptions } from "./service-worker.js";
+export { createSuspenseResource } from "./bindings/suspense.js";

package/dist/index.js

@@ -4,10 +4,16 @@ export { StarfishClient } from "./client.js";
 export { SyncManager } from "./sync.js";
 export { createEncryptor, ENCRYPTED_KEY } from "./crypto.js";
 export { ConflictError, StarfishHttpError, } from "./types.js";
-export { consoleSyncLogger, noopSyncLogger } from "./logger.js";
+export { consoleSyncLogger, noopSyncLogger, createMetricsCollector } from "./logger.js";
 export { createMigrator } from "./migrate.js";
 export { ValidationError, createSchemaValidator } from "./validate.js";
 export { classifyError } from "./fetch.js";
-export { createUnionMerge, createSoftDeleteResolver, timestampWinner, pruneTombstones, } from "./resolvers.js";
+export { createUnionMerge, createSoftDeleteResolver, timestampWinner, pruneTombstones, withConflictMeta, } from "./resolvers.js";
 export { SnapshotHistory } from "./history.js";
 export { startPolling, startAdaptivePolling } from "./polling.js";
+export { createDedupFetch } from "./dedup.js";
+export { createIndexedDBStorage } from "./storage/indexeddb.js";
+export { exportData, importData, exportToBlob } from "./export.js";
+export { isBackgroundSyncSupported, registerBackgroundSync } from "./background-sync.js";
+export { isServiceWorkerSupported, registerServiceWorker, unregisterServiceWorkers } from "./service-worker.js";
+export { createSuspenseResource } from "./bindings/suspense.js";

package/dist/logger.d.ts

@@ -1,10 +1,18 @@
+/** Extended metrics for sync operations. */
+export interface SyncMetrics {
+    bytesTransferred?: number;
+    compressedSize?: number;
+    conflictCount?: number;
+    retryCount?: number;
+    cacheHit?: boolean;
+}
 /** Structured logger for sync operations. */
 export interface SyncLogger {
     pullStart(store: string): void;
-    pullSuccess(store: string, durationMs: number): void;
+    pullSuccess(store: string, durationMs: number, metrics?: SyncMetrics): void;
     pullError(store: string, error: string): void;
     pushStart(store: string): void;
-    pushSuccess(store: string, durationMs: number): void;
+    pushSuccess(store: string, durationMs: number, metrics?: SyncMetrics): void;
     pushError(store: string, error: string): void;
     conflict(store: string, attempt: number): void;
 }
@@ -12,3 +20,19 @@ export interface SyncLogger {
 export declare const consoleSyncLogger: SyncLogger;
 /** Silent sync logger (no output). */
 export declare const noopSyncLogger: SyncLogger;
+/** Collects sync metrics over time. */
+export interface MetricsCollector {
+    recordPull(name: string, durationMs: number, metrics?: SyncMetrics): void;
+    recordPush(name: string, durationMs: number, metrics?: SyncMetrics): void;
+    recordConflict(name: string): void;
+    getSummary(): Record<string, {
+        totalPulls: number;
+        totalPushes: number;
+        avgDurationMs: number;
+        totalBytes: number;
+        totalConflicts: number;
+    }>;
+    reset(): void;
+}
+/** Create a metrics collector that accumulates sync statistics. */
+export declare function createMetricsCollector(): MetricsCollector;

package/dist/logger.js

@@ -1,10 +1,22 @@
 /** Console-based sync logger with structured output. */
 export const consoleSyncLogger = {
     pullStart: (s) => console.log(`[starfish:${s}] pull started`),
-    pullSuccess: (s, ms) => console.log(`[starfish:${s}] pull OK (${ms}ms)`),
+    pullSuccess: (s, ms, m) => {
+        let msg = `[starfish:${s}] pull OK (${ms}ms)`;
+        if (m?.bytesTransferred)
+            msg += ` ${m.bytesTransferred}B`;
+        if (m?.cacheHit)
+            msg += ` (cache hit)`;
+        console.log(msg);
+    },
     pullError: (s, err) => console.error(`[starfish:${s}] pull failed: ${err}`),
     pushStart: (s) => console.log(`[starfish:${s}] push started`),
-    pushSuccess: (s, ms) => console.log(`[starfish:${s}] push OK (${ms}ms)`),
+    pushSuccess: (s, ms, m) => {
+        let msg = `[starfish:${s}] push OK (${ms}ms)`;
+        if (m?.bytesTransferred)
+            msg += ` ${m.bytesTransferred}B`;
+        console.log(msg);
+    },
     pushError: (s, err) => console.error(`[starfish:${s}] push failed: ${err}`),
     conflict: (s, n) => console.warn(`[starfish:${s}] conflict (attempt ${n})`),
 };
@@ -18,3 +30,51 @@ export const noopSyncLogger = {
     pushError: () => { },
     conflict: () => { },
 };
+/** Create a metrics collector that accumulates sync statistics. */
+export function createMetricsCollector() {
+    const stores = new Map();
+    function ensureStore(name) {
+        let s = stores.get(name);
+        if (!s) {
+            s = { totalPulls: 0, totalPushes: 0, totalDurationMs: 0, totalBytes: 0, totalConflicts: 0 };
+            stores.set(name, s);
+        }
+        return s;
+    }
+    return {
+        recordPull(name, durationMs, metrics) {
+            const s = ensureStore(name);
+            s.totalPulls++;
+            s.totalDurationMs += durationMs;
+            if (metrics?.bytesTransferred)
+                s.totalBytes += metrics.bytesTransferred;
+        },
+        recordPush(name, durationMs, metrics) {
+            const s = ensureStore(name);
+            s.totalPushes++;
+            s.totalDurationMs += durationMs;
+            if (metrics?.bytesTransferred)
+                s.totalBytes += metrics.bytesTransferred;
+        },
+        recordConflict(name) {
+            ensureStore(name).totalConflicts++;
+        },
+        getSummary() {
+            const result = {};
+            for (const [name, s] of stores) {
+                const totalOps = s.totalPulls + s.totalPushes;
+                result[name] = {
+                    totalPulls: s.totalPulls,
+                    totalPushes: s.totalPushes,
+                    avgDurationMs: totalOps > 0 ? Math.round(s.totalDurationMs / totalOps) : 0,
+                    totalBytes: s.totalBytes,
+                    totalConflicts: s.totalConflicts,
+                };
+            }
+            return result;
+        },
+        reset() {
+            stores.clear();
+        },
+    };
+}

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.5.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/Drakkar-Software/starfish.git",
@@ -60,7 +60,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);
-}