@svgrid/enterprise 2.5.2 → 2.6.0

package/dist/sveltekit/sql.js

@@ -0,0 +1,73 @@
+export function planToSql(plan, dialect = {}) {
+    const q = dialect.quote ?? '"';
+    const useIlike = dialect.ilike ?? false;
+    const params = [];
+    const ph = () => {
+        if (dialect.placeholders === '$')
+            return `$${params.length}`;
+        if (dialect.placeholders === '@')
+            return `@p${params.length}`;
+        return '?';
+    };
+    const bind = (v) => {
+        params.push(v);
+        return ph();
+    };
+    const columnFor = dialect.column ?? ((f) => f);
+    const id = (field) => {
+        const c = columnFor(field);
+        return `${q}${c.replace(new RegExp(q, 'g'), q + q)}${q}`;
+    };
+    const like = (field, pattern) => {
+        const p = bind(pattern);
+        return useIlike ? `${id(field)} ILIKE ${p}` : `LOWER(${id(field)}) LIKE LOWER(${p})`;
+    };
+    const clauses = [];
+    for (const pred of plan.where) {
+        clauses.push(predicateSql(pred, { id, bind, like }));
+    }
+    if (plan.search && plan.search.fields.length > 0) {
+        const term = `%${plan.search.term}%`;
+        const ors = plan.search.fields.map((f) => like(f, term));
+        clauses.push(`(${ors.join(' OR ')})`);
+    }
+    const where = clauses.join(' AND ');
+    const orderBy = plan.orderBy.map((o) => `${id(o.field)} ${o.desc ? 'DESC' : 'ASC'}`).join(', ');
+    return {
+        where,
+        whereText: where ? `WHERE ${where}` : '',
+        orderBy,
+        orderByText: orderBy ? `ORDER BY ${orderBy}` : '',
+        params,
+        limit: plan.limit,
+        offset: plan.offset,
+    };
+}
+function predicateSql(pred, ctx) {
+    const { id, bind, like } = ctx;
+    const col = id(pred.field);
+    switch (pred.op) {
+        case 'eq':
+            return `${col} = ${bind(pred.value)}`;
+        case 'contains':
+            return like(pred.field, `%${pred.value}%`);
+        case 'startsWith':
+            return like(pred.field, `${pred.value}%`);
+        case 'gt':
+            return `${col} > ${bind(pred.value)}`;
+        case 'lt':
+            return `${col} < ${bind(pred.value)}`;
+        case 'between':
+            return `${col} BETWEEN ${bind(pred.value)} AND ${bind(pred.valueTo)}`;
+        case 'isBlank':
+            return `(${col} IS NULL OR ${col} = '')`;
+        case 'in': {
+            const vals = pred.values ?? [];
+            if (vals.length === 0)
+                return '1 = 0'; // empty IN () matches nothing
+            return `${col} IN (${vals.map((v) => bind(v)).join(', ')})`;
+        }
+        default:
+            return '1 = 1';
+    }
+}

package/dist/sveltekit/transport.d.ts

@@ -0,0 +1,209 @@
+/**
+ * SvelteKit transport - the deep integration an agnostic grid can't ship.
+ *
+ * Two halves that speak one small JSON protocol over a single route:
+ *
+ *   - `createKitDataSource({ endpoint })` runs in the browser (or a `load`
+ *     function) and returns a `ServerDataSource` that POSTs requests to your
+ *     endpoint. Drop it straight into `createServerDataSource`.
+ *
+ *   - `createKitHandlers({ schema, source })` runs on the server and returns a
+ *     `POST` handler for a `+server.ts` route. It parses the protocol, calls
+ *     your backend `ServerDataSource` (in-memory, SQL, Drizzle, ...), and
+ *     returns JSON.
+ *
+ * Example `src/routes/api/customers/+server.ts`:
+ *
+ *     import { createKitHandlers } from '@svgrid/enterprise'
+ *     import { customerSchema, customerSource } from '../lib/customers'
+ *     export const { POST } = createKitHandlers({ schema: customerSchema, source: customerSource })
+ *
+ * Client:
+ *
+ *     const source = createKitDataSource({ endpoint: '/api/customers' })
+ *     const controller = createServerDataSource(source, { onChange: ... })
+ */
+import type { RowData, ServerDataSource, ServerRequest } from '@svgrid/grid';
+import type { EntitySchema } from '../schema';
+import type { WritableDataSource } from './types';
+/** Wire protocol: the single JSON body shape the client POSTs and the server dispatches on. */
+export type KitMessage<TData> = {
+    kind: 'query';
+    request: ServerRequest;
+} | {
+    kind: 'mutate';
+    op: 'create';
+    input: Partial<TData>;
+} | {
+    kind: 'mutate';
+    op: 'update';
+    id: string;
+    patch: Partial<TData>;
+} | {
+    kind: 'mutate';
+    op: 'delete';
+    id: string;
+};
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+export type KitDataSourceOptions = {
+    /** Route that `createKitHandlers` is mounted on, e.g. `'/api/customers'`. */
+    endpoint: string;
+    /**
+     * Fetch implementation. Pass SvelteKit's event `fetch` inside a `load` so
+     * requests are same-origin and SSR-safe; defaults to the global `fetch`.
+     */
+    fetch?: FetchLike;
+};
+export declare function createKitDataSource<TData extends RowData>(options: KitDataSourceOptions): WritableDataSource<TData>;
+/** The CRUD action a Kit message maps to (`query` -> `read`). */
+export type KitAction = 'read' | 'create' | 'update' | 'delete';
+/** Context passed to the `authorize` guard before every op. */
+export type KitAuthorizeContext<TData extends RowData> = {
+    action: KitAction;
+    /** The SvelteKit request event, so you can read `locals` / session for the
+     *  caller's role or user id. Only `request` is guaranteed in non-Kit callers. */
+    event: {
+        request: Request;
+        locals?: Record<string, unknown>;
+    };
+    message: KitMessage<TData>;
+};
+/** A field-error map (`{ field: message }`); empty/undefined means valid. */
+export type KitFieldErrors = Record<string, string>;
+/** Context passed to a custom `validate` function before a create / update. */
+export type KitValidateContext<TData extends RowData> = {
+    action: 'create' | 'update';
+    values: Partial<TData>;
+    event: {
+        request: Request;
+        locals?: Record<string, unknown>;
+    };
+};
+/** A row-scoping rule: every row this caller may touch has `field === value`. */
+export type KitScope = {
+    field: string;
+    value: unknown;
+};
+export type KitHandlerOptions<TData extends RowData> = {
+    schema: EntitySchema<TData>;
+    source: ServerDataSource<TData>;
+    /**
+     * Restrict every operation to rows matching one column - the mechanism behind
+     * multi-tenancy (`field: 'tenantId'`), and usable for any "you only see your
+     * own rows" rule.
+     *
+     * Enforced on all four paths, because scoping reads alone is not isolation:
+     * - **read**: the predicate is merged into the query's filter model;
+     * - **create**: the value is stamped onto the row, overriding whatever the
+     *   client sent;
+     * - **update / delete**: the target row is re-read under the scope first, and
+     *   the write is rejected with `403` if it isn't the caller's - otherwise
+     *   guessing an id would reach across tenants.
+     *
+     * Return `null` to apply no scope (e.g. a super-admin). Throwing rejects the
+     * request, which is the safer default when a tenant cannot be resolved.
+     */
+    scope?: (ctx: {
+        event: {
+            request: Request;
+            locals?: Record<string, unknown>;
+        };
+    }) => KitScope | null | Promise<KitScope | null>;
+    /**
+     * Optional server-side guard run BEFORE every op. Return `false` (or throw) to
+     * reject the request with `403`. Receives the SvelteKit event, so you can read
+     * `event.locals` / the session to resolve the caller's role - this is where
+     * server-enforced authorization (RBAC) lives, independent of any client UI.
+     */
+    authorize?: (ctx: KitAuthorizeContext<TData>) => boolean | Promise<boolean>;
+    /**
+     * Server-enforced validation, run BEFORE a create / update reaches the source.
+     * - `true`: validate the payload against the `schema`'s declarative constraints
+     *   (required, min/max, length, pattern, email/url, per-field + cross-field
+     *   rules) via `validateAll`. Updates validate only the fields present in the
+     *   patch. Defect payloads are rejected with `422 { error, fieldErrors }`.
+     * - a function: your own check returning a `{ field: message }` map (non-empty
+     *   -> 422).
+     * Default off, so existing routes are unchanged; the Studio generator turns it
+     * on. Enforcing here means a client that skips its form validation still can't
+     * write bad data.
+     */
+    validate?: boolean | ((ctx: KitValidateContext<TData>) => KitFieldErrors | null | undefined | Promise<KitFieldErrors | null | undefined>);
+    /**
+     * Called AFTER a successful create / update / delete with the change details,
+     * so you can write an audit record (who / what / when). Receives the SvelteKit
+     * event for `locals` (the actor). Best-effort: a throw here is swallowed and
+     * logged, so an audit-sink hiccup never fails the underlying write.
+     */
+    audit?: (entry: KitAuditEntry<TData>) => void | Promise<void>;
+    /**
+     * Business-logic lifecycle hooks, run server-side around each mutation (the
+     * Studio generator compiles a screen's visual "triggers" into these). A
+     * `before*` hook may transform the payload (return a new object) or throw to
+     * reject the write (-> `422 { error }`), so a rule enforced here holds even if
+     * the client skips it. `after*` hooks run once the write succeeds (cascades,
+     * notifications) - a throw there fails the request (`500`).
+     */
+    hooks?: KitHooks<TData>;
+};
+/** The SvelteKit event slice handed to every hook (read `locals` for the actor). */
+export type KitEvent = {
+    request: Request;
+    locals?: Record<string, unknown>;
+};
+/** Server-side mutation lifecycle hooks (see `KitHandlerOptions.hooks`). */
+export type KitHooks<TData extends RowData> = {
+    beforeCreate?: (ctx: {
+        values: Partial<TData>;
+        event: KitEvent;
+    }) => Partial<TData> | void | Promise<Partial<TData> | void>;
+    afterCreate?: (ctx: {
+        row: TData;
+        event: KitEvent;
+    }) => void | Promise<void>;
+    beforeUpdate?: (ctx: {
+        id: string;
+        patch: Partial<TData>;
+        event: KitEvent;
+    }) => Partial<TData> | void | Promise<Partial<TData> | void>;
+    afterUpdate?: (ctx: {
+        id: string;
+        row: TData;
+        event: KitEvent;
+    }) => void | Promise<void>;
+    beforeDelete?: (ctx: {
+        id: string;
+        event: KitEvent;
+    }) => void | Promise<void>;
+    afterDelete?: (ctx: {
+        id: string;
+        event: KitEvent;
+    }) => void | Promise<void>;
+};
+/** The change details handed to the `audit` hook after a successful mutation. */
+export type KitAuditEntry<TData extends RowData> = {
+    action: 'create' | 'update' | 'delete';
+    /** The affected row's id. */
+    id: string | null;
+    /** Submitted values: create input / update patch. Undefined for delete. */
+    values?: Partial<TData>;
+    /** The row the source returned (create / update). Undefined for delete. */
+    result?: TData;
+    event: {
+        request: Request;
+        locals?: Record<string, unknown>;
+    };
+};
+export type KitHandlers = {
+    /** SvelteKit `+server.ts` route handler. Export it as `export const { POST } = ...`. */
+    POST: (event: {
+        request: Request;
+        locals?: Record<string, unknown>;
+    }) => Promise<Response>;
+    /** Lower-level dispatcher over a raw `Request`, for custom wiring or tests. */
+    handle: (request: Request, event?: {
+        locals?: Record<string, unknown>;
+    }) => Promise<Response>;
+};
+export declare function createKitHandlers<TData extends RowData>(options: KitHandlerOptions<TData>): KitHandlers;
+export {};

package/dist/sveltekit/transport.js

@@ -0,0 +1,219 @@
+import { validateAll } from '../edit-panel';
+function jsonResponse(data, status = 200) {
+    return new Response(JSON.stringify(data), {
+        status,
+        headers: { 'content-type': 'application/json' },
+    });
+}
+export function createKitDataSource(options) {
+    const doFetch = options.fetch ?? ((i, init) => fetch(i, init));
+    async function post(body) {
+        const res = await doFetch(options.endpoint, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const detail = await res.text().catch(() => '');
+            throw new Error(`svgrid kit: ${res.status} ${res.statusText}${detail ? ` - ${detail}` : ''}`);
+        }
+        return (await res.json());
+    }
+    return {
+        getRows: (request) => post({ kind: 'query', request }),
+        createRow: (input) => post({ kind: 'mutate', op: 'create', input }),
+        updateRow: (id, patch) => post({ kind: 'mutate', op: 'update', id, patch }),
+        deleteRow: (id) => post({ kind: 'mutate', op: 'delete', id }).then(() => undefined),
+    };
+}
+const actionOf = (msg) => msg.kind === 'query' ? 'read' : msg.op;
+export function createKitHandlers(options) {
+    const { source, authorize, validate, audit, hooks, scope } = options;
+    const idField = options.schema.idField ?? options.schema.fields.find((f) => f.primaryKey)?.field ?? 'id';
+    const rowId = (row) => {
+        const v = row?.[idField];
+        return v == null ? null : String(v);
+    };
+    // Best-effort: never let an audit-sink error fail the write it's recording.
+    const fireAudit = async (entry) => {
+        if (!audit)
+            return;
+        try {
+            await audit(entry);
+        }
+        catch (err) {
+            console.error('svgrid kit: audit hook failed', err);
+        }
+    };
+    async function handle(request, event) {
+        let msg;
+        try {
+            msg = (await request.json());
+        }
+        catch {
+            return jsonResponse({ error: 'invalid JSON body' }, 400);
+        }
+        // Authorize BEFORE touching the source. A thrown guard is treated as a deny.
+        if (authorize) {
+            let allowed;
+            try {
+                allowed = await authorize({ action: actionOf(msg), event: { request, locals: event?.locals }, message: msg });
+            }
+            catch (err) {
+                return jsonResponse({ error: err instanceof Error ? err.message : 'forbidden' }, 403);
+            }
+            if (!allowed)
+                return jsonResponse({ error: 'forbidden' }, 403);
+        }
+        // Validate create / update payloads BEFORE the source. 422 on field errors.
+        if (validate && msg.kind === 'mutate' && (msg.op === 'create' || msg.op === 'update')) {
+            const values = (msg.op === 'create' ? msg.input : msg.patch);
+            let errors;
+            if (validate === true) {
+                const all = await validateAll(options.schema, values);
+                // On update, only the supplied fields are validated (a patch omits the rest).
+                errors = msg.op === 'update'
+                    ? Object.fromEntries(Object.keys(values).filter((k) => all[k]).map((k) => [k, all[k]]))
+                    : all;
+            }
+            else {
+                errors = await validate({ action: msg.op, values, event: { request, locals: event?.locals } });
+            }
+            if (errors && Object.keys(errors).length) {
+                return jsonResponse({ error: 'validation failed', fieldErrors: errors }, 422);
+            }
+        }
+        // Resolve the row scope once per request. A thrown resolver is a rejection,
+        // not a 500: "I can't tell which tenant you are" must not fall through to
+        // an unscoped query.
+        let activeScope = null;
+        if (scope) {
+            try {
+                activeScope = (await scope({ event: { request, locals: event?.locals } })) ?? null;
+            }
+            catch (err) {
+                return jsonResponse({ error: err instanceof Error ? err.message : 'forbidden' }, 403);
+            }
+        }
+        /** True when `id` exists AND belongs to the caller's scope. */
+        const ownsRow = async (id) => {
+            if (!activeScope)
+                return true;
+            const idField = options.schema.idField ?? options.schema.fields.find((f) => f.primaryKey)?.field ?? 'id';
+            const { rows } = await source.getRows({
+                startRow: 0,
+                endRow: 1,
+                pageIndex: 0,
+                pageSize: 1,
+                sortModel: [],
+                filterModel: {
+                    columns: {
+                        [idField]: { operator: 'equals', value: id },
+                        [activeScope.field]: { operator: 'equals', value: String(activeScope.value) },
+                    },
+                },
+            });
+            return rows.length > 0;
+        };
+        try {
+            if (msg.kind === 'query') {
+                // Merge the scope into the requested filter. Written last so a client
+                // that sends its own `tenantId` filter cannot widen the scope.
+                const request = activeScope
+                    ? {
+                        ...msg.request,
+                        filterModel: {
+                            ...msg.request.filterModel,
+                            columns: {
+                                ...(msg.request.filterModel?.columns ?? {}),
+                                [activeScope.field]: { operator: 'equals', value: String(activeScope.value) },
+                            },
+                        },
+                    }
+                    : msg.request;
+                const result = await source.getRows(request);
+                return jsonResponse(result);
+            }
+            if (msg.kind === 'mutate') {
+                const evt = { request, locals: event?.locals };
+                // Cross-tenant writes: reject before the source sees the id.
+                if (activeScope && (msg.op === 'update' || msg.op === 'delete')) {
+                    if (!(await ownsRow(msg.id)))
+                        return jsonResponse({ error: 'forbidden' }, 403);
+                }
+                // A `before*` hook throwing is a business-rule rejection -> 422 (not a 500).
+                const runBefore = async (fn) => {
+                    try {
+                        return await fn();
+                    }
+                    catch (err) {
+                        return jsonResponse({ error: err instanceof Error ? err.message : 'rejected' }, 422);
+                    }
+                };
+                if (msg.op === 'create') {
+                    if (!source.createRow)
+                        return jsonResponse({ error: 'create not supported' }, 405);
+                    let input = msg.input;
+                    if (hooks?.beforeCreate) {
+                        const r = await runBefore(() => Promise.resolve(hooks.beforeCreate({ values: input, event: evt })));
+                        if (r instanceof Response)
+                            return r;
+                        if (r)
+                            input = r;
+                    }
+                    // Stamp the scope LAST - after the before-hook - so neither the client
+                    // nor a business rule can write a row into another tenant.
+                    if (activeScope)
+                        input = { ...input, [activeScope.field]: activeScope.value };
+                    const row = await source.createRow(input);
+                    if (hooks?.afterCreate)
+                        await hooks.afterCreate({ row, event: evt });
+                    await fireAudit({ action: 'create', id: rowId(row), values: input, result: row, event: evt });
+                    return jsonResponse(row);
+                }
+                if (msg.op === 'update') {
+                    if (!source.updateRow)
+                        return jsonResponse({ error: 'update not supported' }, 405);
+                    let patch = msg.patch;
+                    if (hooks?.beforeUpdate) {
+                        const r = await runBefore(() => Promise.resolve(hooks.beforeUpdate({ id: msg.id, patch, event: evt })));
+                        if (r instanceof Response)
+                            return r;
+                        if (r)
+                            patch = r;
+                    }
+                    // A patch must not be able to hand the row to another tenant.
+                    if (activeScope)
+                        patch = { ...patch, [activeScope.field]: activeScope.value };
+                    const row = await source.updateRow(msg.id, patch);
+                    if (hooks?.afterUpdate)
+                        await hooks.afterUpdate({ id: msg.id, row, event: evt });
+                    await fireAudit({ action: 'update', id: msg.id, values: patch, result: row, event: evt });
+                    return jsonResponse(row);
+                }
+                if (msg.op === 'delete') {
+                    if (!source.deleteRow)
+                        return jsonResponse({ error: 'delete not supported' }, 405);
+                    if (hooks?.beforeDelete) {
+                        const r = await runBefore(() => Promise.resolve(hooks.beforeDelete({ id: msg.id, event: evt })));
+                        if (r instanceof Response)
+                            return r;
+                    }
+                    await source.deleteRow(msg.id);
+                    if (hooks?.afterDelete)
+                        await hooks.afterDelete({ id: msg.id, event: evt });
+                    await fireAudit({ action: 'delete', id: msg.id, event: evt });
+                    return jsonResponse({ ok: true });
+                }
+            }
+            return jsonResponse({ error: 'unknown message kind' }, 400);
+        }
+        catch (err) {
+            return jsonResponse({ error: err instanceof Error ? err.message : String(err) }, 500);
+        }
+    }
+    return {
+        handle,
+        POST: (event) => handle(event.request, event),
+    };
+}

package/{src/sveltekit/types.ts → dist/sveltekit/types.d.ts}

@@ -1,11 +1,8 @@
-import type { RowData, ServerDataSource } from '@svgrid/grid'
-
-/**
- * A `ServerDataSource` that implements the full CRUD contract - the optional
- * `createRow` / `updateRow` / `deleteRow` are required here. Sources that
- * always support writes (the in-memory reference source, the SvelteKit client)
- * return this so callers get the methods without a null check.
- */
-export type WritableDataSource<TData extends RowData> = Required<
-  Pick<ServerDataSource<TData>, 'getRows' | 'createRow' | 'updateRow' | 'deleteRow'>
->
+import type { RowData, ServerDataSource } from '@svgrid/grid';
+/**
+ * A `ServerDataSource` that implements the full CRUD contract - the optional
+ * `createRow` / `updateRow` / `deleteRow` are required here. Sources that
+ * always support writes (the in-memory reference source, the SvelteKit client)
+ * return this so callers get the methods without a null check.
+ */
+export type WritableDataSource<TData extends RowData> = Required<Pick<ServerDataSource<TData>, 'getRows' | 'createRow' | 'updateRow' | 'deleteRow'>>;

package/dist/sveltekit/types.js

@@ -0,0 +1 @@
+export {};

package/dist/upgrade-prompt.d.ts

@@ -0,0 +1,16 @@
+/** Human-readable labels for the Pro surfaces that gate behind a license. */
+export type EnterpriseFeatureLabel = 'Export' | 'Import' | 'Print' | 'AI assistant' | 'Pivot' | 'Studio';
+/**
+ * Show the contextual upgrade prompt for `feature`. No-ops if one has already
+ * been shown this session, a card is already up, or we're on the server. Safe
+ * to call on every Pro feature invocation - it self-throttles.
+ */
+export declare function showUpgradePrompt(feature?: EnterpriseFeatureLabel | string, opts?: {
+    expired?: boolean;
+}): void;
+/**
+ * Remove the card if present and re-arm the once-per-session flag so a later
+ * `showUpgradePrompt()` can show again. Mainly for hosts that want to control
+ * the nudge themselves (and for tests).
+ */
+export declare function dismissUpgradePrompt(): void;