@flopay/shared 1.6.0 → 1.8.1

package/dist/index.d.cts

@@ -332,6 +332,9 @@ interface CheckoutGateway {
      * provider-neutral hosted card form can be recovered from
      * `POST /v1/checkouts/sessions/{id}/vault/capture` when no embedded
      * {@link CheckoutSession.vault} block is present. Absent on legacy backends.
+     * `SplitCardForm` uses this list to scope the retained wallet/APM surfaces.
+     * When a buyer selects one, the SDK requests a session-scoped intent for
+     * that explicit method. Card checkout uses the hosted vault.
      */
     enabledPaymentMethods?: string[];
     /**
@@ -463,22 +466,6 @@ interface PaymentResult {
     checkoutMethod?: CheckoutButtonMethod;
     error?: FloPayError;
 }
-/** Parameters for confirming a wallet/APM payment from a mounted PaymentElement. */
-interface ConfirmPaymentParams {
-    clientSecret: string;
-    /** Explicit non-card category for the selected payment method. */
-    paymentMethodCategory: NonCardPaymentMethodCategory;
-    /** Provider method type (for example `cashapp` or `ideal`); `card` is rejected. */
-    paymentMethodType: string;
-    /** Optional redirect URL after 3-D Secure or wallet authentication. */
-    returnUrl?: string;
-    /**
-     * Optional billing details appended to `payment_method_data` on the confirm call.
-     * Ensures `billing_details.email` (and name/address) lands on the PaymentMethod
-     * Stripe mints from Elements during 3DS confirmation.
-     */
-    billingDetails?: BillingDetails;
-}
 /** Billing details passed to Stripe for AVS (Address Verification). */
 interface BillingDetails {
     email?: string;
@@ -601,71 +588,6 @@ type SessionIntentDeclineRequest = {
     /** Provider classification code only; messages and identifiers are rejected. */
     providerDeclineReason: string;
 };
-/** The type of payment element to render. */
-type ElementType = 'payment' | 'address';
-/** Emitted when an element's internal state changes. */
-interface ElementChangeEvent {
-    elementType: ElementType;
-    complete: boolean;
-    empty: boolean;
-    error?: {
-        message: string;
-        type: string;
-    };
-    /** Only populated for non-sensitive fields (e.g. address). */
-    value?: Record<string, unknown>;
-}
-/** Configuration options when creating an element. */
-interface ElementOptions {
-    appearance?: FloPayAppearance;
-    /**
-     * Explicit non-card provider method types rendered by a payment element.
-     * The SDK removes `card`; card collection belongs to the hosted vault.
-     */
-    paymentMethodTypes?: readonly string[];
-    /**
-     * Client secret for an existing non-card PaymentIntent or SetupIntent.
-     * The explicit `paymentMethodTypes` allowlist remains required; the SDK uses
-     * it to validate the provider intent before mounting. Card checkout uses the
-     * hosted vault.
-     */
-    clientSecret?: string;
-    /**
-     * Total amount in the smallest currency unit (e.g. cents).
-     * Used when no `clientSecret` is available — Stripe Elements needs
-     * `mode` + `amount` + `currency` to render without a server-side intent.
-     */
-    amount?: number;
-    /** ISO 4217 currency code (lowercase). Used with `amount` when no `clientSecret`. */
-    currency?: string;
-    /** How payment methods are created. 'manual' = tokenize only, 'auto' = Stripe handles it. */
-    paymentMethodCreation?: 'manual' | 'auto';
-    /**
-     * Requests reusable payment credentials for future payments when Stripe
-     * creates or validates a deferred PaymentIntent for this Elements group.
-     */
-    setupFutureUsage?: 'off_session' | 'on_session';
-    layout?: 'tabs' | 'accordion' | 'auto';
-    defaultValues?: Record<string, unknown>;
-    readOnly?: boolean;
-    /** Address element mode: 'billing' or 'shipping'. */
-    mode?: 'billing' | 'shipping';
-}
-/**
- * A payment element that has been created and can be mounted into the DOM.
- *
- * TODO: In a future phase, each MountedElement will render inside an iframe
- * for PCI DSS SAQ-A compliance. For now, it wraps the underlying provider
- * element directly.
- */
-interface MountedElement {
-    mount(container: HTMLElement): void;
-    unmount(): void;
-    update(options: Partial<ElementOptions>): void;
-    on(event: string, handler: (...args: unknown[]) => void): void;
-    off(event: string, handler: (...args: unknown[]) => void): void;
-    destroy(): void;
-}
 /** Top-level configuration for initializing FloPay. */
 interface FloPayConfig {
     publishableKey: string;
@@ -691,41 +613,8 @@ interface FloPayConfig {
 interface PaymentProviderAdapter {
     readonly name: string;
     initialize(config: FloPayConfig): Promise<void>;
-    createElement(type: ElementType, options: ElementOptions): Promise<MountedElement>;
-    /** Retrieve an existing element by type, or `null` if not yet created. */
-    getElement(type: ElementType): MountedElement | null;
-    /** Submit elements for validation (Stripe `elements.submit()`). */
-    submitElements(): Promise<{
-        error?: FloPayError;
-    }>;
-    /** Confirm a non-card wallet/APM payment from mounted elements. */
-    confirmPayment(params: ConfirmPaymentParams): Promise<PaymentResult>;
-    /**
-     * Create a PayPal payment: create PM → create intent → confirm with redirect.
-     * Returns the confirmed PaymentIntent ID if completed inline, or redirects to PayPal.
-     *
-     * `nonce` is the session-bound checkout token forwarded to the
-     * session-scoped non-card intent contract.
-     */
-    confirmPayPalPayment(params: {
-        billingApiUrl: string;
-        sessionId: string;
-        email: string;
-        returnUrl: string;
-        nonce?: string;
-    }): Promise<PayPalPaymentResult>;
-    /**
-     * Resume a PayPal payment after redirect return.
-     * Checks URL params for payment_intent + redirect_status.
-     */
-    resumePayPalPayment(): Promise<PayPalPaymentResult | null>;
-    /**
-     * Get the raw underlying provider instance (e.g. Stripe object).
-     * Used internally for creating secondary Elements groups (e.g. PayPal).
-     */
+    /** Get the raw underlying provider instance (e.g. Stripe object). */
     getRawProvider(): unknown;
-    /** Create a secondary Elements group for PayPal's automatic payment-method flow. */
-    createPayPalElements(options: ElementOptions): unknown;
     destroy(): void;
 }
 /**
@@ -1576,196 +1465,133 @@ interface CountryOption {
  */
 declare function isCardSetupCheckoutSession(session: CheckoutSession): boolean;
 
-interface SentryStackFrameLike {
-    in_app?: boolean;
-    filename?: string;
-    abs_path?: string;
-    module?: string;
-}
-interface SentryEventLike {
-    exception?: {
-        values?: Array<{
-            stacktrace?: {
-                frames?: SentryStackFrameLike[];
-            };
-        }>;
-    };
-}
+/** Returns whether a checkout deliberately stops after placing an authorization hold. */
+declare function isAuthorizationOnlySession(session?: {
+    captureMethod?: CaptureMethod;
+} | null): boolean;
 /**
- * Drops errors whose complete exception stack contains recognized hosted
- * third-party code and no resolvable first-party frame. All other events are
- * returned by identity.
+ * Returns whether an outcome represents money settled for the active checkout.
+ *
+ * `requires_capture` remains successful for legacy automatic/PayPal flows, but
+ * can never be treated as settled for a manual-capture session.
  */
-declare function dropThirdPartyOnlyError<T extends SentryEventLike>(event: T): T | null;
-
-/** Wire schema version shared with the Flo telemetry ingestion service. */
-declare const TELEMETRY_SCHEMA_VERSION: 1;
-declare const TELEMETRY_SDK_PACKAGES: readonly ["@flopay/shared", "@flopay/js", "@flopay/react"];
-type TelemetrySdkPackage = (typeof TELEMETRY_SDK_PACKAGES)[number];
-declare const TELEMETRY_MAX_BATCH_BYTES: number;
-declare const TELEMETRY_MAX_BATCH_EVENTS = 20;
-type TelemetryEventClass = 'technical_error' | 'lifecycle' | 'expected_outcome' | 'performance';
-declare const TELEMETRY_PROVIDERS: readonly ["stripe", "paypal"];
-type TelemetryProvider = (typeof TELEMETRY_PROVIDERS)[number];
-type TelemetryProviderInput = TelemetryProvider | 'flo' | 'pcivault' | 'other' | 'unknown';
-declare const TELEMETRY_PAYMENT_METHOD_CATEGORIES: readonly ["card", "wallet", "paypal", "apm", "saved", "unknown"];
-type TelemetryPaymentMethodCategory = (typeof TELEMETRY_PAYMENT_METHOD_CATEGORIES)[number];
-declare const TELEMETRY_STAGES: readonly ["callback", "sdk_initialize", "checkout_mount", "session_create", "session_shell", "session_claim", "session_read", "session_first_byte", "session_complete", "checkout_data_ready", "checkout_render", "checkout_interactive", "provider_load", "provider_ready", "overlay_open", "overlay_return", "redirect", "redirect_resume", "vault_request", "vault_mount", "vault_ready", "vault_submit", "tokenization", "three_ds_handoff", "three_ds_return", "processing", "recovery", "completion", "unmount", "total_journey"];
-type TelemetryStage = (typeof TELEMETRY_STAGES)[number];
-declare const TELEMETRY_ERROR_CODES: readonly ["CALLBACK_FAILED", "CHECKOUT_SESSION_CREATE_FAILED", "CONFIGURATION_INVALID", "INTERNAL_SDK_ERROR", "NETWORK_REQUEST_FAILED", "PAYMENT_PROCESSING_FAILED", "POPUP_BLOCKED", "PROVIDER_LOAD_FAILED", "PROVIDER_RUNTIME_FAILED", "RECOVERY_FAILED", "REDIRECT_RESUME_FAILED", "REQUEST_TIMEOUT", "SDK_INITIALIZATION_FAILED", "THREE_DS_FAILED", "TOKENIZATION_FAILED", "VAULT_LOAD_FAILED", "VAULT_SUBMIT_FAILED"];
-type TelemetryErrorCode = (typeof TELEMETRY_ERROR_CODES)[number];
-declare const TELEMETRY_FAILURE_CATEGORIES: readonly ["server_error", "transport_error", "invalid_response", "provider_runtime"];
-type TelemetryFailureCategory = (typeof TELEMETRY_FAILURE_CATEGORIES)[number];
-/** Closed catalog of SDK-authored lifecycle and operational log names. */
-declare const TELEMETRY_LOG_NAMES: readonly ["sdk.initialize.started", "sdk.initialize.ready", "sdk.cache.hit", "sdk.cache.miss", "checkout.mount", "session.create.started", "session.shell.ready", "session.claim.started", "session.claim.completed", "session.read.started", "session.request.first_byte", "session.request.completed", "checkout.data.ready", "checkout.rendered", "checkout.interactive", "checkout.recovery.started", "checkout.recovery.completed", "checkout.unmount", "provider.load.started", "provider.eligibility.checked", "provider.availability.checked", "provider.ready", "provider.popup.opened", "provider.overlay.opened", "provider.overlay.returned", "provider.redirect.started", "provider.redirect.resumed", "vault.capture.requested", "vault.widget.mounted", "vault.widget.ready", "vault.submission.started", "vault.action.required", "vault.three_ds.handoff", "vault.three_ds.returned", "vault.terminal", "payment.method.selected", "payment.intent.started", "payment.intent.completed", "payment.tokenization.started", "payment.tokenization.completed", "payment.processing.started", "payment.processing.completed", "payment.three_ds.handoff", "payment.three_ds.returned", "operation.retry", "operation.deduplicated", "operation.fallback", "operation.cache.hit", "operation.cache.miss", "operation.recovery.started", "operation.recovery.completed", "operation.state_transition"];
-type TelemetryLogName = (typeof TELEMETRY_LOG_NAMES)[number];
-declare const TELEMETRY_REQUEST_CATEGORIES: readonly ["session_create", "session_claim", "session_read", "intent_create", "process_payment", "vault_capture", "account_snapshot", "provider_sdk", "other"];
-type TelemetryRequestCategory = (typeof TELEMETRY_REQUEST_CATEGORIES)[number];
-declare const TELEMETRY_STATUS_CLASSES: readonly ["2xx", "3xx", "4xx", "5xx", "network_error", "timeout", "unknown"];
-type TelemetryStatusClass = (typeof TELEMETRY_STATUS_CLASSES)[number];
-declare const TELEMETRY_CHECKOUT_MODES: readonly ["full", "auto", "confirm", "setup", "unknown"];
-type TelemetryCheckoutMode = (typeof TELEMETRY_CHECKOUT_MODES)[number];
-declare const TELEMETRY_LAYOUTS: readonly ["embedded", "buttons", "automatic", "unknown"];
-type TelemetryLayout = (typeof TELEMETRY_LAYOUTS)[number];
-declare const TELEMETRY_DURATION_MODES: readonly ["machine", "buyer", "total"];
-type TelemetryDurationMode = (typeof TELEMETRY_DURATION_MODES)[number];
-declare const TELEMETRY_EXPECTED_OUTCOMES: readonly ["action_required", "card_setup_declined", "card_setup_succeeded", "customer_abandoned", "payment_cancelled", "payment_declined", "payment_authorized", "payment_succeeded", "validation_rejected"];
-type TelemetryExpectedOutcome = (typeof TELEMETRY_EXPECTED_OUTCOMES)[number];
-interface TelemetryCommonFields {
-    eventId: string;
-    stage: TelemetryStage;
-    sequence: number;
-    provider?: TelemetryProvider;
-    attempt?: number;
-    statusClass?: TelemetryStatusClass;
-    requestCategory?: TelemetryRequestCategory;
-    paymentMethodCategory?: TelemetryPaymentMethodCategory;
-    checkoutMode?: TelemetryCheckoutMode;
-    layout?: TelemetryLayout;
-}
-interface BuildTelemetryCommonInput {
-    eventId: string;
-    stage: TelemetryStage;
-    sequence: number;
-    provider?: TelemetryProviderInput;
-    attempt?: number;
-    statusClass?: TelemetryStatusClass;
-    requestCategory?: TelemetryRequestCategory;
-    paymentMethodCategory?: TelemetryPaymentMethodCategory;
-    checkoutMode?: TelemetryCheckoutMode;
-    layout?: TelemetryLayout;
-}
-interface TelemetryErrorEvent extends TelemetryCommonFields {
-    class: 'technical_error';
-    code: TelemetryErrorCode;
-    failureCategory?: TelemetryFailureCategory;
-}
-interface BuildTelemetryErrorEventInput extends BuildTelemetryCommonInput {
-    errorCode: TelemetryErrorCode;
-    failureCategory?: TelemetryFailureCategory;
-}
-interface TelemetryLogEvent extends TelemetryCommonFields {
-    class: 'lifecycle';
-    name: TelemetryLogName;
-}
-interface BuildTelemetryLogEventInput extends BuildTelemetryCommonInput {
-    name: TelemetryLogName;
-}
-interface TelemetryExpectedOutcomeEvent extends TelemetryCommonFields {
-    class: 'expected_outcome';
-    outcome: TelemetryExpectedOutcome;
-}
-interface BuildTelemetryTerminalEventInput extends Omit<BuildTelemetryCommonInput, 'stage'> {
-    outcome: TelemetryExpectedOutcome;
-    stage?: TelemetryStage;
-}
-interface TelemetryPerformanceEvent extends TelemetryCommonFields {
-    class: 'performance';
-    durationMs: number;
-    /** True when the measured duration exceeded the bounded wire value. */
-    durationTruncated?: true;
-    durationMode: TelemetryDurationMode;
-}
-interface BuildTelemetryPerformanceEventInput extends BuildTelemetryCommonInput {
-    durationMs: number;
-    /** Preserves a previously sanitized truncation marker during serialization. */
-    durationTruncated?: boolean;
-    durationMode: TelemetryDurationMode;
-}
-type TelemetryEvent = TelemetryErrorEvent | TelemetryLogEvent | TelemetryExpectedOutcomeEvent | TelemetryPerformanceEvent;
-interface SerializeTelemetryBatchOptions {
-    correlationId: string;
-    sdkPackage: TelemetrySdkPackage;
-    sdkVersion: string;
-    batchId?: string;
-}
-interface TelemetryBatchEnvelope {
-    schemaVersion: typeof TELEMETRY_SCHEMA_VERSION;
-    batchId: string;
-    correlationId: string;
-    sdk: {
-        package: TelemetrySdkPackage;
-        version: string;
-    };
-    events: TelemetryEvent[];
-}
-/** Build a closed SDK technical-error event. */
-declare function buildTelemetryErrorEvent(input: BuildTelemetryErrorEventInput): TelemetryErrorEvent;
-/** Build a typed SDK lifecycle event; arbitrary text is never accepted. */
-declare function buildTelemetryLogEvent(input: BuildTelemetryLogEventInput): TelemetryLogEvent;
-/** Build a non-error expected checkout outcome. */
-declare function buildTelemetryTerminalEvent(input: BuildTelemetryTerminalEventInput): TelemetryExpectedOutcomeEvent;
-/** Build a monotonic SDK-owned duration measurement. */
-declare function buildTelemetryPerformanceEvent(input: BuildTelemetryPerformanceEventInput): TelemetryPerformanceEvent;
-/** Serialize one closed backend-owned v1 telemetry envelope. */
-declare function serializeTelemetryBatch(events: readonly TelemetryEvent[], options: SerializeTelemetryBatchOptions): string;
+declare function isMoneySettledOutcome(outcome?: string | null, captureMethod?: CaptureMethod): boolean;
+/** Collapses provider/backend reason strings into the SDK's closed failure vocabulary. */
+declare function normalizeCheckoutFailureOutcome(value: unknown): CheckoutFailureOutcome | undefined;
 
-interface ClassifiedTelemetryFailure {
-    errorCode: TelemetryErrorCode;
-    statusClass: TelemetryStatusClass;
-    failureCategory?: TelemetryFailureCategory;
+interface CaptureMethodEligibilityParams {
+    captureMethod?: CaptureMethod;
+    products?: readonly CheckoutProduct[];
+    items?: readonly CheckoutItem[];
+    subscriptions?: readonly CheckoutSubscription[];
 }
 /**
- * Classify the bounded billing response contract without reading free-form
- * messages, error codes, or provider payloads.
+ * Reject authorisation-only checkout carts that contain a subscription.
+ *
+ * The backend remains authoritative; this shared preflight keeps every SDK
+ * creation style from mounting or redirecting to a checkout that cannot
+ * support manual capture.
+ *
+ * Subscription detection in the unified `products` shape is best-effort:
+ * `CheckoutProduct.type` is optional, so catalog-backed subscriptions that
+ * omit it are resolved and rejected by the authoritative backend validation.
  */
-declare function classifyPaymentRejection(status: number, payload: unknown): Extract<TelemetryExpectedOutcome, 'payment_declined' | 'validation_rejected'> | undefined;
-/** Classify only SDK-owned error structure; never inspect messages or payloads. */
-declare function classifyTelemetryFailure(error: unknown, fallbackCode: TelemetryErrorCode, fallbackStatusClass?: TelemetryStatusClass): ClassifiedTelemetryFailure;
-declare function telemetryStatusClass(status: number | undefined, fallbackStatusClass?: TelemetryStatusClass): TelemetryStatusClass;
-
-/** FloPay environment — determines which billing API URL is used. */
-type FloPayEnvironment = 'staging' | 'production' | 'local';
+declare function assertCaptureMethodEligible(params: CaptureMethodEligibilityParams): void;
 /**
- * Configure the FloPay SDK globally. Call once at app startup.
- *
- * The environment determines which billing API URL is used for all
- * FloPay operations (session creation, payment processing, etc.).
+ * Whether a session may be created through the **detached** shell + claim flow
+ * (TeamFloPay/backend#1099).
  *
- * @example
- * ```ts
- * import { configureFlopay } from '@flopay/shared';
+ * Detached creation is the default, but it is not universally available:
  *
- * // In production
- * configureFlopay({ environment: 'production' });
+ * - The billing API accepts `deferDataAttachment` only for Full checkouts
+ *   (`IsDeferredCheckoutMode`), so `auto` and `confirm` are excluded.
+ * - A saved-payment session (`tokenizedData`) can be charged the moment it
+ *   exists, so it must carry its cart from the start.
+ * - `deferDataAttachment: false` is the caller's explicit opt-out.
+ */
+declare function isDetachedSessionEligible(params: InlineSessionDraft): boolean;
+/**
+ * Resolve the session-level currency, honoring the documented fallback:
+ * `session.currency ?? items[*].currency ?? subscriptions[*].currency ?? products[*].currency`.
  *
- * // In staging/development
- * configureFlopay({ environment: 'staging' });
- * ```
+ * Returns the first non-blank currency found, or `null` when nothing is set.
+ * Empty and whitespace-only strings are treated as unset so they do not
+ * bypass the fallback chain.
  *
- * Alternatively, set the `NEXT_PUBLIC_FLOPAY_ENV` environment variable
- * to `'staging'` or `'production'` — the SDK reads it automatically.
+ * Post-#760 backends reject session-create requests without a session-level
+ * currency (`@IsNotEmpty`); callers should throw a validation error when
+ * this returns `null` rather than silently defaulting.
  */
-declare function configureFlopay(config: {
-    environment: FloPayEnvironment;
-}): void;
-/** Get the billing API URL for the currently configured environment. */
-declare function getConfiguredBillingApiUrl(): string;
-/** Get the current configured environment. */
-declare function getFloPayEnvironment(): FloPayEnvironment;
-
-/** Current SDK version. */
-declare const SDK_VERSION = "1.6.0";
+declare function resolveSessionCurrency(sessionCurrency: string | undefined, items?: ReadonlyArray<{
+    currency?: string;
+}> | undefined, subscriptions?: ReadonlyArray<{
+    currency?: string;
+}> | undefined, products?: ReadonlyArray<{
+    currency?: string;
+}> | undefined): string | null;
+/**
+ * Fold legacy `items` + `subscriptions` arrays into the unified `products[]`
+ * shape introduced by backend #760. Items become `type: 'item'`,
+ * subscriptions become `type: 'subscription'`. The relative order is
+ * subscriptions-first then items, matching the order the previous payload
+ * builders emitted on the wire.
+ */
+declare function foldIntoProducts(items: readonly CheckoutItem[] | undefined, subscriptions: readonly CheckoutSubscription[] | undefined): CheckoutProduct[];
+/**
+ * Build the request payload for a single product in the unified shape
+ * introduced by backend #760. Emits `type`, `code`, `name`, `quantity`,
+ * `totalAmount`, `overrideAmount`, `currency`, and optional `metadata`.
+ */
+declare function buildProductPayload(product: CheckoutProduct, sessionCurrency: string): Record<string, unknown>;
+/**
+ * Build the request payload for a single item.
+ *
+ * @deprecated Use {@link buildProductPayload} with {@link foldIntoProducts}.
+ * Retained until the next major so external callers building the legacy
+ * `items[]` payload manually keep working.
+ */
+declare function buildItemPayload(item: CheckoutItem, sessionCurrency: string): Record<string, unknown>;
+/**
+ * Build the request payload for a single subscription.
+ *
+ * @deprecated Use {@link buildProductPayload} with {@link foldIntoProducts}.
+ * Retained until the next major so external callers building the legacy
+ * `subscriptions[]` payload manually keep working.
+ */
+declare function buildSubscriptionPayload(subscription: CheckoutSubscription, sessionCurrency: string): Record<string, unknown>;
+
+/** FloPay environment — determines which billing API URL is used. */
+type FloPayEnvironment = 'staging' | 'production' | 'local';
+/**
+ * Configure the FloPay SDK globally. Call once at app startup.
+ *
+ * The environment determines which billing API URL is used for all
+ * FloPay operations (session creation, payment processing, etc.).
+ *
+ * @example
+ * ```ts
+ * import { configureFlopay } from '@flopay/shared';
+ *
+ * // In production
+ * configureFlopay({ environment: 'production' });
+ *
+ * // In staging/development
+ * configureFlopay({ environment: 'staging' });
+ * ```
+ *
+ * Alternatively, set the `NEXT_PUBLIC_FLOPAY_ENV` environment variable
+ * to `'staging'` or `'production'` — the SDK reads it automatically.
+ */
+declare function configureFlopay(config: {
+    environment: FloPayEnvironment;
+}): void;
+/** Get the billing API URL for the currently configured environment. */
+declare function getConfiguredBillingApiUrl(): string;
+/** Get the current configured environment. */
+declare function getFloPayEnvironment(): FloPayEnvironment;
+
+/** Current SDK version. */
+declare const SDK_VERSION = "1.8.1";
 /**
  * HTTP header the SDK sends on checkout-session create/read requests so the
  * backend can observe compatibility. Version 1.4.9 is the first release that
@@ -2146,8 +1972,6 @@ declare function partitionStripeMethods(enabledPaymentMethods: readonly string[]
     expressMethods: string[];
     paymentElementMethods: string[];
 };
-/** All supported element type identifiers. */
-declare const ELEMENT_TYPES: readonly ["payment", "address"];
 declare const SUPPORTED_CARD_BRANDS: readonly ["visa", "mastercard", "mastercard_debit", "amex", "discover"];
 /** Country code to currency information mapping. */
 declare const CURRENCY_MAP: Record<string, CurrencyInfo>;
@@ -2194,58 +2018,6 @@ declare function getStateOptions(country: string): StateOption[] | null;
 /** Returns the appropriate label for the state/province field based on country. */
 declare function getStateLabel(countryCode: string): string;
 
-/**
- * Postal-code → state derivation for AVS.
- *
- * Used when the form configuration shows `address_line_1` but hides the
- * `state` input — we still want to populate `billing_details.address.state`
- * so Stripe Radar gets a richer address signal. Currently supports US and CA;
- * other countries return `null` (caller should fall back to omitting state).
- */
-/**
- * Resolve a state / province code from a postal code for the given country.
- *
- * - US: 5-digit ZIP → 2-letter USPS state code (uses 3-digit prefix table).
- * - CA: A1A 1A1 → 2-letter ISO 3166-2:CA province code (first-letter mapping).
- * - All other countries: `null`.
- *
- * Returns `null` when the postal code is malformed or falls in an unmapped
- * range. Callers should treat `null` as "skip — don't derive".
- */
-declare function getStateFromPostalCode(country: string, postalCode: string): string | null;
-
-/**
- * True when `validator` has an authoritative postcode pattern for the country
- * (normalized to ISO 3166-1 alpha-2 via {@link normalizeCountryToIso2}).
- * Supported countries validate the postcode format; unsupported / no-postcode /
- * unresolvable countries fail open. Note the 2-letter passthrough means `UK`
- * (an unsupported `validator` locale) returns `false` here — matching the
- * backend; use the full name `United Kingdom` for `GB` semantics.
- */
-declare function isPostalCodeSupported(country: string): boolean;
-/**
- * Validate a postcode against the country's expected format. A faithful mirror
- * of the backend's `isPostalCodeValidForCountry`, so the SDK never blocks a
- * value the server would accept, nor opens the submit gate on one it would
- * reject. Fail-open (returns `true`) in exactly the backend's three cases:
- *
- * - `postalCode` is blank / whitespace-only;
- * - the country can't be normalized to an ISO-2 locale;
- * - the ISO-2 locale isn't one `validator` recognises.
- *
- * Otherwise returns `validator`'s `isPostalCode(zip.trim(), locale)`. Callers
- * that distinguish "required" (empty) from "malformed" (bad format) must check
- * emptiness themselves — an empty value fails open here, as it does server-side.
- */
-declare function isValidPostalCode(country: string, postalCode: string): boolean;
-/**
- * The example postcode the backend would embed in its 400 message for the
- * country (e.g. US `12345 or 12345-6789`, GB `SW1A 1AA`, CA `A1A 1A1`), or
- * `undefined` when there is none (unresolvable country, or a supported country
- * absent from {@link POSTAL_CODE_EXAMPLES}).
- */
-declare function getPostalCodeExample(country: string): string | undefined;
-
 /** A single line item formatted for display in the checkout UI. */
 interface DisplayLineItem {
     name: string;
@@ -2310,118 +2082,6 @@ interface BuildCheckoutDisplayDataOptions {
  */
 declare function buildCheckoutDisplayData(session: CheckoutSession, options?: BuildCheckoutDisplayDataOptions): CheckoutDisplayData;
 
-interface CaptureMethodEligibilityParams {
-    captureMethod?: CaptureMethod;
-    products?: readonly CheckoutProduct[];
-    items?: readonly CheckoutItem[];
-    subscriptions?: readonly CheckoutSubscription[];
-}
-/**
- * Reject authorisation-only checkout carts that contain a subscription.
- *
- * The backend remains authoritative; this shared preflight keeps every SDK
- * creation style from mounting or redirecting to a checkout that cannot
- * support manual capture.
- *
- * Subscription detection in the unified `products` shape is best-effort:
- * `CheckoutProduct.type` is optional, so catalog-backed subscriptions that
- * omit it are resolved and rejected by the authoritative backend validation.
- */
-declare function assertCaptureMethodEligible(params: CaptureMethodEligibilityParams): void;
-/**
- * Whether a session may be created through the **detached** shell + claim flow
- * (TeamFloPay/backend#1099).
- *
- * Detached creation is the default, but it is not universally available:
- *
- * - The billing API accepts `deferDataAttachment` only for Full checkouts
- *   (`IsDeferredCheckoutMode`), so `auto` and `confirm` are excluded.
- * - A saved-payment session (`tokenizedData`) can be charged the moment it
- *   exists, so it must carry its cart from the start.
- * - `deferDataAttachment: false` is the caller's explicit opt-out.
- */
-declare function isDetachedSessionEligible(params: InlineSessionDraft): boolean;
-/**
- * Resolve the session-level currency, honoring the documented fallback:
- * `session.currency ?? items[*].currency ?? subscriptions[*].currency ?? products[*].currency`.
- *
- * Returns the first non-blank currency found, or `null` when nothing is set.
- * Empty and whitespace-only strings are treated as unset so they do not
- * bypass the fallback chain.
- *
- * Post-#760 backends reject session-create requests without a session-level
- * currency (`@IsNotEmpty`); callers should throw a validation error when
- * this returns `null` rather than silently defaulting.
- */
-declare function resolveSessionCurrency(sessionCurrency: string | undefined, items?: ReadonlyArray<{
-    currency?: string;
-}> | undefined, subscriptions?: ReadonlyArray<{
-    currency?: string;
-}> | undefined, products?: ReadonlyArray<{
-    currency?: string;
-}> | undefined): string | null;
-/**
- * Fold legacy `items` + `subscriptions` arrays into the unified `products[]`
- * shape introduced by backend #760. Items become `type: 'item'`,
- * subscriptions become `type: 'subscription'`. The relative order is
- * subscriptions-first then items, matching the order the previous payload
- * builders emitted on the wire.
- */
-declare function foldIntoProducts(items: readonly CheckoutItem[] | undefined, subscriptions: readonly CheckoutSubscription[] | undefined): CheckoutProduct[];
-/**
- * Build the request payload for a single product in the unified shape
- * introduced by backend #760. Emits `type`, `code`, `name`, `quantity`,
- * `totalAmount`, `overrideAmount`, `currency`, and optional `metadata`.
- */
-declare function buildProductPayload(product: CheckoutProduct, sessionCurrency: string): Record<string, unknown>;
-/**
- * Build the request payload for a single item.
- *
- * @deprecated Use {@link buildProductPayload} with {@link foldIntoProducts}.
- * Retained until the next major so external callers building the legacy
- * `items[]` payload manually keep working.
- */
-declare function buildItemPayload(item: CheckoutItem, sessionCurrency: string): Record<string, unknown>;
-/**
- * Build the request payload for a single subscription.
- *
- * @deprecated Use {@link buildProductPayload} with {@link foldIntoProducts}.
- * Retained until the next major so external callers building the legacy
- * `subscriptions[]` payload manually keep working.
- */
-declare function buildSubscriptionPayload(subscription: CheckoutSubscription, sessionCurrency: string): Record<string, unknown>;
-
-/** Returns whether a checkout deliberately stops after placing an authorization hold. */
-declare function isAuthorizationOnlySession(session?: {
-    captureMethod?: CaptureMethod;
-} | null): boolean;
-/**
- * Returns whether an outcome represents money settled for the active checkout.
- *
- * `requires_capture` remains successful for legacy automatic/PayPal flows, but
- * can never be treated as settled for a manual-capture session.
- */
-declare function isMoneySettledOutcome(outcome?: string | null, captureMethod?: CaptureMethod): boolean;
-/** Collapses provider/backend reason strings into the SDK's closed failure vocabulary. */
-declare function normalizeCheckoutFailureOutcome(value: unknown): CheckoutFailureOutcome | undefined;
-
-/**
- * Look up currency information by ISO 3166-1 alpha-2 country code.
- * Falls back to USD when the country is not in the map.
- */
-declare function getCurrencyByCountry(countryCode: string): CurrencyInfo;
-/** Returns `true` if the string looks like a Stripe publishable key. */
-declare function isValidPublishableKey(key: string): boolean;
-/** Returns `true` if the string looks like a Stripe secret key. */
-declare function isValidSecretKey(key: string): boolean;
-/**
- * Returns `true` when the client secret belongs to a SetupIntent (`seti_…`).
- * Trial-only / $0 checkouts confirm and retrieve a SetupIntent instead of a
- * PaymentIntent, so callers must route those to `confirmCardSetup` /
- * `retrieveSetupIntent` rather than the PaymentIntent equivalents.
- */
-declare function isSetupIntentClientSecret(clientSecret: string | null | undefined): boolean;
-
 /**
  * HTTP header the SDK sends to make checkout-session creation idempotent
  * (TeamFloPay/backend#972, paired SDK issue TeamFloPay/sdk#133).
@@ -2478,6 +2138,266 @@ declare function generateIdempotencyKey(): string | undefined;
  */
 declare function resolveIdempotencyKey(supplied?: string): string | undefined;
 
+/** Schema version for the privacy-safe instrument callback contract. */
+declare const FLO_INSTRUMENT_SCHEMA_VERSION: 1;
+/**
+ * Complete catalog of checkout signals exposed to merchant applications.
+ * Error phases are separate catalog entries so consumers can verify parity
+ * with each arm of their checkout analytics funnel.
+ */
+declare const FLO_INSTRUMENT_CATALOG: readonly [{
+    readonly name: "checkout_mount";
+}, {
+    readonly name: "sdk_loaded";
+}, {
+    readonly name: "form_rendered";
+}, {
+    readonly name: "card_expanded";
+}, {
+    readonly name: "tokenize";
+}, {
+    readonly name: "process_attempt";
+}, {
+    readonly name: "3ds_challenge";
+}, {
+    readonly name: "checkout_error";
+    readonly phase: "session_create";
+}, {
+    readonly name: "checkout_error";
+    readonly phase: "sdk_load";
+}, {
+    readonly name: "checkout_error";
+    readonly phase: "process";
+}, {
+    readonly name: "checkout_error";
+    readonly phase: "wallets";
+}];
+type FloInstrumentLifecycleName = Exclude<(typeof FLO_INSTRUMENT_CATALOG)[number]['name'], 'checkout_error'>;
+type FloInstrumentErrorPhase = Extract<(typeof FLO_INSTRUMENT_CATALOG)[number], {
+    name: 'checkout_error';
+}>['phase'];
+interface FloInstrumentCommonFields {
+    schemaVersion: typeof FLO_INSTRUMENT_SCHEMA_VERSION;
+    /** Gateway selected for this transition, when the checkout has selected one. */
+    gateway?: BillingProvider;
+}
+type FloInstrumentEvent = (FloInstrumentCommonFields & {
+    name: FloInstrumentLifecycleName;
+}) | (FloInstrumentCommonFields & {
+    name: 'checkout_error';
+    phase: FloInstrumentErrorPhase;
+});
+
+/**
+ * Postal-code → state derivation for AVS.
+ *
+ * Used when the form configuration shows `address_line_1` but hides the
+ * `state` input — we still want to populate `billing_details.address.state`
+ * so Stripe Radar gets a richer address signal. Currently supports US and CA;
+ * other countries return `null` (caller should fall back to omitting state).
+ */
+/**
+ * Resolve a state / province code from a postal code for the given country.
+ *
+ * - US: 5-digit ZIP → 2-letter USPS state code (uses 3-digit prefix table).
+ * - CA: A1A 1A1 → 2-letter ISO 3166-2:CA province code (first-letter mapping).
+ * - All other countries: `null`.
+ *
+ * Returns `null` when the postal code is malformed or falls in an unmapped
+ * range. Callers should treat `null` as "skip — don't derive".
+ */
+declare function getStateFromPostalCode(country: string, postalCode: string): string | null;
+
+/**
+ * True when `validator` has an authoritative postcode pattern for the country
+ * (normalized to ISO 3166-1 alpha-2 via {@link normalizeCountryToIso2}).
+ * Supported countries validate the postcode format; unsupported / no-postcode /
+ * unresolvable countries fail open. Note the 2-letter passthrough means `UK`
+ * (an unsupported `validator` locale) returns `false` here — matching the
+ * backend; use the full name `United Kingdom` for `GB` semantics.
+ */
+declare function isPostalCodeSupported(country: string): boolean;
+/**
+ * Validate a postcode against the country's expected format. A faithful mirror
+ * of the backend's `isPostalCodeValidForCountry`, so the SDK never blocks a
+ * value the server would accept, nor opens the submit gate on one it would
+ * reject. Fail-open (returns `true`) in exactly the backend's three cases:
+ *
+ * - `postalCode` is blank / whitespace-only;
+ * - the country can't be normalized to an ISO-2 locale;
+ * - the ISO-2 locale isn't one `validator` recognises.
+ *
+ * Otherwise returns `validator`'s `isPostalCode(zip.trim(), locale)`. Callers
+ * that distinguish "required" (empty) from "malformed" (bad format) must check
+ * emptiness themselves — an empty value fails open here, as it does server-side.
+ */
+declare function isValidPostalCode(country: string, postalCode: string): boolean;
+/**
+ * The example postcode the backend would embed in its 400 message for the
+ * country (e.g. US `12345 or 12345-6789`, GB `SW1A 1AA`, CA `A1A 1A1`), or
+ * `undefined` when there is none (unresolvable country, or a supported country
+ * absent from {@link POSTAL_CODE_EXAMPLES}).
+ */
+declare function getPostalCodeExample(country: string): string | undefined;
+
+interface SentryStackFrameLike {
+    in_app?: boolean;
+    filename?: string;
+    abs_path?: string;
+    module?: string;
+}
+interface SentryEventLike {
+    exception?: {
+        values?: Array<{
+            stacktrace?: {
+                frames?: SentryStackFrameLike[];
+            };
+        }>;
+    };
+}
+/**
+ * Drops errors whose complete exception stack contains recognized hosted
+ * third-party code and no resolvable first-party frame. All other events are
+ * returned by identity.
+ */
+declare function dropThirdPartyOnlyError<T extends SentryEventLike>(event: T): T | null;
+
+/** Wire schema version shared with the Flo telemetry ingestion service. */
+declare const TELEMETRY_SCHEMA_VERSION: 1;
+declare const TELEMETRY_SDK_PACKAGES: readonly ["@flopay/shared", "@flopay/js", "@flopay/react"];
+type TelemetrySdkPackage = (typeof TELEMETRY_SDK_PACKAGES)[number];
+declare const TELEMETRY_MAX_BATCH_BYTES: number;
+declare const TELEMETRY_MAX_BATCH_EVENTS = 20;
+type TelemetryEventClass = 'technical_error' | 'lifecycle' | 'expected_outcome' | 'performance';
+declare const TELEMETRY_PROVIDERS: readonly ["stripe", "paypal"];
+type TelemetryProvider = (typeof TELEMETRY_PROVIDERS)[number];
+type TelemetryProviderInput = TelemetryProvider | 'flo' | 'pcivault' | 'other' | 'unknown';
+declare const TELEMETRY_PAYMENT_METHOD_CATEGORIES: readonly ["card", "wallet", "paypal", "apm", "saved", "unknown"];
+type TelemetryPaymentMethodCategory = (typeof TELEMETRY_PAYMENT_METHOD_CATEGORIES)[number];
+declare const TELEMETRY_STAGES: readonly ["callback", "sdk_initialize", "checkout_mount", "session_create", "session_shell", "session_claim", "session_read", "session_first_byte", "session_complete", "checkout_data_ready", "checkout_render", "provider_load", "provider_ready", "overlay_open", "overlay_return", "redirect", "redirect_resume", "vault_request", "vault_mount", "vault_ready", "vault_submit", "tokenization", "three_ds_handoff", "three_ds_return", "processing", "recovery", "completion", "unmount", "total_journey"];
+type TelemetryStage = (typeof TELEMETRY_STAGES)[number];
+declare const TELEMETRY_ERROR_CODES: readonly ["CALLBACK_FAILED", "CHECKOUT_SESSION_CREATE_FAILED", "CONFIGURATION_INVALID", "INTERNAL_SDK_ERROR", "NETWORK_REQUEST_FAILED", "PAYMENT_PROCESSING_FAILED", "POPUP_BLOCKED", "PROVIDER_LOAD_FAILED", "PROVIDER_RUNTIME_FAILED", "RECOVERY_FAILED", "REDIRECT_RESUME_FAILED", "REQUEST_TIMEOUT", "SDK_INITIALIZATION_FAILED", "THREE_DS_FAILED", "TOKENIZATION_FAILED", "VAULT_LOAD_FAILED", "VAULT_SUBMIT_FAILED"];
+type TelemetryErrorCode = (typeof TELEMETRY_ERROR_CODES)[number];
+declare const TELEMETRY_FAILURE_CATEGORIES: readonly ["server_error", "transport_error", "invalid_response", "provider_runtime"];
+type TelemetryFailureCategory = (typeof TELEMETRY_FAILURE_CATEGORIES)[number];
+/** Closed catalog of SDK-authored lifecycle and operational log names. */
+declare const TELEMETRY_LOG_NAMES: readonly ["sdk.initialize.started", "sdk.initialize.ready", "sdk.cache.hit", "sdk.cache.miss", "checkout.mount", "session.create.started", "session.shell.ready", "session.claim.started", "session.claim.completed", "session.read.started", "session.request.first_byte", "session.request.completed", "checkout.data.ready", "checkout.rendered", "checkout.recovery.started", "checkout.recovery.completed", "checkout.unmount", "provider.load.started", "provider.eligibility.checked", "provider.availability.checked", "provider.ready", "provider.popup.opened", "provider.overlay.opened", "provider.overlay.returned", "provider.redirect.started", "provider.redirect.resumed", "vault.capture.requested", "vault.widget.mounted", "vault.widget.ready", "vault.submission.started", "vault.action.required", "vault.three_ds.handoff", "vault.three_ds.returned", "vault.terminal", "payment.method.selected", "payment.intent.started", "payment.intent.completed", "payment.tokenization.started", "payment.tokenization.completed", "payment.processing.started", "payment.processing.completed", "payment.three_ds.handoff", "payment.three_ds.returned", "operation.retry", "operation.deduplicated", "operation.fallback", "operation.cache.hit", "operation.cache.miss", "operation.recovery.started", "operation.recovery.completed", "operation.state_transition"];
+type TelemetryLogName = (typeof TELEMETRY_LOG_NAMES)[number];
+declare const TELEMETRY_REQUEST_CATEGORIES: readonly ["session_create", "session_claim", "session_read", "intent_create", "process_payment", "vault_capture", "account_snapshot", "provider_sdk", "other"];
+type TelemetryRequestCategory = (typeof TELEMETRY_REQUEST_CATEGORIES)[number];
+declare const TELEMETRY_STATUS_CLASSES: readonly ["2xx", "3xx", "4xx", "5xx", "network_error", "timeout", "unknown"];
+type TelemetryStatusClass = (typeof TELEMETRY_STATUS_CLASSES)[number];
+declare const TELEMETRY_CHECKOUT_MODES: readonly ["full", "auto", "confirm", "setup", "unknown"];
+type TelemetryCheckoutMode = (typeof TELEMETRY_CHECKOUT_MODES)[number];
+declare const TELEMETRY_LAYOUTS: readonly ["embedded", "buttons", "automatic", "unknown"];
+type TelemetryLayout = (typeof TELEMETRY_LAYOUTS)[number];
+declare const TELEMETRY_DURATION_MODES: readonly ["machine", "buyer", "total"];
+type TelemetryDurationMode = (typeof TELEMETRY_DURATION_MODES)[number];
+declare const TELEMETRY_EXPECTED_OUTCOMES: readonly ["action_required", "card_setup_declined", "card_setup_succeeded", "customer_abandoned", "payment_cancelled", "payment_declined", "payment_authorized", "payment_succeeded", "validation_rejected"];
+type TelemetryExpectedOutcome = (typeof TELEMETRY_EXPECTED_OUTCOMES)[number];
+interface TelemetryCommonFields {
+    eventId: string;
+    stage: TelemetryStage;
+    sequence: number;
+    provider?: TelemetryProvider;
+    attempt?: number;
+    statusClass?: TelemetryStatusClass;
+    requestCategory?: TelemetryRequestCategory;
+    paymentMethodCategory?: TelemetryPaymentMethodCategory;
+    checkoutMode?: TelemetryCheckoutMode;
+    layout?: TelemetryLayout;
+}
+interface BuildTelemetryCommonInput {
+    eventId: string;
+    stage: TelemetryStage;
+    sequence: number;
+    provider?: TelemetryProviderInput;
+    attempt?: number;
+    statusClass?: TelemetryStatusClass;
+    requestCategory?: TelemetryRequestCategory;
+    paymentMethodCategory?: TelemetryPaymentMethodCategory;
+    checkoutMode?: TelemetryCheckoutMode;
+    layout?: TelemetryLayout;
+}
+interface TelemetryErrorEvent extends TelemetryCommonFields {
+    class: 'technical_error';
+    code: TelemetryErrorCode;
+    failureCategory?: TelemetryFailureCategory;
+}
+interface BuildTelemetryErrorEventInput extends BuildTelemetryCommonInput {
+    errorCode: TelemetryErrorCode;
+    failureCategory?: TelemetryFailureCategory;
+}
+interface TelemetryLogEvent extends TelemetryCommonFields {
+    class: 'lifecycle';
+    name: TelemetryLogName;
+}
+interface BuildTelemetryLogEventInput extends BuildTelemetryCommonInput {
+    name: TelemetryLogName;
+}
+interface TelemetryExpectedOutcomeEvent extends TelemetryCommonFields {
+    class: 'expected_outcome';
+    outcome: TelemetryExpectedOutcome;
+}
+interface BuildTelemetryTerminalEventInput extends Omit<BuildTelemetryCommonInput, 'stage'> {
+    outcome: TelemetryExpectedOutcome;
+    stage?: TelemetryStage;
+}
+interface TelemetryPerformanceEvent extends TelemetryCommonFields {
+    class: 'performance';
+    durationMs: number;
+    /** True when the measured duration exceeded the bounded wire value. */
+    durationTruncated?: true;
+    durationMode: TelemetryDurationMode;
+}
+interface BuildTelemetryPerformanceEventInput extends BuildTelemetryCommonInput {
+    durationMs: number;
+    /** Preserves a previously sanitized truncation marker during serialization. */
+    durationTruncated?: boolean;
+    durationMode: TelemetryDurationMode;
+}
+type TelemetryEvent = TelemetryErrorEvent | TelemetryLogEvent | TelemetryExpectedOutcomeEvent | TelemetryPerformanceEvent;
+interface SerializeTelemetryBatchOptions {
+    correlationId: string;
+    sdkPackage: TelemetrySdkPackage;
+    sdkVersion: string;
+    batchId?: string;
+}
+interface TelemetryBatchEnvelope {
+    schemaVersion: typeof TELEMETRY_SCHEMA_VERSION;
+    batchId: string;
+    correlationId: string;
+    sdk: {
+        package: TelemetrySdkPackage;
+        version: string;
+    };
+    events: TelemetryEvent[];
+}
+/** Build a closed SDK technical-error event. */
+declare function buildTelemetryErrorEvent(input: BuildTelemetryErrorEventInput): TelemetryErrorEvent;
+/** Build a typed SDK lifecycle event; arbitrary text is never accepted. */
+declare function buildTelemetryLogEvent(input: BuildTelemetryLogEventInput): TelemetryLogEvent;
+/** Build a non-error expected checkout outcome. */
+declare function buildTelemetryTerminalEvent(input: BuildTelemetryTerminalEventInput): TelemetryExpectedOutcomeEvent;
+/** Build a monotonic SDK-owned duration measurement. */
+declare function buildTelemetryPerformanceEvent(input: BuildTelemetryPerformanceEventInput): TelemetryPerformanceEvent;
+/** Serialize one closed backend-owned v1 telemetry envelope. */
+declare function serializeTelemetryBatch(events: readonly TelemetryEvent[], options: SerializeTelemetryBatchOptions): string;
+
+interface ClassifiedTelemetryFailure {
+    errorCode: TelemetryErrorCode;
+    statusClass: TelemetryStatusClass;
+    failureCategory?: TelemetryFailureCategory;
+}
+/**
+ * Classify the bounded billing response contract without reading free-form
+ * messages, error codes, or provider payloads.
+ */
+declare function classifyPaymentRejection(status: number, payload: unknown): Extract<TelemetryExpectedOutcome, 'payment_declined' | 'validation_rejected'> | undefined;
+/** Classify only SDK-owned error structure; never inspect messages or payloads. */
+declare function classifyTelemetryFailure(error: unknown, fallbackCode: TelemetryErrorCode, fallbackStatusClass?: TelemetryStatusClass): ClassifiedTelemetryFailure;
+declare function telemetryStatusClass(status: number | undefined, fallbackStatusClass?: TelemetryStatusClass): TelemetryStatusClass;
+
 /**
  * RFC 4122 v4 UUID shape (case-insensitive). Mirrors the backend's `@IsUUID()`
  * acceptance for the fields the SDK fills, e.g. the session-intent
@@ -2498,4 +2418,21 @@ declare function isUuidV4(value: unknown): value is string;
  */
 declare function randomUuidV4(): string;
 
-export { type AVSFieldConfig, BILLING_API_URL, BILLING_API_URL_PRODUCTION, BILLING_API_URL_STAGING, BOLD_DARK_APPEARANCE, BOLD_LIGHT_APPEARANCE, BUTTONS_LAYOUT_BOLD_DARK, BUTTONS_LAYOUT_BOLD_LIGHT, BUTTONS_LAYOUT_DARK, BUTTONS_LAYOUT_DEFAULT, BUTTONS_LAYOUT_GLASS_DARK, BUTTONS_LAYOUT_GLASS_LIGHT, BUTTONS_LAYOUT_MINIMAL, BUTTONS_LAYOUT_MODERN_DARK, BUTTONS_LAYOUT_MODERN_LIGHT, BUTTONS_LAYOUT_ROUNDED, type BeforeButtonClickEvent, type BillingDetails, type BillingProvider, type BuildCheckoutDisplayDataOptions, type BuildTelemetryErrorEventInput, type BuildTelemetryLogEventInput, type BuildTelemetryPerformanceEventInput, type BuildTelemetryTerminalEventInput, type ButtonsLayoutStyles, type ButtonsLayoutTheme, CA_PROVINCES, COUNTRY_OPTIONS, CURRENCY_MAP, type CaptureMethod, type CardCaptureAdapter, type CardCaptureEventType, type CardCaptureMountOptions, type CardCaptureOutcomeEvent, type CardCaptureProviderId, type CheckoutAccount, type CheckoutButtonMethod, type CheckoutDisplayData, type CheckoutFailureOutcome, type CheckoutGateway, type CheckoutGateways, type CheckoutItem, type CheckoutMode, type CheckoutModeKind, type CheckoutProcessError, type CheckoutProcessingPending, type CheckoutProduct, type CheckoutProductType, type CheckoutSession, type CheckoutSessionMode, type CheckoutSessionProduct, type CheckoutSessionResult, type CheckoutSubscription, type ClassifiedTelemetryFailure, type ConfirmPaymentParams, type CountryOption, type CreateCustomerParams, type CreateSessionIntentRequest, type CreateSessionParams, type CurrencyInfo, type Customer, DEFAULT_API_BASE_URL, DEFAULT_API_VERSION, DEFAULT_APPEARANCE, DEFAULT_CURRENCY, type DeclineEvent, type DetachedCheckoutSession, type DisplayLineItem, ELEMENT_TYPES, type ElementChangeEvent, type ElementOptions, type ElementType, FLAT_APPEARANCE, FLO_SDK_VERSION_HEADER, type FloPayAppearance, type FloPayConfig, type FloPayEnvironment, FloPayError, type FloPayErrorType, type FloPayThemeVariables, GLASS_DARK_APPEARANCE, GLASS_LIGHT_APPEARANCE, type GatewayEnvironment, IDEMPOTENCY_IN_PROGRESS_CODE, IDEMPOTENCY_KEY_HEADER, type InlineSessionDraft, type InlineSessionParams, type InlineSessionPatch, type LineItem, MAX_IDEMPOTENCY_KEY_LENGTH, MODERN_DARK_APPEARANCE, MODERN_LIGHT_APPEARANCE, type MountedElement, NIGHT_APPEARANCE, type NonCardPaymentMethodCategory, type NormalizedCheckoutSession, type NormalizedGatewayEnvironment, PAYPAL_VAULTED_PAYMENT_METHOD_TYPE, type PayPalPaymentResult, type PayPalProviderObjectType, type PayPalSessionIntent, type PayPalSessionIntentRequest, type PaymentMethodRemovalConflictCode, type PaymentMethodRemovalConflictError, type PaymentMethodRemovalError, type PaymentMethodRemovalFailureReason, type PaymentMethodRemovalNotFoundError, type PaymentMethodRemovalRetryableError, type PaymentProviderAdapter, type PaymentResult, type PriceData, type ProcessPaymentParams, type RecurringInterval, SDK_VERSION, STRIPE_EXPRESS_METHODS, STRIPE_METHOD_AMOUNT_LIMITS, STRIPE_METHOD_COUNTRIES, STRIPE_METHOD_CURRENCIES, STRIPE_METHOD_MATRIX, SUPPORTED_CARD_BRANDS, type SavedCardDisplay, type SavedPaymentMethodStatus, type SentryEventLike, type SentryStackFrameLike, type SerializeTelemetryBatchOptions, type SessionIntent, type SessionIntentDeclineRequest, type StateOption, type StripeMethodEntry, type StripeMethodThemeVariant, type StripeSessionIntent, type StripeSessionIntentRequest, TELEMETRY_ERROR_CODES, TELEMETRY_FAILURE_CATEGORIES, TELEMETRY_LOG_NAMES, TELEMETRY_MAX_BATCH_BYTES, TELEMETRY_MAX_BATCH_EVENTS, TELEMETRY_SCHEMA_VERSION, TELEMETRY_SDK_PACKAGES, THEMES, type TagsData, type TelemetryBatchEnvelope, type TelemetryCheckoutMode, type TelemetryDurationMode, type TelemetryErrorCode, type TelemetryErrorEvent, type TelemetryEvent, type TelemetryEventClass, type TelemetryExpectedOutcome, type TelemetryExpectedOutcomeEvent, type TelemetryFailureCategory, type TelemetryLayout, type TelemetryLogEvent, type TelemetryLogName, type TelemetryPaymentMethodCategory, type TelemetryPerformanceEvent, type TelemetryProvider, type TelemetryProviderInput, type TelemetryRequestCategory, type TelemetrySdkPackage, type TelemetryStage, type TelemetryStatusClass, type ThemeBundle, type ThemeBundleId, type ThemeId, type TokenizedBody, US_STATES, UUID_V4, type UpdateCustomerParams, type VaultCaptureBlock, type VaultCaptureResultMessage, type VaultCardFieldKey, type VaultCardThemeColors, type WebhookEvent, apiError, assertCaptureMethodEligible, authenticationError, buildCheckoutDisplayData, buildItemPayload, buildProductPayload, buildSubscriptionPayload, buildTelemetryErrorEvent, buildTelemetryLogEvent, buildTelemetryPerformanceEvent, buildTelemetryTerminalEvent, classifyPaymentRejection, classifyTelemetryFailure, configureFlopay, dropThirdPartyOnlyError, filterStripeMethodsByAmount, filterStripeMethodsByCountry, filterStripeMethodsByCurrency, foldIntoProducts, generateIdempotencyKey, getConfiguredBillingApiUrl, getCountryByCode, getCurrencyByCountry, getFloPayEnvironment, getPostalCodeExample, getPostalCodeLabel, getStateFromPostalCode, getStateLabel, getStateOptions, getStripeMethodDisplayName, hasVendoredStripeMethodLogo, isAVSEnabled, isAVSFieldVisible, isAuthorizationOnlySession, isCardSetupCheckoutSession, isDetachedSessionEligible, isMoneySettledOutcome, isPostalCodeSupported, isSetupIntentClientSecret, isUuidV4, isValidPostalCode, isValidPublishableKey, isValidSecretKey, needsStripeMethodExplicitConfirm, networkError, normalizeCheckoutFailureOutcome, normalizeGatewayEnvironment, partitionStripeMethods, randomUuidV4, rateLimitError, resolveAVSConfig, resolveBillingApiUrl, resolveButtonsLayoutTheme, resolveIdempotencyKey, resolveSessionCurrency, resolveStripeMethodBrandVariant, resolveTheme, serializeTelemetryBatch, stripeExpressMethodToOptionKey, telemetryStatusClass, validationError };
+/**
+ * Look up currency information by ISO 3166-1 alpha-2 country code.
+ * Falls back to USD when the country is not in the map.
+ */
+declare function getCurrencyByCountry(countryCode: string): CurrencyInfo;
+/** Returns `true` if the string looks like a Stripe publishable key. */
+declare function isValidPublishableKey(key: string): boolean;
+/** Returns `true` if the string looks like a Stripe secret key. */
+declare function isValidSecretKey(key: string): boolean;
+/**
+ * Returns `true` when the client secret belongs to a SetupIntent (`seti_…`).
+ * Trial-only / $0 checkouts confirm and retrieve a SetupIntent instead of a
+ * PaymentIntent, so callers must route those to `confirmCardSetup` /
+ * `retrieveSetupIntent` rather than the PaymentIntent equivalents.
+ */
+declare function isSetupIntentClientSecret(clientSecret: string | null | undefined): boolean;
+
+export { type AVSFieldConfig, BILLING_API_URL, BILLING_API_URL_PRODUCTION, BILLING_API_URL_STAGING, BOLD_DARK_APPEARANCE, BOLD_LIGHT_APPEARANCE, BUTTONS_LAYOUT_BOLD_DARK, BUTTONS_LAYOUT_BOLD_LIGHT, BUTTONS_LAYOUT_DARK, BUTTONS_LAYOUT_DEFAULT, BUTTONS_LAYOUT_GLASS_DARK, BUTTONS_LAYOUT_GLASS_LIGHT, BUTTONS_LAYOUT_MINIMAL, BUTTONS_LAYOUT_MODERN_DARK, BUTTONS_LAYOUT_MODERN_LIGHT, BUTTONS_LAYOUT_ROUNDED, type BeforeButtonClickEvent, type BillingDetails, type BillingProvider, type BuildCheckoutDisplayDataOptions, type BuildTelemetryErrorEventInput, type BuildTelemetryLogEventInput, type BuildTelemetryPerformanceEventInput, type BuildTelemetryTerminalEventInput, type ButtonsLayoutStyles, type ButtonsLayoutTheme, CA_PROVINCES, COUNTRY_OPTIONS, CURRENCY_MAP, type CaptureMethod, type CardCaptureAdapter, type CardCaptureEventType, type CardCaptureMountOptions, type CardCaptureOutcomeEvent, type CardCaptureProviderId, type CheckoutAccount, type CheckoutButtonMethod, type CheckoutDisplayData, type CheckoutFailureOutcome, type CheckoutGateway, type CheckoutGateways, type CheckoutItem, type CheckoutMode, type CheckoutModeKind, type CheckoutProcessError, type CheckoutProcessingPending, type CheckoutProduct, type CheckoutProductType, type CheckoutSession, type CheckoutSessionMode, type CheckoutSessionProduct, type CheckoutSessionResult, type CheckoutSubscription, type ClassifiedTelemetryFailure, type CountryOption, type CreateCustomerParams, type CreateSessionIntentRequest, type CreateSessionParams, type CurrencyInfo, type Customer, DEFAULT_API_BASE_URL, DEFAULT_API_VERSION, DEFAULT_APPEARANCE, DEFAULT_CURRENCY, type DeclineEvent, type DetachedCheckoutSession, type DisplayLineItem, FLAT_APPEARANCE, FLO_INSTRUMENT_CATALOG, FLO_INSTRUMENT_SCHEMA_VERSION, FLO_SDK_VERSION_HEADER, type FloInstrumentErrorPhase, type FloInstrumentEvent, type FloInstrumentLifecycleName, type FloPayAppearance, type FloPayConfig, type FloPayEnvironment, FloPayError, type FloPayErrorType, type FloPayThemeVariables, GLASS_DARK_APPEARANCE, GLASS_LIGHT_APPEARANCE, type GatewayEnvironment, IDEMPOTENCY_IN_PROGRESS_CODE, IDEMPOTENCY_KEY_HEADER, type InlineSessionDraft, type InlineSessionParams, type InlineSessionPatch, type LineItem, MAX_IDEMPOTENCY_KEY_LENGTH, MODERN_DARK_APPEARANCE, MODERN_LIGHT_APPEARANCE, NIGHT_APPEARANCE, type NonCardPaymentMethodCategory, type NormalizedCheckoutSession, type NormalizedGatewayEnvironment, PAYPAL_VAULTED_PAYMENT_METHOD_TYPE, type PayPalPaymentResult, type PayPalProviderObjectType, type PayPalSessionIntent, type PayPalSessionIntentRequest, type PaymentMethodRemovalConflictCode, type PaymentMethodRemovalConflictError, type PaymentMethodRemovalError, type PaymentMethodRemovalFailureReason, type PaymentMethodRemovalNotFoundError, type PaymentMethodRemovalRetryableError, type PaymentProviderAdapter, type PaymentResult, type PriceData, type ProcessPaymentParams, type RecurringInterval, SDK_VERSION, STRIPE_EXPRESS_METHODS, STRIPE_METHOD_AMOUNT_LIMITS, STRIPE_METHOD_COUNTRIES, STRIPE_METHOD_CURRENCIES, STRIPE_METHOD_MATRIX, SUPPORTED_CARD_BRANDS, type SavedCardDisplay, type SavedPaymentMethodStatus, type SentryEventLike, type SentryStackFrameLike, type SerializeTelemetryBatchOptions, type SessionIntent, type SessionIntentDeclineRequest, type StateOption, type StripeMethodEntry, type StripeMethodThemeVariant, type StripeSessionIntent, type StripeSessionIntentRequest, TELEMETRY_ERROR_CODES, TELEMETRY_FAILURE_CATEGORIES, TELEMETRY_LOG_NAMES, TELEMETRY_MAX_BATCH_BYTES, TELEMETRY_MAX_BATCH_EVENTS, TELEMETRY_SCHEMA_VERSION, TELEMETRY_SDK_PACKAGES, THEMES, type TagsData, type TelemetryBatchEnvelope, type TelemetryCheckoutMode, type TelemetryDurationMode, type TelemetryErrorCode, type TelemetryErrorEvent, type TelemetryEvent, type TelemetryEventClass, type TelemetryExpectedOutcome, type TelemetryExpectedOutcomeEvent, type TelemetryFailureCategory, type TelemetryLayout, type TelemetryLogEvent, type TelemetryLogName, type TelemetryPaymentMethodCategory, type TelemetryPerformanceEvent, type TelemetryProvider, type TelemetryProviderInput, type TelemetryRequestCategory, type TelemetrySdkPackage, type TelemetryStage, type TelemetryStatusClass, type ThemeBundle, type ThemeBundleId, type ThemeId, type TokenizedBody, US_STATES, UUID_V4, type UpdateCustomerParams, type VaultCaptureBlock, type VaultCaptureResultMessage, type VaultCardFieldKey, type VaultCardThemeColors, type WebhookEvent, apiError, assertCaptureMethodEligible, authenticationError, buildCheckoutDisplayData, buildItemPayload, buildProductPayload, buildSubscriptionPayload, buildTelemetryErrorEvent, buildTelemetryLogEvent, buildTelemetryPerformanceEvent, buildTelemetryTerminalEvent, classifyPaymentRejection, classifyTelemetryFailure, configureFlopay, dropThirdPartyOnlyError, filterStripeMethodsByAmount, filterStripeMethodsByCountry, filterStripeMethodsByCurrency, foldIntoProducts, generateIdempotencyKey, getConfiguredBillingApiUrl, getCountryByCode, getCurrencyByCountry, getFloPayEnvironment, getPostalCodeExample, getPostalCodeLabel, getStateFromPostalCode, getStateLabel, getStateOptions, getStripeMethodDisplayName, hasVendoredStripeMethodLogo, isAVSEnabled, isAVSFieldVisible, isAuthorizationOnlySession, isCardSetupCheckoutSession, isDetachedSessionEligible, isMoneySettledOutcome, isPostalCodeSupported, isSetupIntentClientSecret, isUuidV4, isValidPostalCode, isValidPublishableKey, isValidSecretKey, needsStripeMethodExplicitConfirm, networkError, normalizeCheckoutFailureOutcome, normalizeGatewayEnvironment, partitionStripeMethods, randomUuidV4, rateLimitError, resolveAVSConfig, resolveBillingApiUrl, resolveButtonsLayoutTheme, resolveIdempotencyKey, resolveSessionCurrency, resolveStripeMethodBrandVariant, resolveTheme, serializeTelemetryBatch, stripeExpressMethodToOptionKey, telemetryStatusClass, validationError };