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

package/dist/client/BridgeBootstrap.d.ts

@@ -1,6 +1,53 @@
 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;
+    /** Route params — read to 404 an unknown `[...bridge]` page (TBP-696, TBP-702). */
+    params?: Record<string, string>;
+    /** The matched route — only its id is read. */
+    route?: {
+        id: string | null;
+    };
+}) => 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

@@ -1,5 +1,5 @@
 // src/lib/bridge/bootstrap.ts
-import { redirect, isRedirect } from '@sveltejs/kit';
+import { error, redirect, isRedirect } from '@sveltejs/kit';
 import { get } from 'svelte/store';
 import { createRouteGuard } from '../auth/route-guard.js';
 import { dropFlagCache, guardCacheGeneration } from '../auth/guard-cache.js';
@@ -8,6 +8,9 @@ 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';
+import { BRIDGE_AUTH_ROUTE_PARAM, isBridgeAuthRouteId, parseBridgeAuthRoute } from './auth-routes.js';
+import { appUsesBilling, billingRoutes, isPaywallExempt, parseBridgeBillingRoute, resolveBillingRoutes, } from './billing-routes.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 +32,88 @@ 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, params, route }) => {
+        resolved ??= resolveBridgeConfig(configOptions);
+        rejectUnknownBridgePage(route?.id, params, resolved);
+        await runBootstrap(url, resolved, routeConfig, fetch);
+        return { config: getConfig(), routeConfig };
+    };
+}
+/**
+ * TBP-696 — `src/routes/auth/[...bridge]/+page.svelte` matches every address
+ * under `/auth`, including ones Bridge serves no page for. Those must get the
+ * app's own 404, and only a `load` can produce it: a component that throws
+ * while rendering never reaches the app's error page. The root layout load is
+ * the one `load` every Bridge app already has, so the check lives here and the
+ * app writes no `+page.ts` of its own.
+ *
+ * Only a route whose rest param is literally `[...bridge]` is checked, so an
+ * app's own catch-all is never touched. SvelteKit re-runs this load with empty
+ * params to render its error page; `params.bridge` is then absent and the
+ * check stands aside.
+ *
+ * TBP-702 — the billing catch-all (`src/routes/subscription/[...bridge]`) uses
+ * the same param, and the load cannot see which component a page renders. It
+ * tells them apart by where the catch-all lives: under `manageRoute`
+ * (`/subscription` by default) it is the billing one; under the directory of
+ * `loginRoute` (`/auth` for `/auth/login`) it is the auth one. A catch-all
+ * anywhere else accepts a page of either kind.
+ */
+function rejectUnknownBridgePage(routeId, params, config) {
+    if (!isBridgeAuthRouteId(routeId))
+        return;
+    const rest = params?.[BRIDGE_AUTH_ROUTE_PARAM];
+    if (rest === undefined)
+        return;
+    const kind = catchAllKind(routeId, config);
+    const known = kind === 'billing'
+        ? parseBridgeBillingRoute(rest)
+        : kind === 'auth'
+            ? parseBridgeAuthRoute(rest)
+            : parseBridgeAuthRoute(rest) ?? parseBridgeBillingRoute(rest);
+    if (!known)
+        error(404, 'Not Found');
+}
+/** Which Bridge catch-all a `…/[...bridge]` route id is, from where it lives. */
+function catchAllKind(routeId, config) {
+    // The address the catch-all serves: drop the rest param and any `(group)`
+    // segments, which never appear in a URL.
+    const base = routeId
+        .split('/')
+        .filter((s) => s !== '' && !/^\(.*\)$/.test(s))
+        .slice(0, -1)
+        .join('/');
+    const at = `/${base}`;
+    const trim = (p) => (p.length > 1 ? p.replace(/\/+$/, '') : p);
+    if (at === trim(resolveBillingRoutes(config.billing).manageRoute))
+        return 'billing';
+    if (config.loginRoute) {
+        const loginDir = trim(config.loginRoute).replace(/\/[^/]*$/, '') || '/';
+        if (at === loginDir)
+            return 'auth';
+    }
+    return 'either';
+}
+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 +187,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]);
@@ -169,7 +253,6 @@ function ensureInitialised() {
     })();
     return _initialisation;
 }
-const STRIPE_DEFAULT_RETURN = '/subscription';
 // Where a Stripe success/cancel return lands (TBP-659).
 //
 // The `redirect` parameter arrives on the app's own callback URL, so anyone can
@@ -191,9 +274,11 @@ const STRIPE_DEFAULT_RETURN = '/subscription';
 // Validation runs on the stripped string because that is the one we navigate to.
 function stripeReturnTarget(url) {
     const raw = url.searchParams.get('redirect');
+    // The subscription page (TBP-702: `billing.manageRoute`, `/subscription` by default).
+    const fallback = billingRoutes().manageRoute;
     if (raw === null)
-        return STRIPE_DEFAULT_RETURN;
-    return sanitizeReturnTo(raw.split('?')[0]) ?? STRIPE_DEFAULT_RETURN;
+        return fallback;
+    return sanitizeReturnTo(raw.split('?')[0]) ?? fallback;
 }
 // Unified callback handler — detects what is calling back and routes accordingly
 async function handleCallbackRoute(url, kitFetch) {
@@ -260,7 +345,8 @@ async function handleCallbackRoute(url, kitFetch) {
                     if (isRedirect(err))
                         throw err;
                     logger.warn('[bridgeBootstrap] confirm-checkout error', err);
-                    redirect(303, getConfig().billing?.paymentErrorRoute ?? '/payment-error');
+                    // TBP-702 — `/subscription/error` by default, served by <BridgeBillingRoutes>.
+                    redirect(303, billingRoutes().paymentErrorRoute);
                 }
             }
             else if (stripeCancel) {
@@ -283,14 +369,23 @@ async function handleCallbackRoute(url, kitFetch) {
 // decision (authenticated + shouldSelectPlan + not opted out via
 // paymentsAutoRedirect) lives in auth-core's shouldRedirectToPaywall()
 // (TBP-369). We only own the route/config guards here:
-//   - billing.paywallRoute is configured
-//   - the current path is not already the paywall route (no redirect loop)
+//   - billing.paywallRoute is not turned off (TBP-702: it defaults to
+//     `/subscription/plan`, served by <BridgeBillingRoutes>)
+//   - an explicit paywallRoute always applies; the default only when the app
+//     uses billing (it has plans) — an app without billing has only plan-less
+//     workspaces and no paywall page. The plan list is fetched only here, for a
+//     workspace that would otherwise be redirected.
+//   - the current path is not the paywall (no redirect loop) or the
+//     payment-error page (a failed checkout must be readable)
 async function enforcePaywall(url) {
     try {
-        const paywallRoute = getConfig().billing?.paywallRoute;
-        if (paywallRoute && url.pathname !== paywallRoute) {
+        const routes = billingRoutes();
+        const paywallRoute = routes.paywallRoute;
+        if (paywallRoute && !isPaywallExempt(url.pathname, routes)) {
             const bridge = getBridgeAuth();
             if (await bridge.shouldRedirectToPaywall()) {
+                if (routes.paywallIsDefault && !appUsesBilling(await bridge.getPlans()))
+                    return;
                 logger.debug('[bridgeBootstrap] paywall redirect', paywallRoute);
                 redirect(303, paywallRoute);
             }

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,
@@ -14,6 +15,7 @@
   import { bridge as bridgeSurface } from '../core/bridge.js';
   import { setBridgeContext } from '../core/use-bridge.js';
   import { getConfig, getRouteGuardConfig } from './stores/config.store.js';
+  import { appUsesBilling, billingRoutes, isPaywallExempt } from './billing-routes.js';
   import {
     onBridgeAuthorizationChange,
     onBridgeFlagChange,
@@ -37,14 +39,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);
@@ -61,11 +73,15 @@
   // `shouldSelectPlan` resolves true. Same data source as <BridgePaywall>, so the
   // overlay and the redirect agree. The load() redirect remains a no-flash
   // fast-path for direct loads/refreshes only.
+  //
+  // TBP-702 — the paywall defaults to `/subscription/plan` (served by
+  // <BridgeBillingRoutes>); `billing.paywallRoute: false` turns it off.
   $effect(() => {
-    const paywallRoute = getConfig().billing?.paywallRoute;
+    const routes = billingRoutes();
+    const paywallRoute = routes.paywallRoute;
     if (!paywallRoute || !$isAuthenticated) return;
 
-    const { status, loading, error } = $subscriptionStore;
+    const { status, plans, loading, error } = $subscriptionStore;
 
     // Status unknown → trigger a single load. Guarding on `!error` avoids a
     // tight refetch loop on persistent failure (fail-pending, not fail-open);
@@ -77,11 +93,15 @@
 
     // Status known → enforce. `$page.url.pathname` makes this re-run on
     // navigation too, so manual nav to a protected page while plan-less is
-    // also caught. Path guard prevents a redirect loop on the paywall itself.
+    // also caught. Path guard prevents a redirect loop on the paywall itself,
+    // and leaves the payment-error page readable.
+    // TBP-702 — the default paywall only applies to an app that uses billing
+    // (has plans); an explicit paywallRoute always applies.
     if (
       status?.shouldSelectPlan === true &&
       status?.paymentsAutoRedirect !== false &&
-      $page.url.pathname !== paywallRoute
+      (!routes.paywallIsDefault || appUsesBilling(plans)) &&
+      !isPaywallExempt($page.url.pathname, routes)
     ) {
       goto(paywallRoute);
     }
@@ -210,6 +230,7 @@
     }
 
     // Auth-core manages auto-refresh internally — no startAutoRefresh() needed
+    runtimeAttached = true;
     if (onBootstrapComplete) onBootstrapComplete();
   });
 
@@ -238,3 +259,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/auth-routes.d.ts

@@ -0,0 +1,33 @@
+/** Every page `<BridgeAuthRoutes>` serves, by its first path segment. */
+export declare const BRIDGE_AUTH_PAGES: readonly ["login", "signup", "oauth-callback", "set-password", "forgot-password", "magic-link", "setup-passkey", "workspaces"];
+/** One of the pages `<BridgeAuthRoutes>` serves. */
+export type BridgeAuthPage = (typeof BRIDGE_AUTH_PAGES)[number];
+/** A parsed auth route: which page, and the email-link token where it has one. */
+export interface BridgeAuthRoute {
+    page: BridgeAuthPage;
+    /** The one-time token of `set-password/[token]` and `setup-passkey/[token]`. */
+    token?: string;
+}
+/** The rest parameter name the catch-all route must use: `[...bridge]`. */
+export declare const BRIDGE_AUTH_ROUTE_PARAM = "bridge";
+/**
+ * Parse the `[...bridge]` rest parameter into a page, or `null` when it names
+ * no page Bridge serves — the caller then answers with the app's own 404.
+ *
+ * Exact shapes only: `login` but not `login/extra`, and `set-password/<token>`
+ * but not a bare `set-password`. A page that half-matches would otherwise render
+ * a form at an address nobody links to.
+ */
+export declare function parseBridgeAuthRoute(rest: string | undefined | null): BridgeAuthRoute | null;
+/**
+ * True when a SvelteKit route id is a Bridge auth catch-all, e.g.
+ * `/auth/[...bridge]`. Only that exact param name counts, so an app's own
+ * unrelated catch-all is never 404'd by Bridge.
+ */
+export declare function isBridgeAuthRouteId(routeId: string | null | undefined): boolean;
+/**
+ * The URL prefix the catch-all lives under: `/auth` for `/auth/login` when the
+ * rest parameter is `login`. Links between the pages are built from it, so the
+ * catch-all can live anywhere, not only at `/auth`.
+ */
+export declare function bridgeAuthBase(pathname: string, rest: string | undefined | null): string;

package/dist/client/auth-routes.js

@@ -0,0 +1,70 @@
+// TBP-696 — one file serves every auth page.
+//
+// An app used to hand-write seven near-identical pages under `src/routes/auth/`,
+// and the one it most often skipped — `set-password/[token]`, because "we don't
+// use passwords" — is the address bridge-api writes into every signup
+// verification email. Skipping it sent every new signup to a 404. With
+// `src/routes/auth/[...bridge]/+page.svelte` rendering `<BridgeAuthRoutes />`,
+// the plugin owns that list, so a page cannot be forgotten.
+//
+// This module is the list and its parser. It is shared by the component (which
+// page to render) and by `bridgeBootstrap()`'s load (which answers an unknown
+// segment with a real 404 — a component cannot, since only a `load` reaches the
+// app's own error page).
+/** Every page `<BridgeAuthRoutes>` serves, by its first path segment. */
+export const BRIDGE_AUTH_PAGES = [
+    'login',
+    'signup',
+    'oauth-callback',
+    'set-password',
+    'forgot-password',
+    'magic-link',
+    'setup-passkey',
+    'workspaces',
+];
+/** Pages reached from an email link, whose second segment is the token. */
+const TOKEN_PAGES = new Set(['set-password', 'setup-passkey']);
+/** The rest parameter name the catch-all route must use: `[...bridge]`. */
+export const BRIDGE_AUTH_ROUTE_PARAM = 'bridge';
+/**
+ * Parse the `[...bridge]` rest parameter into a page, or `null` when it names
+ * no page Bridge serves — the caller then answers with the app's own 404.
+ *
+ * Exact shapes only: `login` but not `login/extra`, and `set-password/<token>`
+ * but not a bare `set-password`. A page that half-matches would otherwise render
+ * a form at an address nobody links to.
+ */
+export function parseBridgeAuthRoute(rest) {
+    if (typeof rest !== 'string')
+        return null;
+    const segments = rest.split('/').filter((s) => s !== '');
+    const [first, token] = segments;
+    if (!first || !BRIDGE_AUTH_PAGES.includes(first))
+        return null;
+    const page = first;
+    if (TOKEN_PAGES.has(page)) {
+        return segments.length === 2 && token ? { page, token } : null;
+    }
+    return segments.length === 1 ? { page } : null;
+}
+/**
+ * True when a SvelteKit route id is a Bridge auth catch-all, e.g.
+ * `/auth/[...bridge]`. Only that exact param name counts, so an app's own
+ * unrelated catch-all is never 404'd by Bridge.
+ */
+export function isBridgeAuthRouteId(routeId) {
+    return typeof routeId === 'string' && routeId.endsWith(`/[...${BRIDGE_AUTH_ROUTE_PARAM}]`);
+}
+/**
+ * The URL prefix the catch-all lives under: `/auth` for `/auth/login` when the
+ * rest parameter is `login`. Links between the pages are built from it, so the
+ * catch-all can live anywhere, not only at `/auth`.
+ */
+export function bridgeAuthBase(pathname, rest) {
+    // Count segments rather than comparing text: `pathname` is URL-encoded and the
+    // param is decoded, so a token with an escaped character would not match.
+    const restCount = (rest ?? '').split('/').filter((s) => s !== '').length;
+    const segments = pathname.split('/').filter((s) => s !== '');
+    const kept = segments.slice(0, Math.max(0, segments.length - restCount));
+    return kept.length ? `/${kept.join('/')}` : '';
+}

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

@@ -0,0 +1,72 @@
+import type { BridgeConfig } from '../shared/types/config.js';
+/** Every page `<BridgeBillingRoutes>` serves. `manage` is the catch-all's own address. */
+export declare const BRIDGE_BILLING_PAGES: readonly ["manage", "plan", "success", "error"];
+/** One of the pages `<BridgeBillingRoutes>` serves. */
+export type BridgeBillingPage = (typeof BRIDGE_BILLING_PAGES)[number];
+/** A parsed billing route. */
+export interface BridgeBillingRoute {
+    page: BridgeBillingPage;
+}
+/**
+ * Parse the `[...bridge]` rest parameter into a billing page, or `null` when it
+ * names none — the caller then answers with the app's own 404.
+ *
+ * The bare address (`/subscription`, rest `''`) is the manage page; `plan`,
+ * `success` and `error` are one segment each. Nothing deeper matches.
+ */
+export declare function parseBridgeBillingRoute(rest: string | undefined | null): BridgeBillingRoute | null;
+/** Where each billing destination points when the app configures nothing. */
+export declare const BRIDGE_BILLING_DEFAULTS: {
+    readonly manageRoute: "/subscription";
+    readonly paywallRoute: "/subscription/plan";
+    readonly paymentErrorRoute: "/subscription/error";
+};
+/** The billing destinations in effect. */
+export interface BridgeBillingRoutes {
+    /** The subscription page — where Manage/Upgrade buttons go. */
+    manageRoute: string;
+    /** Where a plan-less workspace is sent; `null` when the redirect is turned off. */
+    paywallRoute: string | null;
+    /**
+     * True when `paywallRoute` is the built-in default rather than the app's own
+     * choice. The default only applies to an app that uses billing — see
+     * `appUsesBilling` — so an app that never set billing up, where every
+     * workspace is plan-less, is not sent to a page it does not have.
+     */
+    paywallIsDefault: boolean;
+    /** Where a failed checkout confirmation lands. */
+    paymentErrorRoute: string;
+    /** Where a completed checkout lands by default: `<manageRoute>/success`. */
+    successRoute: string;
+}
+/**
+ * Resolve the billing destinations from a `billing` config block. An unset
+ * route takes its default; `paywallRoute: false` turns the paywall redirect off
+ * (for an app that gates with the `<BridgePaywall>` overlay, or not at all).
+ */
+export declare function resolveBillingRoutes(billing?: BridgeConfig['billing']): BridgeBillingRoutes;
+/**
+ * The billing destinations for the running app. Before the config exists (a
+ * component rendered outside `<BridgeBootstrap>`, or a unit test) the defaults
+ * apply — the same answer an app that configures nothing gets.
+ */
+export declare function billingRoutes(): BridgeBillingRoutes;
+/**
+ * Whether the app uses billing, for the default paywall (TBP-702): it has at
+ * least one plan. Every workspace of an app with no billing is plan-less
+ * (`shouldSelectPlan` is true whenever a workspace has no plan), so without this
+ * the default would send all of its users to `/subscription/plan`.
+ *
+ * The plan catalogue is the app-level signal the client can see. The
+ * subscription status's `paymentsEnabled` is per workspace (it has a Stripe
+ * customer and subscription), so it is false for every plan-less workspace, and
+ * the app config and the token carry no billing flag. `paymentsAutoRedirect` is
+ * checked separately, by the paywall decision itself.
+ */
+export declare function appUsesBilling(plans: readonly unknown[] | null | undefined): boolean;
+/**
+ * Whether the paywall redirect must leave `pathname` alone: the paywall itself
+ * (no loop), and the payment-error page — a plan-less workspace whose checkout
+ * failed has to be able to read why, not be bounced straight back to the plans.
+ */
+export declare function isPaywallExempt(pathname: string, routes: BridgeBillingRoutes): boolean;

package/dist/client/billing-routes.js

@@ -0,0 +1,97 @@
+// TBP-702 — one file serves the subscription page, the paywall, and the pages a
+// checkout returns to.
+//
+// The plugin used to redirect to `/payment-error` and point every Manage/Upgrade
+// button at `/billing`, and no guide told anyone to create either page — so a
+// guide-following app had two 404s waiting for the first failed checkout and the
+// first "Manage billing" click. With `src/routes/subscription/[...bridge]/+page.svelte`
+// rendering `<BridgeBillingRoutes />`, the defaults below point at pages that
+// exist.
+//
+// This module is the page list, its parser and the route defaults. It is shared
+// by the component (which page to render), by the CTA components (where Manage
+// goes), and by `bridgeBootstrap()` (where the paywall and a failed checkout go,
+// and which unknown segment is a 404).
+import { getConfig } from './stores/config.store.js';
+/** Every page `<BridgeBillingRoutes>` serves. `manage` is the catch-all's own address. */
+export const BRIDGE_BILLING_PAGES = ['manage', 'plan', 'success', 'error'];
+/**
+ * Parse the `[...bridge]` rest parameter into a billing page, or `null` when it
+ * names none — the caller then answers with the app's own 404.
+ *
+ * The bare address (`/subscription`, rest `''`) is the manage page; `plan`,
+ * `success` and `error` are one segment each. Nothing deeper matches.
+ */
+export function parseBridgeBillingRoute(rest) {
+    if (typeof rest !== 'string')
+        return null;
+    const segments = rest.split('/').filter((s) => s !== '');
+    if (segments.length === 0)
+        return { page: 'manage' };
+    if (segments.length !== 1)
+        return null;
+    const [first] = segments;
+    if (first === 'plan' || first === 'success' || first === 'error')
+        return { page: first };
+    return null;
+}
+/** Where each billing destination points when the app configures nothing. */
+export const BRIDGE_BILLING_DEFAULTS = {
+    manageRoute: '/subscription',
+    paywallRoute: '/subscription/plan',
+    paymentErrorRoute: '/subscription/error',
+};
+/**
+ * Resolve the billing destinations from a `billing` config block. An unset
+ * route takes its default; `paywallRoute: false` turns the paywall redirect off
+ * (for an app that gates with the `<BridgePaywall>` overlay, or not at all).
+ */
+export function resolveBillingRoutes(billing) {
+    const manageRoute = billing?.manageRoute || BRIDGE_BILLING_DEFAULTS.manageRoute;
+    const paywall = billing?.paywallRoute;
+    return {
+        manageRoute,
+        paywallRoute: paywall === false ? null : paywall || BRIDGE_BILLING_DEFAULTS.paywallRoute,
+        paywallIsDefault: paywall !== false && !paywall,
+        paymentErrorRoute: billing?.paymentErrorRoute || BRIDGE_BILLING_DEFAULTS.paymentErrorRoute,
+        successRoute: `${manageRoute.replace(/\/+$/, '')}/success`,
+    };
+}
+/**
+ * The billing destinations for the running app. Before the config exists (a
+ * component rendered outside `<BridgeBootstrap>`, or a unit test) the defaults
+ * apply — the same answer an app that configures nothing gets.
+ */
+export function billingRoutes() {
+    let billing;
+    try {
+        billing = getConfig().billing;
+    }
+    catch {
+        billing = undefined;
+    }
+    return resolveBillingRoutes(billing);
+}
+/**
+ * Whether the app uses billing, for the default paywall (TBP-702): it has at
+ * least one plan. Every workspace of an app with no billing is plan-less
+ * (`shouldSelectPlan` is true whenever a workspace has no plan), so without this
+ * the default would send all of its users to `/subscription/plan`.
+ *
+ * The plan catalogue is the app-level signal the client can see. The
+ * subscription status's `paymentsEnabled` is per workspace (it has a Stripe
+ * customer and subscription), so it is false for every plan-less workspace, and
+ * the app config and the token carry no billing flag. `paymentsAutoRedirect` is
+ * checked separately, by the paywall decision itself.
+ */
+export function appUsesBilling(plans) {
+    return Array.isArray(plans) && plans.length > 0;
+}
+/**
+ * Whether the paywall redirect must leave `pathname` alone: the paywall itself
+ * (no loop), and the payment-error page — a plan-less workspace whose checkout
+ * failed has to be able to read why, not be bounced straight back to the plans.
+ */
+export function isPaywallExempt(pathname, routes) {
+    return pathname === routes.paywallRoute || pathname === routes.paymentErrorRoute;
+}