@zveltio/sdk 3.0.0-beta.4 → 3.0.0-beta.68

package/dist/extension/jsonb.js

@@ -0,0 +1,64 @@
+/**
+ * Binding a JavaScript value to a `jsonb` column.
+ *
+ * There is one correct form and three plausible wrong ones. All four were
+ * measured against this driver, on a real `jsonb` column:
+ *
+ *   JSON.stringify(v)                   → a jsonb STRING. `jsonb_typeof` says
+ *                                         `string`, `col->>'k'` is NULL and
+ *                                         `col ? 'k'` is false.
+ *
+ *   the raw value                       → correct for an object, WRONG for an
+ *                                         array: the driver renders a JS array
+ *                                         as a Postgres array literal, so
+ *                                         `[{a:1}]` lands as the string
+ *                                         `{"[object Object]"}`.
+ *
+ *   JSON.stringify(v) + `::jsonb`       → still a jsonb STRING. The obvious
+ *                                         repair and a trap: the driver has
+ *                                         already encoded the parameter as JSON,
+ *                                         so the cast turns a jsonb string into
+ *                                         a jsonb string.
+ *
+ *   JSON.stringify(v) + `::text::jsonb` → correct, and correct for EVERY type —
+ *                                         object, array, string, number, boolean
+ *                                         and null. `::text` forces the parameter
+ *                                         to be read as text first, and the
+ *                                         second cast parses it.
+ *
+ * ── Why this lives in the SDK ─────────────────────────────────────
+ *
+ * Because it had already been written twice. The engine has `lib/jsonb.ts`, and
+ * `content/pages` wrote its own after the defect surfaced there in the way that
+ * hurts: a popup's `targets` were appended with `jsonb ||`, and the result was
+ * an ARRAY CONTAINING THE OLD TEXT, because the old value was text. Seventeen
+ * more extensions were writing the same shape with no helper at all.
+ *
+ * A third copy per extension would be the repository's own dominant bug shape —
+ * one rule, written out again somewhere else with a piece missing — so it goes
+ * where both sides already compile against: `@zveltio/sdk/extension`.
+ *
+ * ── Why the defect is invisible until it is not ───────────────────
+ *
+ * Every reader in both repositories carries `typeof x === 'string' ?
+ * JSON.parse(x) : x`, so a string-scalar column reads back correctly and the
+ * bug hides. It surfaces the moment SQL treats the column as structured — a
+ * `->>`, an index, a `||`, a `jsonb_array_elements`. Two of those have already
+ * happened: the `content/pages` popup above, and the engine's flow scheduler,
+ * which read `trigger_config.interval_seconds` off a string and therefore ran
+ * every cron flow at the default interval instead of its configured one.
+ *
+ * `scripts/check-jsonb-binding.ts` in the engine repository is the ratchet.
+ */
+import { sql } from 'kysely';
+/**
+ * A value ready to be assigned to a `jsonb` column.
+ *
+ * Works in `.values()`, in `.set()` and in a `doUpdateSet()` branch — all three
+ * are writers of the same column and all three have been wrong at some point.
+ *
+ *   await db.insertInto('zv_forms').values({ fields: toJsonb(fields) }).execute();
+ */
+export function toJsonb(value) {
+    return sql `${JSON.stringify(value ?? null)}::text::jsonb`;
+}

package/dist/extension/multipart.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Reading a multipart body without turning a bad request into a crash.
+ *
+ * Six extensions opened an upload handler with
+ *
+ *     const formData = await c.req.formData();
+ *     const file = formData.get('file') as File;
+ *     if (!file) return c.json({ error: 'No file provided' }, 400);
+ *
+ * The 400 on the third line says plainly what the author intended a malformed
+ * request to get. It is unreachable: `formData()` throws when the body is not
+ * multipart at all — a client that sends JSON, or sends nothing, or gets the
+ * content-type wrong — so those requests never reach line three. They surface as
+ * an unhandled rejection and a bare 500.
+ *
+ * That is worth more than tidiness. A 500 tells a caller, a retrying webhook
+ * sender, and an uptime monitor that the SERVER is broken, so the client keeps
+ * resending a request that can never succeed and the operator is paged for a
+ * fault that is not theirs. The same request through this helper gets the 400
+ * the handler already meant to send.
+ *
+ * Deliberately not a middleware: a middleware would have to guess which routes
+ * are multipart, and being wrong in either direction is worse than one explicit
+ * call per handler.
+ */
+/**
+ * The body every caller sends with the 400. One string, so the six upload
+ * handlers cannot drift into six different ways of saying the same thing.
+ */
+export declare const MULTIPART_REQUIRED: {
+    readonly error: "Expected a multipart/form-data body.";
+};
+/**
+ * Parse a multipart body, answering `null` rather than throwing when it is not one.
+ *
+ * ```ts
+ * const form = await readMultipart(c);
+ * if (!form) return c.json(MULTIPART_REQUIRED, 400);
+ * const file = form.get('file');
+ * ```
+ *
+ * Returns `FormData | null` rather than a `{ ok }` result object deliberately.
+ * The extensions repo compiles with `strict: false`, and without
+ * `strictNullChecks` TypeScript will not narrow a discriminated union on a
+ * boolean member — every call site got `Property 'error' does not exist on type
+ * MultipartResult`. A nullable return needs no narrowing to be safe under either
+ * setting, and reads the same.
+ *
+ * `c` is typed structurally rather than as Hono's `Context` on purpose: the SDK
+ * has never taken a dependency on Hono, and every extension bundles its own
+ * copy, so a nominal type here would reject the caller's own context object.
+ */
+export declare function readMultipart(c: {
+    req: {
+        formData: () => Promise<FormData>;
+    };
+}): Promise<FormData | null>;
+//# sourceMappingURL=multipart.d.ts.map

package/dist/extension/multipart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multipart.d.ts","sourceRoot":"","sources":["../../src/extension/multipart.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;GAGG;AACH,eAAO,MAAM,kBAAkB;;CAA6D,CAAC;AAE7F;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,aAAa,CAAC,CAAC,EAAE;IACrC,GAAG,EAAE;QAAE,QAAQ,EAAE,MAAM,OAAO,CAAC,QAAQ,CAAC,CAAA;KAAE,CAAC;CAC5C,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAS3B"}

package/dist/extension/multipart.js

@@ -0,0 +1,61 @@
+/**
+ * Reading a multipart body without turning a bad request into a crash.
+ *
+ * Six extensions opened an upload handler with
+ *
+ *     const formData = await c.req.formData();
+ *     const file = formData.get('file') as File;
+ *     if (!file) return c.json({ error: 'No file provided' }, 400);
+ *
+ * The 400 on the third line says plainly what the author intended a malformed
+ * request to get. It is unreachable: `formData()` throws when the body is not
+ * multipart at all — a client that sends JSON, or sends nothing, or gets the
+ * content-type wrong — so those requests never reach line three. They surface as
+ * an unhandled rejection and a bare 500.
+ *
+ * That is worth more than tidiness. A 500 tells a caller, a retrying webhook
+ * sender, and an uptime monitor that the SERVER is broken, so the client keeps
+ * resending a request that can never succeed and the operator is paged for a
+ * fault that is not theirs. The same request through this helper gets the 400
+ * the handler already meant to send.
+ *
+ * Deliberately not a middleware: a middleware would have to guess which routes
+ * are multipart, and being wrong in either direction is worse than one explicit
+ * call per handler.
+ */
+/**
+ * The body every caller sends with the 400. One string, so the six upload
+ * handlers cannot drift into six different ways of saying the same thing.
+ */
+export const MULTIPART_REQUIRED = { error: 'Expected a multipart/form-data body.' };
+/**
+ * Parse a multipart body, answering `null` rather than throwing when it is not one.
+ *
+ * ```ts
+ * const form = await readMultipart(c);
+ * if (!form) return c.json(MULTIPART_REQUIRED, 400);
+ * const file = form.get('file');
+ * ```
+ *
+ * Returns `FormData | null` rather than a `{ ok }` result object deliberately.
+ * The extensions repo compiles with `strict: false`, and without
+ * `strictNullChecks` TypeScript will not narrow a discriminated union on a
+ * boolean member — every call site got `Property 'error' does not exist on type
+ * MultipartResult`. A nullable return needs no narrowing to be safe under either
+ * setting, and reads the same.
+ *
+ * `c` is typed structurally rather than as Hono's `Context` on purpose: the SDK
+ * has never taken a dependency on Hono, and every extension bundles its own
+ * copy, so a nominal type here would reject the caller's own context object.
+ */
+export async function readMultipart(c) {
+    try {
+        return await c.req.formData();
+    }
+    catch {
+        // The parser's own message is not passed through. It reads like "FormData
+        // parse error" — nothing the caller can act on — and echoing a body parser's
+        // internals back over HTTP is how request contents end up in error strings.
+        return null;
+    }
+}

package/dist/extension/numeric.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Turning what PostgreSQL sends into what JavaScript can add.
+ *
+ * `BIGINT`, `NUMERIC`, `DECIMAL` and every `COUNT`/`SUM`/`AVG` aggregate arrive
+ * from the driver as **strings** — Bun's `SQL` exposes no type-parser hook, so
+ * there is no place to fix this once for the whole process. That leaves the call
+ * site, and the call site is where it goes wrong:
+ *
+ *     total + row.amount        // "0" + "12.50" → "012.50"
+ *     ("012.50") - 1            // NaN
+ *
+ * Only `+` misbehaves; `-`, `*`, `/`, `<` and `>` coerce and give correct
+ * answers. So the failure hides until a sum happens to enter the chain, and then
+ * it does not throw — it produces `NaN`, PostgreSQL accepts `NaN` into a
+ * `NUMERIC` column, and `NaN` compares as LARGER than every number. A row poisoned
+ * this way passes `WHERE balance > 0`, passes `HAVING total >= required`, and
+ * passes a `CHECK (col >= 0)` constraint. The database agrees with the corruption.
+ *
+ * Hence two rules, both enforced here rather than remembered:
+ *
+ *   * `toNumber` REFUSES `NaN` and `Infinity`. Not "returns 0" — refuses. A value
+ *     that reached this point non-finite is already the product of a bug, and
+ *     substituting a plausible number buries it one layer deeper.
+ *   * `sumNumeric` exists so the common case — adding a column across rows — has
+ *     an obvious right answer that is shorter to write than the wrong one.
+ *
+ * This lives in the SDK, not the engine, on purpose. The safe helper existing
+ * somewhere an extension cannot import it is a shape this codebase has produced
+ * four times already — `safeFetch`, `maybeDecrypt`, `requireInstanceAdmin` and
+ * the validation evaluator all had an engine-side implementation and an
+ * extension-side reimplementation that was subtly worse. Every module that
+ * handles money is an extension, so the conversion belongs where they can reach
+ * it: `import { toNumber } from '@zveltio/sdk/extension'`.
+ *
+ * The engine keeps its own copy at `lib/numeric.ts` rather than importing this
+ * one, because the engine's production code has never taken a RUNTIME dependency
+ * on the SDK — only types — and a pure sixty-line converter is not the thing to
+ * change that for. `numeric-parity.test.ts` runs both against the same table of
+ * inputs so the twins cannot drift apart quietly.
+ *
+ * @see `PgNumeric` in the engine's `db/schema.ts` for the type side of the same problem.
+ */
+/** Thrown instead of quietly producing a number nobody can trace. */
+export declare class NumericConversionError extends Error {
+    readonly value: unknown;
+    constructor(value: unknown, label?: string);
+}
+/**
+ * A database numeric as a JS number, or a throw.
+ *
+ * Accepts what the driver actually produces: a string, a number that survived
+ * because the column was `INTEGER`, a `bigint`, or `null`/`undefined` for a
+ * nullable column. Everything else, and anything non-finite, is an error.
+ *
+ * `null` and `undefined` map to `fallback`, which defaults to `0`. That is the
+ * one substitution worth making: "no row" and "no value" genuinely do mean zero
+ * in an aggregate, and the alternative is a `?? 0` at every call site, which is
+ * the shape that lets a real `NaN` through.
+ */
+export declare function toNumber(value: unknown, fallback?: number, label?: string): number;
+/**
+ * `toNumber` for a value that is allowed to be absent, with no substitution.
+ *
+ * Use it where zero and "not set" mean different things — a quota that has not
+ * been configured is not a quota of zero.
+ */
+export declare function toNumberOrNull(value: unknown, label?: string): number | null;
+/**
+ * `toNumber` that answers `fallback` instead of throwing.
+ *
+ * For display paths only — a dashboard tile should not 500 because one row is
+ * bad. Never use it on a value about to be written back to the database, which
+ * is exactly how the poison spreads.
+ */
+export declare function toNumberSafe(value: unknown, fallback?: number): number;
+/** Sum one numeric column across rows, without a `+` on a string in sight. */
+export declare function sumNumeric<T>(rows: readonly T[], pick: (row: T) => unknown, label?: string): number;
+/**
+ * Round to a currency's minor unit.
+ *
+ * Money read as a string and converted to a double is exact for every value a
+ * `NUMERIC(14,2)` can hold, but arithmetic on doubles is not: `0.1 + 0.2` is
+ * `0.30000000000000004`, and written back that is a `NUMERIC` with fourteen
+ * decimal places. Round at the point the result becomes an amount again.
+ */
+export declare function roundMoney(value: number, decimals?: number): number;
+/**
+ * Is this value safe to store in a `NUMERIC` column?
+ *
+ * The database will not tell you. `INSERT ... VALUES ('NaN'::numeric)` succeeds,
+ * and so does a `CHECK (col >= 0)` on the row afterwards. Guard on the way in.
+ */
+export declare function isStorableNumeric(value: unknown): boolean;
+//# sourceMappingURL=numeric.d.ts.map

package/dist/extension/numeric.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"numeric.d.ts","sourceRoot":"","sources":["../../src/extension/numeric.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,qEAAqE;AACrE,qBAAa,sBAAuB,SAAQ,KAAK;IAE7C,QAAQ,CAAC,KAAK,EAAE,OAAO;gBAAd,KAAK,EAAE,OAAO,EACvB,KAAK,CAAC,EAAE,MAAM;CASjB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,SAAI,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAwB7E;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG5E;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,SAAI,GAAG,MAAM,CAMjE;AAED,8EAA8E;AAC9E,wBAAgB,UAAU,CAAC,CAAC,EAC1B,IAAI,EAAE,SAAS,CAAC,EAAE,EAClB,IAAI,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,OAAO,EACzB,KAAK,CAAC,EAAE,MAAM,GACb,MAAM,CAIR;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,MAAM,CAU9D;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAQzD"}

package/dist/extension/numeric.js

@@ -0,0 +1,162 @@
+/**
+ * Turning what PostgreSQL sends into what JavaScript can add.
+ *
+ * `BIGINT`, `NUMERIC`, `DECIMAL` and every `COUNT`/`SUM`/`AVG` aggregate arrive
+ * from the driver as **strings** — Bun's `SQL` exposes no type-parser hook, so
+ * there is no place to fix this once for the whole process. That leaves the call
+ * site, and the call site is where it goes wrong:
+ *
+ *     total + row.amount        // "0" + "12.50" → "012.50"
+ *     ("012.50") - 1            // NaN
+ *
+ * Only `+` misbehaves; `-`, `*`, `/`, `<` and `>` coerce and give correct
+ * answers. So the failure hides until a sum happens to enter the chain, and then
+ * it does not throw — it produces `NaN`, PostgreSQL accepts `NaN` into a
+ * `NUMERIC` column, and `NaN` compares as LARGER than every number. A row poisoned
+ * this way passes `WHERE balance > 0`, passes `HAVING total >= required`, and
+ * passes a `CHECK (col >= 0)` constraint. The database agrees with the corruption.
+ *
+ * Hence two rules, both enforced here rather than remembered:
+ *
+ *   * `toNumber` REFUSES `NaN` and `Infinity`. Not "returns 0" — refuses. A value
+ *     that reached this point non-finite is already the product of a bug, and
+ *     substituting a plausible number buries it one layer deeper.
+ *   * `sumNumeric` exists so the common case — adding a column across rows — has
+ *     an obvious right answer that is shorter to write than the wrong one.
+ *
+ * This lives in the SDK, not the engine, on purpose. The safe helper existing
+ * somewhere an extension cannot import it is a shape this codebase has produced
+ * four times already — `safeFetch`, `maybeDecrypt`, `requireInstanceAdmin` and
+ * the validation evaluator all had an engine-side implementation and an
+ * extension-side reimplementation that was subtly worse. Every module that
+ * handles money is an extension, so the conversion belongs where they can reach
+ * it: `import { toNumber } from '@zveltio/sdk/extension'`.
+ *
+ * The engine keeps its own copy at `lib/numeric.ts` rather than importing this
+ * one, because the engine's production code has never taken a RUNTIME dependency
+ * on the SDK — only types — and a pure sixty-line converter is not the thing to
+ * change that for. `numeric-parity.test.ts` runs both against the same table of
+ * inputs so the twins cannot drift apart quietly.
+ *
+ * @see `PgNumeric` in the engine's `db/schema.ts` for the type side of the same problem.
+ */
+/** Thrown instead of quietly producing a number nobody can trace. */
+export class NumericConversionError extends Error {
+    value;
+    constructor(value, label) {
+        super(`${label ? `${label}: ` : ''}expected a finite number, got ${typeof value === 'string' ? JSON.stringify(value) : String(value)}`);
+        this.value = value;
+        this.name = 'NumericConversionError';
+    }
+}
+/**
+ * A database numeric as a JS number, or a throw.
+ *
+ * Accepts what the driver actually produces: a string, a number that survived
+ * because the column was `INTEGER`, a `bigint`, or `null`/`undefined` for a
+ * nullable column. Everything else, and anything non-finite, is an error.
+ *
+ * `null` and `undefined` map to `fallback`, which defaults to `0`. That is the
+ * one substitution worth making: "no row" and "no value" genuinely do mean zero
+ * in an aggregate, and the alternative is a `?? 0` at every call site, which is
+ * the shape that lets a real `NaN` through.
+ */
+export function toNumber(value, fallback = 0, label) {
+    if (value === null || value === undefined)
+        return fallback;
+    if (typeof value === 'bigint') {
+        // Above 2^53 a bigint cannot round-trip through a double. Refusing beats
+        // returning a number that is quietly off by a few.
+        if (value > Number.MAX_SAFE_INTEGER || value < Number.MIN_SAFE_INTEGER) {
+            throw new NumericConversionError(value, label);
+        }
+        return Number(value);
+    }
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            throw new NumericConversionError(value, label);
+        return value;
+    }
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        // `Number('')` is 0 and `Number(' ')` is 0 — both of which would turn a
+        // malformed column into a confident zero.
+        if (trimmed === '')
+            throw new NumericConversionError(value, label);
+        const n = Number(trimmed);
+        if (!Number.isFinite(n))
+            throw new NumericConversionError(value, label);
+        return n;
+    }
+    throw new NumericConversionError(value, label);
+}
+/**
+ * `toNumber` for a value that is allowed to be absent, with no substitution.
+ *
+ * Use it where zero and "not set" mean different things — a quota that has not
+ * been configured is not a quota of zero.
+ */
+export function toNumberOrNull(value, label) {
+    if (value === null || value === undefined)
+        return null;
+    return toNumber(value, 0, label);
+}
+/**
+ * `toNumber` that answers `fallback` instead of throwing.
+ *
+ * For display paths only — a dashboard tile should not 500 because one row is
+ * bad. Never use it on a value about to be written back to the database, which
+ * is exactly how the poison spreads.
+ */
+export function toNumberSafe(value, fallback = 0) {
+    try {
+        return toNumber(value, fallback);
+    }
+    catch {
+        return fallback;
+    }
+}
+/** Sum one numeric column across rows, without a `+` on a string in sight. */
+export function sumNumeric(rows, pick, label) {
+    let total = 0;
+    for (const row of rows)
+        total += toNumber(pick(row), 0, label);
+    return total;
+}
+/**
+ * Round to a currency's minor unit.
+ *
+ * Money read as a string and converted to a double is exact for every value a
+ * `NUMERIC(14,2)` can hold, but arithmetic on doubles is not: `0.1 + 0.2` is
+ * `0.30000000000000004`, and written back that is a `NUMERIC` with fourteen
+ * decimal places. Round at the point the result becomes an amount again.
+ */
+export function roundMoney(value, decimals = 2) {
+    if (!Number.isFinite(value))
+        throw new NumericConversionError(value, 'roundMoney');
+    const factor = 10 ** decimals;
+    // Round the MAGNITUDE, then restore the sign. `Math.round` breaks ties
+    // towards +Infinity, so a plain `Math.round(v * factor)` rounds 2.675 up to
+    // 2.68 and -2.675 up to -2.67 — a credit note and the charge it reverses
+    // stop cancelling, and `finance/accounting` computes its balance-sheet
+    // difference from exactly that subtraction. Money rounds away from zero.
+    const sign = value < 0 ? -1 : 1;
+    return (sign * Math.round((Math.abs(value) + Number.EPSILON) * factor)) / factor;
+}
+/**
+ * Is this value safe to store in a `NUMERIC` column?
+ *
+ * The database will not tell you. `INSERT ... VALUES ('NaN'::numeric)` succeeds,
+ * and so does a `CHECK (col >= 0)` on the row afterwards. Guard on the way in.
+ */
+export function isStorableNumeric(value) {
+    if (value === null || value === undefined)
+        return true;
+    try {
+        toNumber(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/extension/permission-gate.d.ts

@@ -27,8 +27,23 @@
  * Place AFTER the auth-guard middleware that sets `c.set('user', ...)`.
  */
 type MaybePromise<T> = T | Promise<T>;
+interface Granter {
+    name: string;
+}
+interface DenialContext {
+    resource: string;
+    action: string;
+    confidential: boolean;
+    canGrant: Granter[];
+}
 interface GateContext {
     checkPermission: (userId: string, resource: string, action: string) => Promise<boolean>;
+    /**
+     * Supplied by the host so a refusal can say who to ask. Optional because an
+     * extension may be running against an engine older than this, and a missing
+     * courtesy must never become a missing refusal.
+     */
+    describeDenial?: (resource: string, action: string) => Promise<DenialContext>;
 }
 export declare function permissionGate(ctx: GateContext, resource: string, opts?: {
     actionOverrides?: Record<string, string>;

package/dist/extension/permission-gate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"permission-gate.d.ts","sourceRoot":"","sources":["../../src/extension/permission-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,KAAK,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAEtC,UAAU,WAAW;IACnB,eAAe,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACzF;AAuCD,wBAAgB,cAAc,CAC5B,GAAG,EAAE,WAAW,EAChB,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE;IAAE,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAO,IAEzC,GAAG,GAAG,EAAE,MAAM,MAAM,YAAY,CAAC,OAAO,CAAC,kBAgCxD"}
+{"version":3,"file":"permission-gate.d.ts","sourceRoot":"","sources":["../../src/extension/permission-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,KAAK,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAEtC,UAAU,OAAO;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAED,UAAU,aAAa;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,OAAO,CAAC;IACtB,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB;AAED,UAAU,WAAW;IACnB,eAAe,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACxF;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;CAC/E;AAmGD,wBAAgB,cAAc,CAC5B,GAAG,EAAE,WAAW,EAChB,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE;IAAE,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAO,IAGzC,GAAG,GAAG,EAAE,MAAM,MAAM,YAAY,CAAC,OAAO,CAAC,kBAgCxD"}

package/dist/extension/permission-gate.js

@@ -26,6 +26,36 @@
  *
  * Place AFTER the auth-guard middleware that sets `c.set('user', ...)`.
  */
+async function refuse(ctx, c, resource, action) {
+    let denial = null;
+    try {
+        denial = (await ctx.describeDenial?.(resource, action)) ?? null;
+    }
+    catch {
+        /* the refusal matters more than the suggestion */
+    }
+    const names = denial?.canGrant.map((g) => g.name) ?? [];
+    const who = names.length === 0
+        ? 'An administrator of this workspace'
+        : names.length === 1
+            ? names[0]
+            : `${names.slice(0, -1).join(', ')} or ${names[names.length - 1]}`;
+    const what = denial?.confidential
+        ? `${resource} is confidential`
+        : `you do not have access to ${resource}`;
+    const detail = names.length === 0 ? `${what}. ${who} can grant it.` : `${what}. ${who} can give you access.`;
+    return c.json({
+        type: 'about:blank',
+        title: 'Forbidden',
+        status: 403,
+        code: 'permission_required',
+        detail,
+        resource,
+        action,
+        confidential: denial?.confidential ?? false,
+        can_grant: names.map((name) => ({ name })),
+    }, 403);
+}
 function methodToAction(method) {
     const m = method.toUpperCase();
     switch (m) {
@@ -56,10 +86,12 @@ function methodToAction(method) {
  * Strict (default) is the secure posture and what the SDK ships with.
  */
 function rbacMode() {
+    // biome-ignore lint/suspicious/noExplicitAny: legacy any; tracked in hardening plan item H-01
     const v = globalThis.process?.env?.EXTENSION_RBAC;
     return v === 'permissive' ? 'permissive' : 'strict';
 }
 export function permissionGate(ctx, resource, opts = {}) {
+    // biome-ignore lint/suspicious/noExplicitAny: legacy any; tracked in hardening plan item H-01
     return async (c, next) => {
         // CORS preflight (OPTIONS) must never be authorization-gated —
         // browsers send it without credentials and a 401/403 here breaks
@@ -86,7 +118,7 @@ export function permissionGate(ctx, resource, opts = {}) {
                 await next();
                 return;
             }
-            return c.json({ error: `Forbidden: missing ${resource}:${action} permission` }, 403);
+            return refuse(ctx, c, resource, action);
         }
         await next();
     };

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { ZveltioClient, createZveltioClient } from './client.js';
 export type { ZveltioClientConfig, ListParams, ListResult } from './client.js';
+export { ZveltioApiError, PROBLEM_CONTENT_TYPE } from './errors.js';
+export type { ProblemDetails } from './errors.js';
 export { ZveltioRealtime } from './realtime.js';
 export { LocalStore } from './local-store.js';
 export { SyncManager } from './sync-manager.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,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"}
+{"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,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACpE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,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/index.js

@@ -1,4 +1,5 @@
 export { ZveltioClient, createZveltioClient } from './client.js';
+export { ZveltioApiError, PROBLEM_CONTENT_TYPE } from './errors.js';
 export { ZveltioRealtime } from './realtime.js';
 export { LocalStore } from './local-store.js';
 export { SyncManager } from './sync-manager.js';

package/dist/local-store.d.ts

@@ -51,6 +51,11 @@ export declare class LocalStore {
     markFailed(queueItemId: string, error: string): Promise<void>;
     /** Apply data from server (via WebSocket or pull) */
     applyServerUpdate(collection: string, id: string, data: Record<string, any>, serverVersion: number): Promise<void>;
+    /**
+     * The server deleted a record: drop the local copy WITHOUT queueing a delete.
+     * `delete()` would queue one, echoing the server's own deletion back at it.
+     */
+    applyServerDelete(collection: string, id: string): Promise<void>;
     /** Get records with conflicts for UI resolution */
     getConflicts(collection?: string): Promise<LocalRecord[]>;
     /** Resolve a conflict (user decides which version wins) */

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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"}