@nebulr-group/bridge-svelte 0.9.0-beta.1 → 0.9.0-beta.2

package/dist/client/BridgeBootstrap.svelte

@@ -24,6 +24,10 @@
     type StartBridgeRuntimeOptions,
   } from '../core/bridge-runtime.js';
   import RealtimeDevBadge from './components/developer/RealtimeDevBadge.svelte';
+  import BridgeUpgradeDialog from './components/subscription/BridgeUpgradeDialog.svelte';
+  import { dismissQuotaRefusal, quotaRefusal } from '../core/quota-refusal.js';
+  import { resolveUpgradeDialog, upgradeHrefFor } from './upgrade-dialog.js';
+  import { isBillingAdmin } from './billing-role.js';
 
   // TBP-644 — the "Live updates off — why?" badge is mounted here so every app
   // gets it without code changes. It renders in development builds only;
@@ -36,6 +40,24 @@
     }
   })();
 
+  // TBP-703 — the upgrade dialog is mounted here so a page needs no Bridge code:
+  // when the app's backend refuses a request at a plan limit (402
+  // QUOTA_EXCEEDED), the fetch wrapper / bridgeFetch report it and this opens.
+  // On by default; `billing.upgradeDialog: false` turns it off, a component
+  // replaces it.
+  const billingConfig = (() => {
+    try {
+      return getConfig().billing;
+    } catch {
+      return undefined;
+    }
+  })();
+  const upgradeDialog = resolveUpgradeDialog(billingConfig);
+  const UpgradeDialog = upgradeDialog === 'default' ? BridgeUpgradeDialog : upgradeDialog;
+  const upgradeHref = $derived(upgradeHrefFor($quotaRefusal, billingConfig));
+  // Re-read for every refusal: the same owner rule as <BridgeQuotaBanner>.
+  const canUpgrade = $derived($quotaRefusal ? isBillingAdmin() : false);
+
   // Props: optional `runtime` overrides for advanced/debug use (websocketFactory,
   // reconnect overrides, etc.); `onBootstrapComplete` callback fires after the
   // runtime + any auto-detected capabilities (flags) have attached.
@@ -260,6 +282,10 @@
 
 <RealtimeDevBadge enabled={devBadgeEnabled} />
 
+{#if UpgradeDialog}
+  <UpgradeDialog refusal={$quotaRefusal} {upgradeHref} {canUpgrade} onclose={dismissQuotaRefusal} />
+{/if}
+
 {#if runtimeAttached && $bridgeReadyStore}
   {@render children?.()}
 {/if}

package/dist/client/billing-role.d.ts

@@ -0,0 +1,9 @@
+/** True when the signed-in user may manage this workspace's billing. Fails closed to "member". */
+export declare function isBillingAdmin(): boolean;
+/** Where a member is pointed, in place of an Upgrade button. */
+export declare const CONTACT_WORKSPACE_OWNER = "Contact your workspace owner.";
+/**
+ * The member-facing sentence for a quota, by how close it is to the cap.
+ * `over` is also what a refused request (the upgrade dialog) says.
+ */
+export declare function quotaMemberBody(label: string, state: 'over' | 'critical' | 'approaching'): string;

package/dist/client/billing-role.js

@@ -0,0 +1,36 @@
+// Who may act on a plan limit, and what a member who may not is told.
+//
+// One source for <BridgeQuotaBanner> and <BridgeUpgradeDialog> (TBP-703), so
+// the two never disagree about who gets an Upgrade button and what everyone
+// else reads. The rule is the banner's original one: the Upgrade call to
+// action is for whoever `canManageBilling()` says may manage billing (v1: the
+// workspace owner); anyone else — including when Bridge is not initialised —
+// is a member and is told to contact the workspace owner instead of being
+// sent to a subscription page they cannot act on.
+import { getBridgeAuth } from '../core/bridge-instance.js';
+/** True when the signed-in user may manage this workspace's billing. Fails closed to "member". */
+export function isBillingAdmin() {
+    try {
+        return getBridgeAuth().canManageBilling() === true;
+    }
+    catch {
+        // No BridgeAuth instance — the member variant.
+        return false;
+    }
+}
+/** Where a member is pointed, in place of an Upgrade button. */
+export const CONTACT_WORKSPACE_OWNER = 'Contact your workspace owner.';
+/**
+ * The member-facing sentence for a quota, by how close it is to the cap.
+ * `over` is also what a refused request (the upgrade dialog) says.
+ */
+export function quotaMemberBody(label, state) {
+    switch (state) {
+        case 'over':
+            return `Your workspace is over its ${label} cap. ${CONTACT_WORKSPACE_OWNER}`;
+        case 'critical':
+            return `Your workspace is approaching its ${label} cap. ${CONTACT_WORKSPACE_OWNER}`;
+        case 'approaching':
+            return `Your workspace is approaching its ${label} cap.`;
+    }
+}

package/dist/client/components/subscription/BridgeQuotaBanner.svelte

@@ -26,7 +26,11 @@
     useBridge,
     type QuotaSnapshot,
   } from '@nebulr-group/bridge-auth-core';
+<<<<<<< HEAD
   import { getBridgeAuth } from '../../../core/bridge-instance.js';
+=======
+  import { isBillingAdmin as canManageBilling, quotaMemberBody } from '../../billing-role.js';
+>>>>>>> origin/feature/mcp-journey
   import { billingRoutes } from '../../billing-routes.js';
 
   type Chassis = 'rail';
@@ -81,11 +85,8 @@
     // Re-trigger hydration in case the prop changed since `$state` init.
     snapshot = useBridge().quota(metric);
 
-    try {
-      isBillingAdmin = getBridgeAuth().canManageBilling();
-    } catch {
-      // No BridgeAuth instance — render the member variant.
-    }
+    // Shared with <BridgeUpgradeDialog> (TBP-703): billing-role.ts.
+    isBillingAdmin = canManageBilling();
   });
 
   onDestroy(() => unsubscribe?.());
@@ -187,7 +188,7 @@
           }
         : {
             title: `${displayLabel} over cap`,
-            body: `Your workspace is over its ${displayLabel} cap. Contact your workspace owner.`,
+            body: quotaMemberBody(displayLabel, 'over'),
           };
     }
     if (warningLevel === 'critical') {
@@ -199,7 +200,7 @@
           }
         : {
             title: `${displayLabel} near cap`,
-            body: `Your workspace is approaching its ${displayLabel} cap. Contact your workspace owner.`,
+            body: quotaMemberBody(displayLabel, 'critical'),
           };
     }
     // approaching
@@ -211,7 +212,7 @@
         }
       : {
           title: `${displayLabel} approaching cap`,
-          body: `Your workspace is approaching its ${displayLabel} cap.`,
+          body: quotaMemberBody(displayLabel, 'approaching'),
         };
   }
 

package/dist/client/components/subscription/BridgeUpgradeDialog.svelte

@@ -0,0 +1,69 @@
+<!--
+  TBP-703 — the upgrade dialog. <BridgeBootstrap /> mounts it; the app writes
+  nothing. When the app's backend refuses a request because a plan limit is
+  reached (402, code QUOTA_EXCEEDED — bridge-nestjs's @RequireQuota), it opens,
+  names the metric and the numbers, and links to the refusal's `fix` path or
+  `billing.manageRoute` (default /subscription). A member who cannot manage
+  billing (the <BridgeQuotaBanner> rule, billing-role.ts) is told to contact the
+  workspace owner instead, with no Upgrade link.
+
+  `billing.upgradeDialog: false` turns it off; a component there replaces it
+  and receives the same props.
+
+  Decoration only: the backend already refused the write. This explains why.
+-->
+<script lang="ts">
+  import type { BridgeUpgradeDialogProps } from '../../../shared/types/config.js';
+  import { quotaMemberBody } from '../../billing-role.js';
+
+  let { refusal, upgradeHref, canUpgrade, onclose }: BridgeUpgradeDialogProps = $props();
+
+  let dialogEl: HTMLDialogElement | undefined = $state();
+
+  $effect(() => {
+    if (!dialogEl) return;
+    if (refusal && !dialogEl.open) dialogEl.showModal();
+    else if (!refusal && dialogEl.open) dialogEl.close();
+  });
+
+  const hasNumbers = $derived(refusal?.used != null && refusal?.limit != null);
+</script>
+
+<dialog
+  bind:this={dialogEl}
+  class="bridge-team-dialog bridge-upgrade-dialog"
+  data-bridge-upgrade-dialog
+  data-metric={refusal?.metric}
+  aria-labelledby="bridge-upgrade-dialog-title"
+  onclose={() => {
+    if (refusal) onclose();
+  }}
+>
+  {#if refusal}
+    <div class="bridge-team-dialog-content">
+      <h3 id="bridge-upgrade-dialog-title" class="bridge-team-dialog-title">You've reached your plan's limit</h3>
+      <p class="bridge-team-dialog-message" data-bridge-upgrade-dialog-message data-variant={canUpgrade ? 'admin' : 'member'}>
+        {#if !canUpgrade}
+          {quotaMemberBody(refusal.metric, 'over')}
+        {:else if hasNumbers}
+          This workspace has used <strong>{refusal.used?.toLocaleString()}</strong> of
+          <strong>{refusal.limit?.toLocaleString()}</strong>
+          <strong data-bridge-upgrade-dialog-metric>{refusal.metric}</strong> on its current plan.
+        {:else}
+          This workspace has reached its <strong data-bridge-upgrade-dialog-metric>{refusal.metric}</strong> limit.
+        {/if}
+        {#if canUpgrade}Upgrade the plan to keep going.{/if}
+      </p>
+      <div class="bridge-team-dialog-actions">
+        {#if canUpgrade}
+          <button type="button" class="bridge-btn bridge-btn-secondary" onclick={() => onclose()}>Not now</button>
+          <a class="bridge-btn bridge-btn-primary" href={upgradeHref} data-bridge-upgrade-dialog-cta onclick={() => onclose()}>
+            Upgrade plan
+          </a>
+        {:else}
+          <button type="button" class="bridge-btn bridge-btn-primary" onclick={() => onclose()}>OK</button>
+        {/if}
+      </div>
+    </div>
+  {/if}
+</dialog>

package/dist/client/components/subscription/BridgeUpgradeDialog.svelte.d.ts

@@ -0,0 +1,4 @@
+import type { BridgeUpgradeDialogProps } from '../../../shared/types/config.js';
+declare const BridgeUpgradeDialog: import("svelte").Component<BridgeUpgradeDialogProps, {}, "">;
+type BridgeUpgradeDialog = ReturnType<typeof BridgeUpgradeDialog>;
+export default BridgeUpgradeDialog;

package/dist/client/components/subscription/Entitled.svelte

@@ -0,0 +1,43 @@
+<!--
+  TBP-703 — <Entitled to="analytics">: the children render when the workspace's
+  plan grants the entitlement, the `fallback` snippet when it does not.
+
+    <Entitled to="analytics">
+      <AnalyticsPanel />
+      {#snippet fallback()}
+        <a href="/subscription">Upgrade for analytics</a>
+      {/snippet}
+    </Entitled>
+
+  Until Bridge has answered ($entitlements.ready) it renders neither — only the
+  optional `loading` snippet — so a cold start never flashes the upgrade prompt
+  at a paying workspace, nor the paid feature at a free one.
+
+  The markup form of `$entitlements.can('analytics')`. Decoration only: the
+  backend's @RequireEntitlement is what refuses the request.
+-->
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import { entitlements } from '../../../core/entitlements.js';
+
+  interface Props {
+    /** The entitlement key, e.g. `'analytics'`. */
+    to: string;
+    /** Rendered when the plan grants `to`. */
+    children: Snippet;
+    /** Rendered when Bridge has answered and the plan does not grant `to`. */
+    fallback?: Snippet;
+    /** Rendered until Bridge has answered. Nothing by default. */
+    loading?: Snippet;
+  }
+
+  let { to, children, fallback, loading }: Props = $props();
+</script>
+
+{#if !$entitlements.ready}
+  {@render loading?.()}
+{:else if $entitlements.can(to)}
+  {@render children()}
+{:else}
+  {@render fallback?.()}
+{/if}

package/dist/client/components/subscription/Entitled.svelte.d.ts

@@ -0,0 +1,14 @@
+import type { Snippet } from 'svelte';
+interface Props {
+    /** The entitlement key, e.g. `'analytics'`. */
+    to: string;
+    /** Rendered when the plan grants `to`. */
+    children: Snippet;
+    /** Rendered when Bridge has answered and the plan does not grant `to`. */
+    fallback?: Snippet;
+    /** Rendered until Bridge has answered. Nothing by default. */
+    loading?: Snippet;
+}
+declare const Entitled: import("svelte").Component<Props, {}, "">;
+type Entitled = ReturnType<typeof Entitled>;
+export default Entitled;

package/dist/client/components/subscription/QuotaGate.svelte

@@ -0,0 +1,76 @@
+<!--
+  TBP-703 — <QuotaGate metric="tickets">: the action inside is disabled once the
+  workspace is at its plan's hard cap, and an upgrade prompt shows beside it.
+
+    <QuotaGate metric="tickets">
+      <button onclick={createTicket}>New ticket</button>
+      {#snippet atLimit(quota)}
+        {quota.used} of {quota.limit} tickets used. <a href="/subscription">Upgrade</a>
+      {/snippet}
+    </QuotaGate>
+
+  Disabling is done by a <fieldset disabled> around the children, so every
+  button, input, select and textarea inside is disabled natively and announced
+  as such — no prop threading into your markup. (Links are not form controls;
+  put a link's action behind a button.)
+
+  Never disables on "don't know yet": while the quota is loading, the plan has
+  no quota on the metric, or the quota is metered (it bills overage instead of
+  blocking), the children are enabled. Only a known hard cap with nothing left
+  disables them.
+
+  Decoration only. The backend's @RequireQuota is what refuses the write; this
+  just saves the user a click that would be refused.
+-->
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import { useQuota, type QuotaState } from '../../../core/use-quota.js';
+  import { billingRoutes } from '../../billing-routes.js';
+
+  interface Props {
+    /** The quota metric key, e.g. `'tickets'`. */
+    metric: string;
+    /** The action(s) to disable at the cap. */
+    children: Snippet;
+    /**
+     * What to show at the cap, instead of the default "limit reached — Upgrade"
+     * line. Receives the live quota (`used`, `limit`, `remaining`, …).
+     */
+    atLimit?: Snippet<[QuotaState]>;
+    /** Class on the wrapper. */
+    class?: string;
+  }
+
+  let { metric, children, atLimit, class: className = '' }: Props = $props();
+
+  const quota = useQuota(() => metric);
+
+  // 'loading' | 'unlimited' | 'metered' | 'available' | 'at-limit'
+  const gateState = $derived.by(() => {
+    if (quota.loading) return 'loading';
+    if (quota.unlimited) return 'unlimited';
+    if (quota.snapshot?.policy === 'metered') return 'metered';
+    const atCap =
+      (quota.remaining !== null && quota.remaining <= 0) ||
+      (quota.used !== null && quota.limit !== null && quota.used >= quota.limit);
+    return atCap ? 'at-limit' : 'available';
+  });
+  const blocked = $derived(gateState === 'at-limit');
+  const manageRoute = $derived(billingRoutes().manageRoute);
+</script>
+
+<div class="bridge-quota-gate {className}" data-bridge-quota-gate data-metric={metric} data-state={gateState}>
+  <fieldset disabled={blocked} class="bridge-quota-gate-controls" style="display: contents">
+    {@render children()}
+  </fieldset>
+  {#if blocked}
+    <div class="bridge-quota-gate-limit" data-bridge-quota-gate-limit role="status">
+      {#if atLimit}
+        {@render atLimit(quota)}
+      {:else}
+        You've used all {quota.limit?.toLocaleString()} {metric} on your plan.
+        <a href={manageRoute}>Upgrade</a>
+      {/if}
+    </div>
+  {/if}
+</div>

package/dist/client/components/subscription/QuotaGate.svelte.d.ts

@@ -0,0 +1,18 @@
+import type { Snippet } from 'svelte';
+import { type QuotaState } from '../../../core/use-quota.js';
+interface Props {
+    /** The quota metric key, e.g. `'tickets'`. */
+    metric: string;
+    /** The action(s) to disable at the cap. */
+    children: Snippet;
+    /**
+     * What to show at the cap, instead of the default "limit reached — Upgrade"
+     * line. Receives the live quota (`used`, `limit`, `remaining`, …).
+     */
+    atLimit?: Snippet<[QuotaState]>;
+    /** Class on the wrapper. */
+    class?: string;
+}
+declare const QuotaGate: import("svelte").Component<Props, {}, "">;
+type QuotaGate = ReturnType<typeof QuotaGate>;
+export default QuotaGate;

package/dist/client/upgrade-dialog.d.ts

@@ -0,0 +1,16 @@
+import type { Component } from 'svelte';
+import type { BridgeQuotaRefusal } from '../core/quota-refusal.js';
+import type { BridgeConfig, BridgeUpgradeDialogProps } from '../shared/types/config.js';
+/**
+ * The dialog to mount for a `billing` config: the built-in one (`default`), the
+ * app's own component, or none (`false`). Anything that is not `false` and not
+ * a component — `true`, `undefined`, a stray string — is the built-in default:
+ * the owner decision is that the dialog is on unless turned off.
+ */
+export declare function resolveUpgradeDialog(billing: BridgeConfig['billing'] | undefined): 'default' | Component<BridgeUpgradeDialogProps> | null;
+/**
+ * Where the upgrade button goes: the refusal's own `fix` path (already limited
+ * to a same-app path by `parseQuotaRefusal`), else `billing.manageRoute`
+ * (default `/subscription`).
+ */
+export declare function upgradeHrefFor(refusal: Pick<BridgeQuotaRefusal, 'fix'> | null, billing: BridgeConfig['billing'] | undefined): string;

package/dist/client/upgrade-dialog.js

@@ -0,0 +1,26 @@
+// TBP-703 — which upgrade dialog <BridgeBootstrap> mounts, and where its button
+// goes. Kept out of the component so both are plain functions a unit test can
+// call with a config.
+import { resolveBillingRoutes } from './billing-routes.js';
+/**
+ * The dialog to mount for a `billing` config: the built-in one (`default`), the
+ * app's own component, or none (`false`). Anything that is not `false` and not
+ * a component — `true`, `undefined`, a stray string — is the built-in default:
+ * the owner decision is that the dialog is on unless turned off.
+ */
+export function resolveUpgradeDialog(billing) {
+    const setting = billing?.upgradeDialog;
+    if (setting === false)
+        return null;
+    if (typeof setting === 'function')
+        return setting;
+    return 'default';
+}
+/**
+ * Where the upgrade button goes: the refusal's own `fix` path (already limited
+ * to a same-app path by `parseQuotaRefusal`), else `billing.manageRoute`
+ * (default `/subscription`).
+ */
+export function upgradeHrefFor(refusal, billing) {
+    return refusal?.fix ?? resolveBillingRoutes(billing).manageRoute;
+}

package/dist/core/bridge-fetch.d.ts

@@ -16,3 +16,25 @@
  * Installed by `startBridgeRuntime()` patching `globalThis.fetch`.
  */
 export declare function wrapFetchWithBridgeAuth(baseFetch: typeof fetch, apiBaseUrl: string): typeof fetch;
+/**
+ * TBP-697 — `bridgeFetch(url, init)`: `fetch` for calls to **your own backend**
+ * that carry the signed-in user's Bridge access token.
+ *
+ *   import { bridgeFetch } from '@nebulr-group/bridge-svelte';
+ *   const res = await bridgeFetch('/api/projects', { method: 'POST', body });
+ *
+ * Adds `Authorization: Bearer <access token>` (when signed in), and on a `401`
+ * refreshes the token once and retries — so an expired token mid-session is
+ * not an error the page has to handle. Same signature as `fetch`.
+ *
+ * Bridge's own API calls do not need it: those already carry the token.
+ *
+ * It sends the user's token to whatever URL you give it, so call it for your
+ * backend only — never for a third-party URL.
+ *
+ * TBP-703 — a `402 { code: 'QUOTA_EXCEEDED', … }` answer (what bridge-nestjs's
+ * `@RequireQuota` sends at the plan's cap) opens the upgrade dialog that
+ * `<BridgeBootstrap>` mounts, whatever origin your backend is on. The response
+ * is still returned to you unchanged.
+ */
+export declare function bridgeFetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;

package/dist/core/bridge-fetch.js

@@ -1,4 +1,42 @@
 import { getBridgeAuth } from './bridge-instance.js';
+import { observeQuotaRefusal, watchesQuotaOrigin } from './quota-refusal.js';
+import { getConfig } from '../client/stores/config.store.js';
+function requestUrl(input) {
+    return typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+}
+function pageHref() {
+    const href = globalThis.location?.href;
+    return typeof href === 'string' ? href : undefined;
+}
+/** `url` made absolute against the page, so a relative `/api/x` has an origin. */
+function absoluteUrl(url) {
+    try {
+        return new URL(url, pageHref()).href;
+    }
+    catch {
+        return url;
+    }
+}
+/**
+ * TBP-703 — hand a 402 from a watched origin to the upgrade-dialog check.
+ * Watched: the page's own origin, Bridge's API, and `billing.apiOrigins`.
+ */
+function observeIfWatched(response, url, apiBaseUrl) {
+    if (response.status !== 402)
+        return;
+    let apiOrigins;
+    try {
+        apiOrigins = getConfig().billing?.apiOrigins;
+    }
+    catch {
+        apiOrigins = undefined;
+    }
+    const href = pageHref();
+    const pageOrigin = href ? new URL(href).origin : undefined;
+    if (watchesQuotaOrigin(url, { pageOrigin, apiBaseUrl, apiOrigins })) {
+        void observeQuotaRefusal(response, absoluteUrl(url));
+    }
+}
 /**
  * Wraps a fetch function with Bridge auth concerns for requests to `apiBaseUrl`.
  * Requests to other URLs pass through completely untouched.
@@ -18,14 +56,16 @@ import { getBridgeAuth } from './bridge-instance.js';
  */
 export function wrapFetchWithBridgeAuth(baseFetch, apiBaseUrl) {
     return async function bridgeAuthFetch(input, init) {
-        const url = typeof input === 'string'
-            ? input
-            : input instanceof URL
-                ? input.href
-                : input.url;
-        // Only act on requests to the bridge API — everything else passes through.
-        if (!url.startsWith(apiBaseUrl))
-            return baseFetch(input, init);
+        const url = requestUrl(input);
+        // Only act on requests to the bridge API — everything else passes through
+        // untouched. TBP-703: a 402 from the app's own backend is still LOOKED at
+        // (never changed or delayed) so a plan-limit refusal opens the upgrade
+        // dialog with no code on the page.
+        if (!url.startsWith(apiBaseUrl)) {
+            const passthrough = await baseFetch(input, init);
+            observeIfWatched(passthrough, url, apiBaseUrl);
+            return passthrough;
+        }
         // 1. Inject current access token.
         const token = getBridgeAuth().getTokens()?.accessToken;
         const headers = new Headers(init?.headers);
@@ -33,8 +73,10 @@ export function wrapFetchWithBridgeAuth(baseFetch, apiBaseUrl) {
             headers.set('Authorization', `Bearer ${token}`);
         const response = await baseFetch(input, { ...init, headers });
         // Non-200s are returned as-is; httpFetch handles REST auth errors separately.
-        if (!response.ok)
+        if (!response.ok) {
+            observeIfWatched(response, url, apiBaseUrl);
             return response;
+        }
         // 2. Inspect body for TOKEN_VERSION_STALE without consuming the original
         //    response (URQL / callers need to read it themselves).
         const clone = response.clone();
@@ -57,3 +99,58 @@ export function wrapFetchWithBridgeAuth(baseFetch, apiBaseUrl) {
         return baseFetch(input, { ...init, headers: freshHeaders });
     };
 }
+/**
+ * TBP-697 — `bridgeFetch(url, init)`: `fetch` for calls to **your own backend**
+ * that carry the signed-in user's Bridge access token.
+ *
+ *   import { bridgeFetch } from '@nebulr-group/bridge-svelte';
+ *   const res = await bridgeFetch('/api/projects', { method: 'POST', body });
+ *
+ * Adds `Authorization: Bearer <access token>` (when signed in), and on a `401`
+ * refreshes the token once and retries — so an expired token mid-session is
+ * not an error the page has to handle. Same signature as `fetch`.
+ *
+ * Bridge's own API calls do not need it: those already carry the token.
+ *
+ * It sends the user's token to whatever URL you give it, so call it for your
+ * backend only — never for a third-party URL.
+ *
+ * TBP-703 — a `402 { code: 'QUOTA_EXCEEDED', … }` answer (what bridge-nestjs's
+ * `@RequireQuota` sends at the plan's cap) opens the upgrade dialog that
+ * `<BridgeBootstrap>` mounts, whatever origin your backend is on. The response
+ * is still returned to you unchanged.
+ */
+export async function bridgeFetch(input, init) {
+    const response = await fetchWithToken(input, init);
+    void observeQuotaRefusal(response, absoluteUrl(requestUrl(input)));
+    return response;
+}
+async function fetchWithToken(input, init) {
+    let auth;
+    try {
+        auth = getBridgeAuth();
+    }
+    catch {
+        // Bridge not initialised (SSR, a test) — behave exactly like fetch.
+        return fetch(input, init);
+    }
+    const withToken = (token) => {
+        const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
+        if (token)
+            headers.set('Authorization', `Bearer ${token}`);
+        return { ...init, headers };
+    };
+    const sentToken = auth.getTokens()?.accessToken;
+    const response = await fetch(input, withToken(sentToken));
+    if (response.status !== 401 || !sentToken)
+        return response;
+    // A streamed body is gone after the first attempt; it cannot be replayed.
+    const replayable = !(input instanceof Request) && !(init?.body instanceof ReadableStream);
+    if (!replayable)
+        return response;
+    const fresh = await auth.refreshTokens().catch(() => null);
+    const freshToken = fresh?.accessToken ?? auth.getTokens()?.accessToken;
+    if (!freshToken || freshToken === sentToken)
+        return response;
+    return fetch(input, withToken(freshToken));
+}

package/dist/core/bridge.d.ts

@@ -12,14 +12,13 @@
  * (`subscriptionStore`, `appConfigStore`, etc.) continue to exist and are
  * populated by the same internal state; both surfaces coexist.
  *
- * Note: `useBridge()` (Svelte context hook) lands in TBP-320. This module
- * only exposes the singleton aggregate `bridge`; consumers can import it
- * directly until the context hook ships.
+ * `useBridge()` (use-bridge.ts) returns this same object, or a component-scoped
+ * override set with `setBridgeContext()`.
  */
 import { type Readable } from 'svelte/store';
 import { type BrandingSnapshot, type SubscriptionSnapshot, type UserSnapshot } from './snapshot-stores.js';
 import { LazySlice } from './lazy-slice.js';
-import type { Plan } from '@nebulr-group/bridge-auth-core';
+import type { BridgeAuth, Plan } from '@nebulr-group/bridge-auth-core';
 import { DevAttributeProvider } from '@nebulr-group/bridge-auth-core';
 import { type BridgeEventsDispatcher } from './events.js';
 export interface BridgeAppSurface {
@@ -54,6 +53,39 @@ export interface BridgeTenantSurface {
         can(key: string): boolean;
     };
 }
+/**
+ * TBP-697 — usage reporting from the browser.
+ *
+ * **Self-reported: this is a trusted-client path.** Anything running in the
+ * user's browser can call it with any value, so a frontend-only app cannot
+ * *enforce* a quota with it — only a backend can refuse a write. Use it when the
+ * app has no backend that sees the action: a local-first or mobile app whose
+ * data lives on the device. When you do have a backend, report there instead
+ * (bridge-nestjs `@RequireQuota`, `usage.report` on the server SDK).
+ *
+ * Which call: *if deleting it frees room, it's a gauge and your app counts it
+ * (`set`); if it happened, it's a counter and Bridge counts it (`report`).*
+ */
+export interface BridgeUsageSurface {
+    /**
+     * Count something that happened (a counter): `report('ai_completions')`,
+     * `report('tokens', 1375)`. Fire-and-forget; queued durably and sent in
+     * batches. Pass an `idempotencyKey` when the same event could be reported
+     * twice (a retry), so Bridge counts it once.
+     */
+    report(metric: string, value?: number, idempotencyKey?: string): void;
+    /**
+     * Say how many of something exist right now (a gauge): `set('projects', 8)`
+     * after the app creates or deletes one. Absolute, never added up; resolves
+     * once Bridge has stored it. Needs `@nebulr-group/bridge-auth-core`
+     * 0.8.0-beta.0 or later.
+     */
+    set(metric: string, value: number): Promise<void>;
+    /** Queue depth, retries and the last flush — for a debug panel. */
+    getQueueStatus(): Promise<UsageQueueStatus>;
+}
+/** What `bridge.usage.getQueueStatus()` resolves to. */
+export type UsageQueueStatus = Awaited<ReturnType<BridgeAuth['usage']['getQueueStatus']>>;
 export interface BridgeSurface {
     app: BridgeAppSurface;
     tenant: BridgeTenantSurface;
@@ -75,6 +107,12 @@ export interface BridgeSurface {
      * handlers (`useBridge().handle({...})`, `realtime.setOnXyz()`, etc.).
      */
     events: BridgeEventsDispatcher;
+    /**
+     * TBP-697 — report usage from the browser: `bridge.usage.report(metric)` for
+     * a counter, `bridge.usage.set(metric, value)` for a gauge. Self-reported —
+     * see {@link BridgeUsageSurface}.
+     */
+    usage: BridgeUsageSurface;
 }
 export declare const bridge: BridgeSurface;
 /** Internal: createBridgeFlags imports this to register the dev provider. */