@drakkar.software/starfish-client 1.3.2 → 1.4.1

package/dist/bindings/broadcast.d.ts

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

@@ -0,0 +1,65 @@
+/**
+ * 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/legend.js

@@ -18,7 +18,7 @@ export function createStarfishObservable(options) {
             state.dirty.set(false);
         }
         catch (err) {
-            state.error.set(err.message);
+            state.error.set(err instanceof Error ? err.message : String(err));
         }
         finally {
             state.syncing.set(false);
@@ -32,7 +32,7 @@ export function createStarfishObservable(options) {
             state.data.set(options.syncManager.getData());
         }
         catch (err) {
-            state.error.set(err.message);
+            state.error.set(err instanceof Error ? err.message : String(err));
         }
         finally {
             state.syncing.set(false);
@@ -48,16 +48,16 @@ export function createStarfishObservable(options) {
             state.dirty.set(true);
             state.error.set(null);
             if (state.online.get())
-                flush();
+                flush().catch(() => { });
         }
         catch (err) {
-            state.error.set(err.message);
+            state.error.set(err instanceof Error ? err.message : String(err));
         }
     };
     const setOnline = (online) => {
         state.online.set(online);
         if (online && state.dirty.get())
-            flush();
+            flush().catch(() => { });
     };
     return { state, pull, set, flush, setOnline };
 }

package/dist/bindings/react.d.ts

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

@@ -0,0 +1,25 @@
+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);
+}

package/dist/bindings/zustand.d.ts

@@ -1,6 +1,9 @@
 import { type StoreApi } from "zustand/vanilla";
 import { type StateStorage, type DevtoolsOptions } from "zustand/middleware";
-import type { SyncManager } from "../sync.js";
+import { SyncManager } from "../sync.js";
+import type { AuthProvider, ConflictResolver } from "../types.js";
+import type { SyncLogger } from "../logger.js";
+import type { Validator } from "../validate.js";
 export interface StarfishState {
     data: Record<string, unknown>;
     syncing: boolean;
@@ -11,6 +14,8 @@ export interface StarfishState {
 export interface StarfishActions {
     pull: () => Promise<void>;
     set: (modifier: (current: Record<string, unknown>) => Record<string, unknown>) => void;
+    /** Update data without marking dirty or triggering flush. Use for restoring pulled data into the store. */
+    restore: (data: Record<string, unknown>) => void;
     flush: () => Promise<void>;
     setOnline: (online: boolean) => void;
 }
@@ -28,3 +33,50 @@ export interface CreateStarfishStoreOptions {
 }
 export type { DevtoolsOptions };
 export declare function createStarfishStore(options: CreateStarfishStoreOptions): StoreApi<StarfishStore>;
+/** 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;
+/**
+ * Aggregate multiple sync statuses into a single worst-case status.
+ * Priority (worst first): error > syncing > pending > offline > synced.
+ */
+export declare function aggregateSyncStatus(statuses: SyncStatus[]): 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;
+/** Sets up cross-tab sync for a Starfish store. Cleans up on unmount. */
+export declare function useCrossTabSync(store: StoreApi<StarfishStore>, name: string): void;
+/** Binds browser online/offline events to the store's setOnline action. Cleans up on unmount. */
+export declare function useConnectivity(store: StoreApi<StarfishStore>): void;
+/** Returns a human-readable "last synced" label that updates every 5 seconds. */
+export declare function useLastSynced(store: StoreApi<StarfishStore>): string;
+export interface SyncInitConfig {
+    serverUrl: string;
+    auth?: AuthProvider;
+    pullPath: string;
+    pushPath: string;
+    encryptionSecret?: string;
+    encryptionSalt?: string;
+    onConflict?: ConflictResolver;
+    /** Called when pulled data arrives. Use to restore domain stores. */
+    onData?: (data: Record<string, unknown>) => void;
+    storeName?: string;
+    storage?: StateStorage | false;
+    fetch?: typeof globalThis.fetch;
+    logger?: SyncLogger;
+    validate?: Validator;
+}
+/**
+ * React hook that manages the full Starfish sync lifecycle.
+ *
+ * Creates StarfishClient → SyncManager → Zustand store, pulls on mount,
+ * calls `onData` when remote data arrives, and tears down on unmount or
+ * config change.
+ *
+ * Pass `null` to disable sync (returns `null`).
+ */
+export declare function useSyncInit(config: SyncInitConfig | null): StoreApi<StarfishStore> | null;

package/dist/bindings/zustand.js

@@ -1,5 +1,10 @@
 import { createStore } from "zustand/vanilla";
+import { useStore } from "zustand";
 import { persist, devtools, subscribeWithSelector, createJSONStorage, } from "zustand/middleware";
+import { useEffect, useRef, useState, useCallback } from "react";
+import { StarfishClient } from "../client.js";
+import { SyncManager } from "../sync.js";
+import { setupCrossTabSync } from "../broadcast.js";
 export function createStarfishStore(options) {
     const { name, syncManager, storage } = options;
     const storeCreator = (rawSet, get) => {
@@ -17,7 +22,7 @@ export function createStarfishStore(options) {
                     set({ data: syncManager.getData(), syncing: false }, false, "pull/success");
                 }
                 catch (err) {
-                    set({ syncing: false, error: err.message }, false, "pull/error");
+                    set({ syncing: false, error: err instanceof Error ? err.message : String(err) }, false, "pull/error");
                 }
             },
             set: (modifier) => {
@@ -27,12 +32,15 @@ export function createStarfishStore(options) {
                         : modifier(get().data);
                     set({ data: next, dirty: true, error: null }, false, "set");
                     if (get().online)
-                        get().flush();
+                        get().flush().catch(() => { });
                 }
                 catch (err) {
-                    set({ error: err.message }, false, "set/error");
+                    set({ error: err instanceof Error ? err.message : String(err) }, false, "set/error");
                 }
             },
+            restore: (data) => {
+                set({ data }, false, "restore");
+            },
             flush: async () => {
                 if (get().syncing || !get().dirty)
                     return;
@@ -42,13 +50,13 @@ export function createStarfishStore(options) {
                     set({ data: syncManager.getData(), syncing: false, dirty: false }, false, "flush/success");
                 }
                 catch (err) {
-                    set({ syncing: false, error: err.message }, false, "flush/error");
+                    set({ syncing: false, error: err instanceof Error ? err.message : String(err) }, false, "flush/error");
                 }
             },
             setOnline: (online) => {
                 set({ online }, false, "setOnline");
                 if (online && get().dirty)
-                    get().flush();
+                    get().flush().catch(() => { });
             },
         };
     };
@@ -71,3 +79,174 @@ export function createStarfishStore(options) {
     }
     return createStore()(withSelector);
 }
+/** 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";
+}
+/**
+ * Aggregate multiple sync statuses into a single worst-case status.
+ * Priority (worst first): error > syncing > pending > offline > synced.
+ */
+export function aggregateSyncStatus(statuses) {
+    if (statuses.includes("error"))
+        return "error";
+    if (statuses.includes("syncing"))
+        return "syncing";
+    if (statuses.includes("pending"))
+        return "pending";
+    if (statuses.includes("offline"))
+        return "offline";
+    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);
+}
+/** Sets up cross-tab sync for a Starfish store. Cleans up on unmount. */
+export function useCrossTabSync(store, name) {
+    useEffect(() => {
+        return setupCrossTabSync(store, name);
+    }, [store, name]);
+}
+/** Binds browser online/offline events to the store's setOnline action. Cleans up on unmount. */
+export function useConnectivity(store) {
+    useEffect(() => {
+        const handleOnline = () => store.getState().setOnline(true);
+        const handleOffline = () => store.getState().setOnline(false);
+        window.addEventListener("online", handleOnline);
+        window.addEventListener("offline", handleOffline);
+        return () => {
+            window.removeEventListener("online", handleOnline);
+            window.removeEventListener("offline", handleOffline);
+        };
+    }, [store]);
+}
+/** Returns a human-readable "last synced" label that updates every 5 seconds. */
+export function useLastSynced(store) {
+    const lastSyncedAt = useRef(null);
+    const [label, setLabel] = useState("Never synced");
+    const computeLabel = useCallback(() => {
+        if (lastSyncedAt.current === null)
+            return "Never synced";
+        const seconds = Math.floor((Date.now() - lastSyncedAt.current) / 1000);
+        if (seconds < 10)
+            return "Just now";
+        if (seconds < 60)
+            return `${seconds}s ago`;
+        return `${Math.floor(seconds / 60)}m ago`;
+    }, []);
+    // Track sync completion
+    useEffect(() => {
+        let prevSyncing = store.getState().syncing;
+        const unsub = store.subscribe((state) => {
+            if (prevSyncing && !state.syncing && !state.error) {
+                lastSyncedAt.current = Date.now();
+                setLabel(computeLabel());
+            }
+            prevSyncing = state.syncing;
+        });
+        return unsub;
+    }, [store, computeLabel]);
+    // Update label periodically
+    useEffect(() => {
+        const timer = setInterval(() => {
+            setLabel(computeLabel());
+        }, 5000);
+        return () => clearInterval(timer);
+    }, [computeLabel]);
+    return label;
+}
+/**
+ * React hook that manages the full Starfish sync lifecycle.
+ *
+ * Creates StarfishClient → SyncManager → Zustand store, pulls on mount,
+ * calls `onData` when remote data arrives, and tears down on unmount or
+ * config change.
+ *
+ * Pass `null` to disable sync (returns `null`).
+ */
+export function useSyncInit(config) {
+    const [store, setStore] = useState(null);
+    const onDataRef = useRef(config?.onData);
+    onDataRef.current = config?.onData;
+    useEffect(() => {
+        if (!config) {
+            setStore(null);
+            return;
+        }
+        const client = new StarfishClient({
+            baseUrl: config.serverUrl,
+            auth: config.auth,
+            fetch: config.fetch,
+        });
+        const syncManager = new SyncManager({
+            client,
+            pullPath: config.pullPath,
+            pushPath: config.pushPath,
+            encryptionSecret: config.encryptionSecret,
+            encryptionSalt: config.encryptionSalt,
+            onConflict: config.onConflict,
+            logger: config.logger,
+            validate: config.validate,
+        });
+        const newStore = createStarfishStore({
+            name: config.storeName ?? "sync",
+            syncManager,
+            storage: config.storage,
+        });
+        // Subscribe to data changes from pulls (not local sets)
+        let lastDataRef = newStore.getState().data;
+        const unsub = newStore.subscribe((state) => {
+            const data = state.data;
+            // Only call onData when data changes and store is not dirty
+            // (dirty = false means data came from a pull, not a local set)
+            if (data !== lastDataRef && !state.dirty) {
+                lastDataRef = data;
+                try {
+                    onDataRef.current?.(data);
+                }
+                catch (err) {
+                    newStore.setState({
+                        error: `onData failed: ${err instanceof Error ? err.message : String(err)}`,
+                    });
+                }
+            }
+            else {
+                lastDataRef = data;
+            }
+        });
+        setStore(newStore);
+        // Initial pull — errors are stored in state.error by the pull() action
+        newStore.getState().pull().catch(() => { });
+        return () => {
+            unsub();
+            setStore(null);
+        };
+        // Intentionally depend on serializable config values, not the object reference
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [
+        config?.serverUrl,
+        config?.pullPath,
+        config?.pushPath,
+        config?.encryptionSecret,
+        config?.encryptionSalt,
+        config?.storeName,
+    ]);
+    return store;
+}

package/dist/broadcast.d.ts

@@ -0,0 +1,36 @@
+/** Minimal store interface for cross-tab sync. Works with both Zustand and Legend bindings. */
+export interface BroadcastableStore {
+    getState(): {
+        data: Record<string, unknown>;
+        dirty: boolean;
+    };
+    setState(partial: {
+        data: Record<string, unknown>;
+        dirty: boolean;
+    }): void;
+    subscribe(listener: (state: {
+        data: Record<string, unknown>;
+        dirty: boolean;
+    }, prev: {
+        data: Record<string, unknown>;
+        dirty: boolean;
+    }) => void): () => void;
+}
+/**
+ * Syncs a Starfish store across browser tabs using BroadcastChannel.
+ * Works with any store that has getState/setState/subscribe (Zustand, Legend adapters, etc.).
+ * Returns a cleanup function that closes the channel.
+ */
+export declare function setupBroadcastSync(store: BroadcastableStore, name: string): () => void;
+/**
+ * Syncs a Starfish store across browser tabs using storage events.
+ * Fallback for environments without BroadcastChannel.
+ * Returns a cleanup function.
+ */
+export declare function setupStorageFallback(store: BroadcastableStore, 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: BroadcastableStore, name: string): () => void;

package/dist/broadcast.js

@@ -0,0 +1,83 @@
+/**
+ * Syncs a Starfish store across browser tabs using BroadcastChannel.
+ * Works with any store that has getState/setState/subscribe (Zustand, Legend adapters, etc.).
+ * 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) => {
+        const payload = event.data;
+        if (!payload || typeof payload !== "object" || !payload.data || typeof payload.data !== "object")
+            return;
+        lastReceivedData = payload.data;
+        store.setState({ data: payload.data, dirty: !!payload.dirty });
+    };
+    const unsub = store.subscribe((state, prev) => {
+        if (state.data === lastReceivedData)
+            return;
+        if (state.data !== prev.data || state.dirty !== prev.dirty) {
+            try {
+                channel.postMessage({ data: state.data, dirty: state.dirty });
+            }
+            catch { /* non-serializable data — skip broadcast */ }
+        }
+    });
+    return () => {
+        unsub();
+        channel.close();
+    };
+}
+/**
+ * Syncs a 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;
+        let payload;
+        try {
+            payload = JSON.parse(e.newValue);
+        }
+        catch {
+            return;
+        }
+        if (!payload || typeof payload !== "object" || !payload.data || typeof payload.data !== "object")
+            return;
+        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) {
+            try {
+                localStorage.setItem(storageKey, JSON.stringify({ data: state.data, dirty: state.dirty }));
+            }
+            catch { /* quota exceeded or non-serializable — skip */ }
+        }
+    });
+    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/client.d.ts

@@ -1,5 +1,16 @@
 import type { PullResult, PushSuccess } from "@drakkar.software/starfish-protocol";
 import type { StarfishClientOptions } from "./types.js";
+/** Result of pulling a binary blob from the server. */
+export interface BlobPullResult {
+    data: ArrayBuffer;
+    /** Content hash from the ETag header. Null if the server didn't include an ETag. */
+    hash: string | null;
+    contentType: string;
+}
+/** Result of pushing a binary blob to the server. */
+export interface BlobPushResult {
+    hash: string;
+}
 /**
  * Low-level HTTP client for the Starfish sync protocol.
  * Handles auth headers and response parsing.
@@ -24,4 +35,14 @@ export declare class StarfishClient {
      * @throws {ConflictError} if the server detects a hash mismatch (409)
      */
     push(path: string, data: Record<string, unknown>, baseHash: string | null, authorSignature?: string): Promise<PushSuccess>;
+    /**
+     * Pull binary data from a blob collection.
+     * Returns raw bytes with the content hash from the ETag header.
+     */
+    pullBlob(path: string): Promise<BlobPullResult>;
+    /**
+     * Push binary data to a blob collection.
+     * Binary collections use last-write-wins (no conflict detection).
+     */
+    pushBlob(path: string, data: ArrayBuffer | Uint8Array | Blob, contentType: string): Promise<BlobPushResult>;
 }

package/dist/client.js

@@ -67,4 +67,46 @@ export class StarfishClient {
         }
         return res.json();
     }
+    /**
+     * Pull binary data from a blob collection.
+     * Returns raw bytes with the content hash from the ETag header.
+     */
+    async pullBlob(path) {
+        const authHeaders = this.auth
+            ? await this.auth({ method: "GET", path, body: null })
+            : {};
+        const res = await this.fetch(`${this.baseUrl}${path}`, {
+            method: "GET",
+            headers: { Accept: "*/*", ...authHeaders },
+        });
+        if (!res.ok) {
+            throw new StarfishHttpError(res.status, await res.text());
+        }
+        const etag = res.headers.get("ETag")?.replace(/"/g, "") ?? null;
+        const contentType = res.headers.get("Content-Type") ?? "application/octet-stream";
+        const data = await res.arrayBuffer();
+        return { data, hash: etag, contentType };
+    }
+    /**
+     * Push binary data to a blob collection.
+     * Binary collections use last-write-wins (no conflict detection).
+     */
+    async pushBlob(path, data, contentType) {
+        const authHeaders = this.auth
+            ? await this.auth({ method: "POST", path, body: null })
+            : {};
+        const res = await this.fetch(`${this.baseUrl}${path}`, {
+            method: "POST",
+            headers: {
+                "Content-Type": contentType,
+                Accept: "application/json",
+                ...authHeaders,
+            },
+            body: data,
+        });
+        if (!res.ok) {
+            throw new StarfishHttpError(res.status, await res.text());
+        }
+        return res.json();
+    }
 }