@aforoai/storefront-widgets 1.0.1

package/dist/index.d.cts

@@ -0,0 +1,1228 @@
+import * as React from 'react';
+import { T as ThemeTokenOverrides, O as OfferingPayload, H as HeadlessConfigResponse, S as SubscriptionPayload, W as WidgetErrorPayload, a as SubscriptionForOfferingResponse, C as CheckoutCartType, b as CheckoutConfirmedPayload, c as CheckoutCancelledPayload, d as CheckoutCartResponse, e as SubscriptionStatusFilter, f as SubscriptionPayloadV2, g as SubscriptionPageResponse, I as InvoiceStatusFilter, h as InvoicePayload, i as InvoicePageResponse, U as UsageMetricPayload, j as UsageThreshold, k as UsageResponse, P as PaymentMethodListResponse, A as ApplyAt, l as UpgradeCancelResultPayload, D as DemoModeBridgeProvider, m as TenantBrandKit, n as InitiateCheckoutRequest, o as InitiateCheckoutResponse, p as InvoiceListFilter, q as InvoicePdfUrlResponse, r as InitiateInvoicePaymentRequest, s as InitiateInvoicePaymentResponse, t as CreateCartRequest, u as UpdateCustomerDetailsRequest, v as InitiateCartPaymentRequest, w as ConfirmCartResponse, R as RequestMagicLinkRequest, x as RequestMagicLinkResponse, V as VerifyMagicLinkResponse, y as SubscriptionListFilter, z as PreviewChangeRequest, B as PreviewChangeResponse, E as UpgradeRequest, F as UpgradeResponse, G as CancelWithFeedbackRequest, J as CancelResponse, K as SetupIntentResponse, L as SessionConfig, M as SessionState } from './types-Dm6cp_Cc.cjs';
+export { N as AforoEventPayload, Q as AforoEventType, X as CancelReason, Y as CheckoutBillingAddress, Z as CheckoutCartErrorResponse, _ as CheckoutCartStatus, $ as CheckoutCustomerDetailsSubmittedPayload, a0 as CheckoutExpiredPayload, a1 as CheckoutFlowPhase, a2 as CheckoutPaymentCompletedPayload, a3 as CheckoutPaymentInitiatedPayload, a4 as CheckoutPaymentProvider, a5 as CheckoutStepChangedPayload, a6 as ConsentState, a7 as FeaturePayload, a8 as HeadlessBrandingPayload, a9 as InvoiceDownloadedPayload, aa as InvoiceExpandedPayload, ab as InvoiceFilterChangedPayload, ac as InvoicePaidPayload, ad as InvoicePayRequestedPayload, ae as InvoiceSearchChangedPayload, af as InvoiceStatus, ag as InvoiceTypeKind, ah as LiveSubscriptionStatus, ai as MagicLinkFailureCode, aj as OfferingSummary, ak as RatePlanPayload, al as RetentionOfferShown, am as RetentionOutcome, an as SubscriptionCancelRequestedPayload, ao as SubscriptionChangeType, ap as SubscriptionClickedPayload, aq as SubscriptionFilterChangedPayload, ar as SubscriptionStatus, as as SubscriptionUpgradeRequestedPayload, at as ThemeTokens, au as UpgradeCancelAbandonedPayload, av as UpgradeCancelCompletedPayload, aw as UpgradeCancelDeflectionOfferAcceptedPayload, ax as UpgradeCancelDeflectionOfferShownPayload, ay as UpgradeCancelPreviewFetchedPayload, az as UpgradeCancelStepChangedPayload, aA as UsageMetricClickedPayload, aB as UsageThresholdReachedPayload, aC as WidgetId, aD as WidgetMountConfig } from './types-Dm6cp_Cc.cjs';
+export { A as AforoEmbed } from './AforoEmbed-BqQOFsl3.cjs';
+export { EmbedEnvironment, EmbedKey } from '@aforoai/types';
+
+/**
+ * AforoPricingCard — renders all PUBLISHED offerings for the tenant.
+ *
+ * Spec: FR-WIDGET-PC-1..9 (Section 3.2 of 103-embeddable-plugins-requirements).
+ *
+ * v0.2.0 (Prompt 4 — 2026-05-26): real rendering shipped. Replaces the
+ * placeholder body from Prompt 3 with three layouts (horizontal /
+ * vertical / table), full theme inheritance, locale-aware currency
+ * formatting, the 4 distinct UI states required by FR-WIDGET-X-1, and
+ * postMessage emission of `aforo.pricing-card.cta_clicked` on every CTA
+ * click.
+ *
+ * The component itself is a thin orchestrator over `<WidgetShell>` —
+ * the shell handles session init + theme resolve + event bus +
+ * ErrorBoundary, and exposes everything via the `useWidgetShell()`
+ * context. The actual rendering work lives in `<PricingCardBody>`.
+ */
+
+interface AforoPricingCardProps {
+    /** Tenant slug — required. */
+    tenantSlug: string;
+    /** Embed key (Bearer for all backend calls) — required. */
+    embedKey: string;
+    /** Pre-issued customer bridge token. Optional — pricing card is anonymous-mode safe (FR-AUTH-1). */
+    bridgeToken?: string;
+    /** Layout key. Default `horizontal`. */
+    layout?: 'horizontal' | 'vertical' | 'table';
+    /** Per-offering CTA URL override (Prompt 3 surface). Wins over `ctaUrl`. */
+    ctaUrlByOffering?: Record<string, string>;
+    /** Force-feature a specific offering. Overrides backend `offering.featured`. */
+    featuredOfferingId?: string;
+    /** Theme cascade overrides (applied via the shell's ThemeReader). */
+    themeOverrides?: ThemeTokenOverrides;
+    /** Dark-mode mode. `auto` reads `prefers-color-scheme`. Default `auto`. */
+    theme?: 'light' | 'dark' | 'auto';
+    /** BCP-47 locale (e.g. `en-US`, `de-DE`). Default `navigator.language`. */
+    locale?: string;
+    /** Max plans to render — operator-set per FR-EMB-02. Default 4. */
+    maxPlans?: number;
+    /** Whether to show the per-plan features list. Default `true`. */
+    showFeatures?: boolean;
+    /** Default CTA label when not overridden per-offering. Default `Get Started` (FR-EMB-03). */
+    ctaText?: string;
+    /** Default CTA URL. If absent, CTA click only fires postMessage. */
+    ctaUrl?: string;
+    /** Optional React-side callback fired before the URL navigation + postMessage. */
+    onCtaClick?: (offering: OfferingPayload) => void;
+    /** Optional `Intl.NumberFormat` factory override — used by tests to inject a deterministic formatter. */
+    intlOverride?: (locale: string, currency: string) => Intl.NumberFormat;
+    /**
+     * INTERNAL — operator Embed Studio preview short-circuit. When provided,
+     * the widget bypasses the BridgeClient fetch entirely and renders this
+     * payload directly. Underscore prefix signals "not for production app
+     * code"; this prop has no impact on customer integrations and is
+     * deliberately undocumented in the public README.
+     */
+    _mockHeadlessConfig?: HeadlessConfigResponse | null;
+}
+declare function AforoPricingCard(props: AforoPricingCardProps): React.ReactElement;
+
+/**
+ * AforoSubscribeButton — single CTA that initiates a hosted-checkout
+ * subscription flow for a specific offering.
+ *
+ * Spec: FR-WIDGET-SB-1..7 (Section 3.3) + FR-WIDGET-X-1..11 (Section 3.10).
+ *
+ * v0.3.0 (Prompt 5 — 2026-05-26): real rendering shipped. Replaces the
+ * Prompt 3 placeholder body. After this commit, AforoSubscribeButton is
+ * the first AUTHENTICATED widget in the embed plane — it exercises the
+ * full {@code AforoSession} bridge-token → session-JWT flow end-to-end,
+ * the anti-double-subscribe check against pricing-service, and the
+ * idempotent checkout-initiate path through storefront-service.
+ *
+ * Public prop interface evolves from Prompt 3:
+ *
+ * <ul>
+ *   <li>{@code bridgeToken} is now REQUIRED (was optional)</li>
+ *   <li>{@code buttonText} → {@code ctaText} (renamed to match the Prompt 4
+ *       AforoPricingCard convention)</li>
+ *   <li>New: {@code mode}, {@code returnUrl}, {@code onSubscribed},
+ *       {@code onError}</li>
+ * </ul>
+ *
+ * The {@code sdk-contract.test.ts} surface lock checks only the export name
+ * — prop interface evolution is permitted in v0.x per CLAUDE.md pre-launch
+ * posture. Locked once v1.0 ships.
+ *
+ * The component itself is a thin orchestrator over {@code <WidgetShell>} —
+ * the shell handles session init + theme resolve + event bus +
+ * ErrorBoundary, and exposes everything via the {@code useWidgetShell()}
+ * context. The actual rendering work lives in {@code <SubscribeButtonBody>}.
+ */
+
+interface AforoSubscribeButtonProps {
+    /** Tenant slug — required. */
+    tenantSlug: string;
+    /** Embed key (Bearer for all backend calls) — required. */
+    embedKey: string;
+    /**
+     * Customer bridge token (JWT issued at signup / login). REQUIRED for the
+     * subscribe-button widget — anti-double-subscribe + checkout-initiate both
+     * need a customer-session JWT (different from the embed key) per FR-AUTH-3.
+     */
+    bridgeToken: string;
+    /** Offering to subscribe to — required (FR-WIDGET-SB-1). */
+    offeringId: string;
+    /**
+     * Mode advisory — controls what happens on CTA click:
+     * <ul>
+     *   <li>{@code redirect} (default): navigates to hosted checkout</li>
+     *   <li>{@code event-only}: emits {@code aforo.subscribe.checkout_requested}
+     *       postMessage and lets the parent page handle the redirect</li>
+     *   <li>{@code embedded-flow}: reserved for Prompt 7 (CheckoutFlow widget)
+     *       — currently renders a "Coming soon" stub and falls back to
+     *       redirect mode if the operator wants a working flow today</li>
+     * </ul>
+     */
+    mode?: 'redirect' | 'event-only' | 'embedded-flow';
+    /**
+     * CTA label. Defaults to {@code 'Subscribe'} or {@code 'Start free trial'}
+     * (when {@code trialMode=true}).
+     */
+    ctaText?: string;
+    /** Button size variant (FR-WIDGET-SB-6). Default {@code 'medium'}. */
+    size?: 'small' | 'medium' | 'large';
+    /** Start-free-trial mode — no payment method collected at checkout (FR-WIDGET-SB-5). */
+    trialMode?: boolean;
+    /**
+     * Where hosted checkout returns the customer to on success. Default is
+     * {@code window.location.href}. Validated server-side against the embed
+     * key's {@code allowed_domains} list.
+     */
+    returnUrl?: string;
+    /** Theme cascade overrides (applied via the shell's ThemeReader). */
+    themeOverrides?: ThemeTokenOverrides;
+    /** Dark-mode mode. Default {@code 'auto'}. */
+    theme?: 'light' | 'dark' | 'auto';
+    /** Optional React-side callback fired when {@code aforo.subscription.created} resolves. */
+    onSubscribed?: (subscription: SubscriptionPayload) => void;
+    /** Optional React-side callback fired on any widget error. */
+    onError?: (error: WidgetErrorPayload) => void;
+    /**
+     * INTERNAL — operator Embed Studio preview short-circuit. When provided,
+     * the widget bypasses the AforoSession bridge exchange + the
+     * BridgeClient.fetchSubscriptionForOffering call entirely and renders
+     * directly against this synthetic response. Underscore prefix signals
+     * "not for production app code"; this prop has no impact on customer
+     * integrations and is deliberately undocumented in the public README.
+     * Mirrors AforoPricingCard's `_mockHeadlessConfig` operator-preview
+     * pattern.
+     */
+    _mockSubscriptionForOffering?: SubscriptionForOfferingResponse | null;
+}
+declare function AforoSubscribeButton(props: AforoSubscribeButtonProps): React.ReactElement;
+
+/**
+ * AforoCheckoutFlow — multi-step embedded checkout flow.
+ *
+ * Spec: FR-WIDGET-CK-1..7 (Section 3.4) + FR-WIDGET-X-1..11 (Section 3.10).
+ *
+ * v0.4.0 (Prompt 7B — 2026-05-28): real rendering shipped. Replaces the
+ * Prompt 3 placeholder. After this commit, AforoCheckoutFlow is the
+ * second AUTHENTICATED widget in the embed plane (after SubscribeButton
+ * from Prompt 5) — it exercises the full Prompt 7A backend BFF surface
+ * (createCart / getCart / updateCustomerDetails / initiatePayment /
+ * confirmCart / cancelCart) end-to-end.
+ *
+ * Cart types supported:
+ *  - SUBSCRIBE          — direct-to-checkout for an offering (from SubscribeButton
+ *                          embedded-flow mode OR standalone widget mount)
+ *  - INVOICE_PAYMENT    — pay an existing invoice (from InvoiceList Pay Now)
+ *
+ * Multi-step state machine (4 phases + 3 terminal states):
+ *  bootstrapping → customer-details → payment → confirming → completed
+ *                                                          ↘ cancelled / expired / error
+ *
+ * Payment provider integration is iframe-based per FR-SEC-15 — the widget
+ * never touches raw PAN/CVV; the gateway-hosted form owns that. v1 widget
+ * renders the appropriate surface per provider (Stripe clientSecret →
+ * embedded iframe; Razorpay orderId → embedded checkout; PayPal approvalUrl
+ * → popup window). Cross-origin postMessage on a strict allowlist drives
+ * the tokenization → /initiate-payment → /confirm flow.
+ *
+ * FR-SEC-23 reminder: widget events (subscription.created, invoice.paid)
+ * are advisory only. Backend webhooks are the authoritative source for
+ * customer-side state.
+ */
+
+interface AforoCheckoutFlowProps {
+    /** Tenant slug — required. */
+    tenantSlug: string;
+    /** Embed key (Bearer for all backend calls) — required. */
+    embedKey: string;
+    /**
+     * Customer bridge token (JWT issued at signup / login). REQUIRED — the
+     * checkout-flow widget exercises every mutation under the BFF; needs a
+     * customer-session JWT for every call.
+     */
+    bridgeToken: string;
+    /**
+     * Cart type — drives which downstream-target the cart is bound to. Default
+     * is `SUBSCRIBE`. INVOICE_PAYMENT carts skip the offering anti-double-
+     * subscribe check.
+     */
+    cartType?: CheckoutCartType;
+    /**
+     * Target id for the cart:
+     *  - cartType=SUBSCRIBE       → offering id (required)
+     *  - cartType=INVOICE_PAYMENT → invoice id (required)
+     */
+    targetId: string;
+    /**
+     * Where to return the customer if the payment flow leaves the iframe
+     * (PayPal approval URL, 3DS challenges in a new tab). Defaults to the
+     * current page URL.
+     */
+    returnUrl?: string;
+    /** Theme cascade overrides. */
+    themeOverrides?: ThemeTokenOverrides;
+    /** Dark-mode mode. Default `auto`. */
+    theme?: 'light' | 'dark' | 'auto';
+    /** Optional React callback fired on `aforo.checkout-flow.confirmed`. */
+    onConfirmed?: (payload: CheckoutConfirmedPayload) => void;
+    /** Optional React callback fired on any widget error. */
+    onError?: (error: WidgetErrorPayload) => void;
+    /** Optional React callback fired when customer dismisses the flow. */
+    onCancelled?: (payload: CheckoutCancelledPayload) => void;
+    /**
+     * INTERNAL — operator Embed Studio preview short-circuit. When provided,
+     * the widget bypasses the AforoSession bridge exchange + the BFF
+     * createCart call and uses the supplied cart instead. The Embed Studio
+     * preview pane uses this to render the widget against a synthetic
+     * fixture without depending on a live backend.
+     */
+    _mockCartResponse?: CheckoutCartResponse;
+    /**
+     * INTERNAL — short-circuit for the bridge-token exchange. Pairs with
+     * `_mockCartResponse` for operator preview. Production widget mounts
+     * NEVER pass this.
+     */
+    _mockSessionJwt?: string;
+    /**
+     * INTERNAL — for tests + operator preview. When set, the widget skips the
+     * iframe render entirely and uses the supplied paymentMethodId on the
+     * /initiate-payment call. Production widget mounts NEVER pass this.
+     */
+    _mockPaymentMethodId?: string;
+}
+declare function AforoCheckoutFlow(props: AforoCheckoutFlowProps): React.ReactElement;
+
+/**
+ * AforoSubscriptionManager — paginated list of the signed-in customer's
+ * subscriptions with status filters + per-row actions (Manage / Upgrade /
+ * Cancel / Update payment / Resume / Re-subscribe).
+ *
+ * Spec: FR-WIDGET-SM-1..6 (Section 3.5) + FR-WIDGET-X-1..11 (Section 3.10).
+ *
+ * v0.5.0 (Prompt 12 — 2026-05-29): real rendering shipped. Replaces the
+ * Prompt 3 placeholder body. Consumes the {@code GET /api/v1/portal/embed/subscriptions}
+ * endpoint added in Prompt 12 (storefront-service Embed BFF).
+ *
+ * <p>SSE-driven row refresh ({@code subscription.status_changed} from
+ * Prompt 8) is deliberately deferred — Prompt 8 SSE wiring on
+ * {@code AforoSession.subscribe} is still the Prompt 3 stub. The widget
+ * works correctly via polling-or-manual-refresh in the meantime; SSE
+ * wiring lands in a follow-up commit once Prompt 8 ships for real. The
+ * inbound {@code aforo:subscription-changed} parent-postMessage path works
+ * today and provides the same UX in practice.</p>
+ *
+ * <p>Public prop interface evolves from Prompt 3 (which had a thin 5-prop
+ * shape with {@code statusFilter} as a single-value pre-filter). Following
+ * the Prompt 5 / 6B precedent ({@code buttonText} → {@code ctaText},
+ * {@code statusFilter} → {@code defaultStatus}), the prop interface
+ * evolves freely in v0.x; {@code sdk-contract.test.ts} only locks runtime
+ * exports.</p>
+ */
+
+interface AforoSubscriptionManagerProps {
+    /** Tenant slug — required. */
+    tenantSlug: string;
+    /** Embed key (Bearer for all backend calls) — required. */
+    embedKey: string;
+    /** Customer bridge token (JWT issued at signup / login). */
+    bridgeToken: string;
+    /** Page size for pagination. Default 10. Server clamps to [1, 50]. */
+    pageSize?: number;
+    /**
+     * Status filter on first render. Default {@code 'all'}. The widget
+     * normalises to uppercase before forwarding to the BFF.
+     */
+    defaultStatus?: SubscriptionStatusFilter;
+    /** Whether to render the status filter chips. Default {@code true}. */
+    showFilters?: boolean;
+    /** BCP-47 locale (e.g. {@code 'en-US'}, {@code 'de-DE'}). Default {@code navigator.language}. */
+    locale?: string;
+    /** Theme cascade overrides (applied via the shell's ThemeReader). */
+    themeOverrides?: ThemeTokenOverrides;
+    /** Dark-mode posture. Default {@code 'auto'}. */
+    theme?: 'light' | 'dark' | 'auto';
+    /** Fires when the "Manage" button is clicked (or row click in some layouts). */
+    onSubscriptionClick?: (sub: SubscriptionPayloadV2) => void;
+    /**
+     * Fires when "Upgrade" / "Update payment" / "Re-subscribe" is clicked.
+     * For PAST_DUE rows, the callback receives a payload with
+     * {@code paymentUpdate: true} signalling the parent should drive the
+     * customer to a payment-update flow (Phase 1 — Prompt 13 wires this to
+     * the AforoPaymentMethod widget).
+     */
+    onUpgradeRequested?: (sub: SubscriptionPayloadV2, paymentUpdate: boolean) => void;
+    /** Fires when "Cancel" is clicked. */
+    onCancelRequested?: (sub: SubscriptionPayloadV2) => void;
+    /** Optional React-side callback fired on any widget error. */
+    onError?: (error: WidgetErrorPayload) => void;
+    /**
+     * INTERNAL — operator Embed Studio preview short-circuit. When provided,
+     * the widget bypasses the AforoSession bridge exchange + the
+     * {@code BridgeClient.fetchSubscriptions} call entirely and renders
+     * directly against this synthetic page. Mirrors the
+     * {@code _mockInvoicePage} / {@code _mockHeadlessConfig} patterns.
+     */
+    _mockSubscriptionPage?: SubscriptionPageResponse | null;
+    /** INTERNAL — short-circuits the in-widget refetch on filter changes for static-preview stories. */
+    _mockStaticPreview?: boolean;
+}
+declare function AforoSubscriptionManager(props: AforoSubscriptionManagerProps): React.ReactElement;
+
+/**
+ * AforoInvoiceList — paginated list of the signed-in customer's invoices.
+ *
+ * Spec: FR-WIDGET-IL-1..7 (Section 3.6) + FR-WIDGET-X-1..11 (Section 3.10).
+ *
+ * v0.4.0 (Prompt 6B — 2026-05-27): real rendering shipped. Replaces the
+ * Prompt 3 placeholder body. Consumes the 3 BFF endpoints shipped in Prompt
+ * 6A (storefront-service commit 41c8177):
+ *
+ * <ul>
+ *   <li>{@code GET  /api/v1/portal/embed/invoices} — paginated list with
+ *       page/size/status/search/sort query params</li>
+ *   <li>{@code GET  /api/v1/portal/embed/invoices/{id}/pdf-url} — short-
+ *       lived download link</li>
+ *   <li>{@code POST /api/v1/portal/embed/invoices/{id}/pay/initiate} —
+ *       Phase 0 stub; replaced in-place by Prompt 7 (CheckoutFlow widget)</li>
+ * </ul>
+ *
+ * <p>Public prop interface evolves from Prompt 3 (which had {@code statusFilter}
+ * uppercase). Following the Prompt 5 precedent ({@code buttonText} →
+ * {@code ctaText}), the prop interface evolves freely in v0.x; the
+ * {@code sdk-contract.test.ts} surface lock only covers runtime exports.
+ * Locked once v1.0 ships.</p>
+ *
+ * <p>The component itself is a thin orchestrator over {@code <WidgetShell>}.
+ * The shell handles session init + theme resolve + event bus + ErrorBoundary,
+ * and exposes everything via {@code useWidgetShell()}. Actual rendering
+ * work lives in {@code <InvoiceListBody>}.</p>
+ */
+
+interface AforoInvoiceListProps {
+    /** Tenant slug — required. */
+    tenantSlug: string;
+    /** Embed key (Bearer for all backend calls) — required. */
+    embedKey: string;
+    /**
+     * Customer bridge token (JWT issued at signup / login).
+     *
+     * Either {@link bridgeToken} OR {@link magicLinkMode} MUST be set — the
+     * invoice list is customer-scoped (anonymous mode unsupported per FR-AUTH-3).
+     * Prompt 9 / FR-AUTH-6 made this prop optional so widgets can fall back
+     * to email-based magic-link auth when the host portal doesn't have a
+     * pre-issued bridge token (marketing site, support portal, pre-integration
+     * self-serve).
+     */
+    bridgeToken?: string;
+    /**
+     * Magic-link auth mode (Prompt 9 / FR-AUTH-6). When {@code true}:
+     * <ul>
+     *   <li>If the URL contains an {@code aforo_magic_token} query param, the
+     *       SDK consumes it on mount, exchanges for a session JWT via the
+     *       backend's verify endpoint, then clears the token from the URL
+     *       (via {@code history.replaceState}).</li>
+     *   <li>Otherwise the widget renders a {@link MagicLinkFallback} form —
+     *       the customer enters their email and Aforo sends them a sign-in
+     *       link.</li>
+     * </ul>
+     *
+     * Mutually exclusive with {@link bridgeToken}; when both are set,
+     * {@link bridgeToken} wins (a host portal that has a real session
+     * shouldn't accidentally fall through to the email prompt).
+     */
+    magicLinkMode?: boolean;
+    /** Page size for pagination. Default 10. Server clamps to [1, 50]. */
+    pageSize?: number;
+    /**
+     * Status filter on first render. Default {@code 'all'}. Lowercase per
+     * the prompt's API; the BFF uppercases on receive.
+     */
+    defaultStatus?: InvoiceStatusFilter;
+    /** Whether to render the search input. Default {@code true}. */
+    showSearch?: boolean;
+    /** Whether to render the status filter chips. Default {@code true}. */
+    showFilters?: boolean;
+    /**
+     * Whether to render the Pay Now button on UNPAID / OVERDUE rows.
+     * Default {@code true}. Phase 0: fires {@code aforo.invoice-list.pay_requested}
+     * postMessage only — customer's parent handles payment via their own flow.
+     * Phase 1 (Prompt 7): wires the embedded CheckoutFlow widget in-place.
+     */
+    showPayNow?: boolean;
+    /** BCP-47 locale (e.g. {@code 'en-US'}, {@code 'de-DE'}). Default {@code navigator.language}. */
+    locale?: string;
+    /** Theme cascade overrides (applied via the shell's ThemeReader). */
+    themeOverrides?: ThemeTokenOverrides;
+    /** Dark-mode posture. Default {@code 'auto'}. */
+    theme?: 'light' | 'dark' | 'auto';
+    /** Fires when a row is clicked (in addition to inline expansion). */
+    onInvoiceClick?: (invoice: InvoicePayload) => void;
+    /** Fires when Pay Now is clicked (Phase 0: customer parent handles payment). */
+    onPayRequested?: (invoice: InvoicePayload) => void;
+    /** Fires when a PDF download is initiated. */
+    onDownload?: (invoice: InvoicePayload, downloadUrl: string) => void;
+    /** Optional React-side callback fired on any widget error. */
+    onError?: (error: WidgetErrorPayload) => void;
+    /**
+     * INTERNAL — operator Embed Studio preview short-circuit. When provided,
+     * the widget bypasses the AforoSession bridge exchange + the
+     * {@code BridgeClient.fetchInvoices} call entirely and renders directly
+     * against this synthetic page. Underscore prefix signals "not for
+     * production app code"; this prop has no impact on customer integrations.
+     * Mirrors AforoPricingCard's {@code _mockHeadlessConfig} +
+     * AforoSubscribeButton's {@code _mockSubscriptionForOffering} patterns.
+     */
+    _mockInvoicePage?: InvoicePageResponse | null;
+    /** INTERNAL — short-circuits the in-widget refetch on filter changes for static-preview stories. */
+    _mockStaticPreview?: boolean;
+}
+declare function AforoInvoiceList(props: AforoInvoiceListProps): React.ReactElement;
+
+/**
+ * AforoUsageMeter — current-period usage vs quota for one or more metrics.
+ *
+ * Spec: FR-WIDGET-UM-1..7 (Section 3.7) + FR-WIDGET-X-1..11 (Section 3.10).
+ *
+ * v0.5.0 (Prompt 12 — 2026-05-29): real rendering shipped. Replaces the
+ * Prompt 3 placeholder body. Consumes the {@code GET /api/v1/portal/embed/subscriptions/{id}/usage}
+ * endpoint added in Prompt 12 (storefront-service Embed BFF).
+ *
+ * <p>SSE-driven refresh ({@code usage.threshold_breached} from Prompt 8) is
+ * deferred — Prompt 8 SSE wiring on {@code AforoSession.subscribe} is still
+ * the Prompt 3 stub. The widget refreshes via configurable polling
+ * (default 60s) and the inbound {@code aforo:usage-refresh-requested}
+ * parent-postMessage signal in the meantime.</p>
+ *
+ * <p>Threshold detection ({@code aforo.usage-meter.threshold_reached}
+ * events at 70/90/100%) is fully client-side — the widget compares the
+ * current vs prior {@code quotaUsedPct} across refreshes and fires the
+ * event the FIRST time each threshold is crossed within the current
+ * mount lifetime. Resets when the metric drops below 70% (next period or
+ * a quota reset).</p>
+ */
+
+interface AforoUsageMeterProps {
+    /** Tenant slug — required. */
+    tenantSlug: string;
+    /** Embed key (Bearer for all backend calls) — required. */
+    embedKey: string;
+    /** Customer bridge token. */
+    bridgeToken: string;
+    /** Subscription id whose usage to display — required. */
+    subscriptionId: string;
+    /**
+     * If provided, the widget filters to just this metric (compact mode).
+     * If omitted, shows all metrics in expanded mode by default.
+     */
+    metricName?: string;
+    /**
+     * Polling interval in ms. Default 60_000. Server-side cache returns
+     * stale values within a 30s bucket so the actual refresh tempo is
+     * closer to 60s no matter what this is set to.
+     */
+    pollIntervalMs?: number;
+    /**
+     * Layout mode:
+     *  - 'compact'  — single metric or first-of-many, hero card
+     *  - 'expanded' — grid of metrics
+     * Default: 'compact' if {@code metricName} provided, else 'expanded'.
+     */
+    mode?: 'compact' | 'expanded';
+    /** BCP-47 locale. Default {@code navigator.language}. */
+    locale?: string;
+    /** Theme cascade overrides. */
+    themeOverrides?: ThemeTokenOverrides;
+    /** Dark-mode posture. Default {@code 'auto'}. */
+    theme?: 'light' | 'dark' | 'auto';
+    /** Fires when a metric is clicked (compact mode click area). */
+    onMetricClick?: (metric: UsageMetricPayload) => void;
+    /** Fires the first time {@code quotaUsedPct} crosses 70%, 90%, or 100%. */
+    onThresholdReached?: (metric: UsageMetricPayload, threshold: UsageThreshold) => void;
+    /** Optional callback fired on any widget error. */
+    onError?: (error: WidgetErrorPayload) => void;
+    /**
+     * INTERNAL — operator Embed Studio preview short-circuit. When provided,
+     * the widget bypasses the AforoSession bridge exchange + the
+     * {@code BridgeClient.fetchUsage} call entirely and renders directly
+     * against this synthetic payload. Mirrors the
+     * {@code _mockSubscriptionPage} pattern.
+     */
+    _mockUsage?: UsageResponse | null;
+}
+declare function AforoUsageMeter(props: AforoUsageMeterProps): React.ReactElement;
+
+/**
+ * AforoPaymentMethod — display + manage the customer's stored payment
+ * methods.
+ *
+ * Spec: FR-WIDGET-PM-1..6 (Section 3.8) + FR-WIDGET-X-1..11 (Section 3.10).
+ *
+ * v1.0.0 (Prompt 15 closure — 2026-05-29): real body shipped. Closes the
+ * gap surfaced during the v1.0.0 production-readiness gauntlet where the
+ * prior tracker entry claimed Prompt 13 shipped this widget but no SDK /
+ * loader / preview code was ever committed.
+ *
+ * <p>Two modes:</p>
+ * <ul>
+ *   <li><b>compact</b> — single card showing the default method (brand +
+ *     last4 + expiry) + an "Update" CTA. Sized for embedding in a sidebar
+ *     or modal.</li>
+ *   <li><b>expanded</b> — full list of stored methods with per-row "Set
+ *     default" and "Remove" actions + an "Add method" CTA at the top.</li>
+ * </ul>
+ *
+ * <p>Provider iframe mount (Stripe Elements / Razorpay Drop-in / PayPal
+ * Smart Buttons) is intentionally deferred to Phase 1. v1.0.0 ships the
+ * event-based flow: clicking "Add" or "Update" fires an
+ * {@code aforo.payment-method.update_requested} event carrying the
+ * SetupIntent client secret so the parent page wires their existing
+ * provider SDK to confirm. This is the honest contract — the SDK doesn't
+ * pretend to mount providers it hasn't shipped support for.</p>
+ *
+ * <p>FR-SEC-23 reminder: the {@code aforo.payment-method.updated} event
+ * fired after the parent's provider SDK confirms is ADVISORY only. The
+ * backend webhook on the provider callback is authoritative. Don't trigger
+ * downstream business actions from this client event.</p>
+ */
+
+interface AforoPaymentMethodProps {
+    /** Tenant slug — required. */
+    tenantSlug: string;
+    /** Embed key (Bearer for all backend calls) — required. */
+    embedKey: string;
+    /** Customer bridge token. */
+    bridgeToken: string;
+    /**
+     * Layout mode. Default 'compact' (shows default method only).
+     * 'expanded' shows the full list with per-row actions.
+     */
+    mode?: 'compact' | 'expanded';
+    /** Theme cascade overrides. */
+    themeOverrides?: ThemeTokenOverrides;
+    /** Dark-mode posture. Default {@code 'auto'}. */
+    theme?: 'light' | 'dark' | 'auto';
+    /** Fires when the customer clicks "Add" or "Update" — carries
+     *  {@code clientSecret} for parent-side provider SDK confirmation. */
+    onUpdateRequested?: (clientSecret: string, provider: string) => void;
+    /** Optional callback fired on any widget error. */
+    onError?: (error: WidgetErrorPayload) => void;
+    /**
+     * INTERNAL — operator Embed Studio preview short-circuit. When
+     * provided, the widget bypasses the bridge exchange + BFF call entirely
+     * and renders directly against this synthetic payload. Mirrors the
+     * {@code _mockUsage} / {@code _mockSubscriptionPage} pattern.
+     */
+    _mockPaymentMethods?: PaymentMethodListResponse | null;
+}
+declare function AforoPaymentMethod(props: AforoPaymentMethodProps): React.ReactElement;
+
+/**
+ * AforoUpgradeCancel — upgrade preview + cancel deflection wizard.
+ *
+ * Spec: FR-WIDGET-UC-1..6 (Section 3.9). Builds on the V50 cancellation
+ * feedback infrastructure shipped 2026-05-09 + the storefront-service
+ * `EmbedSubscriptionLifecycleController` shipped 2026-05-29 (3 BFF
+ * endpoints: preview-change / upgrade / cancel).
+ *
+ * Two modes, gated by the required `mode` prop:
+ *
+ *   mode='upgrade' → 4 steps: plan picker → preview impact → confirm → result
+ *   mode='cancel'  → 3 steps: reason → tailored deflection → confirm → result
+ *
+ * Pattern #18: `BridgeClient.previewSubscriptionChange` returns null on
+ * failure (read path). Mutations (`upgradeSubscription`, `cancelSubscription`)
+ * throw BridgeClientError so the widget can surface inline error banners.
+ *
+ * FR-SEC-23 reminder: postMessage events are advisory only — the customer
+ * backend MUST receive the `subscription.status_changed` webhook as the
+ * authoritative signal. Stamped at the `completed` emission site.
+ */
+
+interface AforoUpgradeCancelProps {
+    tenantSlug: string;
+    embedKey: string;
+    bridgeToken: string;
+    /** Subscription this widget targets. */
+    subscriptionId: string;
+    /** REQUIRED. The Prompt 3 placeholder `'both'` value is removed. */
+    mode: 'upgrade' | 'cancel';
+    /** 'inline' renders the wizard inline; 'modal' (default) renders in a dialog overlay. */
+    renderMode?: 'inline' | 'modal';
+    /** Initial ApplyAt selection for upgrade/cancel confirm steps. */
+    defaultApplyAt?: ApplyAt;
+    /** BCP-47 locale for `Intl.NumberFormat` / `Intl.DateTimeFormat`. */
+    locale?: string;
+    /** Per-widget theme overrides (highest priority in the cascade). */
+    themeOverrides?: ThemeTokenOverrides;
+    /** Fires when the customer completes the flow (upgrade applied or cancel scheduled). */
+    onCompleted?: (result: UpgradeCancelResultPayload) => void;
+    /** Fires when the customer dismisses (Esc / backdrop / accepted deflection). */
+    onCancelled?: () => void;
+    /** Fires on any error (preview / mutation). Mirrors `aforo.upgrade-cancel.error`. */
+    onError?: (error: WidgetErrorPayload) => void;
+    /** Test seam — short-circuits offerings fetch in operator preview. */
+    _mockOfferings?: HeadlessConfigResponse | null;
+}
+declare function AforoUpgradeCancel(props: AforoUpgradeCancelProps): React.ReactElement;
+
+/**
+ * BridgeClient — internal fetch wrapper for the embed plane.
+ *
+ * This is the customer-browser equivalent of `@aforoai/api-client`. It is
+ * NEVER exposed publicly from `src/index.ts` — widgets get a configured
+ * instance via the AforoSession singleton. Customers don't construct one
+ * directly.
+ *
+ * Endpoints touched (storefront-service, shipped in Prompt 1):
+ *   POST /api/v1/portal/embed/bridge/exchange       — bridge JWT → session JWT
+ *   POST /api/v1/portal/embed/bridge/refresh        — session JWT refresh (Prompt 8)
+ *   POST /api/v1/portal/embed/telemetry             — telemetry batch sink
+ *   GET  /api/v1/portal/embed/tenant-config/{slug}  — brand kit (this Prompt)
+ *   GET  /api/v1/portal/embed/health                — public liveness
+ *
+ * Headers:
+ *   Authorization: Bearer <embed_key>     (on every embed-key-gated call)
+ *   X-Embed-Domain: <window.location.origin>  (for the backend Origin guard
+ *      cross-check; this is on top of the browser-sent `Origin` header)
+ *   Idempotency-Key: <UUID v4>             (FR-SEC-19 on mutations)
+ *
+ * Error mapping is structured: callers get typed errors with `status` +
+ * `code` fields so widgets can choose their retry / display behavior. The
+ * Pattern #18 fail-soft posture (return null / safe fallback) applies to
+ * READ paths only; WRITE paths throw so widgets can show "couldn't save…"
+ * banners instead of silently no-op'ing.
+ */
+
+type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+interface BridgeClientOptions {
+    /** Default `https://embed.aforo.ai`. Override for tests / dev. */
+    embedBaseUrl?: string;
+    /** Embed key (Bearer token for all embed-key-gated endpoints). */
+    embedKey: string;
+    /** Tenant slug — included as `X-Embed-Tenant` header for backend audit. */
+    tenantSlug: string;
+    /** Pluggable fetch — defaults to `globalThis.fetch`. Test seam. */
+    fetch?: FetchLike;
+    /** Override timeout. Default 15s per outbound call. */
+    timeoutMs?: number;
+}
+interface BridgeExchangeResponse {
+    sessionJwt: string;
+    expiresAt: number;
+    customerId: string | null;
+}
+declare class BridgeClient {
+    private readonly baseUrl;
+    private readonly embedKey;
+    private readonly tenantSlug;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    static demoModeProvider: DemoModeBridgeProvider | null;
+    /**
+     * Install a demo-mode provider that intercepts every BridgeClient call.
+     * Called once by the sandbox playground at startup. Real consumers
+     * never invoke this — wrapping the static setter in a top-level
+     * function ({@code installDemoModeProvider} from src/index.ts) avoids
+     * exposing BridgeClient itself in the public API.
+     *
+     * Pass {@code null} to clear (used by tests in `afterEach`).
+     */
+    static setDemoModeProvider(provider: DemoModeBridgeProvider | null): void;
+    /** True when a demo-mode provider is currently installed. */
+    static isDemoMode(): boolean;
+    constructor(opts: BridgeClientOptions);
+    private withTimeout;
+    private buildHeaders;
+    private send;
+    private parseError;
+    /** Bridge-token → Aforo session JWT. Always a mutation (idempotency-key). */
+    exchange(bridgeToken: string): Promise<BridgeExchangeResponse>;
+    /**
+     * Tenant brand kit — Pattern #18 fail-soft. Returns `null` on any error so
+     * the ThemeReader can fall through to the neutral default cascade.
+     */
+    getTenantBrandKit(slug?: string): Promise<TenantBrandKit | null>;
+    /**
+     * Headless config — the PricingCard widget's primary read path.
+     *
+     * Mirrors `GET /api/v1/portal/headless/config` which returns
+     * `{branding, offerings, ratePlans, themeTokens, customPages, ...}`
+     * denormalized JSON. The endpoint is 60s Caffeine-cached server-side; we
+     * cache once per widget instance on the client.
+     *
+     * Pattern #18 fail-soft — returns `null` on transport failure, 404, or
+     * malformed JSON. Widgets fall through to their empty / error state and
+     * present a retry button instead of crashing.
+     *
+     * NOTE: this surface is anonymous-mode-safe — the embed key in
+     * Authorization is sufficient; no bridge token required.
+     */
+    fetchHeadlessConfig(slug?: string): Promise<HeadlessConfigResponse | null>;
+    /**
+     * Telemetry sink — never throws; respects FR-OBS-1 fail-soft contract.
+     * Consent gating + sampling is the TelemetryReporter's job, not here.
+     */
+    sendTelemetry(batch: ReadonlyArray<Record<string, unknown>>): Promise<boolean>;
+    /**
+     * Anti-double-subscribe lookup for the AforoSubscribeButton widget.
+     *
+     * <p>Mirrors {@code GET /api/v1/portal/embed/subscriptions/by-offering/{offeringId}}.
+     * Customer is resolved server-side from the session JWT (Pattern #7) — never
+     * from the URL or body. Cross-customer probes return
+     * {@code hasActiveSubscription: false} with the same shape as a legitimate
+     * "not subscribed" response (Pattern #9 — no existence-leak).</p>
+     *
+     * <p>Pattern #18 fail-soft: returns {@code null} on any network /
+     * non-2xx failure so the widget can degrade to a working CTA (better
+     * UX than permanently disabling on a transient outage).</p>
+     *
+     * @param offeringId offering to check
+     * @param sessionJwt customer-session JWT (from {@code AforoSession.getSessionJwt()})
+     * @returns subscription state or {@code null} on failure
+     */
+    fetchSubscriptionForOffering(offeringId: string, sessionJwt: string): Promise<SubscriptionForOfferingResponse | null>;
+    /**
+     * Hosted-checkout initiation for the AforoSubscribeButton widget in
+     * {@code redirect} mode.
+     *
+     * <p>Mirrors {@code POST /api/v1/portal/embed/checkout/initiate}. The
+     * underlying CheckoutSessionService delegates to the existing
+     * V43 hosted-checkout infrastructure — this method is a thin embed-tier
+     * adapter on top.</p>
+     *
+     * <p>Idempotency: the caller-supplied {@code request.idempotencyKey}
+     * becomes the {@code Idempotency-Key} request header per FR-SEC-19.
+     * Same key + same payload → cached response replay (200 OK with prior
+     * body). Same key + different payload → 409 Conflict (the
+     * {@link BridgeClientError} carries the status + 'IDEMPOTENCY_CONFLICT'
+     * code).</p>
+     *
+     * <p>Write path — throws {@link BridgeClientError} on any failure so the
+     * widget can surface an actionable error banner instead of silently
+     * no-op'ing. Pattern #18 fail-soft does NOT apply to mutation paths.</p>
+     *
+     * @param request   offering id + return URL + idempotency key
+     * @param sessionJwt customer-session JWT
+     * @returns checkout URL + session id + expiry the widget redirects to
+     * @throws BridgeClientError on transport / non-2xx / malformed response
+     */
+    initiateCheckout(request: InitiateCheckoutRequest, sessionJwt: string): Promise<InitiateCheckoutResponse>;
+    /**
+     * Paginated invoice list — primary read path for the AforoInvoiceList
+     * widget.
+     *
+     * <p>Mirrors {@code GET /api/v1/portal/embed/invoices} with query
+     * parameters {@code page}, {@code size}, {@code status} (lowercase
+     * filter chip value), {@code search}, {@code sort}. Server-side sort
+     * allowlist is {@code issuedAt,desc|asc} or {@code total,desc|asc};
+     * the widget defaults to {@code issuedAt,desc}.</p>
+     *
+     * <p><b>Pattern #18 fail-soft:</b> returns a safe empty page on any
+     * transport / non-2xx / malformed JSON. The widget treats the empty
+     * page identically to a real "no invoices" response and renders the
+     * empty state with a retry affordance.</p>
+     *
+     * @param filter   page + size + status + search + sort
+     * @param sessionJwt customer-session JWT (from {@code AforoSession.getSessionJwt()})
+     * @returns paginated invoice page (always non-null)
+     */
+    fetchInvoices(filter: InvoiceListFilter, sessionJwt: string): Promise<InvoicePageResponse>;
+    /**
+     * Per-invoice PDF download URL.
+     *
+     * <p>Mirrors {@code GET /api/v1/portal/embed/invoices/{invoiceId}/pdf-url}.
+     * v1 returns a session-authenticated companion-endpoint URL the widget
+     * opens in a new tab. v2 will return a standalone JWS-signed URL —
+     * {@code downloadUrl} consumers (the widget's {@code window.open} call)
+     * don't change.</p>
+     *
+     * <p><b>Pattern #18 fail-soft:</b> returns {@code null} on any failure
+     * so the widget can surface an inline tooltip near the Download button
+     * without exploding. Cross-customer access returns 404 same as
+     * not-found (Pattern #9 existence-leak prevention).</p>
+     */
+    fetchInvoicePdfUrl(invoiceId: string, sessionJwt: string): Promise<InvoicePdfUrlResponse | null>;
+    /**
+     * Pay Now mutation — Phase 0 stub.
+     *
+     * <p>Mirrors {@code POST /api/v1/portal/embed/invoices/{invoiceId}/pay/initiate}.
+     * Caller MUST supply an {@code idempotencyKey} (UUID v4 generated client-
+     * side per CTA click) which becomes the {@code Idempotency-Key} request
+     * header per FR-SEC-19. Same key + same payload → cached replay; same key
+     * + different payload → 409 Conflict (the {@link BridgeClientError}
+     * carries the status + {@code 'IDEMPOTENCY_CONFLICT'} code).</p>
+     *
+     * <p><b>Phase 0 contract:</b> the BFF always returns {@code {supported:
+     * false, reason: 'EMBEDDED_CHECKOUT_NOT_YET_WIRED'}} with HTTP 200. The
+     * widget consumes the response shape (not the {@code supported} flag) so
+     * Prompt 7's drop-in replacement that flips {@code supported} to true and
+     * populates {@code checkoutUrl} doesn't change the call site.</p>
+     *
+     * <p>Write path — throws {@link BridgeClientError} on any failure. Pattern
+     * #18 fail-soft does NOT apply to mutations.</p>
+     *
+     * @param invoiceId     invoice id (path param)
+     * @param request       returnUrl payload
+     * @param idempotencyKey UUID v4 — generated client-side per CTA click
+     * @param sessionJwt    customer-session JWT
+     * @returns Phase 0 stub today ({@code supported: false}); v2 returns checkoutUrl
+     * @throws BridgeClientError on transport / non-2xx / malformed response
+     */
+    initiateInvoicePayment(invoiceId: string, request: InitiateInvoicePaymentRequest, idempotencyKey: string, sessionJwt: string): Promise<InitiateInvoicePaymentResponse>;
+    /**
+     * Create a new checkout cart — primary entry point for the CheckoutFlow
+     * widget. Returns gateway secrets ONCE in the response per FR-SEC-9; the
+     * widget MUST sessionStorage them (subsequent {@link getCart} reads
+     * return null for those fields).
+     *
+     * <p>Cart-type-specific behavior:</p>
+     * <ul>
+     *   <li>{@code SUBSCRIBE} — anti-double-subscribe check fires server-side;
+     *       409 Conflict with {@code code: 'ALREADY_SUBSCRIBED'} when an
+     *       active subscription already exists for this (customer, offering)</li>
+     *   <li>{@code INVOICE_PAYMENT} — already-paid check fires server-side;
+     *       409 Conflict with {@code code: 'INVOICE_ALREADY_PAID'} when the
+     *       invoice is already in PAID status</li>
+     * </ul>
+     *
+     * @param request        cartType + targetId + returnUrl
+     * @param idempotencyKey UUID v4 — generated client-side per CTA click
+     * @param sessionJwt     customer-session JWT
+     * @returns cart with gateway secrets populated ONCE
+     * @throws BridgeClientError on transport / non-2xx / malformed response
+     */
+    createCart(request: CreateCartRequest, idempotencyKey: string, sessionJwt: string): Promise<CheckoutCartResponse>;
+    /**
+     * Read cart state — used by the widget to refresh after async events
+     * (3DS challenge return, parent-side inbound messages). Pattern #18
+     * fail-soft: returns null on any transport / non-2xx failure.
+     *
+     * <p>Gateway secrets are NOT returned on this path (per FR-SEC-9 — only
+     * the cart-create response includes them). Widget reads them from
+     * sessionStorage instead.</p>
+     */
+    getCart(cartId: string, sessionJwt: string): Promise<CheckoutCartResponse | null>;
+    /**
+     * Update billing address + display name (Step 1 → Step 2 transition).
+     * All fields optional — pre-filled / returning customers may skip this
+     * step entirely (widget transitions straight to {@code payment} phase).
+     *
+     * @throws BridgeClientError on transport / non-2xx / malformed response
+     */
+    updateCustomerDetails(cartId: string, request: UpdateCustomerDetailsRequest, idempotencyKey: string, sessionJwt: string): Promise<CheckoutCartResponse>;
+    /**
+     * Record the payment method id captured by the provider iframe
+     * (Step 2 — after tokenization succeeds client-side via Stripe Elements /
+     * Razorpay Drop-in / PayPal Smart Buttons).
+     *
+     * <p><b>Intent-swap defense:</b> the {@code gatewayPaymentIntentId} MUST
+     * match the cart's stored intent id. Backend rejects with 400 if they
+     * differ — defense against an attacker swapping in a different cart's
+     * intent. See Prompt 7A round-2 audit.</p>
+     *
+     * @throws BridgeClientError on transport / non-2xx / 400 intent-swap
+     */
+    initiatePayment(cartId: string, request: InitiateCartPaymentRequest, idempotencyKey: string, sessionJwt: string): Promise<CheckoutCartResponse>;
+    /**
+     * Confirm the cart — atomic provisioning step (creates subscription via
+     * pricing-service for SUBSCRIBE carts; marks invoice paid via billing-service
+     * for INVOICE_PAYMENT carts). Either succeeds end-to-end or rolls back.
+     *
+     * <p>Returns a {@link ConfirmCartResponse} with cart-type-specific fields
+     * populated (subscriptionId for SUBSCRIBE, invoiceId for INVOICE_PAYMENT).
+     * The widget's success screen reads these to render the "Welcome to ..."
+     * affordance.</p>
+     *
+     * <p><b>402 Payment Required</b> indicates the gateway declined the card
+     * or returned a 3DS challenge — the {@link BridgeClientError} carries
+     * status=402 and (parsed by the widget) code in {@code PAYMENT_FAILED}
+     * or {@code REQUIRES_ACTION}.</p>
+     *
+     * @throws BridgeClientError on any failure (mutations never silent-fail)
+     */
+    confirmCart(cartId: string, idempotencyKey: string, sessionJwt: string): Promise<ConfirmCartResponse>;
+    /**
+     * Cancel an in-progress cart. Best-effort gateway cancellation runs
+     * server-side; widget surfaces the cancelled state regardless of upstream
+     * success. 204 No Content on success.
+     *
+     * <p>Cart-already-COMPLETED returns 409 — the widget shouldn't allow
+     * cancel after success, but defense-in-depth.</p>
+     *
+     * @throws BridgeClientError on transport / non-2xx
+     */
+    cancelCart(cartId: string, sessionJwt: string): Promise<void>;
+    /**
+     * Shared parser for the 4 mutation methods that return CartResponse.
+     * Throws BridgeClientError on missing required fields so the widget gets
+     * a clear "upstream malformed" signal rather than crashing on a downstream
+     * undefined access.
+     */
+    private parseCartResponse;
+    /** Public liveness probe. Returns null on failure (not an error). */
+    health(): Promise<{
+        status: string;
+    } | null>;
+    /**
+     * Request a magic-link email. Always resolves with {@code {accepted: true}}
+     * on the wire — anti-enumeration per FR-SEC-21. Pattern #18 fail-soft:
+     * transport failure returns a synthesized {@code {accepted: true}} envelope
+     * so the form UX never surfaces "we couldn't send the email" when the
+     * underlying cause is "you're offline" (which the user already knows).
+     *
+     * Idempotency-Key is auto-generated per call when none is supplied —
+     * matches the rest of the BridgeClient mutation pattern.
+     *
+     * @param request body shape mirroring backend {@code RequestMagicLinkRequest}
+     * @param idempotencyKey caller-supplied UUID v4; auto-generated when absent
+     */
+    requestMagicLink(request: RequestMagicLinkRequest, idempotencyKey?: string): Promise<RequestMagicLinkResponse>;
+    /**
+     * Verify a plaintext magic-link token + mint an Aforo session JWT.
+     *
+     * Mutations propagate errors — this path runs ON the URL-param-consumption
+     * branch of {@code AforoSession.init({magicLinkMode: true})}; widgets need
+     * to know if the verify failed so they can render the sign-in prompt UI.
+     *
+     * @throws BridgeClientError on any non-2xx — typed code surfaces in the
+     *         {@code aforo.session.magic_link_failed} event payload
+     */
+    verifyMagicLink(token: string, externalId?: string): Promise<VerifyMagicLinkResponse>;
+    /**
+     * Paginated subscription list — primary read path for the
+     * AforoSubscriptionManager widget.
+     *
+     * <p>Mirrors {@code GET /api/v1/portal/embed/subscriptions} with query
+     * parameters {@code page}, {@code size}, {@code status} (uppercase filter
+     * chip value), {@code sort}. Server-side sort allowlist defaults to
+     * {@code startedAt,desc}; the widget surfaces the same sort vocabulary.</p>
+     *
+     * <p><b>Pattern #18 fail-soft:</b> returns a safe empty page on any
+     * transport / non-2xx / malformed JSON. The widget treats the empty page
+     * identically to a real "no subscriptions" response and renders the empty
+     * state with a retry affordance.</p>
+     *
+     * @param filter     page + size + status + sort
+     * @param sessionJwt customer-session JWT (from {@code AforoSession.getSessionJwt()})
+     * @returns paginated subscription page (always non-null)
+     */
+    fetchSubscriptions(filter: SubscriptionListFilter, sessionJwt: string): Promise<SubscriptionPageResponse>;
+    /**
+     * Current-period usage projection — primary read path for the
+     * AforoUsageMeter widget.
+     *
+     * <p>Mirrors {@code GET /api/v1/portal/embed/subscriptions/{id}/usage}.
+     * The BFF performs a Pattern #9 ownership check before forwarding to
+     * billing-service; cross-customer probes return 404 same as not-found.</p>
+     *
+     * <p><b>Pattern #18 fail-soft:</b> returns {@code null} on any failure so
+     * the widget can render an inline error banner with retry affordance
+     * without crashing the consumer's React tree. The 404 case (cross-customer
+     * or genuinely not found) also returns null — the widget surfaces this
+     * as "couldn't load usage" since the customer has no actionable distinction
+     * between the two.</p>
+     *
+     * @param subscriptionId subscription id (path param)
+     * @param sessionJwt     customer-session JWT
+     * @returns usage payload or null on failure
+     */
+    fetchUsage(subscriptionId: string, sessionJwt: string): Promise<UsageResponse | null>;
+    /**
+     * Preview the prorated impact of switching to {@code targetOfferingId}.
+     *
+     * <p>Pattern #18 fail-soft — returns {@code null} on transport / non-2xx
+     * (including 400 NO_CHANGE) / malformed JSON. The widget renders an
+     * inline error with a Retry button when null and never blocks Back
+     * navigation. NO Idempotency-Key on the wire (this is a read).</p>
+     */
+    previewSubscriptionChange(subscriptionId: string, request: PreviewChangeRequest, sessionJwt: string): Promise<PreviewChangeResponse | null>;
+    /**
+     * Apply an upgrade or downgrade. Mutation path — throws
+     * {@link BridgeClientError} on transport / non-2xx / malformed JSON.
+     *
+     * <p>Idempotency: caller passes UUID v4 {@code idempotencyKey}. Same
+     * key + same body → cached 200 replay; same key + different body →
+     * 409 IDEMPOTENCY_CONFLICT (the error carries the typed code).</p>
+     */
+    upgradeSubscription(subscriptionId: string, request: UpgradeRequest, idempotencyKey: string, sessionJwt: string): Promise<UpgradeResponse>;
+    /**
+     * Cancel a subscription with V50 feedback payload. Mutation path —
+     * throws {@link BridgeClientError} on transport / non-2xx / malformed
+     * JSON.
+     *
+     * <p>The backend maps the widget's {@code retentionOutcome} values onto
+     * V50 audit categories; the widget sends the values defined in
+     * {@link RetentionOutcome} verbatim.</p>
+     */
+    cancelSubscription(subscriptionId: string, request: CancelWithFeedbackRequest, idempotencyKey: string, sessionJwt: string): Promise<CancelResponse>;
+    fetchPaymentMethods(sessionJwt: string): Promise<PaymentMethodListResponse>;
+    createPaymentMethodSetupIntent(sessionJwt: string, idempotencyKey: string): Promise<SetupIntentResponse | null>;
+    setDefaultPaymentMethod(methodId: string, sessionJwt: string): Promise<void>;
+    deletePaymentMethod(methodId: string, sessionJwt: string): Promise<void>;
+}
+
+/**
+ * AforoSession — singleton holding the Aforo session JWT in memory.
+ *
+ * Per §17.16 (Concurrent Widgets — Shared Auth State):
+ *   - First widget to mount triggers bridge-exchange
+ *   - Subsequent widgets reuse the cached session JWT
+ *   - Refresh happens once (~5 min before exp), broadcast to all subscribers
+ *   - Logout clears + fires `aforo.session.cleared`
+ *
+ * Storage: in-memory ONLY (FR-AUTH-11). Never localStorage / cookies. Page
+ * refresh deliberately drops the session — customer's frontend re-runs the
+ * bridge-token flow.
+ *
+ * Multi-tenant: keyed by `tenantSlug` so an agency portal embedding multiple
+ * customers' billing dashboards in the same browser doesn't conflate auth.
+ *
+ * The shared SSE connection (FR-PUSH-3) is stubbed here: `subscribe()`
+ * records the handler in an internal map and returns an unsubscribe fn.
+ * The real EventSource wiring lands in Prompt 8 — this prompt focuses on
+ * the connection-management API contract so widgets can be coded against it
+ * today without rewriting once SSE arrives.
+ */
+
+type RefreshCallback = (state: SessionState) => void;
+type SseHandler = (event: {
+    type: string;
+    data: unknown;
+}) => void;
+/** Public singleton API. */
+declare const AforoSession: {
+    /**
+     * Initialise (or reuse) the session for a tenant. Idempotent — calling
+     * twice with the same `tenantSlug` returns the existing entry instead of
+     * re-running bridge exchange (React Strict Mode safety).
+     *
+     * Does NOT block on bridge exchange — kicks it off in the background.
+     * Callers wanting the JWT in hand should `await getSessionJwt()`.
+     */
+    init(config: SessionConfig): SessionState;
+    /**
+     * Returns the cached JWT — fetching one via bridge exchange if missing
+     * or expired. Concurrent callers share the single in-flight promise.
+     * Returns `null` for anonymous mode (no bridgeToken configured).
+     */
+    getSessionJwt(tenantSlug: string): Promise<string | null>;
+    /** Subscribe to refresh / clear events. Returns an unsubscribe fn. */
+    onSessionRefreshed(tenantSlug: string, cb: RefreshCallback): () => void;
+    /** Snapshot the current state. Useful for tests + debugging. */
+    getState(tenantSlug: string): SessionState | null;
+    /**
+     * Public accessor for the per-tenant BridgeClient. Widgets that need to
+     * hit embed-key-gated endpoints (e.g. PricingCard fetching headless
+     * config) consume this. Returns `null` if `init()` hasn't been called
+     * for the tenant yet — callers should treat that the same as "not
+     * available; surface error state".
+     *
+     * The BridgeClient instance is shared across all widgets on the same
+     * tenant (per §17.16 concurrent-widget contract).
+     */
+    getBridgeClient(tenantSlug: string): BridgeClient | null;
+    /**
+     * Subscribe to a push-event type (FR-PUSH-2). v1: stub — records the
+     * handler; the real SSE connection lands in Prompt 8 and will fan
+     * events out via this same handler registry.
+     */
+    subscribe(tenantSlug: string, eventType: string, handler: SseHandler): () => void;
+    /** Logout: clear in-memory state and fire `aforo.session.cleared`. */
+    logout(tenantSlug: string): void;
+    /**
+     * Full teardown — clears timers, handlers, removes the entry. Useful for
+     * tests + multi-tenant agency portals tearing down per-tenant scopes.
+     */
+    destroy(tenantSlug: string): void;
+    /**
+     * Internal: dispatch an SSE event to subscribers. Called by Prompt 8's
+     * SSE wiring; exposed here so tests can drive it without spinning up
+     * EventSource. Not part of the public surface; not exported from
+     * `src/index.ts`.
+     */
+    _dispatch(tenantSlug: string, event: {
+        type: string;
+        data: unknown;
+    }): number;
+    /**
+     * Programmatic magic-link request. Resolves with {@code {accepted: true}}
+     * on success, transport failure, AND server rate-limit (anti-enumeration).
+     * Only 400 / 409 errors throw — those are developer-side mistakes
+     * (invalid returnUrl, Idempotency-Key collision) that the form must
+     * surface so the developer can fix them.
+     *
+     * Emits {@code aforo.session.magic_link_requested} before the fetch so
+     * parent pages can update progress UI; emits no failure event on the
+     * silent-200 path (per FR-SEC-21 — silent at the wire is silent in the
+     * event stream too).
+     *
+     * @param tenantSlug per-tenant session lookup
+     * @param email recipient email (validated server-side)
+     * @param options.externalId optional binding for the resolved customer id
+     * @param options.returnUrl defaults to {@code window.location.href}
+     */
+    requestMagicLink(tenantSlug: string, email: string, options?: {
+        externalId?: string;
+        returnUrl?: string;
+    }): Promise<{
+        accepted: boolean;
+    }>;
+    /**
+     * Direct magic-link verify. Most consumers use the
+     * {@code init({magicLinkMode: true})} URL-param branch instead — this
+     * method is exposed for (a) tests, (b) future widgets that want to
+     * accept a token from a parent-supplied source instead of the URL.
+     *
+     * Emits {@code aforo.session.magic_link_verified} on success +
+     * {@code aforo.session.magic_link_failed} on any failure.
+     *
+     * @throws BridgeClientError on verify failure (mapped to typed code)
+     */
+    verifyMagicLink(tenantSlug: string, token: string, externalId?: string): Promise<SessionState>;
+    /** Test seam: clear ALL session state. */
+    _resetForTesting(): void;
+    /** Test seam: list active tenant slugs. */
+    _listTenantsForTesting(): string[];
+};
+
+declare function installDemoModeProvider(provider: DemoModeBridgeProvider | null): void;
+
+/**
+ * MagicLinkFallback — shared form rendered by widgets when the customer
+ * needs to authenticate via email magic link instead of a host-portal
+ * bridge token.
+ *
+ * Prompt 9 / FR-AUTH-6 (2026-05-29).
+ *
+ * <p>First non-widget component in the {@code @aforoai/storefront-widgets}
+ * public surface. Widgets that support magic-link mode (Prompt 9: InvoiceList;
+ * later prompts: SubscribeButton, CheckoutFlow) mount this when they detect
+ * "no session JWT + magicLinkMode=true + no URL-param token to consume".</p>
+ *
+ * <h2>UX contract</h2>
+ * <ul>
+ *   <li>Single email input + submit button.</li>
+ *   <li>Submit → fires {@link AforoSession.requestMagicLink} → success
+ *       message ("check your inbox") regardless of whether the email
+ *       actually exists (anti-enumeration per FR-SEC-21).</li>
+ *   <li>Only developer-side errors (returnUrl rejection 400 / Idempotency
+ *       collision 409) surface as inline error banners.</li>
+ *   <li>Theme cascade applied via {@code data-aforo-magic-link-fallback}
+ *       CSS vars so customer-side theming can recolor without prop drilling.</li>
+ *   <li>{@code prefers-reduced-motion} honoured on the loading spinner.</li>
+ *   <li>Aria roles: form has {@code aria-label}, status message
+ *       {@code role="status"} aria-live polite, error message
+ *       {@code role="alert"}.</li>
+ * </ul>
+ *
+ * <h2>Component contract</h2>
+ * <p>Stateless from the parent's perspective — internal state machine
+ * tracks idle / submitting / success / error transitions. Parent supplies:</p>
+ * <ul>
+ *   <li>{@link AforoSession} already initialised for the tenant (the widget
+ *       wrapper takes care of this before mounting the fallback).</li>
+ *   <li>{@code widgetDisplayName} for the header copy
+ *       (e.g. "your invoices" → "Sign in to view your invoices").</li>
+ *   <li>Optional {@code externalId} — forwarded to the request body when the
+ *       host portal already knows the customer's external id.</li>
+ *   <li>Optional {@code onLinkSent} callback — fires after a successful
+ *       request (parent can update its own UI / log analytics).</li>
+ * </ul>
+ */
+
+interface MagicLinkFallbackProps {
+    /** Tenant slug (same as the widget's). */
+    tenantSlug: string;
+    /**
+     * Human-readable phrase for the header copy. Examples:
+     *   "your invoices"     → "Sign in to view your invoices"
+     *   "your subscription" → "Sign in to manage your subscription"
+     */
+    widgetDisplayName: string;
+    /**
+     * Optional binding for the resolved customer id. When the host portal
+     * already knows the external id (e.g. it's in the URL or session
+     * storage), pass it here so the verify path can resolve the Aforo
+     * customer immediately.
+     */
+    externalId?: string;
+    /**
+     * Optional {@code returnUrl} override. Defaults to
+     * {@code window.location.href}.
+     */
+    returnUrl?: string;
+    /** Fires after a successful submit. Parent can log / update UI. */
+    onLinkSent?: (maskedEmail: string) => void;
+    /**
+     * Override the submit button label. Default
+     * {@code "Send sign-in link"}.
+     */
+    submitLabel?: string;
+}
+declare function MagicLinkFallback(props: MagicLinkFallbackProps): React.ReactElement;
+
+declare const VERSION: string;
+
+export { AforoCheckoutFlow, type AforoCheckoutFlowProps, AforoInvoiceList, type AforoInvoiceListProps, AforoPaymentMethod, type AforoPaymentMethodProps, AforoPricingCard, type AforoPricingCardProps, AforoSession, AforoSubscribeButton, type AforoSubscribeButtonProps, AforoSubscriptionManager, type AforoSubscriptionManagerProps, AforoUpgradeCancel, type AforoUpgradeCancelProps, AforoUsageMeter, type AforoUsageMeterProps, ApplyAt, CancelResponse, CancelWithFeedbackRequest, CheckoutCancelledPayload, CheckoutCartResponse, CheckoutCartType, CheckoutConfirmedPayload, ConfirmCartResponse, CreateCartRequest, DemoModeBridgeProvider, HeadlessConfigResponse, InitiateCartPaymentRequest, InitiateCheckoutRequest, InitiateCheckoutResponse, InitiateInvoicePaymentRequest, InitiateInvoicePaymentResponse, InvoiceListFilter, InvoicePageResponse, InvoicePayload, InvoicePdfUrlResponse, InvoiceStatusFilter, MagicLinkFallback, type MagicLinkFallbackProps, OfferingPayload, PreviewChangeRequest, PreviewChangeResponse, RequestMagicLinkRequest, RequestMagicLinkResponse, SessionConfig, SessionState, SubscriptionForOfferingResponse, SubscriptionListFilter, SubscriptionPageResponse, SubscriptionPayload, SubscriptionPayloadV2, SubscriptionStatusFilter, TenantBrandKit, ThemeTokenOverrides, UpdateCustomerDetailsRequest, UpgradeCancelResultPayload, UpgradeRequest, UpgradeResponse, UsageMetricPayload, UsageResponse, UsageThreshold, VERSION, VerifyMagicLinkResponse, WidgetErrorPayload, installDemoModeProvider };