@drakkar.software/starfish-client 3.0.0-alpha.11 → 3.0.0-alpha.12

package/dist/client.js

@@ -0,0 +1,391 @@
+import { AUTHOR_PUBKEY_FIELD, AUTHOR_SIGNATURE_FIELD, DATA_FIELD, TS_FIELD, BASE_HASH_FIELD, PUSH_PATH_PREFIX, HEADER_AUTHORIZATION, HEADER_SIG, HEADER_TS, HEADER_NONCE, HEADER_PUB, HEADER_CONTENT_TYPE, HEADER_ACCEPT, signAppendAuthor, signRequest, stableStringify, } from "@drakkar.software/starfish-protocol";
+import { ConflictError, StarfishHttpError } from "./types.js";
+const APPEND_DEFAULT_FIELD = "items";
+/** The storage `documentKey` for a push `path`: the path with the `/push/`
+ *  action prefix stripped (the namespace lives only in the URL). The author
+ *  signature binds to this key. */
+export function stripPushPrefix(path) {
+    return path.startsWith(PUSH_PATH_PREFIX) ? path.slice(PUSH_PATH_PREFIX.length) : path;
+}
+/**
+ * Base64-encode the canonical stable-stringification of a cap-cert.
+ *
+ * Used as the value of the `Authorization: Cap <…>` header in v3.0. We rely
+ * on the host's `btoa` for browsers and fall back to `Buffer` in Node so the
+ * client stays free of native dependencies.
+ */
+function encodeCapAuth(cap) {
+    const json = stableStringify(cap);
+    if (typeof btoa === "function") {
+        return btoa(json);
+    }
+    const bufCtor = globalThis.Buffer;
+    if (bufCtor)
+        return bufCtor.from(json, "utf-8").toString("base64");
+    throw new Error("No base64 encoder available");
+}
+/**
+ * Low-level HTTP client for the Starfish sync protocol.
+ * Handles auth headers and response parsing.
+ */
+export class StarfishClient {
+    baseUrl;
+    namespace;
+    capProvider;
+    fetch;
+    /**
+     * Installed client-side plugins. Currently stored as inert data; no
+     * hooks fire yet. Extensions can inspect this list if needed.
+     */
+    plugins;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/$/, "");
+        // Empty string ⇒ no namespace (treat like unset), so a falsy env value
+        // doesn't produce a malformed `/v1//…` path.
+        this.namespace = options.namespace || undefined;
+        this.capProvider = options.capProvider;
+        this.fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+        this.plugins = options.plugins ? [...options.plugins] : [];
+    }
+    /**
+     * Resolve the host portion of the URL the client will send to. The host
+     * is folded into the signed canonical input as the `h` field so the
+     * server can refuse a signature that was minted against a different
+     * Starfish host (replay-across-servers defence).
+     *
+     * When `baseUrl` is relative — e.g. the consumer passed a custom `fetch`
+     * that resolves relative URLs in its own context — there is no parseable
+     * host; we return `""` so signing still proceeds. The server-side
+     * verifier will also reconstruct host from its inbound URL, so the
+     * empty-host case still verifies symmetrically when both sides agree.
+     */
+    signingHost() {
+        try {
+            return new URL(this.baseUrl).host;
+        }
+        catch {
+            return "";
+        }
+    }
+    /**
+     * Rewrite a request path for the configured namespace. A no-op when no
+     * namespace is set; otherwise `/{action}/…` becomes `/v1/{namespace}/{action}/…`
+     * (the `/v1` protocol-version segment is part of the namespaced route, matching
+     * the Python client and the server's namespace mount).
+     *
+     * Applied to the path used for BOTH the signature and the URL so the canonical
+     * path the client signs equals the path the server reconstructs from the URL.
+     * Covers SDK-helper-built paths too — that's the point: a namespace-unaware
+     * helper passing `/push/spaces/x/_keyring` reaches `/v1/{ns}/push/spaces/x/_keyring`.
+     */
+    applyNamespace(path) {
+        return this.namespace ? `/v1/${this.namespace}${path}` : path;
+    }
+    /**
+     * Build auth headers for a request. When a `capProvider` is set, signs the
+     * request with the device's Ed25519 private key and returns the v3 header
+     * set (`Authorization: Cap …`, `X-Starfish-Sig`, `X-Starfish-Ts`,
+     * `X-Starfish-Nonce`). Empty when no provider is configured (public reads).
+     *
+     * Body bytes signed MUST equal the bytes sent on the wire — callers pass
+     * the already-serialized body string here so signing and transmission agree.
+     * The host bound into the signature is derived from `baseUrl` once per call.
+     */
+    async buildAuthHeaders(method, pathAndQuery, body) {
+        if (!this.capProvider)
+            return {};
+        const capCtx = await this.capProvider.getCap();
+        return this.capRequestHeaders(capCtx, method, pathAndQuery, body);
+    }
+    /**
+     * Build the request-signing headers from an ALREADY-fetched cap context. Split
+     * out of {@link buildAuthHeaders} so {@link append} can fetch the cap once and
+     * reuse it for BOTH the author signature (over the element data) and the
+     * request signature (over the body), without redeeming the cap twice — a
+     * second `getCap()` could rotate keys and break the `authorPubkey ===
+     * presenter` bind the server checks.
+     */
+    async capRequestHeaders(capCtx, method, pathAndQuery, body) {
+        const { cap, devEdPrivHex, pubHex } = capCtx;
+        const req = {
+            method,
+            pathAndQuery,
+            body,
+            host: this.signingHost(),
+        };
+        const { sig, ts, nonce } = await signRequest(req, devEdPrivHex);
+        const headers = {
+            [HEADER_AUTHORIZATION]: `Cap ${encodeCapAuth(cap)}`,
+            [HEADER_SIG]: sig,
+            [HEADER_TS]: String(ts),
+            [HEADER_NONCE]: nonce,
+        };
+        // Audience (public-link) caps bind no single subject, so the server needs
+        // the presenter's pubkey to verify the signature and check the allow-list.
+        if (pubHex !== undefined)
+            headers[HEADER_PUB] = pubHex;
+        return headers;
+    }
+    /**
+     * Resolve the author public key to attach to a signed append: the redeemer's
+     * `pubHex` for an audience cap, else the cert subject `cap.sub` for a
+     * device/member cap. This is the SAME key that signs the request, so a server
+     * enforcing author proof can bind the stored element to its writer. Returns
+     * undefined only for a (malformed) cap with neither — the append then goes
+     * unsigned and a server requiring signatures rejects it.
+     */
+    appendAuthorKey(capCtx) {
+        const { cap, pubHex } = capCtx;
+        const authorPubHex = pubHex ?? cap.sub;
+        if (authorPubHex === undefined)
+            return null;
+        return { authorPubHex };
+    }
+    async pull(path, checkpointOrOptions) {
+        let pathAndQuery = this.applyNamespace(path);
+        let appendField;
+        if (typeof checkpointOrOptions === "number") {
+            if (checkpointOrOptions)
+                pathAndQuery += `?checkpoint=${checkpointOrOptions}`;
+        }
+        else if (checkpointOrOptions != null) {
+            // Disambiguate AppendPullOptions vs PullOptions.
+            //
+            // PullOptions are identified by the presence of `withKeyring` or
+            // `checkpoint` keys (which AppendPullOptions does not have — append
+            // uses `since`, not `checkpoint`). Anything else, including an empty
+            // `{}` object, retains the historical behavior of AppendPullOptions
+            // (extracts `data.items` with `?` query).
+            const opts = checkpointOrOptions;
+            const isPullOptions = opts.withKeyring !== undefined || opts.checkpoint !== undefined;
+            const params = new URLSearchParams();
+            if (isPullOptions) {
+                if (opts.checkpoint != null && opts.checkpoint > 0) {
+                    params.set("checkpoint", String(opts.checkpoint));
+                }
+                if (opts.withKeyring) {
+                    params.set("withKeyring", "1");
+                }
+            }
+            else {
+                appendField = opts.appendField ?? APPEND_DEFAULT_FIELD;
+                if (opts.since != null) {
+                    if (opts.since < 0)
+                        throw new Error("since must be non-negative");
+                    params.set("checkpoint", String(opts.since));
+                }
+                if (opts.last != null) {
+                    if (opts.last < 0)
+                        throw new Error("last must be non-negative");
+                    params.set("last", String(opts.last));
+                }
+            }
+            if (params.size > 0)
+                pathAndQuery += `?${params.toString()}`;
+        }
+        const url = `${this.baseUrl}${pathAndQuery}`;
+        const authHeaders = await this.buildAuthHeaders("GET", pathAndQuery, undefined);
+        const res = await this.fetch(url, {
+            method: "GET",
+            headers: { [HEADER_ACCEPT]: "application/json", ...authHeaders },
+        });
+        if (!res.ok) {
+            throw new StarfishHttpError(res.status, await res.text());
+        }
+        const result = await res.json();
+        if (appendField !== undefined) {
+            const list = result.data?.[appendField];
+            return (Array.isArray(list) ? list : []);
+        }
+        return result;
+    }
+    /**
+     * Pull several documents in one round-trip via `/batch/pull`. `collections` is
+     * the list of distinct collection names; `opts.params` supplies, per collection,
+     * an ARRAY of path-param sets — one per document to read — so the SAME collection
+     * can fan in many documents (e.g. many users' `profile`) in a single request.
+     * The server auto-fills the `{identity}` param from the authenticated caller for
+     * any set that omits it, so a self-doc collection needs no params. Returns a map
+     * of collection name → an ARRAY of pulled documents (or per-document `{ error }`),
+     * in request order. Honors the configured namespace.
+     *
+     * For the common "many docs of one collection" case prefer {@link batchPullMany}.
+     *
+     * Note: not append/checkpoint-aware — for incremental append-only reads use
+     * `pull(path, { since })` (or `AppendLogCursor`) per collection.
+     */
+    async batchPull(collections, opts = {}) {
+        const search = new URLSearchParams();
+        search.set("collections", collections.join(","));
+        if (opts.params && Object.keys(opts.params).length > 0) {
+            search.set("params", JSON.stringify(opts.params));
+        }
+        const pathAndQuery = `${this.applyNamespace("/batch/pull")}?${search.toString()}`;
+        const url = `${this.baseUrl}${pathAndQuery}`;
+        const authHeaders = await this.buildAuthHeaders("GET", pathAndQuery, undefined);
+        const res = await this.fetch(url, {
+            method: "GET",
+            headers: { [HEADER_ACCEPT]: "application/json", ...authHeaders },
+        });
+        if (!res.ok) {
+            throw new StarfishHttpError(res.status, await res.text());
+        }
+        return await res.json();
+    }
+    /**
+     * Convenience over {@link batchPull} for reading MANY documents of ONE
+     * collection in a single round-trip: pass the per-document param-sets and get
+     * back the {@link BatchPullEntry} array aligned to `paramsList` by index (each
+     * entry is `{ data, hash, timestamp }` or `{ error }`). An empty `paramsList`
+     * issues no request and returns `[]`.
+     */
+    async batchPullMany(collection, paramsList) {
+        if (paramsList.length === 0)
+            return [];
+        const res = await this.batchPull([collection], { params: { [collection]: paramsList } });
+        return res.collections[collection] ?? [];
+    }
+    /**
+     * 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)
+     *
+     * v3 author proof (`authorPubkey` + `authorSignature`) is passed via `author`
+     * (produced by `SyncManager` when a `signer` is configured) and sent as
+     * top-level body siblings of `data`, where the server verifies it.
+     * @throws {ConflictError} if the server detects a hash mismatch (409)
+     */
+    async push(path, data, baseHash, author) {
+        const body = JSON.stringify({
+            [DATA_FIELD]: data,
+            [BASE_HASH_FIELD]: baseHash,
+            ...(author && {
+                [AUTHOR_PUBKEY_FIELD]: author.authorPubkey,
+                [AUTHOR_SIGNATURE_FIELD]: author.authorSignature,
+            }),
+        });
+        const sendPath = this.applyNamespace(path);
+        const authHeaders = await this.buildAuthHeaders("POST", sendPath, body);
+        const res = await this.fetch(`${this.baseUrl}${sendPath}`, {
+            method: "POST",
+            headers: {
+                [HEADER_CONTENT_TYPE]: "application/json",
+                [HEADER_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();
+    }
+    /**
+     * Append an element to an appendOnly (`by_timestamp`) collection.
+     *
+     * Unlike {@link push}, appendOnly writes carry no hash/conflict check — an
+     * authorized append is always accepted. Each element is stored server-side as
+     * `{ts, data}` and pulls can filter by `ts` via `since`/`checkpoint`.
+     *
+     * @param path - the push endpoint (e.g. "/push/events")
+     * @param data - the element payload. For a `delegated` collection, encrypt it
+     *   first (e.g. `createKeyringEncryptor(keyring, kem).encrypt(data)`); the
+     *   server stores it opaquely and never reads it.
+     * @param opts.ts - optional client-supplied element timestamp (ms). Must be a
+     *   non-negative integer strictly greater than the latest stored element's ts
+     *   (else the server responds 409). Omit to let the server assign one.
+     * @throws {StarfishHttpError} on a non-2xx response — e.g. 409
+     *   `{ error: "non_monotonic_timestamp" }` for a non-monotonic timestamp, or
+     *   `{ error: "append_limit_exceeded", limit }` if the collection's `maxItems`
+     *   cap is reached (partition by a path parameter for higher volume).
+     */
+    async append(path, data, opts = {}) {
+        const sendPath = this.applyNamespace(path);
+        const bodyObj = { [DATA_FIELD]: data };
+        if (opts.ts !== undefined)
+            bodyObj[TS_FIELD] = opts.ts;
+        // Author proof. Fetch the cap ONCE and reuse it for both the author
+        // signature (over the element `data`) and the request signature (over the
+        // final body) — see {@link capRequestHeaders}. The author fields are signed
+        // with the same key that authenticates the request, so a collection with
+        // `requireAuthorSignature` (the default) binds the stored element to its
+        // writer. Without a cap provider the append is sent unsigned and such a
+        // collection rejects it.
+        const capCtx = this.capProvider ? await this.capProvider.getCap() : null;
+        if (capCtx) {
+            const authorKey = this.appendAuthorKey(capCtx);
+            if (authorKey) {
+                // The signature binds the author to BOTH the element data AND the
+                // document it is written to (the storage path = `path` minus the
+                // `/push/` action prefix; the namespace lives only in the URL).
+                const documentKey = stripPushPrefix(path);
+                const { authorPubkey, authorSignature } = signAppendAuthor(documentKey, data, authorKey.authorPubHex, capCtx.devEdPrivHex);
+                bodyObj[AUTHOR_PUBKEY_FIELD] = authorPubkey;
+                bodyObj[AUTHOR_SIGNATURE_FIELD] = authorSignature;
+            }
+        }
+        const body = JSON.stringify(bodyObj);
+        const authHeaders = capCtx
+            ? await this.capRequestHeaders(capCtx, "POST", sendPath, body)
+            : {};
+        const res = await this.fetch(`${this.baseUrl}${sendPath}`, {
+            method: "POST",
+            headers: {
+                [HEADER_CONTENT_TYPE]: "application/json",
+                [HEADER_ACCEPT]: "application/json",
+                ...authHeaders,
+            },
+            body,
+        });
+        if (!res.ok) {
+            throw new StarfishHttpError(res.status, await res.text());
+        }
+        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 sendPath = this.applyNamespace(path);
+        const authHeaders = await this.buildAuthHeaders("GET", sendPath, undefined);
+        const res = await this.fetch(`${this.baseUrl}${sendPath}`, {
+            method: "GET",
+            headers: { [HEADER_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(HEADER_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) {
+        // Blobs are not JSON; we leave body undefined when signing — server-side
+        // verification is expected to use a separate path for blob uploads.
+        const sendPath = this.applyNamespace(path);
+        const authHeaders = await this.buildAuthHeaders("POST", sendPath, undefined);
+        const res = await this.fetch(`${this.baseUrl}${sendPath}`, {
+            method: "POST",
+            headers: {
+                [HEADER_CONTENT_TYPE]: contentType,
+                [HEADER_ACCEPT]: "application/json",
+                ...authHeaders,
+            },
+            body: data,
+        });
+        if (!res.ok) {
+            throw new StarfishHttpError(res.status, await res.text());
+        }
+        return res.json();
+    }
+}

package/dist/config.js

@@ -0,0 +1,18 @@
+/**
+ * Fetch the server's collection manifest from GET /config.
+ *
+ * @param baseUrl - Base URL of the Starfish server (e.g. `"https://api.example.com/v1"`).
+ * @param options.headers - Optional request headers (e.g. `Authorization`).
+ * @throws {Error} if the server returns a non-2xx response.
+ */
+export async function fetchServerConfig(baseUrl, options) {
+    const url = `${baseUrl.replace(/\/$/, "")}/config`;
+    const res = await fetch(url, {
+        method: "GET",
+        headers: options?.headers,
+    });
+    if (!res.ok) {
+        throw new Error(`fetchServerConfig: ${res.status} ${res.statusText}`);
+    }
+    return res.json();
+}

package/dist/debounced-sync.js

@@ -0,0 +1,120 @@
+// ── Implementation ────────────────────────────────────────────────────────────
+const DEFAULT_DELAY_MS = 2000;
+const DEFAULT_WARN_BYTES = 900 * 1024; // 900 KB
+const DEFAULT_MAX_BYTES = 1024 * 1024; // 1 MB
+/** Returns true if the push should be blocked. */
+function checkPayloadSize(doc, opts) {
+    // Estimate encrypted payload size. AES-GCM output is similar to input size;
+    // base64 encoding adds ~33% overhead, plus a small IV/tag overhead.
+    const estimatedBytes = Math.ceil(JSON.stringify(doc).length * 1.34);
+    if (estimatedBytes > opts.maxBytes) {
+        if (opts.onSizeExceeded) {
+            opts.onSizeExceeded(estimatedBytes);
+        }
+        else {
+            console.error(`[starfish] Push blocked: estimated payload ${(estimatedBytes / 1024).toFixed(0)} KB ` +
+                `exceeds limit of ${(opts.maxBytes / 1024).toFixed(0)} KB. Prune your data before syncing.`);
+        }
+        return true;
+    }
+    if (estimatedBytes > opts.warnBytes) {
+        if (opts.onSizeWarning) {
+            opts.onSizeWarning(estimatedBytes);
+        }
+        else {
+            console.warn(`[starfish] Payload approaching limit: estimated ${(estimatedBytes / 1024).toFixed(0)} KB ` +
+                `(warn threshold: ${(opts.warnBytes / 1024).toFixed(0)} KB).`);
+        }
+    }
+    return false;
+}
+/**
+ * Creates a debounced push helper that coalesces rapid mutations into a single sync.
+ *
+ * Designed to be called on every domain store mutation (e.g., every keystroke).
+ * The push is delayed by `delayMs` after the **last** call, so typing quickly
+ * results in one push, not one per character.
+ *
+ * Also estimates the encrypted payload size before pushing and warns / blocks
+ * if it approaches the server's body size limit.
+ *
+ * ```ts
+ * const { notify } = createDebouncedSync(starfishStore, {
+ *   serialize: () => ({ tasks: taskStore.getState().tasks }),
+ * })
+ *
+ * // Call on every domain store mutation:
+ * taskStore.subscribe(() => notify())
+ * ```
+ */
+export function createDebouncedSync(store, options = {}) {
+    const { delayMs = DEFAULT_DELAY_MS, warnBytes = DEFAULT_WARN_BYTES, maxBytes = DEFAULT_MAX_BYTES, serialize, onSizeWarning, onSizeExceeded, } = options;
+    let timer = null;
+    function cancel() {
+        if (timer !== null) {
+            clearTimeout(timer);
+            timer = null;
+        }
+    }
+    function notify() {
+        cancel();
+        timer = setTimeout(() => {
+            timer = null;
+            const current = store.getState().data;
+            const doc = serialize ? serialize(current) : current;
+            if (checkPayloadSize(doc, { warnBytes, maxBytes, onSizeWarning, onSizeExceeded }))
+                return;
+            store.getState().set(() => doc);
+        }, delayMs);
+    }
+    return { notify, cancel };
+}
+/**
+ * Creates a debounced push helper that calls `syncManager.push()` directly,
+ * without requiring a Zustand store.
+ *
+ * Use this for one-way publishing workflows: public pages, derived snapshots,
+ * or any case where you want to push data without a full `createStarfishStore` setup.
+ *
+ * ```ts
+ * const syncManager = new SyncManager({ client, pullPath, pushPath })
+ *
+ * const { notify, cancel } = createDebouncedPush(syncManager, {
+ *   serialize: () => buildPublicPageDocument(),
+ * })
+ *
+ * // Push after every relevant store mutation:
+ * planningStore.subscribe(() => notify())
+ *
+ * // Clean up on teardown:
+ * cancel()
+ * ```
+ */
+export function createDebouncedPush(syncManager, options) {
+    const { delayMs = DEFAULT_DELAY_MS, warnBytes = DEFAULT_WARN_BYTES, maxBytes = DEFAULT_MAX_BYTES, serialize, onSizeWarning, onSizeExceeded, onError, } = options;
+    let timer = null;
+    function cancel() {
+        if (timer !== null) {
+            clearTimeout(timer);
+            timer = null;
+        }
+    }
+    function notify() {
+        cancel();
+        timer = setTimeout(() => {
+            timer = null;
+            const doc = serialize();
+            if (checkPayloadSize(doc, { warnBytes, maxBytes, onSizeWarning, onSizeExceeded }))
+                return;
+            syncManager.push(doc).catch((err) => {
+                if (onError) {
+                    onError(err);
+                }
+                else {
+                    console.warn("[starfish] Push failed:", err);
+                }
+            });
+        }, delayMs);
+    }
+    return { notify, cancel };
+}

package/dist/dedup.js

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

package/dist/export.js

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