@bounded-sh/core 0.0.35 → 0.0.37

package/dist/client/decline.d.ts

@@ -0,0 +1,73 @@
+export type DeclineReason = 'rule' | 'invariant';
+/**
+ * The specific boundary a declined write crossed, when the backend can name it
+ * (e.g. a spend cap: `{ type:'rollingSum', field:'amount', cap:1000,
+ * windowSeconds:86400, current:950, attempted:200 }`).
+ */
+export interface DeclineBoundary {
+    type: string;
+    field?: string;
+    cap?: number;
+    windowSeconds?: number;
+    current?: number;
+    attempted?: number;
+    [key: string]: unknown;
+}
+/**
+ * A structured, render-ready explanation of a declined write. `provenAtDeploy`
+ * marks that the crossed boundary was proven to hold against every input at
+ * deploy — the fact the hosted decline card leans on.
+ */
+export interface BoundedDecline {
+    verdict: 'declined';
+    /** 'invariant' (a proven cap/conservation/isolation boundary) or 'rule' (an auth/policy rule). */
+    reason: DeclineReason | string;
+    /** Invariant name, present when `reason === 'invariant'`. */
+    invariant?: string;
+    collection?: string;
+    op?: string;
+    boundary?: DeclineBoundary;
+    /** Human-readable, render-ready explanation. */
+    message: string;
+    /** True when the crossed boundary was proven to hold at deploy. */
+    provenAtDeploy?: boolean;
+    [key: string]: unknown;
+}
+/** The window event the hosted widget listens to for rendering a decline card. */
+export declare const DECLINE_EVENT_NAME = "bounded:decline";
+/**
+ * Normalize a server rejection body into a structured `BoundedDecline`, or
+ * `null` when the rejection is not a policy/invariant decline.
+ *
+ * Prefers a backend-sent `decline` object verbatim; otherwise synthesizes a
+ * minimal `{ verdict, reason, invariant?, message }` from the legacy envelope
+ * (`verdict` / `reason` / `code` / `invariant`). Only strong signals count —
+ * a bare 403/409 with no policy marker is left alone (returns `null`).
+ */
+export declare function deriveDecline(body: any, status?: number): BoundedDecline | null;
+/**
+ * In a browser, dispatch a `bounded:decline` CustomEvent for the surfaced
+ * decline. Fire-and-forget: guarded for non-browser/SSR (no `window`/
+ * `CustomEvent`), never throws, and never delays the rejection it accompanies.
+ */
+export declare function dispatchDeclineEvent(decline: BoundedDecline, appId?: string): void;
+/**
+ * A rejected write that violated a proven policy rule or invariant. Thrown by
+ * the data-plane write paths (set/setMany/update/delete) in place of a bare
+ * Error, and attached (as `.decline`) to live-intent rejections.
+ *
+ * Back-compatible: the full server envelope (code/status/statusCode/requestId/
+ * ...) is copied onto the instance, so existing `catch` handlers keep working;
+ * new code reads `.decline`. Detect it with `err.name === 'BoundedDeclineError'`
+ * or the bundle-copy-safe `err.isBoundedDecline === true`.
+ */
+export declare class BoundedDeclineError extends Error {
+    /** Stable discriminant that survives multiple bundled SDK copies (no `instanceof`). */
+    isBoundedDecline: true;
+    decline: BoundedDecline;
+    code?: string;
+    status?: number;
+    statusCode?: number;
+    requestId?: string;
+    constructor(decline: BoundedDecline, envelope?: Record<string, any>);
+}

package/dist/index.d.ts

@@ -3,6 +3,8 @@ export { getConfig, ClientConfig } from './client/config';
 export { getWebhookKeysUrl } from './client/config';
 export { get, getMany, docId, set, setMany, setFile, getFiles, search, queryAggregate, runQuery, runQueryMany, runExpression, runExpressionMany, signMessage, signTransaction, signAndSubmitTransaction, count, aggregate, RequestOverrides, SetOptions, GetOptions, SearchOptions, RunQueryOptions, CountOptions, AggregateOptions, AggregateOperation, AggregateResult, AggregateSpec, AggregateRow, QueryAggregateOptions, RunExpressionOptions, RunExpressionResult, InsufficientBalanceError, GetManyResult } from './client/operations';
 export { subscribe, closeAllSubscriptions, clearCache, getCachedData, reconnectWithNewAuth } from './client/subscription';
+export { BoundedDeclineError, deriveDecline, dispatchDeclineEvent, DECLINE_EVENT_NAME } from './client/decline';
+export type { BoundedDecline, DeclineReason, DeclineBoundary } from './client/decline';
 export { hasActiveConnection } from './client/subscription-v2';
 export * from './types';
 export { increment, serverTimestamp } from './client/field-values';

package/dist/index.js

@@ -3858,6 +3858,126 @@ async function updateIdTokenAndAccessToken(idToken, accessToken, isServer = fals
     await getActiveSessionManager().updateIdTokenAndAccessToken(idToken, accessToken, refreshToken);
 }
 
+// ---------------------------------------------------------------------------
+// decline.ts -- the structured "declined write" surface.
+//
+// When a data-plane write violates a proven policy rule or invariant, the
+// realtime backend rejects it: HTTP 403 { verdict:'declined', reason:'rule' }
+// or 409 { verdict:'declined', reason:'invariant', invariant } on the request
+// path, or a coded error frame over the room socket. This module turns those
+// rejections into a first-class, share-worthy decline:
+//
+//   - `BoundedDeclineError` -- the thrown error. Keeps every legacy field apps
+//     already catch (code/status/statusCode/requestId/...), and adds `.decline`
+//     (the structured object below) plus a stable `.isBoundedDecline` flag.
+//   - `deriveDecline(body, status)` -- normalizes a server rejection body into a
+//     `BoundedDecline`, trusting a backend-sent `decline` object when present
+//     and synthesizing a minimal one from legacy fields otherwise. Returns
+//     `null` when the rejection is not a policy/invariant decline.
+//   - `dispatchDeclineEvent(decline, appId?)` -- in a browser, fires the
+//     `bounded:decline` CustomEvent the hosted widget listens to. Fire-and-
+//     forget: guarded for non-browser/SSR, never throws, never delays the throw.
+// ---------------------------------------------------------------------------
+const RULE_DEFAULT_MESSAGE = 'This write is not allowed by policy.';
+const INVARIANT_DEFAULT_MESSAGE = 'This write would violate a proven invariant.';
+/** The window event the hosted widget listens to for rendering a decline card. */
+const DECLINE_EVENT_NAME = 'bounded:decline';
+/**
+ * Normalize a server rejection body into a structured `BoundedDecline`, or
+ * `null` when the rejection is not a policy/invariant decline.
+ *
+ * Prefers a backend-sent `decline` object verbatim; otherwise synthesizes a
+ * minimal `{ verdict, reason, invariant?, message }` from the legacy envelope
+ * (`verdict` / `reason` / `code` / `invariant`). Only strong signals count —
+ * a bare 403/409 with no policy marker is left alone (returns `null`).
+ */
+function deriveDecline(body, status) {
+    if (!body || typeof body !== 'object')
+        return null;
+    // Trust a backend-sent structured decline verbatim.
+    const provided = body.decline;
+    if (provided && typeof provided === 'object' && provided.verdict === 'declined') {
+        return provided;
+    }
+    const rawReason = body.reason;
+    const code = body.code;
+    const hasInvariant = body.invariant != null;
+    let reason = rawReason === 'rule' || rawReason === 'invariant' ? rawReason : undefined;
+    if (!reason) {
+        if (code === 'invariant_violation' || hasInvariant)
+            reason = 'invariant';
+        else if (code === 'policy_denied')
+            reason = 'rule';
+    }
+    const isDecline = body.verdict === 'declined' || reason === 'rule' || reason === 'invariant';
+    if (!isDecline)
+        return null;
+    const resolvedReason = reason !== null && reason !== void 0 ? reason : (status === 409 ? 'invariant' : 'rule');
+    const rawMessage = body.message;
+    const message = typeof rawMessage === 'string' && rawMessage.length > 0
+        ? rawMessage
+        : resolvedReason === 'invariant'
+            ? INVARIANT_DEFAULT_MESSAGE
+            : RULE_DEFAULT_MESSAGE;
+    const decline = { verdict: 'declined', reason: resolvedReason, message };
+    if (hasInvariant)
+        decline.invariant = body.invariant;
+    if (typeof body.collection === 'string')
+        decline.collection = body.collection;
+    if (typeof body.op === 'string')
+        decline.op = body.op;
+    if (body.boundary && typeof body.boundary === 'object')
+        decline.boundary = body.boundary;
+    if (typeof body.provenAtDeploy === 'boolean')
+        decline.provenAtDeploy = body.provenAtDeploy;
+    return decline;
+}
+/**
+ * In a browser, dispatch a `bounded:decline` CustomEvent for the surfaced
+ * decline. Fire-and-forget: guarded for non-browser/SSR (no `window`/
+ * `CustomEvent`), never throws, and never delays the rejection it accompanies.
+ */
+function dispatchDeclineEvent(decline, appId) {
+    try {
+        if (typeof window === 'undefined')
+            return;
+        const Ctor = globalThis.CustomEvent;
+        if (typeof Ctor !== 'function')
+            return;
+        const detail = Object.assign({}, decline);
+        if (appId)
+            detail.appId = appId;
+        detail.at = Date.now();
+        window.dispatchEvent(new Ctor(DECLINE_EVENT_NAME, { detail }));
+    }
+    catch (_a) {
+        // Fire-and-forget: a widget/telemetry hiccup must never mask the decline.
+    }
+}
+/**
+ * A rejected write that violated a proven policy rule or invariant. Thrown by
+ * the data-plane write paths (set/setMany/update/delete) in place of a bare
+ * Error, and attached (as `.decline`) to live-intent rejections.
+ *
+ * Back-compatible: the full server envelope (code/status/statusCode/requestId/
+ * ...) is copied onto the instance, so existing `catch` handlers keep working;
+ * new code reads `.decline`. Detect it with `err.name === 'BoundedDeclineError'`
+ * or the bundle-copy-safe `err.isBoundedDecline === true`.
+ */
+class BoundedDeclineError extends Error {
+    constructor(decline, envelope) {
+        super(`Declined: ${decline.message}`);
+        // Copy the legacy envelope FIRST, then re-assert our own fields so a
+        // stray envelope key can never clobber name/message/decline/flag.
+        if (envelope && typeof envelope === 'object')
+            Object.assign(this, envelope);
+        this.name = 'BoundedDeclineError';
+        this.message = `Declined: ${decline.message}`;
+        this.decline = decline;
+        this.isBoundedDecline = true;
+    }
+}
+
 const apiClient = axios.create();
 axiosRetry(apiClient, {
     retries: 2,
@@ -3913,7 +4033,7 @@ async function refreshAuthSessionOnce(appId, isServer) {
     return refreshPromise;
 }
 async function makeApiRequest(method, urlPath, data, _overrides) {
-    var _a, _b, _c, _d, _e, _f, _g, _h;
+    var _a, _b, _c, _d, _e, _f;
     const config = await getConfig();
     async function executeRequest() {
         var _a;
@@ -3964,7 +4084,7 @@ async function makeApiRequest(method, urlPath, data, _overrides) {
                 }
                 return await executeRequest();
             }
-            catch (_j) {
+            catch (_g) {
                 throw error;
             }
         }
@@ -3975,17 +4095,34 @@ async function makeApiRequest(method, urlPath, data, _overrides) {
             const responseData = typeof error.response.data === 'object'
                 ? error.response.data
                 : { message: String(error.response.data) };
-            const apiError = new Error(responseData.message || error.message || 'Request failed');
+            const httpStatus = (_d = error.response) === null || _d === void 0 ? void 0 : _d.status;
+            // A policy/invariant denial (403 rule / 409 invariant) is surfaced as
+            // a first-class BoundedDeclineError carrying `.decline`; every other
+            // failure stays a bare enriched Error (unchanged behavior).
+            const decline = deriveDecline(responseData, httpStatus);
+            const apiError = decline
+                ? new BoundedDeclineError(decline)
+                : new Error(responseData.message || error.message || 'Request failed');
             Object.assign(apiError, responseData);
-            apiError.statusCode = (_d = error.response) === null || _d === void 0 ? void 0 : _d.status;
+            apiError.statusCode = httpStatus;
             // Surface the structured error envelope { code, status, requestId } so
             // callers can branch on the stable category (e.g.
             // `if (e.code === 'invariant_violation')`) without parsing the message.
             // `code` is a stable category ('policy_denied' | 'invariant_violation');
             // `status` is the HTTP status; `requestId` correlates with the decision log.
             apiError.code = (_e = responseData.code) !== null && _e !== void 0 ? _e : apiError.code;
-            apiError.status = (_g = (_f = error.response) === null || _f === void 0 ? void 0 : _f.status) !== null && _g !== void 0 ? _g : responseData.status;
-            apiError.requestId = (_h = responseData.requestId) !== null && _h !== void 0 ? _h : apiError.requestId;
+            apiError.status = httpStatus !== null && httpStatus !== void 0 ? httpStatus : responseData.status;
+            apiError.requestId = (_f = responseData.requestId) !== null && _f !== void 0 ? _f : apiError.requestId;
+            if (decline) {
+                // Re-assert decline-owned fields after the envelope copy, then
+                // notify the browser widget. Fire-and-forget: never delays or
+                // masks the throw.
+                apiError.decline = decline;
+                apiError.name = 'BoundedDeclineError';
+                apiError.isBoundedDecline = true;
+                apiError.message = `Declined: ${decline.message}`;
+                dispatchDeclineEvent(decline, config.appId);
+            }
             throw apiError;
         }
         throw error;
@@ -6062,6 +6199,24 @@ function handleServerMessage(connection, message) {
                     err.requestId = message.requestId;
                 if (message.subscriptionId)
                     err.subscriptionId = message.subscriptionId;
+                // A policy/invariant denial over the socket carries the same
+                // structured decline as the HTTP path (live-intent acks, WS
+                // writes). Mirror `.decline` and notify the browser widget.
+                const declineBody = message.decline
+                    ? { decline: message.decline }
+                    : {
+                        code: message.code,
+                        message: message.message,
+                        reason: message.reason,
+                        invariant: message.invariant,
+                        verdict: message.verdict,
+                    };
+                const decline = deriveDecline(declineBody);
+                if (decline) {
+                    err.decline = decline;
+                    err.isBoundedDecline = true;
+                    dispatchDeclineEvent(decline, connection.appId);
+                }
                 return err;
             };
             const wsError = buildWsError();
@@ -7129,7 +7284,17 @@ async function intent(roomPath, intent, opts = {}) {
     }
     if (!res.ok) {
         const message = (_g = (_f = body === null || body === void 0 ? void 0 : body.error) !== null && _f !== void 0 ? _f : body === null || body === void 0 ? void 0 : body.message) !== null && _g !== void 0 ? _g : `Live intent failed with HTTP ${res.status}`;
-        throw new LiveIntentError(message, res.status, body);
+        const liveError = new LiveIntentError(message, res.status, body);
+        // A policy/invariant denial of a live intent carries the same structured
+        // decline as the data-write path. Mirror `.decline` onto the LiveIntentError
+        // (its name/contract is unchanged) and notify the browser widget.
+        const decline = deriveDecline(body, res.status);
+        if (decline) {
+            liveError.decline = decline;
+            liveError.isBoundedDecline = true;
+            dispatchDeclineEvent(decline, config.appId);
+        }
+        throw liveError;
     }
     return (body !== null && body !== void 0 ? body : { ok: true });
 }
@@ -7283,6 +7448,8 @@ function defineLiveModule(mod) {
     return mod;
 }
 
+exports.BoundedDeclineError = BoundedDeclineError;
+exports.DECLINE_EVENT_NAME = DECLINE_EVENT_NAME;
 exports.EFFECT_INTENT_ADDRESS = EFFECT_INTENT_ADDRESS;
 exports.FunctionInvokeError = FunctionInvokeError;
 exports.InsufficientBalanceError = InsufficientBalanceError;
@@ -7298,7 +7465,9 @@ exports.convertRemainingAccounts = convertRemainingAccounts;
 exports.count = count;
 exports.createSessionWithSignature = createSessionWithSignature;
 exports.defineLiveModule = defineLiveModule;
+exports.deriveDecline = deriveDecline;
 exports.deriveUserIdentityFromIdToken = deriveUserIdentityFromIdToken;
+exports.dispatchDeclineEvent = dispatchDeclineEvent;
 exports.docId = docId;
 exports.functions = functions;
 exports.genAuthNonce = genAuthNonce;