@bounded-sh/core 0.0.35 → 0.0.37

package/dist/index.mjs

@@ -3838,6 +3838,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,
@@ -3893,7 +4013,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;
@@ -3944,7 +4064,7 @@ async function makeApiRequest(method, urlPath, data, _overrides) {
                 }
                 return await executeRequest();
             }
-            catch (_j) {
+            catch (_g) {
                 throw error;
             }
         }
@@ -3955,17 +4075,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;
@@ -6042,6 +6179,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();
@@ -7109,7 +7264,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 });
 }
@@ -7263,5 +7428,5 @@ function defineLiveModule(mod) {
     return mod;
 }
 
-export { EFFECT_INTENT_ADDRESS, FunctionInvokeError, InsufficientBalanceError, LiveIntentError, ReactNativeSessionManager, ServerSessionManager, WebSessionManager, aggregate, buildSetDocumentsTransaction, clearCache, closeAllSubscriptions, convertRemainingAccounts, count, createSessionWithSignature, defineLiveModule, deriveUserIdentityFromIdToken, docId, functions, genAuthNonce, genSolanaMessage, get, getActiveSessionManager, getCachedData, getConfig, getFiles, getIdToken, getMany, getWebhookKeysUrl, hasActiveConnection, increment, init, invoke as invokeFunction, isEffectResult, live, intent as liveIntent, status as liveStatus, now, queryAggregate, reconnectWithNewAuth, refreshSession, revokeSession, runExpression, runExpressionMany, runQuery, runQueryMany, search, serverTimestamp, set, setFile, setMany, signAndSubmitTransaction, signMessage, signSessionCreateMessage, signTransaction, subscribe, subscribeView as subscribeLiveView, toMillis, toSeconds, withEffects };
+export { BoundedDeclineError, DECLINE_EVENT_NAME, EFFECT_INTENT_ADDRESS, FunctionInvokeError, InsufficientBalanceError, LiveIntentError, ReactNativeSessionManager, ServerSessionManager, WebSessionManager, aggregate, buildSetDocumentsTransaction, clearCache, closeAllSubscriptions, convertRemainingAccounts, count, createSessionWithSignature, defineLiveModule, deriveDecline, deriveUserIdentityFromIdToken, dispatchDeclineEvent, docId, functions, genAuthNonce, genSolanaMessage, get, getActiveSessionManager, getCachedData, getConfig, getFiles, getIdToken, getMany, getWebhookKeysUrl, hasActiveConnection, increment, init, invoke as invokeFunction, isEffectResult, live, intent as liveIntent, status as liveStatus, now, queryAggregate, reconnectWithNewAuth, refreshSession, revokeSession, runExpression, runExpressionMany, runQuery, runQueryMany, search, serverTimestamp, set, setFile, setMany, signAndSubmitTransaction, signMessage, signSessionCreateMessage, signTransaction, subscribe, subscribeView as subscribeLiveView, toMillis, toSeconds, withEffects };
 //# sourceMappingURL=index.mjs.map