@flopay/shared 1.5.0 → 1.7.0

package/dist/index.d.cts

@@ -344,6 +344,20 @@ interface CheckoutGateway {
      * backends (the SDK then falls back to its built-in table).
      */
     enabledPaymentMethodCountries?: Record<string, string[]>;
+    /**
+     * PayPal object the backend selected for this checkout continuation — which
+     * PayPal JS flow the session needs. New backends advertise `'order'` or
+     * `'setup_token'` (legacy provider-managed subscriptions are expressed by
+     * omission, though `'subscription'` remains accepted for robustness). Absent
+     * → released fallback: `isSubscription ? 'subscription' : 'order'`. The
+     * backend suppresses this advertisement for `x-flo-sdk-version` readers
+     * older than 1.6.0 (header-less direct integrations always see it);
+     * advertisement only — routing follows the payment-method type the client
+     * requests. On `gateways.paypal`, {@link enabledPaymentMethods} may also
+     * carry an informational `'paypal_vaulted'` entry when the Flo-owned
+     * channel is available.
+     */
+    providerObjectType?: PayPalProviderObjectType;
 }
 /**
  * Map of gateways attached to a session, keyed by gateway code. A session can
@@ -507,30 +521,72 @@ interface StripeSessionIntentRequest extends SessionIntentAuthorizationAttempt {
     paymentMethodId: string | null;
     intentKind: 'payment' | 'setup';
 }
-/**
- * Direct PayPal intent request. Always `intentKind: 'payment'`: the backend
- * derives order vs subscription from the session's products and returns that as
- * the response `providerObjectType`. PayPal setup intents are unsupported —
- * PayPal vaults during a successful Order capture, not via standalone setups.
- */
-interface PayPalSessionIntentRequest extends SessionIntentAuthorizationAttempt {
+/** Fields shared by every direct PayPal intent request channel. */
+interface PayPalSessionIntentRequestBase extends SessionIntentAuthorizationAttempt {
     provider: 'paypal';
     paymentMethodCategory: 'wallet';
-    paymentMethodType: 'paypal';
     paymentMethodId: null;
+}
+/**
+ * Legacy provider-managed channel. `paymentMethodType: 'paypal'` keeps the
+ * released contract byte-identical: always `intentKind: 'payment'`, and the
+ * backend derives Order vs provider-managed Subscription from the session.
+ */
+interface PayPalLegacySessionIntentRequest extends PayPalSessionIntentRequestBase {
+    paymentMethodType: 'paypal';
+    intentKind: 'payment';
+}
+/**
+ * Flo-owned channel, payment continuation. `paymentMethodType:
+ * 'paypal_vaulted'` with `intentKind: 'payment'` requests a Flo-owned PayPal
+ * Order (advertised as `providerObjectType: 'order'`).
+ */
+interface PayPalVaultedPaymentSessionIntentRequest extends PayPalSessionIntentRequestBase {
+    paymentMethodType: 'paypal_vaulted';
     intentKind: 'payment';
 }
+/**
+ * Flo-owned channel, setup continuation. `paymentMethodType: 'paypal_vaulted'`
+ * with `intentKind: 'setup'` requests a PayPal vault setup token for an
+ * item-free deferred Flo-owned start (advertised as `providerObjectType:
+ * 'setup_token'`).
+ */
+interface PayPalVaultedSetupSessionIntentRequest extends PayPalSessionIntentRequestBase {
+    paymentMethodType: 'paypal_vaulted';
+    intentKind: 'setup';
+}
+/**
+ * Direct PayPal intent request. The payment-method type is the in-band channel
+ * selector: `'paypal'` keeps provider-managed semantics, `'paypal_vaulted'`
+ * opts the request into the Flo-owned channel. The union makes the invalid
+ * combination (`'paypal'` with `intentKind: 'setup'`) unrepresentable.
+ */
+type PayPalSessionIntentRequest = PayPalLegacySessionIntentRequest | PayPalVaultedPaymentSessionIntentRequest | PayPalVaultedSetupSessionIntentRequest;
 type CreateSessionIntentRequest = StripeSessionIntentRequest | PayPalSessionIntentRequest;
 interface StripeSessionIntent extends StripeSessionIntentRequest {
     clientSecret: string;
     providerObjectId: string;
 }
-interface PayPalSessionIntent extends PayPalSessionIntentRequest {
+interface PayPalSessionIntentResponse {
     clientSecret: null;
     providerObjectId: string;
-    /** Server-derived from the session's products (a subscription product → 'subscription'). */
-    providerObjectType: 'order' | 'subscription';
 }
+/**
+ * Direct PayPal intent response. The response echoes the request fields and
+ * correlates the selected provider object with the requested channel so
+ * impossible wire responses are not representable to SDK consumers:
+ *
+ * - `'paypal'` + `'payment'` ↔ `providerObjectType: 'order' | 'subscription'`
+ * - `'paypal_vaulted'` + `'payment'` ↔ `providerObjectType: 'order'`
+ * - `'paypal_vaulted'` + `'setup'` ↔ `providerObjectType: 'setup_token'`
+ */
+type PayPalSessionIntent = (PayPalLegacySessionIntentRequest & PayPalSessionIntentResponse & {
+    providerObjectType: 'order' | 'subscription';
+}) | (PayPalVaultedPaymentSessionIntentRequest & PayPalSessionIntentResponse & {
+    providerObjectType: 'order';
+}) | (PayPalVaultedSetupSessionIntentRequest & PayPalSessionIntentResponse & {
+    providerObjectType: 'setup_token';
+});
 type SessionIntent = StripeSessionIntent | PayPalSessionIntent;
 type SessionIntentDeclineRequest = {
     provider: 'stripe';
@@ -950,6 +1006,8 @@ interface CardCaptureAdapter {
 type VaultCardFieldKey = 'name' | 'number' | 'expiry';
 /** Supported upstream gateway codes. */
 type BillingProvider = 'stripe' | 'paypal';
+/** PayPal continuation object selected by the billing backend. */
+type PayPalProviderObjectType = 'order' | 'subscription' | 'setup_token';
 /** Token payload produced by client-side tokenization. */
 interface TokenizedBody {
     id?: string;
@@ -958,8 +1016,9 @@ interface TokenizedBody {
     originalPaymentMethodId?: string;
     /**
      * @deprecated Use {@link TokenizedBody.gateway} + {@link TokenizedBody.paymentMethodType}.
-     * Still populated by the SDK for PayPal payments so backends that gate on
-     * `isPaypal === 'true'` keep working through the deprecation window.
+     * Still populated by the SDK for PayPal compatibility as the boolean `true`,
+     * never the string `"true"`. New integrations must route by `gateway` and
+     * `paymentMethodType` instead.
      */
     isPaypal?: boolean;
     /**
@@ -1056,6 +1115,7 @@ interface NormalizedCheckoutSession {
         paypal?: {
             publishableKey?: string;
             environment?: GatewayEnvironment;
+            providerObjectType?: PayPalProviderObjectType;
         };
     };
     raw?: unknown;
@@ -1516,218 +1576,173 @@ 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.
- */
-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';
-/**
- * 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' });
+ * Reject authorisation-only checkout carts that contain a subscription.
  *
- * // In staging/development
- * configureFlopay({ environment: 'staging' });
- * ```
+ * The backend remains authoritative; this shared preflight keeps every SDK
+ * creation style from mounting or redirecting to a checkout that cannot
+ * support manual capture.
  *
- * Alternatively, set the `NEXT_PUBLIC_FLOPAY_ENV` environment variable
- * to `'staging'` or `'production'` — the SDK reads it automatically.
+ * 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 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.5.0";
+declare function assertCaptureMethodEligible(params: CaptureMethodEligibilityParams): void;
 /**
- * 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
- * can discover hosted card capture from an explicit Stripe `card` capability
- * and recover the widget lazily when `session.vault` is omitted.
+ * Whether a session may be created through the **detached** shell + claim flow
+ * (TeamFloPay/backend#1099).
  *
- * @see SDK_VERSION — the value sent in this header.
+ * 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 const FLO_SDK_VERSION_HEADER = "x-flo-sdk-version";
-/** Billing API URL for staging environment. */
-declare const BILLING_API_URL_STAGING = "https://api.stage.flopay.com";
-/** Billing API URL for production environment. */
-declare const BILLING_API_URL_PRODUCTION = "https://api.flopay.com";
-/** Default FloPay API base URL (used by @flopay/node). Alias for staging. */
-declare const DEFAULT_API_BASE_URL = "https://api.stage.flopay.com";
-/** Default billing API base URL. Alias for staging — prefer `resolveBillingApiUrl()`. */
-declare const BILLING_API_URL = "https://api.stage.flopay.com";
+declare function isDetachedSessionEligible(params: InlineSessionDraft): boolean;
 /**
- * Resolve the billing API URL from available configuration.
+ * Resolve the session-level currency, honoring the documented fallback:
+ * `session.currency ?? items[*].currency ?? subscriptions[*].currency ?? products[*].currency`.
  *
- * Priority:
- * 1. Explicit `billingApiUrl` (prop/param override)
+ * 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>;
+
+/** 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.7.0";
+/**
+ * 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
+ * can discover hosted card capture from an explicit Stripe `card` capability
+ * and recover the widget lazily when `session.vault` is omitted. The backend
+ * also uses this value to suppress the Flo-owned PayPal advertisement fields
+ * (`gateways.paypal.providerObjectType` and the `paypal_vaulted` entry in
+ * `enabledPaymentMethods`) for readers older than 1.6.0 — advertisement only,
+ * never request routing.
+ *
+ * @see SDK_VERSION — the value sent in this header.
+ */
+declare const FLO_SDK_VERSION_HEADER = "x-flo-sdk-version";
+/**
+ * In-band payment-method CHANNEL for Flo-owned PayPal continuations.
+ *
+ * The payment-method type sent to `POST /v1/checkouts/sessions/{id}/intents`
+ * is the channel selector: requesting `paypal_vaulted` opts a single request
+ * into the Flo-owned channel (an Order for `intentKind: 'payment'`, a vault
+ * setup token for `intentKind: 'setup'`), while the legacy `paypal` type keeps
+ * the released provider-managed semantics byte-identical — even when the
+ * backend feature flag is on. Sessions advertise availability via
+ * `gateways.paypal.providerObjectType` and an informational `paypal_vaulted`
+ * entry in `gateways.paypal.enabledPaymentMethods`; there is no capability
+ * header and no version-gated routing.
+ */
+declare const PAYPAL_VAULTED_PAYMENT_METHOD_TYPE = "paypal_vaulted";
+/** Billing API URL for staging environment. */
+declare const BILLING_API_URL_STAGING = "https://api.stage.flopay.com";
+/** Billing API URL for production environment. */
+declare const BILLING_API_URL_PRODUCTION = "https://api.flopay.com";
+/** Default FloPay API base URL (used by @flopay/node). Alias for staging. */
+declare const DEFAULT_API_BASE_URL = "https://api.stage.flopay.com";
+/** Default billing API base URL. Alias for staging — prefer `resolveBillingApiUrl()`. */
+declare const BILLING_API_URL = "https://api.stage.flopay.com";
+/**
+ * Resolve the billing API URL from available configuration.
+ *
+ * Priority:
+ * 1. Explicit `billingApiUrl` (prop/param override)
  * 2. `NEXT_PUBLIC_FLOPAY_ENV` environment variable (`'staging'` | `'production'`)
  * 3. `configureFlopay()` global environment setting
  * 4. Fallback: staging URL
@@ -2116,58 +2131,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;
@@ -2232,118 +2195,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).
@@ -2400,6 +2251,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", "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;
+
+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
@@ -2420,4 +2531,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, type PayPalPaymentResult, 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 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_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, 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 };