@nebulr-group/bridge-svelte 0.8.2 → 0.9.0-beta.0

package/dist/client/BridgeBootstrap.d.ts

@@ -1,6 +1,47 @@
 import type { RouteGuardConfig } from '../auth/route-guard.js';
 import { waitForBridge as _waitForBridge } from '../core/bridge-instance.js';
 import type { BridgeConfig } from '../shared/types/config.js';
+/**
+ * Options for `bridgeBootstrap()`: any `BridgeConfig` field plus the route
+ * rules. Every field is optional.
+ *
+ * Precedence: an option you pass explicitly wins over the environment
+ * (`VITE_BRIDGE_APP_ID`, `VITE_BRIDGE_API_BASE_URL`, `VITE_BRIDGE_HOSTED_URL`,
+ * `VITE_BRIDGE_DEBUG`), and the environment wins over the built-in default.
+ */
+export type BridgeBootstrapOptions = Partial<BridgeConfig> & Partial<RouteGuardConfig>;
+/** What the `load` returned by `bridgeBootstrap()` hands to your layout. */
+export interface BridgeBootstrapData {
+    /** The effective config, after options, environment and defaults. */
+    config: BridgeConfig;
+    /** The route rules Bridge is enforcing. */
+    routeConfig: RouteGuardConfig;
+}
+/** The SvelteKit `load` function `bridgeBootstrap()` returns. */
+export type BridgeBootstrapLoad = (event: {
+    url: URL;
+    fetch: typeof globalThis.fetch;
+}) => Promise<BridgeBootstrapData>;
+/**
+ * Start Bridge from your root layout. Returns the layout's `load` function.
+ *
+ * The app id and addresses come from `VITE_BRIDGE_APP_ID` (and
+ * `VITE_BRIDGE_API_BASE_URL` for a stage or local app); anything passed here
+ * wins over the environment. With no app id anywhere it throws rather than
+ * guessing.
+ *
+ * @example
+ * // src/routes/+layout.ts
+ * import { bridgeBootstrap } from '@nebulr-group/bridge-svelte';
+ * export const ssr = false;
+ * export const load = bridgeBootstrap({ rules: [{ match: '/', public: true }] });
+ */
+export declare function bridgeBootstrap(options?: BridgeBootstrapOptions): BridgeBootstrapLoad;
+/**
+ * @deprecated Use `export const load = bridgeBootstrap({ rules })` — it reads
+ * the app id and addresses from the `VITE_BRIDGE_*` variables. This positional
+ * form keeps working unchanged and reads no environment.
+ */
 export declare function bridgeBootstrap(url: URL, config: BridgeConfig | string, routeConfig?: RouteGuardConfig, kitFetch?: typeof globalThis.fetch): Promise<{
     flagsReady: Promise<void>;
 }>;

package/dist/client/BridgeBootstrap.js

@@ -8,6 +8,7 @@ import { installBridgeAuthFetch } from '../core/bridge-runtime.js';
 import { useBridge, sanitizeReturnTo, stashReturnTo, takeReturnTo, withReturnTo, } from '@nebulr-group/bridge-auth-core';
 import { logger } from '../shared/logger.js';
 import { bridgeConfig, getConfig, getRouteGuardConfig } from './stores/config.store.js';
+import { resolveBridgeConfig } from './resolve-config.js';
 // TBP-653 — `bridgeBootstrap` used to short-circuit on every call after the
 // first completed one, and the route guard lived below that return. SvelteKit
 // re-runs the root layout load for every navigation (it reads `url`), so the
@@ -29,7 +30,32 @@ const _configuredPromise = new Promise((resolve) => {
 // Child loads can start before the root layout load has run; this only has to
 // cover that ordering, not a missing bootstrap.
 const CONFIGURE_TIMEOUT_MS = 10_000;
-export async function bridgeBootstrap(url, config, routeConfig = { rules: [], defaultAccess: 'protected' }, kitFetch) {
+export function bridgeBootstrap(urlOrOptions, config, routeConfig, kitFetch) {
+    if (urlOrOptions instanceof URL) {
+        if (config === undefined) {
+            throw new Error('[bridge] bridgeBootstrap(url, config) was called without a config.');
+        }
+        return runBootstrap(urlOrOptions, config, routeConfig, kitFetch);
+    }
+    return createBootstrapLoad(urlOrOptions ?? {});
+}
+function createBootstrapLoad(options) {
+    const { rules, defaultAccess, returnTo, ...configOptions } = options;
+    const routeConfig = {
+        rules: rules ?? [],
+        defaultAccess: defaultAccess ?? 'protected',
+        ...(returnTo ? { returnTo } : {}),
+    };
+    // Resolved on the first call, not at import: a missing app id must surface
+    // as a load error the developer sees, and the environment is only final then.
+    let resolved = null;
+    return async ({ url, fetch }) => {
+        resolved ??= resolveBridgeConfig(configOptions);
+        await runBootstrap(url, resolved, routeConfig, fetch);
+        return { config: getConfig(), routeConfig };
+    };
+}
+async function runBootstrap(url, config, routeConfig = { rules: [], defaultAccess: 'protected' }, kitFetch) {
     // Until one call has completed, a call may be the one that lands on a
     // callback URL or needs the no-flash paywall redirect. Afterwards those are
     // owned by <BridgeBootstrap> (reactive paywall) — same split as before.
@@ -103,7 +129,7 @@ async function waitForConfigured() {
     let timer;
     const timeout = new Promise((_, reject) => {
         timer = setTimeout(() => reject(new Error('[bridge] assertAuthorized() ran but bridgeBootstrap() never configured the SDK. ' +
-            'Call bridgeBootstrap(url, config, routeConfig) in your root +layout.ts load.')), CONFIGURE_TIMEOUT_MS);
+            'Add `export const load = bridgeBootstrap({ rules })` to your root +layout.ts.')), CONFIGURE_TIMEOUT_MS);
     });
     try {
         await Promise.race([_configuredPromise, timeout]);

package/dist/client/BridgeBootstrap.svelte

@@ -1,11 +1,12 @@
 <script lang="ts">
   import { beforeNavigate, goto } from '$app/navigation';
   import { page } from '$app/stores';
-  import { onMount, onDestroy } from 'svelte';
+  import { onMount, onDestroy, type Snippet } from 'svelte';
   import { createRouteGuard, routeRulesReferenceFlag } from '../auth/route-guard.js';
   import { stashReturnTo, withReturnTo } from '@nebulr-group/bridge-auth-core';
   import {
     getBridgeAuth,
+    bridgeReadyStore,
     isAuthenticated,
     subscriptionStore,
     loadSubscription,
@@ -37,14 +38,24 @@
   // 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.
+  //
+  // TBP-695 — the shell owns readiness. Wrap the app in <BridgeBootstrap> and
+  // `children` render only once Bridge is ready: the root `load`
+  // (bridgeBootstrap) has finished AND the runtime + capabilities attached
+  // below. The developer writes no ready flag. Self-closing use (no children)
+  // still works for apps that gate on `onBootstrapComplete` themselves.
   let {
     runtime,
     onBootstrapComplete,
+    children,
   }: {
     runtime?: StartBridgeRuntimeOptions;
     onBootstrapComplete?: () => void;
+    children?: Snippet;
   } = $props();
 
+  let runtimeAttached = $state(false);
+
   // Phase 4 (TBP-288/320) — expose the unified bridge surface via Svelte
   // context so descendants can call `useBridge()`.
   setBridgeContext(bridgeSurface);
@@ -210,6 +221,7 @@
     }
 
     // Auth-core manages auto-refresh internally — no startAutoRefresh() needed
+    runtimeAttached = true;
     if (onBootstrapComplete) onBootstrapComplete();
   });
 
@@ -238,3 +250,7 @@
 </script>
 
 <RealtimeDevBadge enabled={devBadgeEnabled} />
+
+{#if runtimeAttached && $bridgeReadyStore}
+  {@render children?.()}
+{/if}

package/dist/client/BridgeBootstrap.svelte.d.ts

@@ -1,7 +1,9 @@
+import { type Snippet } from 'svelte';
 import { type StartBridgeRuntimeOptions } from '../core/bridge-runtime.js';
 type $$ComponentProps = {
     runtime?: StartBridgeRuntimeOptions;
     onBootstrapComplete?: () => void;
+    children?: Snippet;
 };
 declare const BridgeBootstrap: import("svelte").Component<$$ComponentProps, {}, "">;
 type BridgeBootstrap = ReturnType<typeof BridgeBootstrap>;

package/dist/client/resolve-config.d.ts

@@ -0,0 +1,43 @@
+import type { BridgeConfig } from '../shared/types/config.js';
+/** Where Bridge's production API lives — the default when no address is set. */
+export declare const PRODUCTION_API_BASE_URL = "https://api.thebridge.dev";
+/** The standard Vite variables Bridge reads, already mapped to config fields. */
+export interface BridgeEnv {
+    appId?: string;
+    apiBaseUrl?: string;
+    hostedUrl?: string;
+    debug?: string;
+}
+/**
+ * Read the `VITE_BRIDGE_*` variables from the consuming app's build.
+ *
+ * Every access is a literal `import.meta.env.VITE_…` property read on purpose:
+ * that is the form Vite statically replaces, including in a library consumed
+ * from node_modules. A dynamic key (`env[name]`) would not be replaced.
+ * The try/catch covers a non-Vite bundler, where `import.meta.env` is undefined.
+ */
+export declare function readBridgeEnv(): BridgeEnv;
+/**
+ * The hosted pages for an API address on Bridge's own domains: `api` becomes
+ * `auth`, so `api-stage.thebridge.dev` pairs with `auth-stage.thebridge.dev`.
+ *
+ * Without this, a stage app that sets only its API address (the documented
+ * shape) still sent sign-in to production's hosted pages, where its app id does
+ * not exist — the same wrong-environment failure as the API address, one hop
+ * later. Any other host (localhost, self-hosted) cannot be derived.
+ */
+export declare function hostedUrlFor(apiBaseUrl: string): string | undefined;
+/**
+ * Build the effective config: an option passed explicitly wins over the
+ * environment, and the environment wins over the built-in default.
+ *
+ * The hosted-pages address follows the API address on Bridge's own domains
+ * (see `hostedUrlFor`), so one variable is enough for stage.
+ *
+ * Refuses to guess: with no app id anywhere it throws, naming the variable to
+ * set. An app id with no API address runs against production — that is the
+ * documented shape of a production app (`VITE_BRIDGE_APP_ID` alone) — and in a
+ * development build it says so once, naming `VITE_BRIDGE_API_BASE_URL`, because
+ * a stage or local id against production is the mistake this exists to catch.
+ */
+export declare function resolveBridgeConfig(options?: Partial<BridgeConfig>, env?: BridgeEnv, dev?: boolean): BridgeConfig;

package/dist/client/resolve-config.js

@@ -0,0 +1,112 @@
+// TBP-695 — Bridge starts from one line with no arguments.
+//
+// The SDK used to read no environment at all: every app re-typed the same four
+// `import.meta.env.VITE_BRIDGE_*` lines into its own +layout.ts, and the one it
+// most often left out was the API address. A stage or local app id without it
+// silently talked to PRODUCTION, where that app does not exist. Reading the
+// standard variables here removes the boilerplate AND the trap; the no-guess
+// rule below is what keeps the second half true.
+import { logger } from '../shared/logger.js';
+/** Where Bridge's production API lives — the default when no address is set. */
+export const PRODUCTION_API_BASE_URL = 'https://api.thebridge.dev';
+/**
+ * Read the `VITE_BRIDGE_*` variables from the consuming app's build.
+ *
+ * Every access is a literal `import.meta.env.VITE_…` property read on purpose:
+ * that is the form Vite statically replaces, including in a library consumed
+ * from node_modules. A dynamic key (`env[name]`) would not be replaced.
+ * The try/catch covers a non-Vite bundler, where `import.meta.env` is undefined.
+ */
+export function readBridgeEnv() {
+    try {
+        return {
+            appId: import.meta.env.VITE_BRIDGE_APP_ID,
+            apiBaseUrl: import.meta.env.VITE_BRIDGE_API_BASE_URL,
+            hostedUrl: import.meta.env.VITE_BRIDGE_HOSTED_URL,
+            debug: import.meta.env.VITE_BRIDGE_DEBUG,
+        };
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * The hosted pages for an API address on Bridge's own domains: `api` becomes
+ * `auth`, so `api-stage.thebridge.dev` pairs with `auth-stage.thebridge.dev`.
+ *
+ * Without this, a stage app that sets only its API address (the documented
+ * shape) still sent sign-in to production's hosted pages, where its app id does
+ * not exist — the same wrong-environment failure as the API address, one hop
+ * later. Any other host (localhost, self-hosted) cannot be derived.
+ */
+export function hostedUrlFor(apiBaseUrl) {
+    try {
+        const url = new URL(apiBaseUrl);
+        const match = /^api(-[a-z0-9-]+)?\.thebridge\.dev$/.exec(url.hostname);
+        return match ? `https://auth${match[1] ?? ''}.thebridge.dev` : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isDevBuild() {
+    try {
+        return import.meta.env.DEV === true;
+    }
+    catch {
+        return false;
+    }
+}
+// An empty variable means "not set". Vite loads `KEY=` as '' and the demo's
+// tracked .env files use exactly that to stop a key falling through to a
+// developer's .env.local — so '' must never count as a value.
+function present(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed === '' ? undefined : trimmed;
+}
+/**
+ * Build the effective config: an option passed explicitly wins over the
+ * environment, and the environment wins over the built-in default.
+ *
+ * The hosted-pages address follows the API address on Bridge's own domains
+ * (see `hostedUrlFor`), so one variable is enough for stage.
+ *
+ * Refuses to guess: with no app id anywhere it throws, naming the variable to
+ * set. An app id with no API address runs against production — that is the
+ * documented shape of a production app (`VITE_BRIDGE_APP_ID` alone) — and in a
+ * development build it says so once, naming `VITE_BRIDGE_API_BASE_URL`, because
+ * a stage or local id against production is the mistake this exists to catch.
+ */
+export function resolveBridgeConfig(options = {}, env = readBridgeEnv(), dev = isDevBuild()) {
+    const appId = present(options.appId) ?? present(env.appId);
+    if (!appId) {
+        throw new Error('[bridge] No Bridge app id was found. Set VITE_BRIDGE_APP_ID in your .env ' +
+            '(plus VITE_BRIDGE_API_BASE_URL for a stage or local app), ' +
+            'or pass { appId } to bridgeBootstrap().');
+    }
+    const apiBaseUrl = present(options.apiBaseUrl) ?? present(env.apiBaseUrl);
+    const hostedUrl = present(options.hostedUrl) ?? present(env.hostedUrl) ?? (apiBaseUrl ? hostedUrlFor(apiBaseUrl) : undefined);
+    const debug = options.debug ?? (present(env.debug) === undefined ? undefined : env.debug === 'true');
+    if (!apiBaseUrl && dev) {
+        logger.warn(`[bridge] VITE_BRIDGE_API_BASE_URL is not set, so app ${appId} is using production ` +
+            `(${PRODUCTION_API_BASE_URL}). Set it if this is a stage or local app.`);
+    }
+    if (apiBaseUrl && !hostedUrl && dev) {
+        logger.warn(`[bridge] VITE_BRIDGE_HOSTED_URL is not set and cannot be derived from ${apiBaseUrl}, ` +
+            `so sign-in pages will open on production. Set it to this environment's hosted pages.`);
+    }
+    const resolved = { ...options, appId };
+    if (apiBaseUrl)
+        resolved.apiBaseUrl = apiBaseUrl;
+    else
+        delete resolved.apiBaseUrl;
+    if (hostedUrl)
+        resolved.hostedUrl = hostedUrl;
+    else
+        delete resolved.hostedUrl;
+    if (debug !== undefined)
+        resolved.debug = debug;
+    return resolved;
+}

package/dist/core/bridge-runtime.js

@@ -263,6 +263,91 @@ export function startBridgeRuntime(options = {}) {
             // Best-effort: the next reconnect or push repairs it.
         }
     };
+    // TBP-686 — the same repair, for the one live payload the session snapshot
+    // does not carry: `quota.updated`.
+    //
+    // `GET /session/init` has no quota slice (nothing in bridge-api's
+    // session-snapshot types mentions it), and auth-core's QuotaStore fills
+    // itself from exactly two places: a one-shot lazy `GET /usage/quota/:metric`
+    // on the FIRST read of a metric, and live `quota.updated` pushes. It never
+    // re-reads — `ensureHydrated()` returns the cached snapshot on every
+    // subsequent call. So a push lost across a socket swap leaves `used` frozen
+    // at whatever it was when the metric was first read, for the rest of the
+    // session, with no error anywhere: the ingest returns 201, the server
+    // computes correctly and AppSync accepts the publish.
+    //
+    // That is what `metered-display` and `metered-plan-switch` hit on stage: a
+    // token refresh reauthorized mid-test, and the server published `used`
+    // 5-160ms before the replacement subscription was acknowledged.
+    //
+    // The ordering guarantee is the one stated above for the session snapshot,
+    // and it is what makes this deterministic rather than lucky: setOnOpen fires
+    // from markOpen(), which AppSync's `subscribe_success` drives — so anything
+    // published before this point is already durable and the REST read sees it,
+    // and anything published after arrives on the live socket.
+    //
+    // Scope: only metrics the store has already hydrated. A page that never
+    // asked about a metric has nothing stale to repair, so this costs one GET
+    // per watched metric per open and nothing at all for apps that do not use
+    // quotas.
+    const catchUpQuotaSnapshots = async () => {
+        if (_realtime !== rt)
+            return;
+        const token = _currentAuthToken;
+        const doFetch = _originalFetch ?? globalThis.fetch;
+        if (!token || typeof doFetch !== 'function')
+            return;
+        // One try over BOTH the lookup and the read: `requestCatchUp` fires this
+        // without a `.catch()`, so anything thrown out here becomes an unhandled
+        // rejection in the host app rather than a swallowed best-effort repair.
+        let quotas;
+        let metrics = [];
+        try {
+            quotas = useBridge().quotas;
+            metrics = [...quotas.getAll().keys()];
+        }
+        catch {
+            return; // useBridge() not constructed, or no quota surface — nothing to repair.
+        }
+        if (metrics.length === 0)
+            return;
+        let appId = config.appId;
+        try {
+            appId = getBridgeAuth().getApiContext().appId ?? appId;
+        }
+        catch {
+            // BridgeAuth not constructed — config.appId it is.
+        }
+        const base = (config.apiBaseUrl ?? 'https://api.thebridge.dev').replace(/\/+$/, '');
+        await Promise.all(metrics.map(async (metric) => {
+            // The value this repair is replacing. If a live push lands while the
+            // GET is in flight, the push is NEWER than the answer coming back and
+            // must win — otherwise the repair itself would reintroduce a stale
+            // `used`, which is the very bug it exists to fix.
+            const before = quotas.getAll().get(metric);
+            try {
+                const res = await doFetch(`${base}/usage/quota/${encodeURIComponent(metric)}`, {
+                    method: 'GET',
+                    headers: { Authorization: `Bearer ${token}`, 'x-app-id': appId ?? '' },
+                });
+                if (!res.ok)
+                    return;
+                const data = (await res.json());
+                // Stopped, or the session changed while this was in flight: the
+                // answer describes a workspace we no longer have.
+                if (_realtime !== rt || _currentAuthToken !== token)
+                    return;
+                if (quotas.getAll().get(metric) !== before)
+                    return; // a push won the race
+                // `null` is a real answer — "no quota configured for this metric" —
+                // and applyInitialSnapshot drops the cached entry for it.
+                quotas.applyInitialSnapshot(metric, data ?? null);
+            }
+            catch {
+                // Best-effort, per metric: one failure must not skip the others.
+            }
+        }));
+    };
     const requestCatchUp = () => {
         if (!_currentAuthToken)
             return; // signed out: no tenant or user scope to fetch
@@ -271,7 +356,13 @@ export function startBridgeRuntime(options = {}) {
             return;
         }
         _catchUpInFlight = true;
-        void catchUpSessionSnapshot().finally(() => {
+        // Both repairs ride the one in-flight/queued gate, so an open storm still
+        // costs one round of requests, and neither can starve the other.
+        void Promise.all([catchUpSessionSnapshot(), catchUpQuotaSnapshots()]).catch(() => {
+            // Both halves are already best-effort internally; this is the backstop
+            // that keeps a repair failure from surfacing as an unhandled rejection
+            // in the consuming app. `.finally` below still drains the queue.
+        }).finally(() => {
             _catchUpInFlight = false;
             if (_catchUpQueued) {
                 _catchUpQueued = false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebulr-group/bridge-svelte",
-  "version": "0.8.2",
+  "version": "0.9.0-beta.0",
   "description": "Bridge Svelte library, This library helps you to add bridge authentication and feature flags, and payments to your svelte application.",
   "author": "Iman Pouya",
   "license": "MIT",