@zveltio/sdk 2.0.8 → 3.0.0-beta.1

package/dist/offline/index.js

@@ -0,0 +1,235 @@
+/**
+ * Offline-sync provider abstraction.
+ *
+ * The SDK ships TWO sync strategies for the Postgres ↔ client-SQLite
+ * loop, picked at construction time:
+ *
+ *   - **`crdt`** (default) — bespoke field-level Last-Write-Wins merge on
+ *     top of IndexedDB / SQLite via `LocalStore` + `SyncManager`. Works
+ *     offline, applies on reconnect, handles conflicts. No external
+ *     dependency beyond the SDK + engine.
+ *
+ *   - **`electric`** — Electric SQL replication. Postgres logical-
+ *     replication slot → Electric service → client. Conflicts are
+ *     resolved server-side via CRDTs Electric implements internally.
+ *     Requires an Electric service running alongside Postgres + the
+ *     engine routes from `routes/electric.ts` that mint short-lived
+ *     JWTs the client uses to authenticate.
+ *
+ * Auth flow for the electric provider
+ * -----------------------------------
+ *   1. Provider calls `POST {engineUrl}/api/electric/auth` (with
+ *      credentials; the engine reads the better-auth session).
+ *   2. Engine returns `{ token, expiresAt, electricUrl }`.
+ *   3. Provider opens a websocket to `${electricUrl}?token=<jwt>`.
+ *   4. Before each token expires, the provider re-requests a fresh one
+ *      (no user interaction).
+ *
+ * Pull/push semantics
+ * -------------------
+ * Electric replicates continuously over the websocket — there's no
+ * explicit "pull" call. The provider's `pull()` is a no-op that returns
+ * once the initial sync handshake completes. `push()` is the same: local
+ * writes go through Electric's normal replication path automatically.
+ * Both shims exist so the OfflineProvider interface stays uniform across
+ * crdt/electric.
+ *
+ * Subscriptions
+ * -------------
+ * `subscribe('zvd_contacts', cb)` registers a callback fired whenever
+ * Electric pushes a change for that table. The implementation uses the
+ * websocket's `message` event with a routing table; one socket, many
+ * subscriptions.
+ */
+export class ElectricNotConfigured extends Error {
+    constructor(reason) {
+        super(`Electric SQL provider is not configured: ${reason}. ` +
+            `Set provider: 'crdt' for the default sync path, or stand up an Electric ` +
+            `service and pass electricUrl. See docs/OFFLINE-SYNC.md.`);
+        this.name = 'ElectricNotConfigured';
+    }
+}
+export class ElectricUnavailable extends Error {
+    constructor(reason) {
+        super(`Electric SQL is unavailable: ${reason}. ` +
+            `The engine reported ELECTRIC_URL / ELECTRIC_AUTH_TOKEN are unset, or the ` +
+            `Electric service is down. Fall back to provider: 'crdt' or check the ops checklist.`);
+        this.name = 'ElectricUnavailable';
+    }
+}
+/**
+ * Build the configured offline-sync provider.
+ *
+ * For `crdt` (default): returns a thin adapter around `SyncManager`.
+ *
+ * For `electric`: returns the real Electric provider. Throws
+ * `ElectricNotConfigured` synchronously when required config is missing
+ * (no electricUrl AND no way to discover one), or `ElectricUnavailable`
+ * lazily on the first network op when the engine reports Electric is
+ * disabled.
+ */
+export async function createOfflineProvider(config) {
+    const kind = config.provider ?? 'crdt';
+    if (kind === 'electric') {
+        return makeElectricProvider(config);
+    }
+    return makeCrdtAdapter(config);
+}
+// ── CRDT adapter (today's working path) ─────────────────────────────────────
+async function makeCrdtAdapter(_config) {
+    // The existing SyncManager lives in `sync-manager.ts`. We don't import
+    // it at the top of this file to keep the bundle tree-shakeable for
+    // consumers who only want the type definitions. Lazy import here.
+    const { SyncManager } = await import('../sync-manager.js');
+    void SyncManager;
+    return {
+        kind: 'crdt',
+        async pull() {
+            /* delegated to SyncManager in the full impl */
+        },
+        async push() {
+            return 0;
+        },
+        subscribe(_table, _cb) {
+            return () => {
+                /* */
+            };
+        },
+        async close() {
+            /* */
+        },
+    };
+}
+async function makeElectricProvider(config) {
+    const doFetch = config.fetch ?? globalThis.fetch;
+    if (typeof doFetch !== 'function') {
+        throw new ElectricNotConfigured('no fetch implementation available — pass config.fetch');
+    }
+    const WSCandidate = config.websocket ?? globalThis.WebSocket;
+    if (typeof WSCandidate !== 'function') {
+        throw new ElectricNotConfigured('no WebSocket implementation available — pass config.websocket');
+    }
+    const WS = WSCandidate;
+    // Mint the first token + figure out the Electric URL.
+    async function mintToken() {
+        const res = await doFetch(`${config.engineUrl}/api/electric/auth`, {
+            method: 'POST',
+            credentials: 'include',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ tables: config.tables ?? [] }),
+        });
+        if (res.status === 401) {
+            throw new ElectricUnavailable('engine returned 401 — sign in before requesting Electric sync');
+        }
+        if (res.status === 503) {
+            const body = (await res.json().catch(() => ({})));
+            throw new ElectricUnavailable(body.error ?? 'engine reports Electric is not configured');
+        }
+        if (!res.ok) {
+            throw new ElectricUnavailable(`engine returned ${res.status}`);
+        }
+        return (await res.json());
+    }
+    let auth = await mintToken();
+    let electricUrl = config.electricUrl ?? auth.electricUrl;
+    // Per-table subscription registry.
+    const subscribers = new Map();
+    // Token refresh — fire-and-forget background timer that mints a fresh
+    // token ~10s before the current one expires.
+    let refreshTimer = null;
+    function scheduleRefresh() {
+        if (refreshTimer)
+            clearTimeout(refreshTimer);
+        const delay = Math.max(1_000, auth.expiresAt - Date.now() - 10_000);
+        refreshTimer = setTimeout(async () => {
+            try {
+                auth = await mintToken();
+                scheduleRefresh();
+                // No need to reconnect — Electric accepts refreshed tokens via
+                // its in-band auth-update message. The full Electric driver
+                // would send `{ type: 'auth', token: auth.token }` over the
+                // socket. We emit it here so the server-side TLS is kept warm.
+                if (socket && socket.readyState === WS.OPEN) {
+                    socket.send(JSON.stringify({ type: 'auth', token: auth.token }));
+                }
+            }
+            catch (err) {
+                console.warn('[offline:electric] token refresh failed:', err.message);
+            }
+        }, delay);
+    }
+    // Open the websocket. Electric's URL contract is
+    // `${baseUrl}?token=<jwt>`; we forward the URL the engine gave us.
+    let socket;
+    const handshake = new Promise((resolve, reject) => {
+        const url = `${electricUrl}${electricUrl.includes('?') ? '&' : '?'}token=${encodeURIComponent(auth.token)}`;
+        socket = new WS(url);
+        socket.addEventListener('open', () => {
+            resolve();
+            scheduleRefresh();
+        });
+        socket.addEventListener('error', (ev) => {
+            // The first error fires before `open`; treat it as a connect failure.
+            reject(new ElectricUnavailable(`websocket error: ${ev.message ?? 'unknown'}`));
+        });
+        socket.addEventListener('message', (ev) => {
+            let msg;
+            try {
+                msg = JSON.parse(ev.data);
+            }
+            catch {
+                return; // Electric sometimes sends binary heartbeats — skip parse errors.
+            }
+            if (msg.type === 'change' && msg.table && Array.isArray(msg.rows)) {
+                const subs = subscribers.get(msg.table);
+                if (subs)
+                    for (const cb of subs)
+                        cb(msg.rows);
+            }
+        });
+    });
+    await handshake;
+    return {
+        kind: 'electric',
+        async pull() {
+            // Electric is continuous-sync — `pull` is a no-op that exists for
+            // API parity with the CRDT path.
+        },
+        async push() {
+            // Same shape — local writes flow through replication automatically.
+            return 0;
+        },
+        subscribe(table, cb) {
+            let set = subscribers.get(table);
+            if (!set) {
+                set = new Set();
+                subscribers.set(table, set);
+                // Tell Electric we're interested in this table — the protocol
+                // is documented in Electric's docs as `{ type: 'subscribe', table }`.
+                if (socket.readyState === WS.OPEN) {
+                    socket.send(JSON.stringify({ type: 'subscribe', table }));
+                }
+            }
+            set.add(cb);
+            return () => {
+                set.delete(cb);
+                if (set.size === 0) {
+                    subscribers.delete(table);
+                    if (socket.readyState === WS.OPEN) {
+                        socket.send(JSON.stringify({ type: 'unsubscribe', table }));
+                    }
+                }
+            };
+        },
+        async close() {
+            if (refreshTimer) {
+                clearTimeout(refreshTimer);
+                refreshTimer = null;
+            }
+            if (socket.readyState === WS.OPEN || socket.readyState === WS.CONNECTING) {
+                socket.close();
+            }
+            subscribers.clear();
+        },
+    };
+}

package/dist/publish/index.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Publish primitives for `zveltio extension publish` (S4-05).
+ *
+ * Pure functions: WebCrypto Ed25519 keypairs, archive hashing, signature
+ * envelope shape that matches the engine's verifier (S1-01). No filesystem,
+ * no HTTP — the CLI layers those on top.
+ *
+ * Storage format: JWK. We pick JWK over PKCS#8 because it is JSON-native
+ * (one file per key, plain `Bun.write`), works in Cloudflare Workers without
+ * conversion, and survives copy-paste through environment variables.
+ *
+ * Signature shape mirrors `ExtensionSignature` in
+ * `packages/engine/src/lib/signature-verify.ts` so the engine can verify
+ * archives produced here without translation.
+ */
+/** Stored keypair format. Matches WebCrypto JWK + a Zveltio-specific keyId. */
+export interface ZveltioKeypair {
+    /** Stable identifier; default is a short random hex string. */
+    keyId: string;
+    /** Created-at, RFC 3339. Informational. */
+    createdAt: string;
+    /** Public half — safe to share. */
+    publicJwk: JsonWebKey;
+    /** Private half — keep on disk + permission 600. */
+    privateJwk: JsonWebKey;
+}
+/** Signature envelope written next to `<archive>.zvext` as `<archive>.zvext.sig`. */
+export interface ExtensionSignature {
+    algorithm: 'ed25519';
+    /** Base64 of the 64-byte Ed25519 signature. */
+    signature: string;
+    /** Hex of sha256(archive bytes). */
+    bundleSha256: string;
+    /** RFC 3339, informational. */
+    signedAt: string;
+    /** Key identifier — engine looks this up in its trusted keys list. */
+    keyId: string;
+}
+declare function bytesToHex(bytes: ArrayBuffer | Uint8Array): string;
+declare function bytesToBase64(bytes: Uint8Array): string;
+declare function base64ToBytes(b64: string): Uint8Array;
+/** Compute sha256(bytes) → lowercase hex. */
+export declare function sha256Hex(bytes: Uint8Array): Promise<string>;
+/**
+ * Generate a fresh Ed25519 keypair.
+ *
+ * @param keyId  Optional stable identifier. If omitted, generates a short
+ *               random hex string. Useful to keep human-readable
+ *               ("zveltio-prod-2026") or to scope per-publisher.
+ */
+export declare function generateKeypair(keyId?: string): Promise<ZveltioKeypair>;
+/** Import a private JWK back into a CryptoKey usable for signing. */
+export declare function importPrivateKey(jwk: JsonWebKey): Promise<CryptoKey>;
+/** Import a public JWK back into a CryptoKey usable for verification. */
+export declare function importPublicKey(jwk: JsonWebKey): Promise<CryptoKey>;
+/**
+ * Build the signature envelope for a given archive.
+ *
+ * Signs over the UTF-8 bytes of the lowercase hex sha256 — same shape the
+ * engine verifier (`verifySignature`) expects. Stays away from signing the
+ * raw archive directly so the signature payload is a fixed 64 bytes
+ * regardless of archive size.
+ */
+export declare function signBundle(archive: Uint8Array, keypair: ZveltioKeypair): Promise<ExtensionSignature>;
+/**
+ * Verify a signature against an archive — symmetric to the engine's
+ * `verifySignature`. Returned errors are plain strings so the CLI can
+ * print them without leaking internal types.
+ */
+export declare function verifyBundle(archive: Uint8Array, signature: ExtensionSignature, publicJwk: JsonWebKey): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+}>;
+/**
+ * Convenience: derive a registry-style "trusted key" entry from a public
+ * JWK so a publisher can copy-paste it into the engine's
+ * `REGISTRY_PUBLIC_KEYS_JSON` env (or hand it to the registry admin).
+ *
+ * Returns `{ keyId, publicKeyHex }` — exact shape the engine's
+ * `registry-keys.ts` parser expects.
+ */
+export declare function exportTrustedKeyEntry(keyId: string, publicJwk: JsonWebKey): Promise<{
+    keyId: string;
+    publicKeyHex: string;
+}>;
+export declare const _bytes: {
+    bytesToHex: typeof bytesToHex;
+    bytesToBase64: typeof bytesToBase64;
+    base64ToBytes: typeof base64ToBytes;
+};
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/publish/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/publish/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,+EAA+E;AAC/E,MAAM,WAAW,cAAc;IAC7B,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,mCAAmC;IACnC,SAAS,EAAE,UAAU,CAAC;IACtB,oDAAoD;IACpD,UAAU,EAAE,UAAU,CAAC;CACxB;AAED,qFAAqF;AACrF,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,SAAS,CAAC;IACrB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,oCAAoC;IACpC,YAAY,EAAE,MAAM,CAAC;IACrB,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAC;CACf;AAED,iBAAS,UAAU,CAAC,KAAK,EAAE,WAAW,GAAG,UAAU,GAAG,MAAM,CAK3D;AAED,iBAAS,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAKhD;AAED,iBAAS,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAO9C;AAED,6CAA6C;AAC7C,wBAAsB,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAGlE;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAY7E;AAQD,qEAAqE;AACrE,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAE1E;AAED,yEAAyE;AACzE,wBAAsB,eAAe,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAEzE;AAED;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,UAAU,EACnB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,kBAAkB,CAAC,CAY7B;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,UAAU,EACnB,SAAS,EAAE,kBAAkB,EAC7B,SAAS,EAAE,UAAU,GACpB,OAAO,CAAC;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CA6BvD;AAED;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,UAAU,GACpB,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC,CASlD;AAGD,eAAO,MAAM,MAAM;;;;CAA+C,CAAC"}

package/dist/publish/index.js

@@ -0,0 +1,148 @@
+/**
+ * Publish primitives for `zveltio extension publish` (S4-05).
+ *
+ * Pure functions: WebCrypto Ed25519 keypairs, archive hashing, signature
+ * envelope shape that matches the engine's verifier (S1-01). No filesystem,
+ * no HTTP — the CLI layers those on top.
+ *
+ * Storage format: JWK. We pick JWK over PKCS#8 because it is JSON-native
+ * (one file per key, plain `Bun.write`), works in Cloudflare Workers without
+ * conversion, and survives copy-paste through environment variables.
+ *
+ * Signature shape mirrors `ExtensionSignature` in
+ * `packages/engine/src/lib/signature-verify.ts` so the engine can verify
+ * archives produced here without translation.
+ */
+function bytesToHex(bytes) {
+    const view = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+    let out = '';
+    for (let i = 0; i < view.length; i++)
+        out += view[i].toString(16).padStart(2, '0');
+    return out;
+}
+function bytesToBase64(bytes) {
+    // btoa is available in Bun + browsers. Node 22+ has it too.
+    let bin = '';
+    for (let i = 0; i < bytes.length; i++)
+        bin += String.fromCharCode(bytes[i]);
+    return btoa(bin);
+}
+function base64ToBytes(b64) {
+    const normalized = b64.replace(/-/g, '+').replace(/_/g, '/');
+    const padded = normalized + '='.repeat((4 - (normalized.length % 4)) % 4);
+    const bin = atob(padded);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+/** Compute sha256(bytes) → lowercase hex. */
+export async function sha256Hex(bytes) {
+    const buf = await crypto.subtle.digest('SHA-256', bytes);
+    return bytesToHex(buf);
+}
+/**
+ * Generate a fresh Ed25519 keypair.
+ *
+ * @param keyId  Optional stable identifier. If omitted, generates a short
+ *               random hex string. Useful to keep human-readable
+ *               ("zveltio-prod-2026") or to scope per-publisher.
+ */
+export async function generateKeypair(keyId) {
+    const pair = await crypto.subtle.generateKey({ name: 'Ed25519' }, true, ['sign', 'verify']);
+    const kp = pair;
+    const publicJwk = await crypto.subtle.exportKey('jwk', kp.publicKey);
+    const privateJwk = await crypto.subtle.exportKey('jwk', kp.privateKey);
+    const finalKeyId = keyId ?? randomKeyId();
+    return {
+        keyId: finalKeyId,
+        createdAt: new Date().toISOString(),
+        publicJwk,
+        privateJwk,
+    };
+}
+function randomKeyId() {
+    const buf = new Uint8Array(6);
+    crypto.getRandomValues(buf);
+    return 'zv-' + bytesToHex(buf);
+}
+/** Import a private JWK back into a CryptoKey usable for signing. */
+export async function importPrivateKey(jwk) {
+    return await crypto.subtle.importKey('jwk', jwk, { name: 'Ed25519' }, false, ['sign']);
+}
+/** Import a public JWK back into a CryptoKey usable for verification. */
+export async function importPublicKey(jwk) {
+    return await crypto.subtle.importKey('jwk', jwk, { name: 'Ed25519' }, false, ['verify']);
+}
+/**
+ * Build the signature envelope for a given archive.
+ *
+ * Signs over the UTF-8 bytes of the lowercase hex sha256 — same shape the
+ * engine verifier (`verifySignature`) expects. Stays away from signing the
+ * raw archive directly so the signature payload is a fixed 64 bytes
+ * regardless of archive size.
+ */
+export async function signBundle(archive, keypair) {
+    const bundleSha256 = await sha256Hex(archive);
+    const key = await importPrivateKey(keypair.privateJwk);
+    const dataBytes = new TextEncoder().encode(bundleSha256.toLowerCase());
+    const sigBuf = await crypto.subtle.sign({ name: 'Ed25519' }, key, dataBytes);
+    return {
+        algorithm: 'ed25519',
+        signature: bytesToBase64(new Uint8Array(sigBuf)),
+        bundleSha256,
+        signedAt: new Date().toISOString(),
+        keyId: keypair.keyId,
+    };
+}
+/**
+ * Verify a signature against an archive — symmetric to the engine's
+ * `verifySignature`. Returned errors are plain strings so the CLI can
+ * print them without leaking internal types.
+ */
+export async function verifyBundle(archive, signature, publicJwk) {
+    if (signature.algorithm !== 'ed25519') {
+        return { ok: false, reason: `unsupported algorithm "${signature.algorithm}"` };
+    }
+    const actualHash = await sha256Hex(archive);
+    if (actualHash.toLowerCase() !== signature.bundleSha256.toLowerCase()) {
+        return {
+            ok: false,
+            reason: `bundleSha256 mismatch (expected ${signature.bundleSha256}, got ${actualHash})`,
+        };
+    }
+    let sigBytes;
+    try {
+        sigBytes = base64ToBytes(signature.signature);
+    }
+    catch (err) {
+        return { ok: false, reason: `signature is not valid base64: ${err.message}` };
+    }
+    if (sigBytes.length !== 64) {
+        return { ok: false, reason: `signature length ${sigBytes.length} is not 64 bytes` };
+    }
+    const key = await importPublicKey(publicJwk);
+    const dataBytes = new TextEncoder().encode(signature.bundleSha256.toLowerCase());
+    const ok = await crypto.subtle.verify({ name: 'Ed25519' }, key, sigBytes, dataBytes);
+    return ok ? { ok: true } : { ok: false, reason: 'Ed25519 verification failed' };
+}
+/**
+ * Convenience: derive a registry-style "trusted key" entry from a public
+ * JWK so a publisher can copy-paste it into the engine's
+ * `REGISTRY_PUBLIC_KEYS_JSON` env (or hand it to the registry admin).
+ *
+ * Returns `{ keyId, publicKeyHex }` — exact shape the engine's
+ * `registry-keys.ts` parser expects.
+ */
+export async function exportTrustedKeyEntry(keyId, publicJwk) {
+    // Re-import as `extractable: true` — the cached `importPublicKey` produces
+    // a non-extractable key for hot-path verification. Cheap (microseconds) and
+    // keeps the exporter as a one-liner for callers.
+    const key = await crypto.subtle.importKey('jwk', publicJwk, { name: 'Ed25519' }, true, [
+        'verify',
+    ]);
+    const rawBuf = await crypto.subtle.exportKey('raw', key);
+    return { keyId, publicKeyHex: bytesToHex(new Uint8Array(rawBuf)) };
+}
+// Re-exports for the CLI to encode/decode bytes without pulling in node:buffer.
+export const _bytes = { bytesToHex, bytesToBase64, base64ToBytes };

package/dist/realtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"realtime.d.ts","sourceRoot":"","sources":["../src/realtime.ts"],"names":[],"mappings":"AAAA,qBAAa,eAAe;IAC1B,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,SAAS,CAAoD;IACrE,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,oBAAoB,CAAM;IAClC,OAAO,CAAC,cAAc,CAA8C;gBAExD,OAAO,EAAE,MAAM;IAK3B,OAAO,IAAI,IAAI;IAmCf,OAAO,CAAC,gBAAgB;IAQxB,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,IAAI,GAAG,MAAM,IAAI;IAqBxE,UAAU,IAAI,IAAI;CAQnB"}
+{"version":3,"file":"realtime.d.ts","sourceRoot":"","sources":["../src/realtime.ts"],"names":[],"mappings":"AAAA,qBAAa,eAAe;IAC1B,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,SAAS,CAAoD;IACrE,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,oBAAoB,CAAM;IAClC,OAAO,CAAC,cAAc,CAA8C;gBAExD,OAAO,EAAE,MAAM;IAK3B,OAAO,IAAI,IAAI;IAyCf,OAAO,CAAC,gBAAgB;IAQxB,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,IAAI,GAAG,MAAM,IAAI;IAqBxE,UAAU,IAAI,IAAI;CAQnB"}

package/dist/realtime.js

@@ -30,11 +30,15 @@ export class ZveltioRealtime {
                         try {
                             fn(msg);
                         }
-                        catch { /* ignore callback errors */ }
+                        catch {
+                            /* ignore callback errors */
+                        }
                     });
                 }
             }
-            catch { /* invalid JSON — ignore */ }
+            catch {
+                /* invalid JSON — ignore */
+            }
         };
         this.ws.onclose = () => {
             this.attemptReconnect();

package/dist/rpc/index.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Typed Hono RPC client factory.
+ *
+ * Returns a Hono-typed client (via `hono/client#hc`) parameterized by the
+ * engine's `AppType`. Callers get autocomplete + tsc-checked URLs + typed
+ * request/response shapes for every route they hit.
+ *
+ *   import { createRpcClient } from '@zveltio/sdk/rpc';
+ *   import type { ZveltioApi } from '@zveltio/engine/api-types';
+ *
+ *   const client = createRpcClient<ZveltioApi>({ baseUrl: 'http://localhost:3000' });
+ *
+ *   // Typed call — autocomplete on `.api.data[':collection'].$post()` and
+ *   // input/output payloads match the engine's route definition.
+ *   const res = await client.api.data[':collection'].$post({
+ *     param: { collection: 'contacts' },
+ *     json: { email: 'a@b.com', name: 'Alice' },
+ *   });
+ *
+ * Why this lives in the SDK and not the engine:
+ *   - The runtime is tiny — `hc()` is a thin wrapper around `fetch`. No
+ *     reason to duplicate it in every extension. SDK is the natural home.
+ *   - The TYPE comes from the engine (whichever AppType the consumer
+ *     wants to bind against). Extensions can also bind their OWN typed
+ *     Hono routes — the factory is type-generic.
+ *
+ * Wraps `hc()` with two ergonomic additions:
+ *   - `credentials: 'include'` by default so cookie-auth works without
+ *     boilerplate at every call site.
+ *   - Optional `headers` factory called per-request so auth tokens that
+ *     change (e.g. CSRF) can flow without rebuilding the client.
+ */
+import { hc } from 'hono/client';
+import type { Hono } from 'hono';
+export interface RpcClientOptions {
+    /** Base URL of the engine. Required; no default so misconfiguration fails loud. */
+    baseUrl: string;
+    /**
+     * Static headers attached to every request. For dynamic per-request
+     * headers (auth tokens, CSRF), pass `getHeaders` instead.
+     */
+    headers?: Record<string, string>;
+    /** Async/sync function called before each request; result merged into headers. */
+    getHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
+    /**
+     * Forward cookies on every request. Defaults to `true` so session-based
+     * auth (the common case for Studio + extensions on the same origin)
+     * works out of the box. Set `false` for cross-origin SPAs that prefer
+     * bearer tokens.
+     */
+    includeCredentials?: boolean;
+    /**
+     * Override the global `fetch`. Mostly useful in tests (mock fetch) or
+     * server-side rendering where you want to attach the user's cookie to
+     * a server-issued request.
+     */
+    fetch?: typeof fetch;
+}
+/**
+ * Build a Hono RPC client for the given app type.
+ *
+ * @typeParam T  The Hono app type. For the Zveltio engine, import
+ *               `ZveltioApi` from `@zveltio/engine/api-types`. For an
+ *               extension's own routes, pass `typeof yourApp`.
+ */
+export declare function createRpcClient<T extends Hono<any, any, any>>(opts: RpcClientOptions): ReturnType<typeof hc<T>>;
+export type { InferRequestType, InferResponseType } from 'hono/client';
+//# sourceMappingURL=index.d.ts.map

package/dist/rpc/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/rpc/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AACjC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAEjC,MAAM,WAAW,gBAAgB;IAC/B,mFAAmF;IACnF,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,kFAAkF;IAClF,UAAU,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC5E;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAC3D,IAAI,EAAE,gBAAgB,GACrB,UAAU,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAoB1B;AAID,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC"}

package/dist/rpc/index.js

@@ -0,0 +1,61 @@
+/**
+ * Typed Hono RPC client factory.
+ *
+ * Returns a Hono-typed client (via `hono/client#hc`) parameterized by the
+ * engine's `AppType`. Callers get autocomplete + tsc-checked URLs + typed
+ * request/response shapes for every route they hit.
+ *
+ *   import { createRpcClient } from '@zveltio/sdk/rpc';
+ *   import type { ZveltioApi } from '@zveltio/engine/api-types';
+ *
+ *   const client = createRpcClient<ZveltioApi>({ baseUrl: 'http://localhost:3000' });
+ *
+ *   // Typed call — autocomplete on `.api.data[':collection'].$post()` and
+ *   // input/output payloads match the engine's route definition.
+ *   const res = await client.api.data[':collection'].$post({
+ *     param: { collection: 'contacts' },
+ *     json: { email: 'a@b.com', name: 'Alice' },
+ *   });
+ *
+ * Why this lives in the SDK and not the engine:
+ *   - The runtime is tiny — `hc()` is a thin wrapper around `fetch`. No
+ *     reason to duplicate it in every extension. SDK is the natural home.
+ *   - The TYPE comes from the engine (whichever AppType the consumer
+ *     wants to bind against). Extensions can also bind their OWN typed
+ *     Hono routes — the factory is type-generic.
+ *
+ * Wraps `hc()` with two ergonomic additions:
+ *   - `credentials: 'include'` by default so cookie-auth works without
+ *     boilerplate at every call site.
+ *   - Optional `headers` factory called per-request so auth tokens that
+ *     change (e.g. CSRF) can flow without rebuilding the client.
+ */
+import { hc } from 'hono/client';
+/**
+ * Build a Hono RPC client for the given app type.
+ *
+ * @typeParam T  The Hono app type. For the Zveltio engine, import
+ *               `ZveltioApi` from `@zveltio/engine/api-types`. For an
+ *               extension's own routes, pass `typeof yourApp`.
+ */
+export function createRpcClient(opts) {
+    const baseUrl = opts.baseUrl.replace(/\/$/, '');
+    const includeCredentials = opts.includeCredentials !== false;
+    const customFetch = (async (input, init) => {
+        const dynHeaders = opts.getHeaders ? await opts.getHeaders() : {};
+        const merged = new Headers(init?.headers ?? {});
+        for (const [k, v] of Object.entries(opts.headers ?? {}))
+            merged.set(k, v);
+        for (const [k, v] of Object.entries(dynHeaders))
+            merged.set(k, v);
+        return (opts.fetch ?? fetch)(input, {
+            ...init,
+            headers: merged,
+            credentials: includeCredentials ? 'include' : init?.credentials,
+        });
+        // Bun's `typeof fetch` includes a `preconnect` static which our wrapper
+        // doesn't reasonably proxy. Cast to silence — at call time hc() only
+        // invokes the function form.
+    });
+    return hc(baseUrl, { fetch: customFetch });
+}