@drakkar.software/starfish-client 1.3.2 → 1.4.1

package/dist/fetch.d.ts

@@ -0,0 +1,53 @@
+/** Error category returned by classifyError. */
+export type ErrorCategory = "network" | "auth" | "conflict" | "rate-limited" | "server" | "client" | "unknown";
+/** Classify an error from a fetch response or network failure. */
+export declare function classifyError(err: unknown): ErrorCategory;
+export interface RetryOptions {
+    /** Max number of retries (default: 3). */
+    maxRetries?: number;
+    /** Initial delay in ms before first retry (default: 500). */
+    initialDelayMs?: number;
+    /** Maximum delay in ms (default: 10000). */
+    maxDelayMs?: number;
+}
+/**
+ * Wraps a fetch function with automatic retry for retriable errors
+ * (network failures, 429, 5xx). Respects Retry-After headers.
+ */
+export declare function createRetryFetch(options?: RetryOptions): typeof globalThis.fetch;
+type BreakerState = "closed" | "open" | "half-open";
+export interface CircuitBreakerOptions {
+    /** Number of consecutive failures to open the circuit (default: 5). */
+    threshold?: number;
+    /** Cooldown in ms before transitioning from open to half-open (default: 30000). */
+    cooldownMs?: number;
+}
+/** Circuit breaker that prevents requests when the backend is unavailable. */
+export declare class CircuitBreaker {
+    private state;
+    private failures;
+    private openedAt;
+    private readonly threshold;
+    private readonly cooldownMs;
+    constructor(options?: CircuitBreakerOptions);
+    getState(): BreakerState;
+    isOpen(): boolean;
+    recordSuccess(): void;
+    recordFailure(): void;
+    private maybeTransition;
+}
+/**
+ * Wraps fetch to gzip-compress string request bodies using the CompressionStream API.
+ * Adds Content-Encoding: gzip header. Non-string bodies (ArrayBuffer, Blob, etc.)
+ * are passed through uncompressed. Requires CompressionStream (browsers, Node.js 18+, Deno).
+ */
+export declare function createCompressedFetch(inner?: typeof globalThis.fetch): typeof globalThis.fetch;
+/**
+ * Combines retry and circuit breaker into a single resilient fetch wrapper.
+ * Rejects immediately when the circuit is open.
+ */
+export declare function createResilientFetch(retryOptions?: RetryOptions, breakerOptions?: CircuitBreakerOptions): {
+    fetch: typeof globalThis.fetch;
+    breaker: CircuitBreaker;
+};
+export {};

package/dist/fetch.js

@@ -0,0 +1,166 @@
+/** Classify an error from a fetch response or network failure. */
+export function classifyError(err) {
+    if (err instanceof Response || (err && typeof err === "object" && "status" in err)) {
+        const status = err.status;
+        if (typeof status !== "number" || isNaN(status))
+            return "unknown";
+        if (status === 0)
+            return "network";
+        if (status === 401 || status === 403)
+            return "auth";
+        if (status === 409)
+            return "conflict";
+        if (status === 429)
+            return "rate-limited";
+        if (status >= 500)
+            return "server";
+        if (status >= 400)
+            return "client";
+    }
+    if (err instanceof Error && /failed to fetch|fetch failed|network|load failed|ECONNREFUSED|ENOTFOUND/i.test(err.message))
+        return "network";
+    return "unknown";
+}
+/**
+ * Wraps a fetch function with automatic retry for retriable errors
+ * (network failures, 429, 5xx). Respects Retry-After headers.
+ */
+export function createRetryFetch(options) {
+    const maxRetries = Math.max(0, options?.maxRetries ?? 3);
+    const initialDelay = options?.initialDelayMs ?? 500;
+    const maxDelay = options?.maxDelayMs ?? 10_000;
+    return async (input, init) => {
+        let attempt = 0;
+        while (true) {
+            try {
+                const res = await globalThis.fetch(input, init);
+                if (res.ok || attempt >= maxRetries)
+                    return res;
+                const category = classifyError(res);
+                if (category !== "rate-limited" && category !== "server")
+                    return res;
+                const retryAfter = res.headers.get("Retry-After")?.trim();
+                let delay;
+                if (retryAfter) {
+                    const seconds = Number(retryAfter);
+                    if (retryAfter !== "" && !isNaN(seconds)) {
+                        delay = Math.min(seconds * 1000, maxDelay);
+                    }
+                    else {
+                        const date = Date.parse(retryAfter);
+                        delay = isNaN(date) ? initialDelay : Math.min(Math.max(date - Date.now(), 0), maxDelay);
+                    }
+                }
+                else {
+                    delay = Math.min(initialDelay * Math.pow(2, attempt), maxDelay);
+                }
+                await new Promise((r) => setTimeout(r, delay));
+                attempt++;
+            }
+            catch (err) {
+                if (attempt >= maxRetries)
+                    throw err;
+                const category = classifyError(err);
+                if (category !== "network")
+                    throw err;
+                const delay = Math.min(initialDelay * Math.pow(2, attempt), maxDelay);
+                await new Promise((r) => setTimeout(r, delay));
+                attempt++;
+            }
+        }
+    };
+}
+/** Circuit breaker that prevents requests when the backend is unavailable. */
+export class CircuitBreaker {
+    state = "closed";
+    failures = 0;
+    openedAt = 0;
+    threshold;
+    cooldownMs;
+    constructor(options) {
+        this.threshold = options?.threshold ?? 5;
+        this.cooldownMs = options?.cooldownMs ?? 30_000;
+    }
+    getState() {
+        this.maybeTransition();
+        return this.state;
+    }
+    isOpen() {
+        return this.getState() === "open";
+    }
+    recordSuccess() {
+        this.failures = 0;
+        this.state = "closed";
+    }
+    recordFailure() {
+        this.failures++;
+        if (this.state === "half-open" || this.failures >= this.threshold) {
+            this.state = "open";
+            this.openedAt = Date.now();
+        }
+    }
+    maybeTransition() {
+        if (this.state === "open" && Date.now() - this.openedAt >= this.cooldownMs) {
+            this.state = "half-open";
+        }
+    }
+}
+/**
+ * Wraps fetch to gzip-compress string request bodies using the CompressionStream API.
+ * Adds Content-Encoding: gzip header. Non-string bodies (ArrayBuffer, Blob, etc.)
+ * are passed through uncompressed. Requires CompressionStream (browsers, Node.js 18+, Deno).
+ */
+export function createCompressedFetch(inner) {
+    const baseFetch = inner ?? globalThis.fetch.bind(globalThis);
+    return async (input, init) => {
+        if (!init?.body || typeof CompressionStream === "undefined") {
+            return baseFetch(input, init);
+        }
+        const bodyText = typeof init.body === "string" ? init.body : null;
+        if (!bodyText)
+            return baseFetch(input, init);
+        try {
+            const stream = new Blob([bodyText]).stream().pipeThrough(new CompressionStream("gzip"));
+            const compressed = await new Response(stream).arrayBuffer();
+            const normalized = Object.fromEntries(new Headers(init.headers).entries());
+            normalized["content-encoding"] = "gzip";
+            return baseFetch(input, {
+                ...init,
+                body: compressed,
+                headers: normalized,
+            });
+        }
+        catch {
+            return baseFetch(input, init);
+        }
+    };
+}
+/**
+ * Combines retry and circuit breaker into a single resilient fetch wrapper.
+ * Rejects immediately when the circuit is open.
+ */
+export function createResilientFetch(retryOptions, breakerOptions) {
+    const breaker = new CircuitBreaker(breakerOptions);
+    const retryFetch = createRetryFetch(retryOptions);
+    const resilientFetch = async (input, init) => {
+        if (breaker.isOpen()) {
+            const cooldown = Math.ceil((breakerOptions?.cooldownMs ?? 30_000) / 1000);
+            throw new Error(`Request blocked: too many consecutive failures. Retry in ${cooldown}s.`);
+        }
+        try {
+            const res = await retryFetch(input, init);
+            if (res.status >= 500) {
+                breaker.recordFailure();
+            }
+            else {
+                breaker.recordSuccess();
+            }
+            return res;
+        }
+        catch (err) {
+            breaker.recordFailure();
+            throw err;
+        }
+    };
+    return { fetch: resilientFetch, breaker };
+}

package/dist/history.d.ts

@@ -0,0 +1,29 @@
+export interface Snapshot {
+    timestamp: number;
+    label: string;
+    data: string;
+}
+export interface SnapshotHistoryOptions {
+    /** Maximum number of snapshots to retain. Oldest are trimmed first. Default: 20. */
+    maxSnapshots?: number;
+    /** localStorage key for persistence. Pass to enable auto-save/load. */
+    storageKey?: string;
+}
+export declare class SnapshotHistory {
+    private snapshots;
+    private readonly maxSnapshots;
+    private readonly storageKey;
+    constructor(options?: SnapshotHistoryOptions);
+    /** Take a labeled snapshot of the given data. */
+    take(label: string, data: Record<string, unknown>): void;
+    /** Restore data from a snapshot at the given index. Returns undefined if index is invalid or data is corrupt. */
+    restore(index: number): Record<string, unknown> | undefined;
+    /** List available snapshots (metadata only, no data payload). */
+    list(): Array<{
+        timestamp: number;
+        label: string;
+    }>;
+    /** Clear all snapshots. */
+    clear(): void;
+    private persist;
+}

package/dist/history.js

@@ -0,0 +1,61 @@
+export class SnapshotHistory {
+    snapshots = [];
+    maxSnapshots;
+    storageKey;
+    constructor(options) {
+        this.maxSnapshots = options?.maxSnapshots ?? 20;
+        this.storageKey = options?.storageKey;
+        if (this.storageKey) {
+            try {
+                const raw = localStorage.getItem(this.storageKey);
+                if (raw) {
+                    const parsed = JSON.parse(raw);
+                    if (Array.isArray(parsed))
+                        this.snapshots = parsed;
+                }
+            }
+            catch { /* corrupted or unavailable — start fresh */ }
+        }
+    }
+    /** Take a labeled snapshot of the given data. */
+    take(label, data) {
+        this.snapshots.push({
+            timestamp: Date.now(),
+            label,
+            data: JSON.stringify(data),
+        });
+        if (this.snapshots.length > this.maxSnapshots) {
+            this.snapshots = this.snapshots.slice(-this.maxSnapshots);
+        }
+        this.persist();
+    }
+    /** Restore data from a snapshot at the given index. Returns undefined if index is invalid or data is corrupt. */
+    restore(index) {
+        const snapshot = this.snapshots[index];
+        if (!snapshot)
+            return undefined;
+        try {
+            return JSON.parse(snapshot.data);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** List available snapshots (metadata only, no data payload). */
+    list() {
+        return this.snapshots.map(({ timestamp, label }) => ({ timestamp, label }));
+    }
+    /** Clear all snapshots. */
+    clear() {
+        this.snapshots = [];
+        this.persist();
+    }
+    persist() {
+        if (!this.storageKey)
+            return;
+        try {
+            localStorage.setItem(this.storageKey, JSON.stringify(this.snapshots));
+        }
+        catch { /* quota exceeded — skip silently */ }
+    }
+}

package/dist/index.d.ts

@@ -3,9 +3,23 @@ export type { CryptoProvider, Base64Provider, PlatformConfig } from "@drakkar.so
 export { stableStringify, computeHash } from "@drakkar.software/starfish-protocol";
 export type { PullResult, PushSuccess } from "@drakkar.software/starfish-protocol";
 export { StarfishClient } from "./client.js";
+export type { BlobPullResult, BlobPushResult } from "./client.js";
 export { SyncManager } from "./sync.js";
 export type { SyncManagerOptions } from "./sync.js";
 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 { 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 { 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";

package/dist/index.js

@@ -4,3 +4,10 @@ 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 { createMigrator } from "./migrate.js";
+export { ValidationError, createSchemaValidator } from "./validate.js";
+export { classifyError } from "./fetch.js";
+export { createUnionMerge, createSoftDeleteResolver, timestampWinner, pruneTombstones, } from "./resolvers.js";
+export { SnapshotHistory } from "./history.js";
+export { startPolling, startAdaptivePolling } from "./polling.js";

package/dist/logger.d.ts

@@ -0,0 +1,14 @@
+/** Structured logger for sync operations. */
+export interface SyncLogger {
+    pullStart(store: string): void;
+    pullSuccess(store: string, durationMs: number): void;
+    pullError(store: string, error: string): void;
+    pushStart(store: string): void;
+    pushSuccess(store: string, durationMs: number): void;
+    pushError(store: string, error: string): void;
+    conflict(store: string, attempt: number): void;
+}
+/** Console-based sync logger with structured output. */
+export declare const consoleSyncLogger: SyncLogger;
+/** Silent sync logger (no output). */
+export declare const noopSyncLogger: SyncLogger;

package/dist/logger.js

@@ -0,0 +1,20 @@
+/** 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)`),
+    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)`),
+    pushError: (s, err) => console.error(`[starfish:${s}] push failed: ${err}`),
+    conflict: (s, n) => console.warn(`[starfish:${s}] conflict (attempt ${n})`),
+};
+/** Silent sync logger (no output). */
+export const noopSyncLogger = {
+    pullStart: () => { },
+    pullSuccess: () => { },
+    pullError: () => { },
+    pushStart: () => { },
+    pushSuccess: () => { },
+    pushError: () => { },
+    conflict: () => { },
+};

package/dist/migrate.d.ts

@@ -0,0 +1,16 @@
+/** A function that migrates data from one schema version to the next. */
+export type MigrationFn = (data: Record<string, unknown>) => Record<string, unknown>;
+export interface MigrationConfig {
+    /** The current schema version of the application. */
+    currentVersion: number;
+    /** Map of version number to the migration that upgrades FROM that version. */
+    migrations: Record<number, MigrationFn>;
+}
+/**
+ * Creates a migration runner that upgrades documents to the current schema version.
+ *
+ * Given a document with `_schemaVersion`, applies each migration in sequence
+ * until the document reaches `currentVersion`. Throws if the document version
+ * is ahead of the app (forward compatibility guard).
+ */
+export declare function createMigrator(config: MigrationConfig): (data: Record<string, unknown>) => Record<string, unknown>;

package/dist/migrate.js

@@ -0,0 +1,38 @@
+/**
+ * Creates a migration runner that upgrades documents to the current schema version.
+ *
+ * Given a document with `_schemaVersion`, applies each migration in sequence
+ * until the document reaches `currentVersion`. Throws if the document version
+ * is ahead of the app (forward compatibility guard).
+ */
+export function createMigrator(config) {
+    // Eagerly validate the migration chain
+    for (let v = 1; v < config.currentVersion; v++) {
+        if (!config.migrations[v]) {
+            throw new Error(`Missing migration for version ${v} -> ${v + 1}`);
+        }
+    }
+    return (data) => {
+        const version = typeof data._schemaVersion === "number" ? data._schemaVersion : 1;
+        if (version > config.currentVersion) {
+            throw new Error(`Document schema version ${version} is newer than app version ${config.currentVersion}. Update the app.`);
+        }
+        if (version === config.currentVersion)
+            return data;
+        let result = { ...data };
+        for (let v = version; v < config.currentVersion; v++) {
+            const fn = config.migrations[v];
+            if (!fn) {
+                throw new Error(`Missing migration for version ${v} -> ${v + 1}`);
+            }
+            try {
+                result = fn(result);
+            }
+            catch (err) {
+                throw new Error(`Migration from version ${v} to ${v + 1} failed: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+            }
+        }
+        result._schemaVersion = config.currentVersion;
+        return result;
+    };
+}

package/dist/polling.d.ts

@@ -0,0 +1,28 @@
+/** Minimal state needed by polling utilities. */
+export interface PollableState {
+    online: boolean;
+    syncing: boolean;
+}
+/**
+ * Start periodic pulling at a fixed interval.
+ * Skips pulls when offline or already syncing.
+ * Returns a cleanup function that stops polling.
+ */
+export declare function startPolling(pullFn: () => Promise<void>, getState: () => PollableState, intervalMs?: number): () => void;
+export interface AdaptivePollingOptions {
+    /** Override the base interval in ms. If set, skips network quality detection. */
+    intervalMs?: number;
+    /** Custom mapping from effectiveType to interval in ms. */
+    intervals?: Record<string, number>;
+}
+export interface AdaptivePollingControls {
+    pause: () => void;
+    resume: () => void;
+    stop: () => void;
+}
+/**
+ * Start polling with adaptive intervals based on network quality.
+ * Uses the Network Information API (`navigator.connection.effectiveType`) when available.
+ * Returns controls to pause, resume, or stop polling.
+ */
+export declare function startAdaptivePolling(pullFn: () => Promise<void>, getState: () => PollableState, options?: AdaptivePollingOptions): AdaptivePollingControls;

package/dist/polling.js

@@ -0,0 +1,52 @@
+const DEFAULT_INTERVALS = {
+    "slow-2g": 120_000,
+    "2g": 60_000,
+    "3g": 30_000,
+    "4g": 10_000,
+};
+const DEFAULT_FALLBACK_MS = 15_000;
+/**
+ * Start periodic pulling at a fixed interval.
+ * Skips pulls when offline or already syncing.
+ * Returns a cleanup function that stops polling.
+ */
+export function startPolling(pullFn, getState, intervalMs = 30_000) {
+    const timer = setInterval(() => {
+        const { online, syncing } = getState();
+        if (online && !syncing)
+            pullFn().catch(() => { });
+    }, intervalMs);
+    return () => clearInterval(timer);
+}
+/**
+ * Start polling with adaptive intervals based on network quality.
+ * Uses the Network Information API (`navigator.connection.effectiveType`) when available.
+ * Returns controls to pause, resume, or stop polling.
+ */
+export function startAdaptivePolling(pullFn, getState, options) {
+    let intervalMs;
+    if (options?.intervalMs != null) {
+        intervalMs = options.intervalMs;
+    }
+    else {
+        const intervals = options?.intervals ?? DEFAULT_INTERVALS;
+        let effectiveType;
+        if (typeof navigator !== "undefined" && "connection" in navigator) {
+            effectiveType = navigator.connection.effectiveType;
+        }
+        intervalMs = (effectiveType != null ? intervals[effectiveType] : undefined) ?? DEFAULT_FALLBACK_MS;
+    }
+    let paused = false;
+    const timer = setInterval(() => {
+        if (paused)
+            return;
+        const { online, syncing } = getState();
+        if (online && !syncing)
+            pullFn().catch(() => { });
+    }, intervalMs);
+    return {
+        pause: () => { paused = true; },
+        resume: () => { paused = false; },
+        stop: () => clearInterval(timer),
+    };
+}

package/dist/resolvers.d.ts

@@ -0,0 +1,50 @@
+import type { ConflictResolver } from "./types.js";
+/**
+ * Creates a conflict resolver that merges arrays by ID with per-item
+ * timestamp comparison, and uses document-level timestamp for scalars.
+ *
+ * For arrays: builds a union of both sets keyed by `idKey`. When both
+ * sides have the same item, the one with the newer `timestampKey` wins.
+ * For scalars: the document with the newer `documentTimestampKey` wins.
+ *
+ * @example
+ * ```ts
+ * const merge = createUnionMerge()
+ * const sync = new SyncManager({ ..., onConflict: merge })
+ * ```
+ */
+export declare function createUnionMerge(options?: {
+    /** Key used to identify items in arrays (default: "id"). */
+    idKey?: string;
+    /** Key used for per-item timestamp comparison (default: "updatedAt"). */
+    timestampKey?: string;
+    /** Key used for document-level timestamp comparison (default: "timestamp"). */
+    documentTimestampKey?: string;
+}): ConflictResolver;
+/**
+ * Creates a conflict resolver that handles soft-deleted items (tombstones).
+ * Extends union merge with tombstone awareness: if an item exists on one side
+ * with a `deletedAtKey` set, that deletion is respected even if the other side
+ * still has the item alive — as long as the deletion timestamp is newer.
+ */
+export declare function createSoftDeleteResolver(options?: {
+    idKey?: string;
+    timestampKey?: string;
+    documentTimestampKey?: string;
+    /** Key marking an item as deleted (default: "_deletedAt"). */
+    deletedAtKey?: string;
+}): ConflictResolver;
+/**
+ * Simple resolver: the document with the newer timestamp wins entirely.
+ * No per-field or per-item merging.
+ */
+export declare function timestampWinner(timestampKey?: string): ConflictResolver;
+/**
+ * Remove expired tombstones from an array of items.
+ * Items with a `deletedAtKey` older than `ttlMs` are pruned.
+ *
+ * @param items - Array of items, some with a deletedAt timestamp
+ * @param ttlMs - Time-to-live in ms for tombstones (default: 30 days)
+ * @param deletedAtKey - Key marking deletion timestamp (default: "_deletedAt")
+ */
+export declare function pruneTombstones<T extends Record<string, unknown>>(items: T[], ttlMs?: number, deletedAtKey?: string): T[];