@drakkar.software/starfish-client 1.4.1 → 1.6.0

package/dist/identity.d.ts

@@ -0,0 +1,72 @@
+declare const WORDLIST: string[];
+/** Credentials derived from a passphrase. Pass directly to SyncManager / StarfishClient. */
+export interface DerivedCredentials {
+    /** Hex-encoded auth token. Use as `Bearer ${authToken}` in request headers. */
+    authToken: string;
+    /**
+     * Short identifier derived from the auth token (first 16 hex chars = 8 bytes).
+     * Used as the user/namespace segment in collection paths.
+     */
+    userId: string;
+    /**
+     * Hex-encoded key suitable as `encryptionSecret` for SyncManager.
+     * Combined with `encryptionSalt` to derive the AES-256-GCM key via HKDF.
+     */
+    encryptionSecret: string;
+    /**
+     * Value suitable as `encryptionSalt` for SyncManager. Equals `userId`.
+     * Using a per-identity salt ensures that even if two users share a passphrase,
+     * their encryption keys are different.
+     */
+    encryptionSalt: string;
+}
+/**
+ * Generates a cryptographically random passphrase from the built-in 256-word list.
+ *
+ * Each word represents one byte of entropy (256 words = one byte per word, zero modulo bias).
+ * A 12-word passphrase gives 96 bits of entropy — stronger than a random UUID.
+ *
+ * @param wordCount Number of words (default: 12).
+ * @param wordlist Custom word list (must have exactly 256 entries).
+ */
+export declare function generatePassphrase(wordCount?: number, wordlist?: string[]): string;
+/**
+ * Derives auth credentials from a passphrase.
+ *
+ * All derivations are deterministic — the same passphrase always produces the same credentials.
+ * Sharing the passphrase grants access on any device.
+ *
+ * The returned values map directly to Starfish options:
+ * ```ts
+ * const creds = await deriveCredentials(passphrase)
+ *
+ * const client = new StarfishClient({
+ *   baseUrl: serverUrl,
+ *   auth: () => ({ Authorization: `Bearer ${creds.authToken}` }),
+ * })
+ * const syncManager = new SyncManager({
+ *   client,
+ *   pullPath: `/pull/${creds.userId}/wedding`,
+ *   pushPath: `/push/${creds.userId}/wedding`,
+ *   encryptionSecret: creds.encryptionSecret,
+ *   encryptionSalt: creds.encryptionSalt,
+ * })
+ * ```
+ */
+export declare function deriveCredentials(passphrase: string): Promise<DerivedCredentials>;
+/**
+ * Encodes an invite payload as a URL-safe token and appends it as `?t=<token>`.
+ *
+ * ```ts
+ * const url = buildInviteUrl("myapp://join", { name: "Alice & Bob", p: passphrase })
+ * // → "myapp://join?t=eyJuYW1lIjoiQWxpY2UgJiBCb2IifQ"
+ * ```
+ */
+export declare function buildInviteUrl(baseUrl: string, payload: Record<string, unknown>): string;
+/**
+ * Decodes an invite URL produced by `buildInviteUrl`.
+ *
+ * Returns the decoded payload, or `null` if the URL is missing or malformed.
+ */
+export declare function parseInviteUrl(url: string): Record<string, unknown> | null;
+export { WORDLIST as DEFAULT_WORDLIST };

package/dist/identity.js

@@ -0,0 +1,161 @@
+import { getCrypto, getBase64 } from "@drakkar.software/starfish-protocol";
+// ── Word list ─────────────────────────────────────────────────────────────────
+// 256 common English words, one per index (0-255). One byte of entropy per word.
+// 12 words = 96 bits of entropy (stronger than a random UUID).
+const WORDLIST = [
+    "able", "acid", "aged", "also", "area", "army", "away", "back",
+    "ball", "band", "bank", "base", "bath", "bean", "bear", "beat",
+    "bell", "best", "bird", "blue", "boat", "bold", "bolt", "bone",
+    "born", "bowl", "burn", "calm", "call", "camp", "card", "care",
+    "cash", "cast", "cave", "city", "clam", "clay", "clip", "coal",
+    "coat", "coin", "cold", "cook", "cool", "corn", "cost", "cozy",
+    "dark", "data", "dawn", "dead", "deal", "deck", "deep", "dew",
+    "dish", "dome", "door", "down", "draw", "drop", "drum", "dusk",
+    "dust", "each", "earn", "east", "edge", "even", "ever", "face",
+    "fact", "fair", "fall", "fame", "farm", "fast", "felt", "file",
+    "fill", "fire", "fish", "fist", "flag", "flat", "flew", "flow",
+    "foam", "fold", "fond", "food", "foot", "form", "frog", "fuel",
+    "full", "gain", "game", "gate", "gave", "gaze", "gift", "glad",
+    "glow", "glue", "goal", "good", "grab", "gray", "grip", "grow",
+    "gulf", "gust", "half", "hall", "hand", "hard", "harm", "have",
+    "hawk", "head", "heal", "heap", "heat", "held", "helm", "help",
+    "herb", "here", "hero", "high", "hill", "hint", "hold", "hole",
+    "home", "hope", "horn", "hour", "huge", "hunt", "idea", "inch",
+    "into", "iris", "isle", "jade", "jail", "join", "jump", "just",
+    "keep", "kind", "king", "knot", "know", "lack", "lake", "land",
+    "lane", "last", "late", "lawn", "lead", "leaf", "lean", "leap",
+    "left", "lend", "less", "life", "lift", "like", "lime", "line",
+    "lion", "list", "live", "load", "lock", "loft", "long", "look",
+    "loop", "loud", "love", "luck", "lung", "made", "main", "mark",
+    "mast", "math", "maze", "meal", "meet", "melt", "mild", "mind",
+    "mint", "mist", "mode", "moon", "more", "most", "move", "much",
+    "must", "name", "near", "neck", "need", "next", "nice", "nine",
+    "none", "noon", "note", "noun", "oath", "once", "open", "oval",
+    "over", "pack", "page", "paid", "pain", "pale", "palm", "park",
+    "part", "path", "pave", "peak", "pier", "pile", "pine", "pipe",
+    "plan", "plum", "poem", "pole", "pool", "port", "pose", "post",
+    "pray", "prey", "pull", "pure", "push", "quit", "race", "rack",
+];
+// ── Helpers ───────────────────────────────────────────────────────────────────
+function bytesToHex(bytes) {
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+async function sha256Hex(input) {
+    const c = getCrypto();
+    const encoded = new TextEncoder().encode(input);
+    const hash = await c.subtle.digest("SHA-256", encoded);
+    return bytesToHex(new Uint8Array(hash));
+}
+// URL-safe base64 (RFC 4648 §5): replaces + → -, / → _, strips trailing =
+function base64UrlEncode(data) {
+    const b64 = getBase64();
+    return b64
+        .encode(data)
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/, "");
+}
+function base64UrlDecode(encoded) {
+    const b64 = getBase64();
+    // Restore standard base64 padding
+    const padded = encoded.replace(/-/g, "+").replace(/_/g, "/");
+    const rem = padded.length % 4;
+    const padded2 = rem === 0 ? padded : padded + "=".repeat(4 - rem);
+    return b64.decode(padded2);
+}
+// ── Public API ────────────────────────────────────────────────────────────────
+/**
+ * Generates a cryptographically random passphrase from the built-in 256-word list.
+ *
+ * Each word represents one byte of entropy (256 words = one byte per word, zero modulo bias).
+ * A 12-word passphrase gives 96 bits of entropy — stronger than a random UUID.
+ *
+ * @param wordCount Number of words (default: 12).
+ * @param wordlist Custom word list (must have exactly 256 entries).
+ */
+export function generatePassphrase(wordCount = 12, wordlist = WORDLIST) {
+    if (wordlist.length !== 256) {
+        throw new Error(`Word list must have exactly 256 entries, got ${wordlist.length}`);
+    }
+    const c = getCrypto();
+    const bytes = c.getRandomValues(new Uint8Array(wordCount));
+    return Array.from(bytes, (b) => wordlist[b]).join(" ");
+}
+/**
+ * Derives auth credentials from a passphrase.
+ *
+ * All derivations are deterministic — the same passphrase always produces the same credentials.
+ * Sharing the passphrase grants access on any device.
+ *
+ * The returned values map directly to Starfish options:
+ * ```ts
+ * const creds = await deriveCredentials(passphrase)
+ *
+ * const client = new StarfishClient({
+ *   baseUrl: serverUrl,
+ *   auth: () => ({ Authorization: `Bearer ${creds.authToken}` }),
+ * })
+ * const syncManager = new SyncManager({
+ *   client,
+ *   pullPath: `/pull/${creds.userId}/wedding`,
+ *   pushPath: `/push/${creds.userId}/wedding`,
+ *   encryptionSecret: creds.encryptionSecret,
+ *   encryptionSalt: creds.encryptionSalt,
+ * })
+ * ```
+ */
+export async function deriveCredentials(passphrase) {
+    if (!passphrase.trim())
+        throw new Error("Passphrase must not be empty");
+    // authToken = SHA-256(passphrase) — used as Bearer token
+    const authToken = await sha256Hex(passphrase);
+    // userId = first 16 hex chars of authToken (8 bytes)
+    const userId = authToken.slice(0, 16);
+    // encryptionSecret = SHA-256(passphrase + ":" + userId)
+    // Domain separation from authToken ensures they cannot be recovered from each other.
+    const encryptionSecret = await sha256Hex(`${passphrase}:${userId}`);
+    return {
+        authToken,
+        userId,
+        encryptionSecret,
+        encryptionSalt: userId,
+    };
+}
+/**
+ * Encodes an invite payload as a URL-safe token and appends it as `?t=<token>`.
+ *
+ * ```ts
+ * const url = buildInviteUrl("myapp://join", { name: "Alice & Bob", p: passphrase })
+ * // → "myapp://join?t=eyJuYW1lIjoiQWxpY2UgJiBCb2IifQ"
+ * ```
+ */
+export function buildInviteUrl(baseUrl, payload) {
+    const json = JSON.stringify(payload);
+    const bytes = new TextEncoder().encode(json);
+    const token = base64UrlEncode(bytes);
+    const separator = baseUrl.includes("?") ? "&" : "?";
+    return `${baseUrl}${separator}t=${token}`;
+}
+/**
+ * Decodes an invite URL produced by `buildInviteUrl`.
+ *
+ * Returns the decoded payload, or `null` if the URL is missing or malformed.
+ */
+export function parseInviteUrl(url) {
+    try {
+        const tokenMatch = url.match(/[?&]t=([^&]+)/);
+        if (!tokenMatch?.[1])
+            return null;
+        const bytes = base64UrlDecode(tokenMatch[1]);
+        const json = new TextDecoder().decode(bytes);
+        const parsed = JSON.parse(json);
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+// Export word list for consumers that want to provide localized alternatives
+export { WORDLIST as DEFAULT_WORDLIST };

package/dist/index.d.ts

@@ -10,16 +10,31 @@ 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";
+export { createDebouncedSync } from "./debounced-sync.js";
+export type { DebouncedSyncOptions, DebouncedSync } from "./debounced-sync.js";
+export { createMultiStoreSync } from "./multi-store.js";
+export type { StoreSlice, BackupDocument, MultiStoreMigrationFn, MultiStoreSyncOptions, MultiStoreSync, } from "./multi-store.js";

package/dist/index.js

@@ -4,10 +4,18 @@ 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";
+export { createDebouncedSync } from "./debounced-sync.js";
+export { createMultiStoreSync } from "./multi-store.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/multi-store.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Serializer/deserializer pair for one slice of application state.
+ *
+ * `serialize` snapshots the current state into a plain object.
+ * `restore` applies a snapshot (potentially from a different app version after migration).
+ */
+export interface StoreSlice<T = unknown> {
+    /**
+     * Snapshot the current state of this slice into a serializable value.
+     * Called during `serialize()`.
+     */
+    serialize: () => T;
+    /**
+     * Apply a snapshot to this slice.
+     * Called during `restore()` — data may be from an older schema version after migration.
+     */
+    restore: (data: T) => void;
+}
+/**
+ * A versioned backup document produced by `MultiStoreSync.serialize()`.
+ * Safe to pass to `store.set()` as the Starfish sync document.
+ */
+export interface BackupDocument<T = Record<string, unknown>> {
+    /** Schema version declared in `createMultiStoreSync`. */
+    version: number;
+    /** Unix timestamp (ms) when this backup was created. */
+    timestamp: number;
+    /** Serialized slice data, keyed by slice name. */
+    data: T;
+}
+/**
+ * A migration function that transforms data from one version to the next.
+ * Receives the full `data` object and must return an updated `data` object.
+ * Only the `data` field is passed; `version` and `timestamp` are managed automatically.
+ */
+export type MultiStoreMigrationFn = (data: Record<string, unknown>) => Record<string, unknown>;
+export interface MultiStoreSyncOptions<T extends Record<string, unknown>> {
+    /**
+     * Named slices to include in the backup document.
+     * Each slice provides `serialize()` and `restore()` methods.
+     *
+     * @example
+     * ```ts
+     * slices: {
+     *   tasks: {
+     *     serialize: () => taskStore.getState().tasks,
+     *     restore: (data) => taskStore.setState({ tasks: data }),
+     *   },
+     *   settings: {
+     *     serialize: () => settingsStore.getState().settings,
+     *     restore: (data) => settingsStore.setState({ settings: data }),
+     *   },
+     * }
+     * ```
+     */
+    slices: {
+        [K in keyof T]: StoreSlice<T[K]>;
+    };
+    /**
+     * Current schema version. Increment when slices are added, renamed, or their shape changes.
+     * Used to detect forward-incompatible documents from future app versions.
+     */
+    version: number;
+    /**
+     * Optional migration chain. Key is the version number that produced the data;
+     * value is a function that upgrades it to the next version.
+     *
+     * Migrations run sequentially from the document version up to the current version.
+     *
+     * @example
+     * ```ts
+     * migrations: {
+     *   1: (data) => ({ ...data, settings: { ...data.settings, theme: "light" } }),
+     *   2: (data) => ({ ...data, tasks: data.todos, todos: undefined }),
+     * }
+     * ```
+     */
+    migrations?: Record<number, MultiStoreMigrationFn>;
+}
+/**
+ * Returned by `createMultiStoreSync`. Serialize and restore coordinated multi-store state.
+ */
+export interface MultiStoreSync<T extends Record<string, unknown>> {
+    /**
+     * Snapshot all slices into a `BackupDocument`.
+     * Pass the result to `starfishStore.getState().set(() => multiSync.serialize())`.
+     */
+    serialize: () => BackupDocument<T>;
+    /**
+     * Apply a `BackupDocument` to all slices, running migrations as needed.
+     *
+     * Throws if the document version is newer than the current version (forward-incompatible).
+     * Silently migrates older documents.
+     */
+    restore: (doc: BackupDocument) => void;
+    /** Current schema version as declared in options. */
+    readonly version: number;
+}
+/**
+ * Creates a multi-store sync coordinator.
+ *
+ * Collects multiple application stores into a single Starfish sync document,
+ * with versioned schema migrations for backward compatibility.
+ *
+ * ```ts
+ * const multiSync = createMultiStoreSync({
+ *   slices: {
+ *     tasks: {
+ *       serialize: () => taskStore.getState().tasks,
+ *       restore: (tasks) => taskStore.setState({ tasks }),
+ *     },
+ *     settings: {
+ *       serialize: () => settingsStore.getState().settings,
+ *       restore: (settings) => settingsStore.setState({ settings }),
+ *     },
+ *   },
+ *   version: 2,
+ *   migrations: {
+ *     // data from version 1 → upgrade to version 2
+ *     1: (data) => ({ ...data, settings: { ...(data.settings as object), darkMode: false } }),
+ *   },
+ * })
+ *
+ * // Push:
+ * starfishStore.getState().set(() => multiSync.serialize())
+ *
+ * // Restore on pull (pass as onRemoteUpdate to createStarfishStore):
+ * createStarfishStore({
+ *   name: "app",
+ *   syncManager,
+ *   onRemoteUpdate: (doc) => multiSync.restore(doc as BackupDocument),
+ * })
+ * ```
+ */
+export declare function createMultiStoreSync<T extends Record<string, unknown>>(options: MultiStoreSyncOptions<T>): MultiStoreSync<T>;

package/dist/multi-store.js

@@ -0,0 +1,92 @@
+// ── Types ─────────────────────────────────────────────────────────────────────
+// ── Implementation ────────────────────────────────────────────────────────────
+/**
+ * Creates a multi-store sync coordinator.
+ *
+ * Collects multiple application stores into a single Starfish sync document,
+ * with versioned schema migrations for backward compatibility.
+ *
+ * ```ts
+ * const multiSync = createMultiStoreSync({
+ *   slices: {
+ *     tasks: {
+ *       serialize: () => taskStore.getState().tasks,
+ *       restore: (tasks) => taskStore.setState({ tasks }),
+ *     },
+ *     settings: {
+ *       serialize: () => settingsStore.getState().settings,
+ *       restore: (settings) => settingsStore.setState({ settings }),
+ *     },
+ *   },
+ *   version: 2,
+ *   migrations: {
+ *     // data from version 1 → upgrade to version 2
+ *     1: (data) => ({ ...data, settings: { ...(data.settings as object), darkMode: false } }),
+ *   },
+ * })
+ *
+ * // Push:
+ * starfishStore.getState().set(() => multiSync.serialize())
+ *
+ * // Restore on pull (pass as onRemoteUpdate to createStarfishStore):
+ * createStarfishStore({
+ *   name: "app",
+ *   syncManager,
+ *   onRemoteUpdate: (doc) => multiSync.restore(doc as BackupDocument),
+ * })
+ * ```
+ */
+export function createMultiStoreSync(options) {
+    const { slices, version, migrations = {} } = options;
+    // Validate migration chain at construction time (fail fast)
+    for (const fromVersion of Object.keys(migrations)) {
+        const v = Number(fromVersion);
+        if (isNaN(v) || v < 1) {
+            throw new Error(`Migration key must be a positive integer, got: "${fromVersion}"`);
+        }
+    }
+    function serialize() {
+        const data = {};
+        for (const key of Object.keys(slices)) {
+            data[key] = slices[key].serialize();
+        }
+        return { version, timestamp: Date.now(), data };
+    }
+    function restore(doc) {
+        if (typeof doc !== "object" || doc === null) {
+            throw new Error("restore: expected a BackupDocument object");
+        }
+        const docVersion = doc.version ?? 1;
+        if (typeof docVersion !== "number" || !Number.isInteger(docVersion) || docVersion < 1) {
+            throw new Error(`restore: invalid document version: ${String(doc.version)}`);
+        }
+        if (docVersion > version) {
+            throw new Error(`restore: document version ${docVersion} is newer than current version ${version}. ` +
+                `Update the app to restore this backup.`);
+        }
+        // Run migrations sequentially from docVersion up to current version
+        let data = typeof doc.data === "object" && doc.data !== null
+            ? { ...doc.data }
+            : {};
+        for (let v = docVersion; v < version; v++) {
+            const migration = migrations[v];
+            if (!migration)
+                continue;
+            try {
+                data = migration(data);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                throw new Error(`restore: migration from version ${v} to ${v + 1} failed: ${msg}`);
+            }
+        }
+        // Restore each slice
+        for (const key of Object.keys(slices)) {
+            const sliceData = data[key];
+            if (sliceData !== undefined) {
+                slices[key].restore(sliceData);
+            }
+        }
+    }
+    return { serialize, restore, version };
+}