@drakkar.software/starfish-client 1.3.1

package/dist/bindings/legend.d.ts

@@ -0,0 +1,25 @@
+import type { Observable } from "@legendapp/state";
+import type { SyncManager } from "../sync.js";
+export interface StarfishLegendState {
+    data: Record<string, unknown>;
+    syncing: boolean;
+    online: boolean;
+    dirty: boolean;
+    error: string | null;
+}
+export interface StarfishLegendStore {
+    /** The observable state tree — read fields with `.get()` inside `observer` components. */
+    state: Observable<StarfishLegendState>;
+    pull: () => Promise<void>;
+    set: (modifier: (current: Record<string, unknown>) => Record<string, unknown>) => void;
+    flush: () => Promise<void>;
+    setOnline: (online: boolean) => void;
+}
+export interface CreateStarfishObservableOptions {
+    /** Unique name for this collection (used for persistence keys when applicable). */
+    name: string;
+    syncManager: SyncManager;
+    /** Pass `produce` from `immer` to enable draft-based mutations in `set()`. */
+    produce?: <T>(base: T, recipe: (draft: T) => T | void) => T;
+}
+export declare function createStarfishObservable(options: CreateStarfishObservableOptions): StarfishLegendStore;

package/dist/bindings/legend.js

@@ -0,0 +1,63 @@
+import { observable } from "@legendapp/state";
+export function createStarfishObservable(options) {
+    const state = observable({
+        data: {},
+        syncing: false,
+        online: true,
+        dirty: false,
+        error: null,
+    });
+    const flush = async () => {
+        if (state.syncing.get() || !state.dirty.get())
+            return;
+        state.syncing.set(true);
+        state.error.set(null);
+        try {
+            await options.syncManager.push(state.data.get());
+            state.data.set(options.syncManager.getData());
+            state.dirty.set(false);
+        }
+        catch (err) {
+            state.error.set(err.message);
+        }
+        finally {
+            state.syncing.set(false);
+        }
+    };
+    const pull = async () => {
+        state.syncing.set(true);
+        state.error.set(null);
+        try {
+            await options.syncManager.pull();
+            state.data.set(options.syncManager.getData());
+        }
+        catch (err) {
+            state.error.set(err.message);
+        }
+        finally {
+            state.syncing.set(false);
+        }
+    };
+    const set = (modifier) => {
+        try {
+            const current = state.data.get();
+            const next = options.produce
+                ? options.produce(current, modifier)
+                : modifier(current);
+            state.data.set(next);
+            state.dirty.set(true);
+            state.error.set(null);
+            if (state.online.get())
+                flush();
+        }
+        catch (err) {
+            state.error.set(err.message);
+        }
+    };
+    const setOnline = (online) => {
+        state.online.set(online);
+        if (online && state.dirty.get())
+            flush();
+    };
+    return { state, pull, set, flush, setOnline };
+}

package/dist/bindings/zustand.d.ts

@@ -0,0 +1,30 @@
+import { type StoreApi } from "zustand/vanilla";
+import { type StateStorage, type DevtoolsOptions } from "zustand/middleware";
+import type { SyncManager } from "../sync.js";
+export interface StarfishState {
+    data: Record<string, unknown>;
+    syncing: boolean;
+    online: boolean;
+    dirty: boolean;
+    error: string | null;
+}
+export interface StarfishActions {
+    pull: () => Promise<void>;
+    set: (modifier: (current: Record<string, unknown>) => Record<string, unknown>) => void;
+    flush: () => Promise<void>;
+    setOnline: (online: boolean) => void;
+}
+export type StarfishStore = StarfishState & StarfishActions;
+export interface CreateStarfishStoreOptions {
+    /** Unique name used as the persistence key (prefixed with `starfish-`) */
+    name: string;
+    syncManager: SyncManager;
+    /** Pass `false` to disable persistence. Defaults to `localStorage` in browsers. */
+    storage?: StateStorage | false;
+    /** Enable Redux DevTools. Pass `true` or a `DevtoolsOptions` object. */
+    devtools?: boolean | DevtoolsOptions;
+    /** Pass `produce` from `immer` to enable draft-based mutations in `set()`. */
+    produce?: <T>(base: T, recipe: (draft: T) => T | void) => T;
+}
+export type { DevtoolsOptions };
+export declare function createStarfishStore(options: CreateStarfishStoreOptions): StoreApi<StarfishStore>;

package/dist/bindings/zustand.js

@@ -0,0 +1,73 @@
+import { createStore } from "zustand/vanilla";
+import { persist, devtools, subscribeWithSelector, createJSONStorage, } from "zustand/middleware";
+export function createStarfishStore(options) {
+    const { name, syncManager, storage } = options;
+    const storeCreator = (rawSet, get) => {
+        const set = rawSet;
+        return {
+            data: {},
+            syncing: false,
+            online: true,
+            dirty: false,
+            error: null,
+            pull: async () => {
+                set({ syncing: true, error: null }, false, "pull/start");
+                try {
+                    await syncManager.pull();
+                    set({ data: syncManager.getData(), syncing: false }, false, "pull/success");
+                }
+                catch (err) {
+                    set({ syncing: false, error: err.message }, false, "pull/error");
+                }
+            },
+            set: (modifier) => {
+                try {
+                    const next = options.produce
+                        ? options.produce(get().data, modifier)
+                        : modifier(get().data);
+                    set({ data: next, dirty: true, error: null }, false, "set");
+                    if (get().online)
+                        get().flush();
+                }
+                catch (err) {
+                    set({ error: err.message }, false, "set/error");
+                }
+            },
+            flush: async () => {
+                if (get().syncing || !get().dirty)
+                    return;
+                set({ syncing: true, error: null }, false, "flush/start");
+                try {
+                    await syncManager.push(get().data);
+                    set({ data: syncManager.getData(), syncing: false, dirty: false }, false, "flush/success");
+                }
+                catch (err) {
+                    set({ syncing: false, error: err.message }, false, "flush/error");
+                }
+            },
+            setOnline: (online) => {
+                set({ online }, false, "setOnline");
+                if (online && get().dirty)
+                    get().flush();
+            },
+        };
+    };
+    const withPersist = storage === false
+        ? storeCreator
+        : persist(storeCreator, {
+            name: `starfish-${name}`,
+            storage: storage ? createJSONStorage(() => storage) : undefined,
+            partialize: (state) => ({
+                data: state.data,
+                dirty: state.dirty,
+            }),
+        });
+    const withSelector = subscribeWithSelector(withPersist);
+    if (options.devtools) {
+        const devtoolsOpts = typeof options.devtools === "object"
+            ? options.devtools
+            : { name: `starfish-${name}` };
+        return createStore()(devtools(withSelector, devtoolsOpts));
+    }
+    return createStore()(withSelector);
+}

package/dist/client.d.ts

@@ -0,0 +1,27 @@
+import type { PullResult, PushSuccess } from "@drakkar.software/starfish-protocol";
+import type { StarfishClientOptions } from "./types.js";
+/**
+ * Low-level HTTP client for the Starfish sync protocol.
+ * Handles auth headers and response parsing.
+ */
+export declare class StarfishClient {
+    private readonly baseUrl;
+    private readonly auth?;
+    private readonly fetch;
+    constructor(options: StarfishClientOptions);
+    /**
+     * Pull synced data from the server.
+     * @param path - The pull endpoint path (e.g. "/pull/users/abc/settings")
+     * @param checkpoint - Only return data updated after this timestamp (0 = full pull)
+     */
+    pull(path: string, checkpoint?: number): Promise<PullResult>;
+    /**
+     * Push synced data to the server.
+     * @param path - The push endpoint path (e.g. "/push/users/abc/settings")
+     * @param data - The full document data to push
+     * @param baseHash - Hash of the document this push is based on (null for first push)
+     * @param authorSignature - Optional author signature for provenance
+     * @throws {ConflictError} if the server detects a hash mismatch (409)
+     */
+    push(path: string, data: Record<string, unknown>, baseHash: string | null, authorSignature?: string): Promise<PushSuccess>;
+}

package/dist/client.js

@@ -0,0 +1,70 @@
+import { ConflictError, StarfishHttpError } from "./types.js";
+/**
+ * Low-level HTTP client for the Starfish sync protocol.
+ * Handles auth headers and response parsing.
+ */
+export class StarfishClient {
+    baseUrl;
+    auth;
+    fetch;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/$/, "");
+        this.auth = options.auth;
+        this.fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    /**
+     * Pull synced data from the server.
+     * @param path - The pull endpoint path (e.g. "/pull/users/abc/settings")
+     * @param checkpoint - Only return data updated after this timestamp (0 = full pull)
+     */
+    async pull(path, checkpoint) {
+        const url = checkpoint
+            ? `${this.baseUrl}${path}?checkpoint=${checkpoint}`
+            : `${this.baseUrl}${path}`;
+        const authHeaders = this.auth
+            ? await this.auth({ method: "GET", path, body: null })
+            : {};
+        const res = await this.fetch(url, {
+            method: "GET",
+            headers: { Accept: "application/json", ...authHeaders },
+        });
+        if (!res.ok) {
+            throw new StarfishHttpError(res.status, await res.text());
+        }
+        return res.json();
+    }
+    /**
+     * Push synced data to the server.
+     * @param path - The push endpoint path (e.g. "/push/users/abc/settings")
+     * @param data - The full document data to push
+     * @param baseHash - Hash of the document this push is based on (null for first push)
+     * @param authorSignature - Optional author signature for provenance
+     * @throws {ConflictError} if the server detects a hash mismatch (409)
+     */
+    async push(path, data, baseHash, authorSignature) {
+        const body = JSON.stringify({
+            data,
+            baseHash,
+            ...(authorSignature && { authorSignature }),
+        });
+        const authHeaders = this.auth
+            ? await this.auth({ method: "POST", path, body })
+            : {};
+        const res = await this.fetch(`${this.baseUrl}${path}`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Accept: "application/json",
+                ...authHeaders,
+            },
+            body,
+        });
+        if (res.status === 409) {
+            throw new ConflictError();
+        }
+        if (!res.ok) {
+            throw new StarfishHttpError(res.status, await res.text());
+        }
+        return res.json();
+    }
+}

package/dist/crypto.d.ts

@@ -0,0 +1,11 @@
+import { ENCRYPTED_KEY } from "@drakkar.software/starfish-protocol";
+export { ENCRYPTED_KEY };
+/** Encrypt/decrypt interface for client-side E2E encryption. */
+export interface Encryptor {
+    encrypt(data: Record<string, unknown>): Promise<Record<string, unknown>>;
+    decrypt(wrapper: Record<string, unknown>): Promise<Record<string, unknown>>;
+}
+/**
+ * Creates an Encryptor that uses AES-256-GCM with HKDF-derived keys.
+ */
+export declare function createEncryptor(secret: string, salt: string, info?: string): Encryptor;

package/dist/crypto.js

@@ -0,0 +1,49 @@
+import { getCrypto, getBase64, IV_BYTES, ENCRYPTED_KEY, deriveKey } from "@drakkar.software/starfish-protocol";
+const ALGO = "AES-GCM";
+export { ENCRYPTED_KEY };
+/**
+ * Creates an Encryptor that uses AES-256-GCM with HKDF-derived keys.
+ */
+export function createEncryptor(secret, salt, info = "starfish-e2e") {
+    if (!secret)
+        throw new Error("encryptionSecret must not be empty");
+    if (!salt)
+        throw new Error("encryptionSalt must not be empty");
+    const keyPromise = deriveKey(secret, salt, info);
+    return {
+        async encrypt(data) {
+            const key = await keyPromise;
+            const c = getCrypto();
+            const b64 = getBase64();
+            const plaintext = new TextEncoder().encode(JSON.stringify(data));
+            const iv = c.getRandomValues(new Uint8Array(IV_BYTES));
+            const ciphertext = await c.subtle.encrypt({ name: ALGO, iv }, key, plaintext);
+            const combined = new Uint8Array(iv.length + ciphertext.byteLength);
+            combined.set(iv);
+            combined.set(new Uint8Array(ciphertext), iv.length);
+            return { [ENCRYPTED_KEY]: b64.encode(combined) };
+        },
+        async decrypt(wrapper) {
+            const encoded = wrapper[ENCRYPTED_KEY];
+            if (typeof encoded !== "string") {
+                throw new Error("Expected encrypted data but received unencrypted document");
+            }
+            const key = await keyPromise;
+            const c = getCrypto();
+            const b64 = getBase64();
+            const combined = b64.decode(encoded);
+            if (combined.length < IV_BYTES) {
+                throw new Error("Encrypted data is too short");
+            }
+            const iv = combined.slice(0, IV_BYTES);
+            const ciphertext = combined.slice(IV_BYTES);
+            try {
+                const plaintext = await c.subtle.decrypt({ name: ALGO, iv }, key, ciphertext);
+                return JSON.parse(new TextDecoder().decode(plaintext));
+            }
+            catch (err) {
+                throw new Error("Decryption failed: data may be tampered or key is incorrect", { cause: err });
+            }
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { configurePlatform } from "@drakkar.software/starfish-protocol";
+export type { CryptoProvider, Base64Provider, PlatformConfig } from "@drakkar.software/starfish-protocol";
+export { stableStringify, computeHash } from "@drakkar.software/starfish-protocol";
+export type { PullResult, PushSuccess } from "@drakkar.software/starfish-protocol";
+export { StarfishClient } 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";

package/dist/index.js

@@ -0,0 +1,6 @@
+export { configurePlatform } from "@drakkar.software/starfish-protocol";
+export { stableStringify, computeHash } from "@drakkar.software/starfish-protocol";
+export { StarfishClient } from "./client.js";
+export { SyncManager } from "./sync.js";
+export { createEncryptor, ENCRYPTED_KEY } from "./crypto.js";
+export { ConflictError, StarfishHttpError, } from "./types.js";

package/dist/sync.d.ts

@@ -0,0 +1,41 @@
+import type { PullResult } from "@drakkar.software/starfish-protocol";
+import type { ConflictResolver } from "./types.js";
+import { StarfishClient } from "./client.js";
+export interface SyncManagerOptions {
+    client: StarfishClient;
+    pullPath: string;
+    pushPath: string;
+    /** Custom conflict resolver. Defaults to remote-wins deep merge. Arrays are atomic. */
+    onConflict?: ConflictResolver;
+    /** Max conflict retry attempts (default: 3). */
+    maxRetries?: number;
+    encryptionSecret?: string;
+    encryptionSalt?: string;
+    encryptionInfo?: string;
+    signData?: (data: string) => Promise<string>;
+}
+export declare class SyncManager {
+    private readonly client;
+    private readonly pullPath;
+    private readonly pushPath;
+    private readonly onConflict;
+    private readonly maxRetries;
+    private readonly encryptor;
+    private readonly signData?;
+    private lastHash;
+    private lastCheckpoint;
+    private localData;
+    constructor(options: SyncManagerOptions);
+    getData(): Record<string, unknown>;
+    getHash(): string | null;
+    getCheckpoint(): number;
+    pull(): Promise<PullResult>;
+    push(data: Record<string, unknown>): Promise<{
+        hash: string;
+        timestamp: number;
+    }>;
+    update(modifier: (current: Record<string, unknown>) => Record<string, unknown>): Promise<{
+        hash: string;
+        timestamp: number;
+    }>;
+}

package/dist/sync.js

@@ -0,0 +1,92 @@
+import { deepMerge, stableStringify } from "@drakkar.software/starfish-protocol";
+import { ConflictError } from "./types.js";
+import { createEncryptor } from "./crypto.js";
+export class SyncManager {
+    client;
+    pullPath;
+    pushPath;
+    onConflict;
+    maxRetries;
+    encryptor;
+    signData;
+    lastHash = null;
+    lastCheckpoint = 0;
+    localData = {};
+    constructor(options) {
+        this.client = options.client;
+        this.pullPath = options.pullPath;
+        this.pushPath = options.pushPath;
+        this.onConflict = options.onConflict ?? deepMerge;
+        this.maxRetries = options.maxRetries ?? 3;
+        this.signData = options.signData;
+        this.encryptor =
+            options.encryptionSecret && options.encryptionSalt
+                ? createEncryptor(options.encryptionSecret, options.encryptionSalt, options.encryptionInfo)
+                : null;
+    }
+    getData() {
+        return { ...this.localData };
+    }
+    getHash() {
+        return this.lastHash;
+    }
+    getCheckpoint() {
+        return this.lastCheckpoint;
+    }
+    async pull() {
+        const result = await this.client.pull(this.pullPath, this.lastCheckpoint);
+        if (this.encryptor) {
+            const decrypted = await this.encryptor.decrypt(result.data);
+            this.localData = decrypted;
+            result.data = decrypted;
+        }
+        else if (this.lastCheckpoint > 0) {
+            this.localData = deepMerge(this.localData, result.data);
+        }
+        else {
+            this.localData = result.data;
+        }
+        this.lastHash = result.hash;
+        this.lastCheckpoint = result.timestamp;
+        return result;
+    }
+    async push(data) {
+        let attempt = 0;
+        let pendingData = data;
+        while (attempt <= this.maxRetries) {
+            try {
+                const payload = this.encryptor
+                    ? await this.encryptor.encrypt(pendingData)
+                    : pendingData;
+                const sig = this.signData
+                    ? await this.signData(stableStringify(payload))
+                    : undefined;
+                const result = await this.client.push(this.pushPath, payload, this.lastHash, sig);
+                this.lastHash = result.hash;
+                this.lastCheckpoint = result.timestamp;
+                this.localData = pendingData;
+                return result;
+            }
+            catch (err) {
+                if (!(err instanceof ConflictError) || attempt >= this.maxRetries) {
+                    throw err;
+                }
+                const remote = await this.client.pull(this.pullPath);
+                this.lastHash = remote.hash;
+                this.lastCheckpoint = remote.timestamp;
+                const remoteData = this.encryptor
+                    ? await this.encryptor.decrypt(remote.data)
+                    : remote.data;
+                pendingData = this.onConflict(pendingData, remoteData);
+                await new Promise(resolve => setTimeout(resolve, Math.min(100 * Math.pow(2, attempt), 2000) + Math.random() * 100));
+                attempt++;
+            }
+        }
+        throw new ConflictError();
+    }
+    async update(modifier) {
+        await this.pull();
+        const updated = modifier(this.localData);
+        return this.push(updated);
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,30 @@
+/** Push conflict error (HTTP 409). */
+export declare class ConflictError extends Error {
+    constructor();
+}
+/** HTTP error from the Starfish server. */
+export declare class StarfishHttpError extends Error {
+    readonly status: number;
+    readonly body: string;
+    constructor(status: number, body: string);
+}
+/**
+ * Auth provider: returns headers to include in requests.
+ * Called for every authenticated request (pull and push).
+ */
+export type AuthProvider = (req: {
+    method: string;
+    path: string;
+    body: string | null;
+}) => Record<string, string> | Promise<Record<string, string>>;
+/** Options for creating a StarfishClient. */
+export interface StarfishClientOptions {
+    /** Base URL of the Starfish server (e.g. "https://api.example.com/v1"). */
+    baseUrl: string;
+    /** Auth provider that returns headers for authenticated requests. Optional for public-read collections. */
+    auth?: AuthProvider;
+    /** Optional fetch implementation (defaults to global fetch). */
+    fetch?: typeof fetch;
+}
+/** Conflict resolver: given local and remote data, return merged result. */
+export type ConflictResolver = (local: Record<string, unknown>, remote: Record<string, unknown>) => Record<string, unknown>;

package/dist/types.js

@@ -0,0 +1,18 @@
+/** Push conflict error (HTTP 409). */
+export class ConflictError extends Error {
+    constructor() {
+        super("hash_mismatch");
+        this.name = "ConflictError";
+    }
+}
+/** HTTP error from the Starfish server. */
+export class StarfishHttpError extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        super(`HTTP ${status}: ${body}`);
+        this.status = status;
+        this.body = body;
+        this.name = "StarfishHttpError";
+    }
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@drakkar.software/starfish-client",
+  "version": "1.3.1",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Drakkar-Software/starfish.git",
+    "directory": "packages/ts/client"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "TypeScript client SDK for the Starfish sync protocol",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./zustand": {
+      "types": "./dist/bindings/zustand.d.ts",
+      "import": "./dist/bindings/zustand.js"
+    },
+    "./legend": {
+      "types": "./dist/bindings/legend.d.ts",
+      "import": "./dist/bindings/legend.js"
+    }
+  },
+  "peerDependencies": {
+    "zustand": ">=4.0.0",
+    "immer": ">=9.0.0",
+    "@legendapp/state": ">=2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "zustand": {
+      "optional": true
+    },
+    "immer": {
+      "optional": true
+    },
+    "@legendapp/state": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@drakkar.software/starfish-protocol": "workspace:*"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@legendapp/state": "^2.0.0",
+    "hono": "^4.12.7",
+    "immer": "^11.1.4",
+    "typescript": "^5.5.0",
+    "vitest": "^3.0.0",
+    "zustand": "^5.0.11"
+  },
+  "files": [
+    "dist"
+  ]
+}