@aforoai/storefront-widgets 1.0.1

package/dist/types-Dm6cp_Cc.d.cts

@@ -0,0 +1,1185 @@
+/**
+ * Local types used internally by the storefront-widgets SDK. Most public
+ * types come from `@aforoai/types/embed-studio` (e.g. EmbedKey,
+ * EmbedKeyEnvironment) — anything customer-facing belongs there.
+ *
+ * Types in this file MAY be re-exported from `src/index.ts` if they form
+ * part of the locked public surface; check `tests/sdk-contract.test.ts`.
+ */
+/** Canonical 8 widget ids served by Prompts 4–7. */
+type WidgetId = 'pricing-card' | 'subscribe-button' | 'checkout-flow' | 'subscription-manager' | 'invoice-list' | 'usage-meter' | 'payment-method' | 'upgrade-cancel';
+/** Event payload envelope. `version` allows non-breaking evolution. */
+interface AforoEventPayload<T = unknown> {
+    type: string;
+    payload: T;
+    version: '1';
+    /**
+     * Optional widget id the event originated from. Set automatically by
+     * widget components; not required for parent-to-widget messages.
+     */
+    source?: WidgetId;
+    /**
+     * Optional monotonic id for diagnostics. Auto-stamped by EventBus.
+     */
+    emittedAt?: number;
+}
+/** Known event types (extended in Prompts 4-7 as widgets ship). */
+type AforoEventType = `aforo.${WidgetId}.ready` | `aforo.${WidgetId}.error` | 'aforo.session.refreshed' | 'aforo.session.cleared' | 'aforo.session.magic_link_requested' | 'aforo.session.magic_link_verified' | 'aforo.session.magic_link_failed' | 'aforo.theme.changed' | 'aforo.subscribe-button.ready' | 'aforo.subscribe-button.disabled' | 'aforo.subscribe.checkout_requested' | 'aforo.subscription.created' | 'aforo.subscribe.error' | 'aforo.invoice-list.invoice.downloaded' | 'aforo.invoice-list.pay_requested' | 'aforo.invoice-list.invoice.expanded' | 'aforo.invoice-list.filter_changed' | 'aforo.invoice-list.search_changed' | 'aforo.invoice-list.invoice.paid' | 'aforo.checkout-flow.step_changed' | 'aforo.checkout-flow.customer_details_submitted' | 'aforo.checkout-flow.payment_initiated' | 'aforo.checkout-flow.payment_completed' | 'aforo.checkout-flow.confirmed' | 'aforo.checkout-flow.cancelled' | 'aforo.checkout-flow.expired' | 'aforo.subscription-manager.subscription.clicked' | 'aforo.subscription-manager.upgrade_requested' | 'aforo.subscription-manager.cancel_requested' | 'aforo.subscription-manager.filter_changed' | 'aforo.usage-meter.metric_clicked' | 'aforo.usage-meter.threshold_reached' | 'aforo.upgrade-cancel.step_changed' | 'aforo.upgrade-cancel.preview_fetched' | 'aforo.upgrade-cancel.deflection_offer_shown' | 'aforo.upgrade-cancel.deflection_offer_accepted' | 'aforo.upgrade-cancel.completed' | 'aforo.upgrade-cancel.abandoned' | 'aforo.payment-method.update_requested' | 'aforo.payment-method.method_set_default' | 'aforo.payment-method.method_removed' | 'aforo.payment-method.updated' | string;
+/** Theme tokens read by widgets. */
+interface ThemeTokens {
+    primary: string;
+    primaryContrast: string;
+    text: string;
+    textMuted: string;
+    bg: string;
+    border: string;
+    radius: string;
+    fontFamily: string;
+    /** Source tier — useful for debugging which layer of the cascade applied. */
+    source: 'css-variables' | 'brand-kit' | 'neutral-default' | 'overrides';
+}
+interface ThemeTokenOverrides {
+    primary?: string;
+    primaryContrast?: string;
+    text?: string;
+    textMuted?: string;
+    bg?: string;
+    border?: string;
+    radius?: string;
+    fontFamily?: string;
+}
+interface SessionConfig {
+    tenantSlug: string;
+    embedKey: string;
+    /** Pre-issued customer bridge token (JWT). Optional for anonymous. */
+    bridgeToken?: string;
+    /**
+     * Magic-link auth mode (Prompt 9 / FR-AUTH-6). When `true`, the session
+     * lazy-initialises by consuming an {@code aforo_magic_token} URL param on
+     * mount. Mutually exclusive with {@link bridgeToken} — when both are set,
+     * {@link bridgeToken} wins (anonymous host portals + magic-link callers
+     * naturally only ever set one).
+     */
+    magicLinkMode?: boolean;
+    /** Override the default `https://embed.aforo.ai` origin. Tests + dev. */
+    apiBaseUrl?: string;
+    /** Override embed-key authenticated endpoint base. */
+    embedBaseUrl?: string;
+}
+/**
+ * Body for {@code AforoSession.requestMagicLink} / {@code BridgeClient.requestMagicLink}.
+ * Mirrors the storefront-service {@code RequestMagicLinkRequest} DTO.
+ */
+interface RequestMagicLinkRequest {
+    email: string;
+    externalId?: string;
+    returnUrl: string;
+}
+/** Always {@code {accepted: true}} on the wire — anti-enumeration. */
+interface RequestMagicLinkResponse {
+    accepted: boolean;
+}
+/**
+ * Success envelope from {@code POST /api/v1/portal/embed/auth/magic-link/verify}.
+ * Mirrors the storefront-service {@code VerifyMagicLinkResponse} DTO.
+ */
+interface VerifyMagicLinkResponse {
+    sessionJwt: string;
+    expiresIn: number;
+    customerId: string;
+}
+/**
+ * Typed error code emitted via {@code aforo.session.magic_link_failed}.
+ * {@code INVALID_OR_EXPIRED} maps to the backend's generic 401 envelope
+ * (anti-enumeration: not-found / consumed / expired all collapse). Network
+ * failures and configuration gaps surface as distinct codes so widgets can
+ * branch on retry-ability.
+ */
+type MagicLinkFailureCode = 'INVALID_OR_EXPIRED' | 'NO_CUSTOMER_FOR_EMAIL' | 'NETWORK_ERROR' | 'CONFIG_MISSING';
+interface SessionState {
+    sessionJwt: string | null;
+    expiresAt: number | null;
+    tenantSlug: string;
+    customerId: string | null;
+}
+interface WidgetMountConfig {
+    widget: WidgetId;
+    tenantSlug: string;
+    embedKey: string;
+    bridgeToken?: string;
+    layout?: string;
+    themeOverrides?: ThemeTokenOverrides;
+    /**
+     * Additional widget-specific config — passed as a Record so each widget
+     * shell can validate its own subset.
+     */
+    config?: Record<string, unknown>;
+}
+interface TenantBrandKit {
+    primaryColor?: string | null;
+    secondaryColor?: string | null;
+    logoUrl?: string | null;
+    fontFamily?: string | null;
+}
+/** Inferred consent posture. Set via parent `aforo:consent-state` message. */
+interface ConsentState {
+    telemetry: boolean;
+    marketing: boolean;
+}
+/** A single feature row inside a plan card. */
+interface FeaturePayload {
+    /** Stable id — used as React key when rendering. */
+    id?: string;
+    /** Visible label. */
+    label: string;
+    /** Optional cell value for the comparison-table layout (e.g. "Unlimited"). */
+    value?: string;
+    /** Truthy → row renders ✓ ; falsy → row renders × (table layout). */
+    included?: boolean;
+    /** Optional explanation surfaced via `title` attribute / aria-describedby. */
+    description?: string;
+}
+/** Per-tier pricing breakpoint (for graduated/tiered models — display only). */
+interface RatePlanPayload {
+    ratePlanId: string;
+    /** Display unit, e.g. "API call", "GB-hour". */
+    unitLabel?: string;
+    /** Free quota included before per-unit pricing kicks in. */
+    includedUnits?: number | null;
+    /** Per-unit price in minor units (cents/paise). */
+    perUnitPriceCents?: number | null;
+    /** Tiered model identifier — operator-set, surfaced to telemetry. */
+    pricingModel?: string;
+}
+/** A single offering as rendered in the pricing card. */
+interface OfferingPayload {
+    offeringId: string;
+    /** Human-visible name (e.g. "Pro", "Enterprise"). */
+    name: string;
+    /** Optional localized name override (FR-WIDGET-PC-9). */
+    localizedDisplayName?: string;
+    /** Optional short subtitle. */
+    description?: string;
+    /** Optional localized description override (FR-WIDGET-PC-9). */
+    localizedDescription?: string;
+    /** ISO 4217 currency code, e.g. "USD". */
+    currency: string;
+    /** Subscription price in MINOR units (cents/paise). NaN/undefined → "Contact us". */
+    priceCents: number | null | undefined;
+    /** Billing period — `monthly` / `annual` / `one_time` / `custom`. */
+    billingCycle: string;
+    /** Free-form CTA label (e.g. "Start trial"). Operator may override per-offering. */
+    ctaText?: string;
+    /** Optional CTA url override (FR-WIDGET-PC-7). When unset the widget's ctaUrl prop wins. */
+    ctaUrl?: string;
+    /** Featured plan flag (FR-WIDGET-PC-8). */
+    featured?: boolean;
+    /** Render order — ascending. Stable per FR-WIDGET-PC-1. */
+    displayOrder?: number;
+    /** Plan status — only PUBLISHED offerings render. */
+    status?: 'DRAFT' | 'PUBLISHED' | 'ARCHIVED' | string;
+    /** Features list rendered inside the card. */
+    features?: FeaturePayload[];
+    /** Optional bound rate plan(s) — surfaced in the cta_clicked event payload. */
+    ratePlans?: RatePlanPayload[];
+    /** Primary rate plan id for telemetry + the cta_clicked envelope. */
+    primaryRatePlanId?: string;
+    /** Free-form metadata bag — kept opaque, surfaced verbatim in events. */
+    metadata?: Record<string, unknown>;
+}
+/** Branding block in the headless config (intersects TenantBrandKit). */
+interface HeadlessBrandingPayload {
+    primaryColor?: string | null;
+    secondaryColor?: string | null;
+    logoUrl?: string | null;
+    fontFamily?: string | null;
+    /** Optional contact for the "Contact sales" fallback CTA. */
+    contactSalesEmail?: string | null;
+}
+/** Top-level shape returned by `GET /api/v1/portal/headless/config`. */
+interface HeadlessConfigResponse {
+    /** Tenant slug echo. */
+    tenantSlug?: string;
+    /** Display name (rendered in operator-empty-state copy). */
+    tenantName?: string | null;
+    branding?: HeadlessBrandingPayload | null;
+    /** Ordered list of PUBLISHED offerings. */
+    offerings?: OfferingPayload[];
+    /** Locale hint from operator config — widget's prop still wins. */
+    defaultLocale?: string | null;
+    /**
+     * 2026-06-01 — Tenant-wide defaults for embeddable widgets, authored in
+     * the admin `EmbeddableWidgetTab`. Read by widgets at mount time as
+     * fallback defaults; the customer's mount config (`<script>` data-*
+     * attributes) still wins on a per-widget basis.
+     *
+     * Field shape mirrors `EmbeddableWidgetConfig` in `@aforoai/types`. Kept
+     * loose here (`Record<string, unknown>`) so the SDK doesn't have a hard
+     * compile dependency on the admin types — widgets pick the fields they
+     * recognise and ignore the rest.
+     */
+    embeddableWidget?: EmbeddableWidgetDefaults | null;
+    /**
+     * 2026-06-01 — Up to 5 tenant-authored page-context-scoped CSS files.
+     * The storefont-ui's `<PageScopedStylesheets>` injector consumes these
+     * from `publishedConfig.customStylesheets`; we re-expose them here so
+     * headless third-party storefronts can replicate the same cascade in
+     * their own builds.
+     */
+    customStylesheets?: HeadlessCustomStylesheet[] | null;
+}
+/**
+ * Subset of {@link EmbeddableWidgetConfig} (in `@aforoai/types`) the SDK
+ * recognises. Loose typing — extra fields are dropped, missing fields fall
+ * back to widget-level defaults.
+ */
+interface EmbeddableWidgetDefaults {
+    layout?: 'horizontal' | 'vertical' | string;
+    theme?: 'light' | 'dark' | 'auto' | string;
+    ctaText?: string;
+    showFeatures?: boolean;
+    maxPlans?: number;
+    borderRadius?: number;
+}
+/** Page-context-scoped CSS stylesheet emitted by the headless config endpoint. */
+interface HeadlessCustomStylesheet {
+    id: string;
+    name: string;
+    description?: string;
+    css: string;
+    enabled: boolean;
+    sortOrder?: number;
+    pageContext?: 'LANDING' | 'PRICING' | 'DOCS' | 'CATALOG' | 'PORTAL' | 'ALL' | string;
+}
+/**
+ * Live-subscription status set the BFF reports back to the widget for
+ * anti-double-subscribe decisions. Mirrors backend pricing-service
+ * SubscriptionStatus enum (subset shown — only states that gate a
+ * re-subscribe attempt).
+ */
+type LiveSubscriptionStatus = 'ACTIVE' | 'TRIALING' | 'PAST_DUE' | 'EXPIRING_SOON';
+/**
+ * Response shape for {@code GET /api/v1/portal/embed/subscriptions/by-offering/{offeringId}}.
+ *
+ * <p>{@code subscriptionId} + {@code status} are omitted when
+ * {@code hasActiveSubscription=false} — same shape as a legitimate "not
+ * subscribed" response, no existence-leak via differential field presence
+ * (Pattern #9).</p>
+ */
+interface SubscriptionForOfferingResponse {
+    hasActiveSubscription: boolean;
+    subscriptionId?: string;
+    status?: LiveSubscriptionStatus | string;
+}
+/**
+ * Request body for {@code POST /api/v1/portal/embed/checkout/initiate}.
+ *
+ * <p>Idempotency contract per FR-SEC-19: callers MUST supply a UUID v4 (or
+ * other RFC 4122 shape) in {@code idempotencyKey}; same key + same payload
+ * → cached response replay, same key + different payload → 409 Conflict.</p>
+ */
+interface InitiateCheckoutRequest {
+    offeringId: string;
+    /** UUID v4 — generated client-side per CTA click. */
+    idempotencyKey: string;
+    /**
+     * Where hosted checkout returns the customer to on success. Validated
+     * server-side against the embed key's {@code allowed_domains} list — host
+     * outside the allowlist returns 400 (defense vs. open-redirect).
+     */
+    returnUrl: string;
+    /** Optional coupon code applied to the underlying checkout session. */
+    couponCode?: string;
+    /**
+     * Mode advisory — v1 always produces a real checkoutUrl; the
+     * {@code embedded-flow} mode is reserved for Prompt 7 (CheckoutFlow widget).
+     */
+    mode?: 'redirect' | 'event-only' | 'embedded-flow';
+}
+/** Response shape for {@code POST /api/v1/portal/embed/checkout/initiate}. */
+interface InitiateCheckoutResponse {
+    checkoutUrl: string;
+    checkoutSessionId: string;
+    expiresAt: string;
+}
+/**
+ * Payload for the {@code aforo.subscription.created} outbound event +
+ * the {@code onSubscribed} React callback. Backend webhook is the
+ * authoritative source for subscription state; this event is advisory.
+ */
+interface SubscriptionPayload {
+    subscriptionId: string;
+    offeringId: string;
+    /** Optional plan name for display. */
+    planName?: string;
+    /** ISO-4217 currency code echoed from offering. */
+    currency?: string;
+    /** Price in MINOR units (cents/paise) at the time of subscription. */
+    priceCents?: number | null;
+    /** Billing period at time of subscription. */
+    billingCycle?: string;
+    /** Status returned by the BFF after checkout-complete signal. */
+    status?: LiveSubscriptionStatus | string;
+    /** Server-side timestamp the subscription was created (ISO-8601). */
+    createdAt?: string;
+}
+/**
+ * Payload for the {@code aforo.subscribe.error} (and other widget error)
+ * events + the {@code onError} React callback. Surfaced when a fetch /
+ * checkout-initiate fails or when an inbound checkout-completed event
+ * carries an error state.
+ */
+interface WidgetErrorPayload {
+    /** Stable machine-readable code (e.g. SESSION_EXPIRED, NETWORK_ERROR). */
+    code: string;
+    /** Human-readable message — suitable for surfacing in UI banners. */
+    message: string;
+    /** HTTP status when the error originated from a network call. */
+    status?: number;
+    /** Whether the operation is safe to retry (e.g. transient 5xx / timeout). */
+    retryable?: boolean;
+    /** Optional widget id for cross-event correlation. */
+    widget?: WidgetId;
+}
+/**
+ * Customer-facing status vocabulary for the AforoInvoiceList widget. The
+ * upstream {@code Invoice.status} enum (DRAFT/PENDING/OPEN/PAID/OVERDUE/
+ * CANCELLED/VOID/UNCOLLECTIBLE) is normalised to this 4-state set at the
+ * BFF slimming boundary — DRAFT invoices are filtered out, and
+ * CANCELLED/UNCOLLECTIBLE/VOID collapse to {@code VOID}.
+ */
+type InvoiceStatus = 'UNPAID' | 'PAID' | 'OVERDUE' | 'VOID';
+/**
+ * Filter chip value for the widget UI + {@code status} query param sent to
+ * the BFF. Lowercase per the prompt's API (the BFF uppercases on receive).
+ */
+type InvoiceStatusFilter = 'all' | 'unpaid' | 'paid' | 'overdue' | 'void';
+/**
+ * Invoice type — STANDARD invoices are the common case; AMENDMENT renders
+ * a small "Amendment" badge per the B2 2026-05-09 ship parity. The widget
+ * doesn't distinguish AMENDMENT vs AMENDMENT_CREDIT visually beyond the
+ * badge — both are post-creation adjustments.
+ */
+type InvoiceTypeKind = 'STANDARD' | 'AMENDMENT' | 'AMENDMENT_CREDIT';
+/**
+ * Per-row invoice payload — mirrors
+ * {@code com.aforo.billing.storefront.embed.dto.EmbedInvoiceResponse}
+ * field-for-field. {@code BigDecimal} amounts are serialised by Jackson
+ * as JSON numbers (Spring's default {@code JsonNumber} mapping); we type
+ * them as {@code number | string} so a future serialiser switch (e.g. to
+ * {@code String} for arbitrary precision) doesn't break the widget.
+ *
+ * <p>NaN-defensive formatting: {@code total}, {@code amountPaid}, and
+ * {@code amountDue} render as {@code '—'} when null / undefined / non-
+ * finite per FR-WIDGET-X-9.</p>
+ */
+interface InvoicePayload {
+    id: string;
+    invoiceNumber: string;
+    /**
+     * Customer-facing status (UNPAID / PAID / OVERDUE / VOID). DRAFT
+     * invoices are filtered server-side; widget never sees them.
+     */
+    status: InvoiceStatus | string;
+    invoiceType?: InvoiceTypeKind | string;
+    issuedAt?: string | null;
+    dueAt?: string | null;
+    billingPeriodStart?: string | null;
+    billingPeriodEnd?: string | null;
+    total?: number | string | null;
+    amountPaid?: number | string | null;
+    amountDue?: number | string | null;
+    currency?: string | null;
+    lineItemCount?: number | null;
+    /**
+     * Server-derived overdue flag. Widget UI prefers this over re-computing
+     * from {@code dueAt} so all widget instances on a page agree regardless
+     * of client clock drift.
+     */
+    isOverdue?: boolean;
+    /**
+     * Days from now until {@code dueAt} — negative when overdue. Null when
+     * {@code dueAt} is missing.
+     */
+    daysUntilDue?: number | null;
+}
+/** Paginated envelope returned by {@code GET /api/v1/portal/embed/invoices}. */
+interface InvoicePageResponse {
+    content: InvoicePayload[];
+    totalElements: number;
+    totalPages: number;
+    page: number;
+    size: number;
+}
+/**
+ * Filter query for {@code BridgeClient.fetchInvoices}. The widget builds
+ * one of these on every fetch, and a stable JSON encoding of it is the
+ * cache key (so refetching the same page is a noop).
+ */
+interface InvoiceListFilter {
+    page: number;
+    size: number;
+    /** {@code 'all'} → unspecified (BFF ignores the param entirely). */
+    status?: InvoiceStatusFilter;
+    /** Substring match against {@code invoice_number}. Max 200 chars (BFF clamps). */
+    search?: string;
+    /**
+     * Server-side sort. v1 widget UI doesn't expose this (defaults to
+     * {@code issuedAt,desc}); kept on the API for forward-compat with
+     * sortable-column work (Phase 1 follow-up).
+     */
+    sort?: string;
+}
+/** Response shape for {@code GET /api/v1/portal/embed/invoices/{id}/pdf-url}. */
+interface InvoicePdfUrlResponse {
+    /**
+     * Absolute URL pointing at the session-authenticated companion endpoint
+     * (v1) or the standalone signed URL (v2). Widget opens in a new tab via
+     * {@code window.open(url, '_blank', 'noopener,noreferrer')}.
+     */
+    downloadUrl: string;
+    /** ISO-8601 timestamp the widget should consider {@code downloadUrl} stale. */
+    expiresAt: string;
+    fileName: string;
+    /** Always null in v1 (upstream doesn't emit Content-Length yet). */
+    sizeBytes?: number | null;
+}
+/**
+ * Request body for {@code POST /api/v1/portal/embed/invoices/{id}/pay/initiate}.
+ *
+ * <p>Idempotency-Key is sent as an HTTP header (FR-SEC-19), NOT in the body —
+ * mirrors the EmbedCheckoutController convention. The widget generates a
+ * UUID v4 on every CTA click.</p>
+ */
+interface InitiateInvoicePaymentRequest {
+    returnUrl: string;
+}
+/**
+ * Response shape for {@code POST /api/v1/portal/embed/invoices/{id}/pay/initiate}.
+ *
+ * <p><b>Phase 0 stub (Prompt 6A, 2026-05-27):</b> the BFF always returns
+ * {@code {supported: false, reason: 'EMBEDDED_CHECKOUT_NOT_YET_WIRED'}} with
+ * HTTP 200. Prompt 7 (CheckoutFlow widget) drop-in replaces the response
+ * to populate {@code checkoutUrl} / {@code checkoutSessionId} /
+ * {@code expiresAt} — the type stays the same so the widget's call site
+ * doesn't change.</p>
+ */
+interface InitiateInvoicePaymentResponse {
+    supported: boolean;
+    reason?: string;
+    /** Populated when Prompt 7 ships the real CheckoutFlow integration. */
+    checkoutUrl?: string;
+    checkoutSessionId?: string;
+    expiresAt?: string;
+}
+/**
+ * Payload for the {@code aforo.invoice-list.invoice.downloaded} outbound
+ * event + the {@code onDownload} React callback (when the widget's
+ * downloaded action fires).
+ */
+interface InvoiceDownloadedPayload {
+    invoiceId: string;
+    invoiceNumber: string;
+    fileName: string;
+    sizeBytes?: number | null;
+}
+/**
+ * Payload for the {@code aforo.invoice-list.pay_requested} outbound event +
+ * the {@code onPayRequested} React callback. Phase 0: customer's parent
+ * page handles payment in its own flow. Phase 1 (Prompt 7): the embedded
+ * CheckoutFlow widget consumes this signal in-place.
+ */
+interface InvoicePayRequestedPayload {
+    invoiceId: string;
+    invoiceNumber: string;
+    total: number | string | null;
+    currency: string | null;
+    status: string;
+    dueAt: string | null;
+    returnUrl: string;
+}
+/** Payload for the informational {@code aforo.invoice-list.filter_changed} event. */
+interface InvoiceFilterChangedPayload {
+    status: InvoiceStatusFilter;
+}
+/** Payload for the informational {@code aforo.invoice-list.search_changed} event. */
+interface InvoiceSearchChangedPayload {
+    /** Empty string when the search was cleared. */
+    query: string;
+}
+/** Payload for the informational {@code aforo.invoice-list.invoice.expanded} event. */
+interface InvoiceExpandedPayload {
+    invoiceId: string;
+    invoiceNumber: string;
+    expanded: boolean;
+}
+/**
+ * Payload for the {@code aforo.invoice-list.invoice.paid} outbound event.
+ * Fires when the parent posts inbound {@code aforo:invoice-paid} OR when
+ * Prompt 7's CheckoutFlow signals a successful invoice payment. Backend
+ * webhook is still authoritative per FR-SEC-23.
+ */
+interface InvoicePaidPayload {
+    invoiceId: string;
+    invoiceNumber?: string;
+}
+/** Cart type — SUBSCRIBE creates a new subscription; INVOICE_PAYMENT pays an existing invoice. */
+type CheckoutCartType = 'SUBSCRIBE' | 'INVOICE_PAYMENT';
+/** Backend cart status — must stay in lock-step with `EmbedCheckoutCartStatus.java`. */
+type CheckoutCartStatus = 'CREATED' | 'CUSTOMER_DETAILS' | 'PAYMENT_REDIRECTED' | 'COMPLETED' | 'EXPIRED' | 'CANCELLED';
+/**
+ * Client-side phase — combines backend status with UI-layer states. The
+ * widget renders different content per phase:
+ *
+ * - `bootstrapping` — bridge-token → session-JWT exchange + cart create
+ *   (loading skeleton, role=status)
+ * - `customer-details` — Step 1 form (name + email + billing address)
+ * - `payment` — Step 2 payment-provider iframe
+ * - `confirming` — Step 3 confirm + provisioning spinner
+ * - `completed` — Step 4 success screen
+ * - `cancelled` / `expired` / `error` — terminal/recoverable states
+ */
+type CheckoutFlowPhase = 'bootstrapping' | 'customer-details' | 'payment' | 'confirming' | 'completed' | 'cancelled' | 'expired' | 'error';
+/** Payment provider — drives which iframe contract the widget renders. */
+type CheckoutPaymentProvider = 'stripe' | 'razorpay' | 'paypal';
+/**
+ * Billing address — captured at the customer-details step. All fields
+ * optional per backend `UpdateCartCustomerDetailsRequest.BillingAddress`.
+ */
+interface CheckoutBillingAddress {
+    line1?: string;
+    line2?: string;
+    city?: string;
+    state?: string;
+    postalCode?: string;
+    /** ISO 3166-1 alpha-2 — e.g. "US", "DE". 2 chars max. */
+    country?: string;
+}
+/**
+ * Request body for {@code POST /api/v1/portal/embed/checkout/cart}.
+ *
+ * <p>Idempotency-Key header carries the per-click UUID v4; not part of the
+ * body. Cart-create is the only POST that doesn't take an explicit
+ * idempotencyKey field — the {@code BridgeClient.createCart} method accepts
+ * one as a separate parameter, mirroring the {@code initiateInvoicePayment}
+ * call shape from Prompt 6B.</p>
+ */
+interface CreateCartRequest {
+    cartType: CheckoutCartType;
+    /** Offering id when cartType=SUBSCRIBE; invoice id when cartType=INVOICE_PAYMENT. */
+    targetId: string;
+    /**
+     * Where to return the customer if the payment flow leaves the iframe
+     * (PayPal redirect, 3DS challenges in a new tab). Validated server-side
+     * against the embed key's allowed_domains list.
+     */
+    returnUrl: string;
+}
+/**
+ * Request body for {@code PATCH /api/v1/portal/embed/checkout/cart/{cartId}/customer-details}.
+ * Both fields optional — widget pre-fills + skips for returning customers.
+ */
+interface UpdateCustomerDetailsRequest {
+    billingAddress?: CheckoutBillingAddress;
+    displayName?: string;
+}
+/**
+ * Request body for {@code POST /api/v1/portal/embed/checkout/cart/{cartId}/initiate-payment}.
+ *
+ * <p>Called AFTER the customer enters card details in the provider iframe.
+ * The {@code gatewayPaymentIntentId} MUST match the cart's stored intent
+ * id (defense against intent-swap attacks per Prompt 7A round-2 audit).</p>
+ */
+interface InitiateCartPaymentRequest {
+    gatewayPaymentMethodId: string;
+    gatewayPaymentIntentId: string;
+}
+/**
+ * Response shape for {@code POST /cart}, {@code GET /cart/{id}}, and
+ * {@code PATCH /cart/{id}/customer-details}.
+ *
+ * <p>Gateway secrets ({@code gatewayClientSecret}, {@code gatewayOrderId},
+ * {@code gatewayApprovalUrl}, {@code gatewaySandboxMode}) are populated
+ * ONLY on the cart-create response per FR-SEC-9. Subsequent GET / PATCH
+ * reads return null for those fields — widget MUST sessionStorage them.</p>
+ */
+interface CheckoutCartResponse {
+    cartId: string;
+    cartType: CheckoutCartType;
+    targetId: string;
+    status: CheckoutCartStatus;
+    totalCents: number;
+    currency: string;
+    gatewayProvider?: CheckoutPaymentProvider | string | null;
+    /** Stripe — null on read after create. */
+    gatewayClientSecret?: string | null;
+    /** Razorpay / hosted — null on read after create. */
+    gatewayOrderId?: string | null;
+    /** PayPal redirect URL — null on read after create. */
+    gatewayApprovalUrl?: string | null;
+    /** PayPal — true when test creds, null for others. */
+    gatewaySandboxMode?: boolean | null;
+    /** Populated when status=COMPLETED + cartType=SUBSCRIBE. */
+    subscriptionId?: string | null;
+    /** Populated when status=COMPLETED + cartType=INVOICE_PAYMENT. */
+    invoiceId?: string | null;
+    /** ISO-8601 — widget shows countdown when within last 5 min. */
+    expiresAt: string;
+    completedAt?: string | null;
+}
+/**
+ * Response shape for {@code POST /cart/{cartId}/confirm}.
+ *
+ * <p>SUBSCRIBE-variant populates {@code subscriptionId} + {@code subscriptionStatus};
+ * INVOICE_PAYMENT-variant populates {@code invoiceId} + {@code invoiceStatus}.</p>
+ *
+ * <p><b>FR-SEC-23 reminder:</b> these fields are returned synchronously for
+ * widget UX but the authoritative state comes via Kafka webhook events.</p>
+ */
+interface ConfirmCartResponse {
+    cartId: string;
+    status: CheckoutCartStatus;
+    subscriptionId?: string | null;
+    subscriptionStatus?: string | null;
+    invoiceId?: string | null;
+    invoiceStatus?: string | null;
+    completedAt?: string | null;
+}
+/**
+ * Typed error envelope from the embed checkout endpoints — mirrors backend
+ * {@code CartErrorResponse} record. Surfaces 402 Payment Required (declined
+ * cards, 3DS challenges) + 409 Conflict (already-subscribed, invoice-already-paid,
+ * cart-state-invalid).
+ *
+ * <p>Codes the widget UI branches on:</p>
+ * <ul>
+ *   <li>{@code PAYMENT_FAILED} — show error + retry affordance</li>
+ *   <li>{@code REQUIRES_ACTION} — open {@code nextActionUrl} in popup; listen
+ *       for {@code aforo:payment-challenge-completed} inbound event</li>
+ *   <li>{@code ALREADY_SUBSCRIBED} — show "Already subscribed" with link to
+ *       {@code existingSubscriptionId} subscription</li>
+ *   <li>{@code INVOICE_ALREADY_PAID} — show "Invoice already paid" + dismiss</li>
+ *   <li>{@code CART_STATE_INVALID} — cart not in expected state for transition</li>
+ * </ul>
+ */
+interface CheckoutCartErrorResponse {
+    code: string;
+    message: string;
+    requiresAction?: boolean;
+    nextActionUrl?: string | null;
+    gatewayCode?: string | null;
+    existingSubscriptionId?: string | null;
+}
+/**
+ * Payload for {@code aforo.checkout-flow.step_changed} outbound event.
+ * Fires whenever the widget's phase changes (e.g. customer-details → payment).
+ */
+interface CheckoutStepChangedPayload {
+    from: CheckoutFlowPhase;
+    to: CheckoutFlowPhase;
+    cartId: string;
+    cartType: CheckoutCartType;
+}
+/**
+ * Payload for {@code aforo.checkout-flow.customer_details_submitted} event.
+ * Fires after a successful PATCH /customer-details — does NOT include the
+ * raw billing address (PII), only the fields that were populated.
+ */
+interface CheckoutCustomerDetailsSubmittedPayload {
+    cartId: string;
+    /** True when the customer supplied a non-empty billing address (any field). */
+    billingAddressProvided: boolean;
+    /** True when displayName was supplied. */
+    displayNameProvided: boolean;
+}
+/**
+ * Payload for {@code aforo.checkout-flow.payment_initiated} event. Fires
+ * AFTER /initiate-payment returns 200 — i.e. payment method id is captured
+ * but the cart is not yet confirmed (still in PAYMENT_REDIRECTED state).
+ */
+interface CheckoutPaymentInitiatedPayload {
+    cartId: string;
+    cartType: CheckoutCartType;
+    /** Provider that owned the tokenization step. */
+    gatewayProvider: CheckoutPaymentProvider | string;
+}
+/**
+ * Payload for {@code aforo.checkout-flow.payment_completed} event. Fires
+ * AFTER the gateway tokenization succeeds AND the cart is confirmed —
+ * the customer's payment has cleared.
+ */
+interface CheckoutPaymentCompletedPayload {
+    cartId: string;
+    cartType: CheckoutCartType;
+    gatewayProvider: CheckoutPaymentProvider | string;
+}
+/**
+ * Payload for {@code aforo.checkout-flow.confirmed} event. Fires at the
+ * same moment as the SUBSCRIBE-variant aforo.subscription.created OR the
+ * INVOICE_PAYMENT-variant aforo.invoice-list.invoice.paid event, but
+ * carries the unified shape regardless of cart type.
+ */
+interface CheckoutConfirmedPayload {
+    cartId: string;
+    cartType: CheckoutCartType;
+    /** Populated for SUBSCRIBE carts. */
+    subscriptionId?: string | null;
+    /** Populated for INVOICE_PAYMENT carts. */
+    invoiceId?: string | null;
+}
+/**
+ * Payload for {@code aforo.checkout-flow.cancelled} event. Fires when the
+ * customer dismisses the flow OR the parent posts {@code aforo:checkout-flow-dismissed}.
+ */
+interface CheckoutCancelledPayload {
+    cartId: string;
+    cartType: CheckoutCartType;
+    /** UI vs. parent-driven dismissal. */
+    source: 'customer' | 'parent';
+}
+/**
+ * Payload for {@code aforo.checkout-flow.expired} event. Fires when the
+ * cart's {@code expiresAt} window elapses while the widget is still
+ * mounted in a non-terminal phase.
+ */
+interface CheckoutExpiredPayload {
+    cartId: string;
+    cartType: CheckoutCartType;
+    expiresAt: string;
+}
+/**
+ * Customer-facing subscription status vocabulary. Mirrors backend
+ * {@code SubscriptionStatus} enum minus operator-internal states.
+ *
+ * <p>Status meanings:</p>
+ * <ul>
+ *   <li>{@code ACTIVE} — billing normally</li>
+ *   <li>{@code TRIALING} — in trial period</li>
+ *   <li>{@code PAST_DUE} — payment failed, dunning in progress</li>
+ *   <li>{@code PAUSED} — customer-initiated pause</li>
+ *   <li>{@code EXPIRING_SOON} — auto-renew off, within 30 days of expiry</li>
+ *   <li>{@code EXPIRED} — past renewal date, no auto-renew</li>
+ *   <li>{@code CANCELLED} — customer cancelled (terminal)</li>
+ *   <li>{@code SUSPENDED} — operator suspended (terminal-ish)</li>
+ * </ul>
+ */
+type SubscriptionStatus = 'ACTIVE' | 'TRIALING' | 'PAST_DUE' | 'PAUSED' | 'EXPIRING_SOON' | 'EXPIRED' | 'CANCELLED' | 'SUSPENDED';
+/**
+ * Filter chip value for the SubscriptionManager widget UI + {@code status}
+ * query param sent to the BFF. Lowercase per the prompt's API; the BFF
+ * uppercases on receive.
+ */
+type SubscriptionStatusFilter = 'all' | 'ACTIVE' | 'TRIALING' | 'PAST_DUE' | 'PAUSED' | 'EXPIRING_SOON' | 'EXPIRED' | 'CANCELLED' | 'SUSPENDED';
+/**
+ * Per-row subscription payload — mirrors {@code EmbedSubscriptionResponse}
+ * field-for-field. {@code BigDecimal} amounts are serialised by Jackson as
+ * JSON numbers; we type them as {@code number | string} so a future
+ * serializer switch (e.g. to {@code String} for arbitrary precision) doesn't
+ * break the widget.
+ *
+ * <p>NaN-defensive formatting: {@code mrr}, {@code nextInvoiceAmount} render
+ * as {@code '—'} when null / undefined / non-finite per FR-WIDGET-X-9.</p>
+ */
+interface SubscriptionPayloadV2 {
+    id: string;
+    planName: string;
+    offeringId: string;
+    status: SubscriptionStatus | string;
+    startedAt?: string | null;
+    currentPeriodStart?: string | null;
+    currentPeriodEnd?: string | null;
+    renewsAt?: string | null;
+    mrr?: number | string | null;
+    currency?: string | null;
+    nextInvoiceAmount?: number | string | null;
+    trialEndsAt?: string | null;
+    isExpiringSoon?: boolean;
+    daysUntilRenewal?: number | null;
+}
+/** Paginated envelope returned by {@code GET /api/v1/portal/embed/subscriptions}. */
+interface SubscriptionPageResponse {
+    content: SubscriptionPayloadV2[];
+    totalElements: number;
+    totalPages: number;
+    page: number;
+    size: number;
+}
+/**
+ * Filter query for {@code BridgeClient.fetchSubscriptions}. The widget builds
+ * one of these on every fetch; the BFF receives it via query params.
+ */
+interface SubscriptionListFilter {
+    page: number;
+    size: number;
+    /** {@code 'all'} → unspecified (BFF ignores the param entirely). */
+    status?: SubscriptionStatusFilter;
+    /**
+     * Server-side sort. Default {@code startedAt,desc}; allowed values
+     * {@code startedAt,desc/asc}, {@code renewsAt,asc/desc}, {@code mrr,desc/asc}
+     * (mrr falls back to default at pricing-service today — Phase 1 follow-up).
+     */
+    sort?: string;
+}
+/**
+ * Per-metric usage row — mirrors {@code EmbedUsageMetricResponse}.
+ *
+ * <p>{@code quotaLimit=0} signals an unlimited / no-quota metric (e.g.
+ * PERCENTAGE / FLAT_RATE pricing) — the widget renders "Unlimited" in that
+ * case. {@code quotaUsedPct=0.0} with {@code quotaLimit=0} is consistent
+ * (no limit known → no pct).</p>
+ *
+ * <p>{@code isApproximated=true} for TIERED / VOLUME / STAIRCASE /
+ * INCLUDED_QUOTA pricing models — the widget renders a ⚠ icon next to the
+ * metric name with a tooltip explaining the upper-bound approximation.</p>
+ */
+interface UsageMetricPayload {
+    metricName: string;
+    displayName?: string;
+    quotaLimit: number;
+    quotaUsed: number;
+    quotaUsedPct: number;
+    unit?: string | null;
+    pricingModel?: string | null;
+    isApproximated: boolean;
+    projectedEndOfPeriod?: number | null;
+    currency?: string | null;
+    estimatedSpend?: number | string | null;
+}
+/**
+ * Current-period usage payload — mirrors {@code EmbedUsageResponse}.
+ *
+ * <p>{@code periodProgress} is server-computed (0.0 - 1.0) for clock-drift
+ * resistance — the widget renders the progress bar at this width directly
+ * rather than recomputing client-side.</p>
+ *
+ * <p>{@code approximationNote} is non-null when ANY metric in {@code metrics}
+ * has {@code isApproximated=true} — the widget renders it as a single
+ * envelope-level banner instead of per-metric duplication.</p>
+ */
+interface UsageResponse {
+    subscriptionId: string;
+    periodStart?: string | null;
+    periodEnd?: string | null;
+    periodProgress: number;
+    metrics: UsageMetricPayload[];
+    totalEstimatedSpend?: number | string | null;
+    approximationNote?: string | null;
+    computedAt?: string | null;
+}
+/** Payload for the {@code aforo.subscription-manager.subscription.clicked} event. */
+interface SubscriptionClickedPayload {
+    subscriptionId: string;
+    offeringId: string;
+    planName: string;
+    status: string;
+}
+/** Payload for the {@code aforo.subscription-manager.upgrade_requested} event. */
+interface SubscriptionUpgradeRequestedPayload {
+    subscriptionId: string;
+    offeringId: string;
+    planName: string;
+    status: string;
+    /**
+     * When {@code true}, the parent should drive the customer to a payment-
+     * update flow rather than an upgrade flow. Fired when the customer
+     * clicks "Update payment" on a PAST_DUE row.
+     */
+    paymentUpdate?: boolean;
+}
+/** Payload for the {@code aforo.subscription-manager.cancel_requested} event. */
+interface SubscriptionCancelRequestedPayload {
+    subscriptionId: string;
+    offeringId: string;
+    planName: string;
+    status: string;
+}
+/** Payload for the {@code aforo.subscription-manager.filter_changed} event. */
+interface SubscriptionFilterChangedPayload {
+    status: SubscriptionStatusFilter;
+}
+/** Payload for the {@code aforo.usage-meter.metric_clicked} event (compact mode). */
+interface UsageMetricClickedPayload {
+    subscriptionId: string;
+    metricName: string;
+    quotaUsed: number;
+    quotaLimit: number;
+    quotaUsedPct: number;
+}
+/**
+ * Threshold values the {@code aforo.usage-meter.threshold_reached} event
+ * fires at. Crossings detected client-side by comparing current vs prior
+ * {@code quotaUsedPct}.
+ */
+type UsageThreshold = 70 | 90 | 100;
+/** Payload for the {@code aforo.usage-meter.threshold_reached} event. */
+interface UsageThresholdReachedPayload {
+    subscriptionId: string;
+    metricName: string;
+    quotaUsed: number;
+    quotaLimit: number;
+    quotaUsedPct: number;
+    threshold: UsageThreshold;
+    /** When non-null, the projected end-of-period quantity at the time of crossing. */
+    projectedEndOfPeriod?: number | null;
+}
+/** When the change applies. UPGRADE forces IMMEDIATE; DOWNGRADE/CANCEL default PERIOD_END. */
+type ApplyAt = 'IMMEDIATE' | 'PERIOD_END';
+/** Direction of the requested subscription change. Derived server-side from price comparison. */
+type SubscriptionChangeType = 'UPGRADE' | 'DOWNGRADE' | 'LATERAL';
+/** Compact offering summary used by the upgrade preview "from/to" comparison cards. */
+interface OfferingSummary {
+    id: string;
+    name: string;
+    priceCents: number;
+    currency: string;
+}
+/** Request body for {@code POST /preview-change}. NO Idempotency-Key (read). */
+interface PreviewChangeRequest {
+    targetOfferingId: string;
+    applyAt: ApplyAt;
+}
+/**
+ * Response body for {@code POST /preview-change}. Pattern #18 fail-soft:
+ * {@code BridgeClient.previewSubscriptionChange} returns {@code null} on
+ * transport / non-2xx / malformed JSON so the widget can render an inline
+ * error + retry without blocking Back navigation.
+ *
+ * Amounts are in MINOR units (cents). Net positive → customer charged today;
+ * net negative → customer credited; zero → "No charge today".
+ */
+interface PreviewChangeResponse {
+    currentOffering: OfferingSummary;
+    targetOffering: OfferingSummary;
+    changeType: SubscriptionChangeType;
+    applyAt: ApplyAt;
+    /** Credit for the unused portion of the current period (positive value). */
+    creditCents: number;
+    /** Prorated charge for the target plan (positive value). */
+    debitCents: number;
+    /** debitCents - creditCents. Positive = customer pays today; negative = customer credited. */
+    netCents: number;
+    currency: string;
+    /** Fraction of the period remaining at change-effective time, 0..1. */
+    prorationFactor: number;
+    /** ISO-8601 timestamp of the current period end. */
+    currentPeriodEnd: string;
+    /** Backend-generated plain-English summary suitable for Step 3 confirm. */
+    summary: string;
+    /** Caveats list rendered as footnote (e.g. "Discount expires at next renewal"). */
+    caveats: string[];
+}
+/** Request body for {@code POST /upgrade}. Idempotency-Key REQUIRED on header. */
+interface UpgradeRequest {
+    targetOfferingId: string;
+    applyAt: ApplyAt;
+}
+/**
+ * Response body for {@code POST /upgrade}. Mutation path — throws
+ * {@link BridgeClientError} on failure.
+ *
+ * - {@code status=ACTIVE} + {@code appliedAt} set when IMMEDIATE succeeded.
+ * - {@code status=ACTIVE_PENDING_CHANGE} + {@code scheduledFor} set when PERIOD_END.
+ * - {@code invoiceId} present on net-positive upgrades; {@code creditNoteId} on net-negative downgrades.
+ */
+interface UpgradeResponse {
+    subscriptionId: string;
+    previousOfferingId: string;
+    newOfferingId: string;
+    status: 'ACTIVE' | 'ACTIVE_PENDING_CHANGE';
+    /** ISO-8601 timestamp when an IMMEDIATE change applied, else null. */
+    appliedAt: string | null;
+    /** ISO-8601 timestamp when a PERIOD_END change will apply, else null. */
+    scheduledFor: string | null;
+    /** Invoice produced by an IMMEDIATE upgrade with net-positive charge. */
+    invoiceId: string | null;
+    /** Credit note produced by an IMMEDIATE downgrade with net-negative refund. */
+    creditNoteId: string | null;
+}
+/** 6 canonical cancel reason categories surfaced as Step 1 radio options. */
+type CancelReason = 'TOO_EXPENSIVE' | 'NOT_USING_ENOUGH' | 'MISSING_FEATURE' | 'TECHNICAL_ISSUES' | 'SWITCHED_TO_COMPETITOR' | 'OTHER';
+/** Which deflection offer the widget surfaced at Step 2. Captured for V50 audit. */
+type RetentionOfferShown = 'DISCOUNT_20_PCT' | 'PAUSE_3_MONTHS' | 'DOWNGRADE' | 'NONE';
+/**
+ * What the customer did with the offer. Backend maps the widget's
+ * {@code CANCELLED_ANYWAY} + {@code ACCEPTED_OFFER} to V50's
+ * {@code DECLINED_OFFERS} — this is a BFF detail, the widget sends the values
+ * below verbatim.
+ */
+type RetentionOutcome = 'NONE' | 'DECLINED_OFFERS' | 'CANCELLED_ANYWAY' | 'NO_OFFER_PRESENTED' | 'ACCEPTED_OFFER';
+/** Request body for {@code POST /cancel}. Idempotency-Key REQUIRED on header. */
+interface CancelWithFeedbackRequest {
+    applyAt: ApplyAt;
+    reason: CancelReason;
+    /** Free-form additional context, capped at 1000 chars client-side; backend caps at 64. */
+    reasonDetail?: string;
+    retentionOfferShown: RetentionOfferShown;
+    retentionOutcome: RetentionOutcome;
+}
+/**
+ * Response body for {@code POST /cancel}. Mutation path — throws
+ * {@link BridgeClientError} on failure.
+ *
+ * - {@code status=CANCELLED} + {@code cancelledAt} set when IMMEDIATE succeeded.
+ * - {@code status=ACTIVE_PENDING_CANCEL} + {@code effectiveAt} ≈ current period end when PERIOD_END.
+ * - {@code creditNoteId} present on IMMEDIATE cancellations with prorated refund.
+ */
+interface CancelResponse {
+    subscriptionId: string;
+    status: 'CANCELLED' | 'ACTIVE_PENDING_CANCEL';
+    /** ISO-8601 timestamp when IMMEDIATE cancel applied, else null. */
+    cancelledAt: string | null;
+    /** ISO-8601 timestamp the cancellation takes/took effect (today for IMMEDIATE, period end for PERIOD_END). */
+    effectiveAt: string;
+    /** V50 feedback row id — useful for audit cross-reference. */
+    feedbackId: string;
+    /** Credit note produced by an IMMEDIATE cancel with prorated refund. */
+    creditNoteId: string | null;
+}
+/** Convenience union emitted as the {@code onCompleted} callback argument. */
+interface UpgradeCancelResultPayload {
+    mode: 'upgrade' | 'cancel';
+    upgrade?: UpgradeResponse;
+    cancel?: CancelResponse;
+}
+/** Payload for {@code aforo.upgrade-cancel.step_changed}. Non-PII. */
+interface UpgradeCancelStepChangedPayload {
+    from: number;
+    to: number;
+    mode: 'upgrade' | 'cancel';
+}
+/**
+ * Payload for {@code aforo.upgrade-cancel.preview_fetched}. Non-PII —
+ * carries the change shape but never the actual amounts (parent pages
+ * shouldn't observe per-customer pricing from event traffic).
+ */
+interface UpgradeCancelPreviewFetchedPayload {
+    changeType: SubscriptionChangeType;
+    applyAt: ApplyAt;
+    /** True when the preview returned a non-zero net charge. */
+    hasNet: boolean;
+}
+/** Payload for {@code aforo.upgrade-cancel.deflection_offer_shown}. */
+interface UpgradeCancelDeflectionOfferShownPayload {
+    reason: CancelReason;
+    offer: RetentionOfferShown;
+}
+/** Payload for {@code aforo.upgrade-cancel.deflection_offer_accepted}. */
+interface UpgradeCancelDeflectionOfferAcceptedPayload {
+    reason: CancelReason;
+    offer: RetentionOfferShown;
+}
+/**
+ * Payload for {@code aforo.upgrade-cancel.completed}. Non-PII — carries
+ * mode + status + presence flags only, never invoice/credit-note ids.
+ *
+ * FR-SEC-23 reminder: this event is INFORMATIONAL. The customer backend
+ * MUST receive the {@code subscription.status_changed} webhook as the
+ * authoritative signal. postMessage events are advisory only.
+ */
+interface UpgradeCancelCompletedPayload {
+    mode: 'upgrade' | 'cancel';
+    status: string;
+    hasInvoice: boolean;
+    hasCreditNote: boolean;
+}
+/** Payload for {@code aforo.upgrade-cancel.abandoned}. */
+interface UpgradeCancelAbandonedPayload {
+    step: number;
+    mode: 'upgrade' | 'cancel';
+}
+/**
+ * Interface every public method of the real BridgeClient mirrors by name.
+ * The sandbox package implements this against client-side mock fixtures;
+ * tests can install a recording stub. All methods MUST be async.
+ *
+ * Read methods that today return null on miss preserve that contract
+ * (Pattern #18). Write methods that today throw on failure also throw
+ * here when the demo provider chooses to surface an error.
+ */
+interface DemoModeBridgeProvider {
+    exchange(bridgeToken: string): Promise<{
+        sessionJwt: string;
+        expiresAt: number;
+        customerId: string | null;
+    }>;
+    getTenantBrandKit(slug?: string): Promise<TenantBrandKit | null>;
+    fetchHeadlessConfig(slug?: string): Promise<HeadlessConfigResponse | null>;
+    sendTelemetry(batch: ReadonlyArray<Record<string, unknown>>): Promise<boolean>;
+    fetchSubscriptionForOffering(offeringId: string, sessionJwt: string): Promise<SubscriptionForOfferingResponse | null>;
+    initiateCheckout(request: InitiateCheckoutRequest, sessionJwt: string): Promise<InitiateCheckoutResponse>;
+    fetchInvoices(filter: InvoiceListFilter, sessionJwt: string): Promise<InvoicePageResponse>;
+    fetchInvoicePdfUrl(invoiceId: string, sessionJwt: string): Promise<InvoicePdfUrlResponse | null>;
+    initiateInvoicePayment(invoiceId: string, request: InitiateInvoicePaymentRequest, idempotencyKey: string, sessionJwt: string): Promise<InitiateInvoicePaymentResponse>;
+    createCart(request: CreateCartRequest, idempotencyKey: string, sessionJwt: string): Promise<CheckoutCartResponse>;
+    getCart(cartId: string, sessionJwt: string): Promise<CheckoutCartResponse | null>;
+    updateCustomerDetails(cartId: string, request: UpdateCustomerDetailsRequest, idempotencyKey: string, sessionJwt: string): Promise<CheckoutCartResponse>;
+    initiatePayment(cartId: string, request: InitiateCartPaymentRequest, idempotencyKey: string, sessionJwt: string): Promise<CheckoutCartResponse>;
+    confirmCart(cartId: string, idempotencyKey: string, sessionJwt: string): Promise<ConfirmCartResponse>;
+    cancelCart(cartId: string, sessionJwt: string): Promise<void>;
+    health(): Promise<{
+        status: string;
+    } | null>;
+    requestMagicLink(req: RequestMagicLinkRequest, idempotencyKey?: string): Promise<RequestMagicLinkResponse>;
+    verifyMagicLink(token: string, externalId?: string): Promise<VerifyMagicLinkResponse>;
+    fetchSubscriptions(filter: SubscriptionListFilter, sessionJwt: string): Promise<SubscriptionPageResponse>;
+    fetchUsage(subscriptionId: string, sessionJwt: string): Promise<UsageResponse | null>;
+    previewSubscriptionChange(subscriptionId: string, request: PreviewChangeRequest, sessionJwt: string): Promise<PreviewChangeResponse | null>;
+    upgradeSubscription(subscriptionId: string, request: UpgradeRequest, idempotencyKey: string, sessionJwt: string): Promise<UpgradeResponse>;
+    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>;
+}
+/** Brand identifier — common card networks + ACH/SEPA shapes. Open string
+ * so future providers (e.g. UPI / iDEAL) extend without an SDK bump. */
+type PaymentMethodBrand = "visa" | "mastercard" | "amex" | "discover" | "diners" | "jcb" | "unionpay" | "unknown" | string;
+/** Type — `card` is v1 baseline. `us_bank_account` / `sepa_debit` flow
+ * through the same provider-iframe pattern in Phase 1. */
+type PaymentMethodType = "card" | "us_bank_account" | "sepa_debit" | string;
+interface PaymentMethodPayload {
+    id: string;
+    type: PaymentMethodType;
+    brand: PaymentMethodBrand;
+    last4: string;
+    expiryMonth?: number;
+    expiryYear?: number;
+    holderName?: string;
+    isDefault: boolean;
+    /** ISO-8601 timestamp the method was created in billing-service. */
+    createdAt?: string;
+}
+interface PaymentMethodListResponse {
+    methods: PaymentMethodPayload[];
+    defaultMethodId: string | null;
+}
+/** Returned by POST /payment-methods/setup-intent — the widget forwards
+ * `clientSecret` to the parent page via the update_requested event. */
+interface SetupIntentResponse {
+    clientSecret: string;
+    provider: "stripe" | "razorpay" | "paypal" | string;
+    /** Provider-specific opaque payload (e.g. Razorpay order id, PayPal
+     * billing-token). Not introspected by the SDK. */
+    providerData?: Record<string, unknown>;
+}
+declare global {
+    interface Window {
+        /**
+         * The loader's shared `AforoEmbed` instance, attached at bootstrap
+         * (see `loader/loader.ts`). Per-widget bundles (`loader/*.entry.ts`)
+         * MUST register against this, not a locally-imported copy of
+         * `src/core/AforoEmbed` — each widget bundle compiles to a standalone
+         * IIFE, and importing `AforoEmbed` directly inlines a private copy of
+         * the module (its own private `widgetRegistry`), disconnected from
+         * the loader's copy. Registering into the private copy while the
+         * loader's `mount()` reads from its own copy means the registration
+         * silently never reaches the loader — "No mount handler registered"
+         * even though the bundle loaded successfully.
+         */
+        aforoEmbed?: {
+            _registerWidget: (id: WidgetId, mountFn: (element: HTMLElement, config: WidgetMountConfig) => () => void) => void;
+        };
+    }
+}
+
+export type { CheckoutCustomerDetailsSubmittedPayload as $, ApplyAt as A, PreviewChangeResponse as B, CheckoutCartType as C, DemoModeBridgeProvider as D, UpgradeRequest as E, UpgradeResponse as F, CancelWithFeedbackRequest as G, HeadlessConfigResponse as H, InvoiceStatusFilter as I, CancelResponse as J, SetupIntentResponse as K, SessionConfig as L, SessionState as M, AforoEventPayload as N, OfferingPayload as O, PaymentMethodListResponse as P, AforoEventType as Q, RequestMagicLinkRequest as R, SubscriptionPayload as S, ThemeTokenOverrides as T, UsageMetricPayload as U, VerifyMagicLinkResponse as V, WidgetErrorPayload as W, CancelReason as X, CheckoutBillingAddress as Y, CheckoutCartErrorResponse as Z, CheckoutCartStatus as _, SubscriptionForOfferingResponse as a, CheckoutExpiredPayload as a0, CheckoutFlowPhase as a1, CheckoutPaymentCompletedPayload as a2, CheckoutPaymentInitiatedPayload as a3, CheckoutPaymentProvider as a4, CheckoutStepChangedPayload as a5, ConsentState as a6, FeaturePayload as a7, HeadlessBrandingPayload as a8, InvoiceDownloadedPayload as a9, UsageMetricClickedPayload as aA, UsageThresholdReachedPayload as aB, WidgetId as aC, WidgetMountConfig as aD, InvoiceExpandedPayload as aa, InvoiceFilterChangedPayload as ab, InvoicePaidPayload as ac, InvoicePayRequestedPayload as ad, InvoiceSearchChangedPayload as ae, InvoiceStatus as af, InvoiceTypeKind as ag, LiveSubscriptionStatus as ah, MagicLinkFailureCode as ai, OfferingSummary as aj, RatePlanPayload as ak, RetentionOfferShown as al, RetentionOutcome as am, SubscriptionCancelRequestedPayload as an, SubscriptionChangeType as ao, SubscriptionClickedPayload as ap, SubscriptionFilterChangedPayload as aq, SubscriptionStatus as ar, SubscriptionUpgradeRequestedPayload as as, ThemeTokens as at, UpgradeCancelAbandonedPayload as au, UpgradeCancelCompletedPayload as av, UpgradeCancelDeflectionOfferAcceptedPayload as aw, UpgradeCancelDeflectionOfferShownPayload as ax, UpgradeCancelPreviewFetchedPayload as ay, UpgradeCancelStepChangedPayload as az, CheckoutConfirmedPayload as b, CheckoutCancelledPayload as c, CheckoutCartResponse as d, SubscriptionStatusFilter as e, SubscriptionPayloadV2 as f, SubscriptionPageResponse as g, InvoicePayload as h, InvoicePageResponse as i, UsageThreshold as j, UsageResponse as k, UpgradeCancelResultPayload as l, TenantBrandKit as m, InitiateCheckoutRequest as n, InitiateCheckoutResponse as o, InvoiceListFilter as p, InvoicePdfUrlResponse as q, InitiateInvoicePaymentRequest as r, InitiateInvoicePaymentResponse as s, CreateCartRequest as t, UpdateCustomerDetailsRequest as u, InitiateCartPaymentRequest as v, ConfirmCartResponse as w, RequestMagicLinkResponse as x, SubscriptionListFilter as y, PreviewChangeRequest as z };