@zveltio/sdk 2.0.8 → 3.0.0-beta.1

package/dist/extension/permission-gate.js

@@ -0,0 +1,93 @@
+/**
+ * `permissionGate` — minimal route-level RBAC for extensions.
+ *
+ * Default-deny: if no Casbin policy grants the resource/action, the request
+ * is rejected with 403. The god role bypasses the gate (handled by the
+ * engine's `checkPermission`).
+ *
+ * Action is derived from the HTTP method using the standard CRUD mapping
+ * (GET → read, POST → create, PATCH/PUT → update, DELETE → delete). The
+ * `resource` is the extension's logical name (e.g. `'crm'`, `'invoices'`);
+ * operators grant access by adding a Casbin policy:
+ *
+ *     INSERT INTO zvd_permissions (ptype, v0, v1, v2)
+ *     VALUES ('p', 'user_role', 'crm', 'read');
+ *
+ * Why this exists: many extensions historically only checked
+ * `auth.api.getSession(...)` — i.e. any authenticated user could
+ * read/write the entire extension. That's the right default for a
+ * single-tenant deployment but unacceptable in multi-tenant or
+ * role-segmented installs. The gate gives operators a single knob to
+ * tighten access without each extension having to roll its own RBAC.
+ *
+ * Usage in an extension's `routes.ts`:
+ *
+ *     app.use('*', permissionGate(ctx, 'crm'));
+ *
+ * Place AFTER the auth-guard middleware that sets `c.set('user', ...)`.
+ */
+function methodToAction(method) {
+    const m = method.toUpperCase();
+    switch (m) {
+        case 'GET':
+        case 'HEAD':
+        case 'OPTIONS':
+            return 'read';
+        case 'POST':
+            return 'create';
+        case 'PATCH':
+        case 'PUT':
+            return 'update';
+        case 'DELETE':
+            return 'delete';
+        default:
+            // Unknown method → demand the most restrictive action so the gate
+            // never fails open.
+            return 'delete';
+    }
+}
+/**
+ * Operators can disable the gate temporarily during a permission backfill
+ * by setting `EXTENSION_RBAC=permissive`. When permissive, the gate becomes
+ * a no-op (any authenticated user passes) but still logs the denied
+ * attempts so the operator can preview what *would* have been blocked
+ * before flipping to strict.
+ *
+ * Strict (default) is the secure posture and what the SDK ships with.
+ */
+function rbacMode() {
+    const v = globalThis.process?.env?.EXTENSION_RBAC;
+    return v === 'permissive' ? 'permissive' : 'strict';
+}
+export function permissionGate(ctx, resource, opts = {}) {
+    return async (c, next) => {
+        // CORS preflight (OPTIONS) must never be authorization-gated —
+        // browsers send it without credentials and a 401/403 here breaks
+        // the actual cross-origin request that would follow. The global
+        // CORS middleware in the engine returns the preflight response;
+        // we just need to let it through.
+        if (c.req.method === 'OPTIONS') {
+            await next();
+            return;
+        }
+        const user = c.get('user');
+        if (!user?.id) {
+            return c.json({ error: 'Unauthorized' }, 401);
+        }
+        const methodKey = c.req.method.toUpperCase();
+        const action = opts.actionOverrides?.[methodKey] ?? methodToAction(methodKey);
+        const allowed = await ctx.checkPermission(user.id, resource, action);
+        if (!allowed) {
+            if (rbacMode() === 'permissive') {
+                // Audit-log mode: surface what WOULD be blocked so operators can
+                // configure policies before flipping to strict. Stays a single
+                // console.warn — no DB writes on the hot path.
+                console.warn(`[permissionGate] WOULD DENY user=${user.id} ${c.req.method} ${c.req.path} → ${resource}:${action} (EXTENSION_RBAC=permissive — gate bypassed)`);
+                await next();
+                return;
+            }
+            return c.json({ error: `Forbidden: missing ${resource}:${action} permission` }, 403);
+        }
+        await next();
+    };
+}

package/dist/generate-types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * generate-types.ts
+ *
+ * Programmatic type generator for Zveltio collections.
+ * Fetches collection schemas from a running Zveltio engine and generates
+ * TypeScript interface declarations with full type information.
+ *
+ * Usage (programmatic):
+ *   import { generateTypes } from '@zveltio/sdk/generate-types';
+ *   const dts = await generateTypes({ url: 'http://localhost:3000', apiKey: 'sk-...' });
+ *   await fs.writeFile('./types/zveltio.d.ts', dts);
+ *
+ * Usage (CLI):
+ *   zveltio generate-types --output ./types/zveltio.d.ts
+ *   zveltio types --output ./types/zveltio.d.ts
+ */
+export interface GenerateTypesOptions {
+    /** Zveltio engine URL (default: http://localhost:3000) */
+    url?: string;
+    /** API key for authentication */
+    apiKey?: string;
+    /** Only generate types for this collection */
+    collection?: string;
+}
+/**
+ * Generates TypeScript declarations for all (or one) Zveltio collection(s).
+ *
+ * Returns the `.d.ts` file content as a string. The caller is responsible for
+ * writing it to disk.
+ *
+ * The engine endpoint `/api/admin/types` is used when available (returns
+ * pre-generated TS from the server's field-type registry). If the endpoint
+ * fails or is unavailable this function falls back to generating types from
+ * the collection schema returned by `/api/collections`.
+ */
+export declare function generateTypes(options?: GenerateTypesOptions): Promise<string>;
+//# sourceMappingURL=generate-types.d.ts.map

package/dist/generate-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-types.d.ts","sourceRoot":"","sources":["../src/generate-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AA0HH,MAAM,WAAW,oBAAoB;IACnC,0DAA0D;IAC1D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,iCAAiC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,MAAM,CAAC,CAyDvF"}

package/dist/generate-types.js

@@ -0,0 +1,157 @@
+/**
+ * generate-types.ts
+ *
+ * Programmatic type generator for Zveltio collections.
+ * Fetches collection schemas from a running Zveltio engine and generates
+ * TypeScript interface declarations with full type information.
+ *
+ * Usage (programmatic):
+ *   import { generateTypes } from '@zveltio/sdk/generate-types';
+ *   const dts = await generateTypes({ url: 'http://localhost:3000', apiKey: 'sk-...' });
+ *   await fs.writeFile('./types/zveltio.d.ts', dts);
+ *
+ * Usage (CLI):
+ *   zveltio generate-types --output ./types/zveltio.d.ts
+ *   zveltio types --output ./types/zveltio.d.ts
+ */
+// ── Field type → TypeScript type mapping ─────────────────────────────────────
+const FIELD_TYPE_MAP = {
+    text: 'string',
+    textarea: 'string',
+    richtext: 'string',
+    markdown: 'string',
+    email: 'string',
+    url: 'string',
+    password: 'string',
+    slug: 'string',
+    uuid: 'string',
+    color: 'string',
+    number: 'number',
+    integer: 'number',
+    decimal: 'number',
+    float: 'number',
+    currency: 'number',
+    percentage: 'number',
+    boolean: 'boolean',
+    toggle: 'boolean',
+    date: 'string', // ISO 8601 date string
+    datetime: 'string', // ISO 8601 datetime string
+    time: 'string',
+    timestamp: 'string',
+    json: 'Record<string, unknown>',
+    jsonb: 'Record<string, unknown>',
+    object: 'Record<string, unknown>',
+    array: 'unknown[]',
+    tags: 'string[]',
+    select: 'string',
+    multiselect: 'string[]',
+    relation: 'string', // UUID of related record
+    file: 'string', // storage path
+    image: 'string', // storage path
+    point: '{ lat: number; lng: number }',
+    geojson: 'GeoJSON.Geometry',
+};
+function fieldTypeToTs(fieldType) {
+    return FIELD_TYPE_MAP[fieldType.toLowerCase()] ?? 'unknown';
+}
+/**
+ * Converts a collection name (snake_case) to a PascalCase interface name.
+ * Examples: "my_orders" → "MyOrders", "products" → "Products"
+ */
+function toPascalCase(name) {
+    return name
+        .split(/[_\s-]+/)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1).toLowerCase())
+        .join('');
+}
+function generateCollectionInterface(col) {
+    const interfaceName = toPascalCase(col.name) + 'Collection';
+    const fields = col.fields ?? [];
+    const lines = [];
+    if (col.description) {
+        lines.push(`/** ${col.description} */`);
+    }
+    lines.push(`export interface ${interfaceName} {`);
+    lines.push(`  /** Internal record ID (UUID) */`);
+    lines.push(`  id: string;`);
+    for (const field of fields) {
+        if (field.description) {
+            lines.push(`  /** ${field.description} */`);
+        }
+        const tsType = fieldTypeToTs(field.type);
+        const optional = field.required ? '' : '?';
+        lines.push(`  ${field.name}${optional}: ${tsType};`);
+    }
+    lines.push(`  /** ISO 8601 creation timestamp */`);
+    lines.push(`  created_at: string;`);
+    lines.push(`  /** ISO 8601 last-updated timestamp */`);
+    lines.push(`  updated_at: string;`);
+    lines.push(`}`);
+    return lines.join('\n');
+}
+function generateIndexInterface(collections) {
+    const lines = [];
+    lines.push(`/** Index of all Zveltio collections — use with \`ZveltioClient<ZveltioCollections>\` */`);
+    lines.push(`export interface ZveltioCollections {`);
+    for (const col of collections) {
+        const interfaceName = toPascalCase(col.name) + 'Collection';
+        const comment = col.display_name || col.name;
+        lines.push(`  /** ${comment} */`);
+        lines.push(`  ${col.name}: ${interfaceName};`);
+    }
+    lines.push(`}`);
+    return lines.join('\n');
+}
+/**
+ * Generates TypeScript declarations for all (or one) Zveltio collection(s).
+ *
+ * Returns the `.d.ts` file content as a string. The caller is responsible for
+ * writing it to disk.
+ *
+ * The engine endpoint `/api/admin/types` is used when available (returns
+ * pre-generated TS from the server's field-type registry). If the endpoint
+ * fails or is unavailable this function falls back to generating types from
+ * the collection schema returned by `/api/collections`.
+ */
+export async function generateTypes(options = {}) {
+    const engineUrl = (options.url ?? process.env.ZVELTIO_URL ?? 'http://localhost:3000').replace(/\/$/, '');
+    const apiKey = options.apiKey ?? process.env.ZVELTIO_API_KEY ?? '';
+    const headers = {};
+    if (apiKey)
+        headers['Authorization'] = `Bearer ${apiKey}`;
+    // ── Try fast path: engine pre-generates types ────────────────────────────
+    try {
+        const path = options.collection
+            ? `/api/admin/types/${encodeURIComponent(options.collection)}`
+            : '/api/admin/types';
+        const res = await fetch(`${engineUrl}${path}`, { headers });
+        if (res.ok) {
+            return await res.text();
+        }
+        // Fall through to manual generation on 404/401/500
+        if (res.status !== 404) {
+            console.warn(`[generate-types] Engine /api/admin/types returned ${res.status}, falling back to manual generation.`);
+        }
+    }
+    catch {
+        // Engine unreachable or endpoint absent — use fallback
+    }
+    // ── Fallback: fetch schema and generate types locally ────────────────────
+    const collectionsUrl = options.collection
+        ? `${engineUrl}/api/collections/${encodeURIComponent(options.collection)}`
+        : `${engineUrl}/api/collections`;
+    const res = await fetch(collectionsUrl, { headers });
+    if (!res.ok) {
+        throw new Error(`Failed to fetch collections from ${collectionsUrl}: ${res.status} ${res.statusText}`);
+    }
+    const data = (await res.json());
+    const collections = Array.isArray(data.collections)
+        ? data.collections.filter((c) => !c.is_system)
+        : data.collection
+            ? [data.collection]
+            : [];
+    const header = `// Auto-generated by Zveltio\n// Do not edit manually — run: zveltio generate-types\n// Generated: ${new Date().toISOString()}\n`;
+    const interfaces = collections.map(generateCollectionInterface).join('\n\n');
+    const indexType = options.collection ? '' : '\n\n' + generateIndexInterface(collections);
+    return `${header}\n${interfaces}${indexType}\n`;
+}

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export type { ZveltioClientConfig, ListParams, ListResult } from './client.js';
 export { ZveltioRealtime } from './realtime.js';
 export { LocalStore } from './local-store.js';
 export { SyncManager } from './sync-manager.js';
-export type { ZveltioExtension } from './extension/index.js';
+export type { ZveltioExtension, ExtensionContext, FieldTypeRegistryAPI, StudioExtensionAPI, StudioRoute, StudioFieldType, AssetPreviewHandler, } from './extension/index.js';
 export type { LocalRecord, SyncQueueItem } from './local-store.js';
 export type { SyncManagerConfig } from './sync-manager.js';
 export { useSyncCollection, useSyncStatus } from './svelte.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACjE,YAAY,EAAE,mBAAmB,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC/E,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACnE,YAAY,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC/D,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAG1B,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACjE,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACjE,YAAY,EAAE,mBAAmB,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC/E,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EACV,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,kBAAkB,EAClB,WAAW,EACX,eAAe,EACf,mBAAmB,GACpB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACnE,YAAY,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC/D,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAG1B,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACjE,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/local-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"local-store.d.ts","sourceRoot":"","sources":["../src/local-store.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"local-store.d.ts","sourceRoot":"","sources":["../src/local-store.ts"],"names":[],"mappings":"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"}

package/dist/local-store.js

@@ -134,9 +134,7 @@ export class LocalStore {
         // Remove from queue
         await tx.objectStore('sync_queue').delete(queueItemId);
         // Update record status
-        const record = (await tx
-            .objectStore('records')
-            .get([collection, recordId]));
+        const record = (await tx.objectStore('records').get([collection, recordId]));
         if (record) {
             record._serverVersion = serverVersion;
             record._syncStatus = 'synced';

package/dist/offline/index.d.ts

@@ -0,0 +1,105 @@
+/**
+ * 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 type OfflineProviderKind = 'crdt' | 'electric';
+export interface OfflineProviderConfig {
+    /** Which sync engine to use. Default: 'crdt'. */
+    provider?: OfflineProviderKind;
+    /** Engine base URL — used for the token-mint call AND CRDT push/pull. */
+    engineUrl: string;
+    /**
+     * Override the Electric websocket URL. When omitted, the provider asks
+     * the engine via `GET /api/electric/config` so operators have a single
+     * place to configure it. Useful for tests + dev setups.
+     */
+    electricUrl?: string;
+    /**
+     * Tables to record on the audit token claim. Does NOT restrict what
+     * Electric replicates — Electric enforces that via its own config.
+     */
+    tables?: string[];
+    /**
+     * Override the `fetch` impl — handy for tests + SSR. Default: globalThis.fetch.
+     */
+    fetch?: typeof fetch;
+    /**
+     * Override the WebSocket constructor — handy for tests + non-browser
+     * runtimes. Default: globalThis.WebSocket.
+     */
+    websocket?: typeof WebSocket;
+}
+/**
+ * Public interface every provider implements. Today the CRDT provider
+ * wraps `SyncManager`; the Electric provider wraps a websocket. Both
+ * expose the same surface.
+ */
+export interface OfflineProvider {
+    readonly kind: OfflineProviderKind;
+    /** Pull remote rows into the local store. Cheap to call repeatedly. */
+    pull(): Promise<void>;
+    /** Push local mutations to the server. Returns the number of ops sent. */
+    push(): Promise<number>;
+    /** Subscribe to live changes on a table. Returns an unsubscribe fn. */
+    subscribe(table: string, cb: (rows: unknown[]) => void): () => void;
+    /** Stop background sync + release resources. */
+    close(): Promise<void>;
+}
+export declare class ElectricNotConfigured extends Error {
+    constructor(reason: string);
+}
+export declare class ElectricUnavailable extends Error {
+    constructor(reason: string);
+}
+/**
+ * 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 declare function createOfflineProvider(config: OfflineProviderConfig): Promise<OfflineProvider>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/offline/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,UAAU,CAAC;AAEtD,MAAM,WAAW,qBAAqB;IACpC,iDAAiD;IACjD,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IAC/B,yEAAyE;IACzE,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,SAAS,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,uEAAuE;IACvE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,0EAA0E;IAC1E,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACxB,uEAAuE;IACvE,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACpE,gDAAgD;IAChD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,MAAM,EAAE,MAAM;CAQ3B;AAED,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,MAAM,EAAE,MAAM;CAQ3B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,eAAe,CAAC,CAQ1B"}