@nebulr-group/bridge-svelte 0.8.3 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebulr-group/bridge-svelte",
-  "version": "0.8.3",
+  "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",