@nebulr-group/bridge-svelte 0.7.1 → 0.8.0-beta.1

package/dist/client/BridgeBootstrap.svelte

@@ -20,6 +20,18 @@
     stopBridgeRuntime,
     type StartBridgeRuntimeOptions,
   } from '../core/bridge-runtime.js';
+  import RealtimeDevBadge from './components/developer/RealtimeDevBadge.svelte';
+
+  // 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;
+  // `devBadge: false` in the config turns it off there too.
+  const devBadgeEnabled = (() => {
+    try {
+      return getConfig().devBadge !== false;
+    } catch {
+      return true;
+    }
+  })();
 
   // Props: optional `runtime` overrides for advanced/debug use (websocketFactory,
   // reconnect overrides, etc.); `onBootstrapComplete` callback fires after the
@@ -194,3 +206,5 @@
     await handleRoute(to.url.pathname, cancel, to.url.search);
   });
 </script>
+
+<RealtimeDevBadge enabled={devBadgeEnabled} />

package/dist/client/components/developer/RealtimeDevBadge.svelte

@@ -0,0 +1,216 @@
+<!--
+  TBP-644 — development-only "Live updates off — why?" corner badge.
+
+  <BridgeBootstrap /> mounts this automatically. It renders only in
+  development builds (`dev` from `$app/environment`, which SvelteKit resolves
+  to a constant `false` in production builds) and only while live updates are
+  actually off: refused (`unauthorized`), connected but deaf (`degraded`), or
+  retrying for longer than 30 s. Opt out with `devBadge: false` in
+  `bridgeConfig.initConfig({...})`.
+
+  Styling is self-contained — every element resets with `all: unset` — so it
+  neither depends on nor inherits from the host app's CSS.
+-->
+<script lang="ts">
+  import { dev } from '$app/environment';
+  import { realtimeStatusDetail } from '../../../core/realtime-status.js';
+  import {
+    REALTIME_BADGE_RETRYING_AFTER_MS,
+    createRetryClock,
+    realtimeBadgeView,
+  } from '../../../core/realtime-dev-badge.js';
+
+  let { enabled = true }: { enabled?: boolean } = $props();
+
+  const PANEL_ID = 'bridge-realtime-dev-badge-panel';
+  const retryClock = createRetryClock();
+
+  let now = $state(Date.now());
+  let expanded = $state(false);
+  let dismissedKey = $state<string | undefined>(undefined);
+  let toggleEl = $state<HTMLButtonElement | undefined>(undefined);
+
+  const status = $derived($realtimeStatusDetail);
+  // Start of the current retry run — stable across the closed/connecting
+  // flips inside one episode (see createRetryClock).
+  const retryingSince = $derived(retryClock(status, Date.now()));
+
+  // Tick `now` once the retrying threshold passes — nothing else re-renders.
+  $effect(() => {
+    if (retryingSince === undefined) return;
+    const remaining = retryingSince + REALTIME_BADGE_RETRYING_AFTER_MS - Date.now();
+    const timer = setTimeout(() => (now = Date.now()), Math.max(0, remaining) + 50);
+    return () => clearTimeout(timer);
+  });
+
+  const view = $derived(realtimeBadgeView(status, retryingSince, now));
+  const visible = $derived(!!view && view.key !== dismissedKey);
+
+  function dismiss() {
+    dismissedKey = view?.key;
+    expanded = false;
+  }
+
+  function onKeydown(event: KeyboardEvent) {
+    if (event.key === 'Escape' && expanded) {
+      expanded = false;
+      toggleEl?.focus();
+    }
+  }
+</script>
+
+{#if dev && enabled}
+  <div class="bridge-rt-root" data-testid="bridge-realtime-dev-badge-root">
+    <span class="bridge-rt-sr" role="status" aria-live="polite"
+      >{visible && view ? `Bridge live updates are off: ${view.reason}` : ''}</span
+    >
+    {#if visible && view}
+      <!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
+      <aside
+        class="bridge-rt-badge"
+        aria-label="Bridge live updates (development only)"
+        data-testid="bridge-realtime-dev-badge"
+        onkeydown={onKeydown}
+      >
+        <div class="bridge-rt-bar">
+          <button
+            bind:this={toggleEl}
+            type="button"
+            class="bridge-rt-toggle"
+            aria-expanded={expanded}
+            aria-controls={PANEL_ID}
+            onclick={() => (expanded = !expanded)}
+          >
+            <span class="bridge-rt-dot" aria-hidden="true">●</span> Live updates off — why?
+          </button>
+          <button
+            type="button"
+            class="bridge-rt-close"
+            aria-label="Dismiss the live updates notice"
+            onclick={dismiss}>×</button
+          >
+        </div>
+        {#if expanded}
+          <div id={PANEL_ID} class="bridge-rt-panel">
+            <div class="bridge-rt-row">
+              <span class="bridge-rt-label">Reason</span>
+              <code class="bridge-rt-code">{view.reason}</code>
+            </div>
+            <div class="bridge-rt-row">
+              <span class="bridge-rt-label">Whose side</span>
+              <span class="bridge-rt-value">{view.sideLabel}</span>
+            </div>
+            {#if view.ref}
+              <div class="bridge-rt-row">
+                <span class="bridge-rt-label">Ref</span>
+                <code class="bridge-rt-code">{view.ref}</code>
+              </div>
+            {/if}
+            {#if view.docsUrl}
+              <a class="bridge-rt-link" href={view.docsUrl} target="_blank" rel="noopener noreferrer"
+                >How to fix this ↗</a
+              >
+            {/if}
+            <span class="bridge-rt-note">Development builds only — never shown to your users.</span>
+          </div>
+        {/if}
+      </aside>
+    {/if}
+  </div>
+{/if}
+
+<style>
+  .bridge-rt-root,
+  .bridge-rt-root * {
+    all: unset;
+    box-sizing: border-box;
+  }
+  .bridge-rt-root {
+    position: fixed;
+    right: 16px;
+    bottom: 16px;
+    z-index: 2147483000;
+    display: block;
+    font-family: ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
+    font-size: 12px;
+    line-height: 1.4;
+    color: #f5f5f5;
+  }
+  .bridge-rt-sr {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    overflow: hidden;
+    clip: rect(0 0 0 0);
+    white-space: nowrap;
+  }
+  .bridge-rt-badge {
+    display: block;
+    max-width: min(360px, calc(100vw - 32px));
+    background: #1f2328;
+    border: 1px solid #3d444d;
+    border-radius: 8px;
+    box-shadow: 0 4px 16px rgba(0, 0, 0, 0.25);
+  }
+  .bridge-rt-bar {
+    display: flex;
+    align-items: center;
+  }
+  .bridge-rt-toggle,
+  .bridge-rt-close {
+    cursor: pointer;
+    padding: 6px 10px;
+    border-radius: 8px;
+  }
+  .bridge-rt-toggle {
+    flex: 1;
+  }
+  .bridge-rt-close {
+    font-size: 14px;
+    line-height: 1;
+    color: #b0b8c1;
+  }
+  .bridge-rt-toggle:focus-visible,
+  .bridge-rt-close:focus-visible,
+  .bridge-rt-link:focus-visible {
+    outline: 2px solid #58a6ff;
+    outline-offset: 1px;
+  }
+  .bridge-rt-dot {
+    color: #f85149;
+  }
+  .bridge-rt-panel {
+    display: block;
+    padding: 4px 10px 10px;
+    border-top: 1px solid #3d444d;
+  }
+  .bridge-rt-row {
+    display: flex;
+    gap: 8px;
+    padding-top: 6px;
+  }
+  .bridge-rt-label {
+    flex: 0 0 72px;
+    color: #9198a1;
+  }
+  .bridge-rt-value {
+    flex: 1;
+  }
+  .bridge-rt-code {
+    font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+    overflow-wrap: anywhere;
+  }
+  .bridge-rt-link {
+    display: inline-block;
+    margin-top: 8px;
+    color: #58a6ff;
+    text-decoration: underline;
+    cursor: pointer;
+  }
+  .bridge-rt-note {
+    display: block;
+    margin-top: 8px;
+    color: #9198a1;
+    font-size: 11px;
+  }
+</style>

package/dist/client/components/developer/RealtimeDevBadge.svelte.d.ts

@@ -0,0 +1,6 @@
+type $$ComponentProps = {
+    enabled?: boolean;
+};
+declare const RealtimeDevBadge: import("svelte").Component<$$ComponentProps, {}, "">;
+type RealtimeDevBadge = ReturnType<typeof RealtimeDevBadge>;
+export default RealtimeDevBadge;

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

@@ -41,7 +41,7 @@
  * instance. Call `stopBridgeRuntime()` (e.g. on `<BridgeBootstrap />` destroy)
  * to flush the realtime client and unsubscribe from the token store.
  */
-import { RealtimeClient, type FlagChange, type RealtimeClientConfig, type SessionSnapshotMessage } from '@nebulr-group/bridge-auth-core';
+import { RealtimeClient, type FlagChange, type RealtimeClientConfig, type RealtimeStatus, type SessionSnapshotMessage } from '@nebulr-group/bridge-auth-core';
 /**
  * Advanced runtime overrides. Product consumers never pass these; tests,
  * Storybook harnesses, and the demo workspace use them to override the
@@ -105,6 +105,14 @@ export declare function onBridgeRealtimeClose(handler: () => void): () => void;
 export declare function onBridgeFlagChange(handler: (change: FlagChange) => void): () => void;
 /** Subscribe to `session.snapshot` messages. Returns an unsubscribe fn. */
 export declare function onBridgeRealtimeSnapshot(handler: (msg: SessionSnapshotMessage) => void): () => void;
+/**
+ * Subscribe to realtime status changes (TBP-644): state, the machine-readable
+ * reason, whose side a fault is on (`app` / `config` / `bridge` / `network`),
+ * whether the client is still retrying, a docs link and a support ref.
+ * Fires on every change, not with the current value — read
+ * `realtimeStatusDetail` for that. Returns an unsubscribe fn.
+ */
+export declare function onBridgeRealtimeStatus(handler: (status: RealtimeStatus) => void): () => void;
 /**
  * Subscribe to server-side `user.state_changed` signals (fired before the
  * runtime triggers a token refresh). Useful for debug overlays + tests.

package/dist/core/bridge-runtime.js

@@ -45,9 +45,9 @@ import { RealtimeClient, useBridge, } from '@nebulr-group/bridge-auth-core';
 import { getConfig } from '../client/stores/config.store.js';
 import { getBridgeAuth, tokenStore } from './bridge-instance.js';
 import { wrapFetchWithBridgeAuth } from './bridge-fetch.js';
-import { applySessionSnapshot } from './snapshot-stores.js';
+import { applyEntitlementsChanged, applySessionSnapshot, applySubscriptionPlanChanged, } from './snapshot-stores.js';
 import { bridgeEvents } from './events.js';
-import { _setRealtimeStatus } from './realtime-status.js';
+import { _setRealtimeStatus, _setRealtimeStatusDetail } from './realtime-status.js';
 let _realtime;
 let _unsubscribeAuth;
 let _currentAuthToken;
@@ -59,6 +59,8 @@ const _onSnapshotSubs = new Set();
 // invalidate its (separate) cache and re-evaluate the current route.
 const _onFlagChangeSubs = new Set();
 const _onUserStateSubs = new Set();
+// TBP-644 — full realtime status (state + reason + whose side + retrying).
+const _onStatusSubs = new Set();
 /**
  * Start the Bridge runtime. Idempotent — repeated calls are a no-op. Reads
  * `appId` + `apiBaseUrl` from the auth config store (`bridgeConfig.initConfig`).
@@ -105,6 +107,25 @@ export function startBridgeRuntime(options = {}) {
         apiKey: config.appId,
         appId: _bootstrapAppId,
         getAuthToken: () => _currentAuthToken,
+        // TBP-644 — a refused connection gets ONE session refresh per episode
+        // (auth-core enforces the once) and reconnects with the new token instead
+        // of parking. A signed-out session has nothing to refresh. Loop safety:
+        // the refreshed token lands in the tokenStore subscription below, whose
+        // reauthorize() is a no-op while that episode is still connecting, and
+        // the reconnect it produces is flagged self-induced so setOnOpen does not
+        // refresh a second time.
+        refreshAuthToken: options.realtime?.refreshAuthToken ??
+            (async () => {
+                if (!_currentAuthToken)
+                    return undefined;
+                try {
+                    const tokens = await getBridgeAuth().refreshTokens();
+                    return tokens?.accessToken ?? undefined;
+                }
+                catch {
+                    return undefined;
+                }
+            }),
     });
     let _connectedOnce = false;
     // Set just before we call _realtime.reauthorize() so the resulting
@@ -159,6 +180,23 @@ export function startBridgeRuntime(options = {}) {
     _realtime.setOnDegraded?.(() => {
         _setRealtimeStatus('degraded');
     });
+    // TBP-644 — the full status: why the connection is not working, whose side
+    // the fault is on, and whether it is still retrying. Guarded for the same
+    // reason as setOnDegraded (an older auth-core has no such hook; the
+    // open/close/degraded mirrors above keep `realtimeStatus` working there).
+    _realtime.setOnStatusChange?.((status) => {
+        _setRealtimeStatusDetail(status);
+        // A parked client never opens, so a reauthorize that ended in a refusal
+        // must not leave the self-induced flag set for the next genuine reconnect.
+        if (status.state === 'unauthorized')
+            _reauthInFlight = false;
+        for (const fn of _onStatusSubs) {
+            try {
+                fn(status);
+            }
+            catch { /* subscriber errors swallowed */ }
+        }
+    });
     // TBP-575 — a flag changed on the wire. Two caches need to hear about it and
     // only one of them was ever told:
     //   - BridgeFlags (FF 2.0)      — driven by realtime already, via attach()
@@ -209,8 +247,21 @@ export function startBridgeRuntime(options = {}) {
     useBridge().attachToRealtimeClient(_realtime);
     // Phase 5 (TBP-331) + TBP-360 — billing-family events flow through the
     // unified bridge events surface via `useBridge().handle({...})`.
+    //
+    // TBP-644 — the two pushes that carry the complete new value also move the
+    // `bridge.tenant.*` stores, which were otherwise written only by
+    // `session.snapshot`. A plan change never re-sends a snapshot, so without
+    // this an upgraded app kept rendering the old plan until a reload. The store
+    // is patched BEFORE dispatch so a `bridge.events` handler that reads
+    // `bridge.tenant.subscription` already sees the new plan.
     useBridge().handle({
-        'subscription.plan_changed': (msg) => bridgeEvents._dispatch(msg),
+        'subscription.plan_changed': (msg) => {
+            try {
+                applySubscriptionPlanChanged(msg);
+            }
+            catch { /* store updates shouldn't throw, defensive */ }
+            bridgeEvents._dispatch(msg);
+        },
         'payment.failed': (msg) => bridgeEvents._dispatch(msg),
         'payment.succeeded': (msg) => bridgeEvents._dispatch(msg),
         'subscription.created': (msg) => bridgeEvents._dispatch(msg),
@@ -226,15 +277,37 @@ export function startBridgeRuntime(options = {}) {
         'dunning.recovered': (msg) => bridgeEvents._dispatch(msg),
         'dunning.exhausted': (msg) => bridgeEvents._dispatch(msg),
         'quota.updated': (msg) => bridgeEvents._dispatch(msg),
-        'entitlements.changed': (msg) => bridgeEvents._dispatch(msg),
+        'entitlements.changed': (msg) => {
+            // Only the payload-carrying variant has a map; the signal-only one is a no-op here.
+            try {
+                applyEntitlementsChanged(msg);
+            }
+            catch { /* defensive */ }
+            bridgeEvents._dispatch(msg);
+        },
     });
     // Token store subscription — owns realtime channel scoping + quotas HTTP
     // options + reauthorize on token-only refresh. Capability-specific subs
     // (e.g. flag eval context) are layered on top by their own bootstrappers.
     const apiBaseUrl = config.apiBaseUrl ?? 'https://api.thebridge.dev';
+    // TBP-644 — the realtime connection must be re-authorized whenever the
+    // token VALUE changes: rotation (A → B), but also first sign-in
+    // (none → A) and sign-out (A → none). Keying this on rotation only meant a
+    // session that signed in after page load kept the anonymous connection —
+    // or stayed parked after a refusal — until something else reconnected it.
+    // Flagged self-induced so setOnOpen skips its catch-up refresh (see the
+    // loop note there): the token we reconnect with is already current.
+    const reauthorizeForTokenChange = () => {
+        _reauthInFlight = true;
+        void _realtime.reauthorize();
+    };
+    // `subscribe` emits the current value synchronously, before `start()` below.
+    // That first emission is not a change: start() connects with it anyway.
+    let _tokenSubscriptionLive = false;
     _unsubscribeAuth = tokenStore.subscribe((tokens) => {
         const prevAuthToken = _currentAuthToken;
-        _currentAuthToken = tokens?.accessToken;
+        _currentAuthToken = tokens?.accessToken ?? undefined;
+        const tokenChanged = _tokenSubscriptionLive && prevAuthToken !== _currentAuthToken;
         // Quota store hydrate requests carry the current access token; configure
         // here so post-login state is picked up. Best-effort: a missing
         // BridgeAuth means SDK isn't fully initialized yet — skip.
@@ -254,29 +327,28 @@ export function startBridgeRuntime(options = {}) {
             // its anonymous app-id auth.
             _realtime.setUserId(undefined);
             _realtime.setWorkspaceId(undefined);
+            // Reconnect as the signed-out session now, rather than riding the old
+            // user's socket until something else drops it.
+            if (tokenChanged)
+                reauthorizeForTokenChange();
             return;
         }
         const claims = decodeJwtPayload(tokens.accessToken);
-        if (!claims)
-            return;
-        // Wire all three SDK channel scopes from the JWT. `aid` → app, `tid` →
-        // workspace, `sub` → user. Each setter is idempotent; only changes trigger
-        // a reconnect.
-        _realtime.setAppId(typeof claims.aid === 'string' ? claims.aid : undefined);
-        _realtime.setWorkspaceId(typeof claims.tid === 'string' ? claims.tid : undefined);
-        _realtime.setUserId(typeof claims.sub === 'string' ? claims.sub : undefined);
-        // Token-only refresh (same user, new JWT): setUserId is a no-op when
-        // userId hasn't changed, leaving the channel riding the OLD JWT until
-        // Centrifugo's connection-token TTL drops it. Force a reauthorize so the
-        // server re-validates against the new token immediately.
-        if (prevAuthToken && _currentAuthToken && prevAuthToken !== _currentAuthToken) {
-            // Flag this as a self-induced reconnect so setOnOpen does NOT fire its
-            // proactive refresh (which would mint a new token → land back here →
-            // loop forever). The token we're reauthorizing with is already current.
-            _reauthInFlight = true;
-            void _realtime.reauthorize();
+        if (claims) {
+            // Wire all three SDK channel scopes from the JWT. `aid` → app, `tid` →
+            // workspace, `sub` → user. Each setter is idempotent; only changes
+            // trigger a reconnect.
+            _realtime.setAppId(typeof claims.aid === 'string' ? claims.aid : undefined);
+            _realtime.setWorkspaceId(typeof claims.tid === 'string' ? claims.tid : undefined);
+            _realtime.setUserId(typeof claims.sub === 'string' ? claims.sub : undefined);
         }
+        // setUserId is a no-op when the user is unchanged (token-only refresh),
+        // and a setter-driven reconnect waits out a backoff and cannot lift a
+        // parked refusal — so reauthorize explicitly on every value change.
+        if (tokenChanged)
+            reauthorizeForTokenChange();
     });
+    _tokenSubscriptionLive = true;
     // Best-effort start. RealtimeClient gracefully no-ops if the workspace's
     // `/realtime/config` returns `kind: 'noop'`.
     void _realtime.start();
@@ -346,6 +418,17 @@ export function onBridgeRealtimeSnapshot(handler) {
     _onSnapshotSubs.add(handler);
     return () => _onSnapshotSubs.delete(handler);
 }
+/**
+ * Subscribe to realtime status changes (TBP-644): state, the machine-readable
+ * reason, whose side a fault is on (`app` / `config` / `bridge` / `network`),
+ * whether the client is still retrying, a docs link and a support ref.
+ * Fires on every change, not with the current value — read
+ * `realtimeStatusDetail` for that. Returns an unsubscribe fn.
+ */
+export function onBridgeRealtimeStatus(handler) {
+    _onStatusSubs.add(handler);
+    return () => _onStatusSubs.delete(handler);
+}
 /**
  * Subscribe to server-side `user.state_changed` signals (fired before the
  * runtime triggers a token refresh). Useful for debug overlays + tests.
@@ -364,6 +447,7 @@ export function __resetBridgeRuntime() {
     _onSnapshotSubs.clear();
     _onFlagChangeSubs.clear();
     _onUserStateSubs.clear();
+    _onStatusSubs.clear();
     _currentAuthToken = undefined;
     if (_unsubscribeAuth) {
         _unsubscribeAuth();