@flopay/shared 1.3.4 → 1.4.1

package/dist/index.d.cts

@@ -413,12 +413,20 @@ interface ConfirmCardPaymentParams {
     clientSecret: string;
     paymentMethodId: string;
 }
+/** Provider-observed 3DS lifecycle for one opaque, attempt-scoped confirmation. */
+interface CardThreeDsLifecycle {
+    /** Opaque in-memory identifier; never derived from payment identifiers. */
+    attemptId: string;
+    status: 'handoff' | 'returned' | 'failed';
+}
 /** Result from confirming a card payment. */
 interface ConfirmCardPaymentResult {
     status: 'succeeded' | 'processing' | 'requires_action' | 'requires_capture' | 'failed';
     paymentIntentId?: string;
     paymentMethodId?: string;
     error?: FloPayError;
+    /** @internal Provider-observed lifecycle used for privacy-safe telemetry. */
+    threeDs?: CardThreeDsLifecycle;
 }
 /** The type of payment element to render. */
 type ElementType = 'payment' | 'card' | 'cardNumber' | 'cardExpiry' | 'cardCvc' | 'address';
@@ -493,6 +501,12 @@ interface FloPayConfig {
     publishableKey: string;
     /** Billing API base URL (e.g. https://api.stage.flopay.com). */
     billingApiUrl?: string;
+    /**
+     * Flo-owned privacy-safe operational telemetry. Enabled by default; set to
+     * `false` to opt out. This intentionally accepts no endpoint, tags, user
+     * context, messages, or custom metadata.
+     */
+    telemetry?: boolean;
     locale?: string;
     appearance?: FloPayAppearance;
     apiVersion?: string;
@@ -1051,6 +1065,8 @@ interface CreateSessionParams {
     billingApiUrl: string;
     /** Base URL of the checkout frontend, e.g. https://checkout.clicktech.com */
     checkoutBaseUrl: string;
+    /** Flo-owned privacy-safe telemetry is enabled by default; set false to opt out. */
+    telemetry?: boolean;
     /** The client ID for the checkout session. */
     clientId: string;
     /**
@@ -1302,6 +1318,120 @@ interface CountryOption {
     flag: string;
 }
 
+/** 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_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];
+/** 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.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_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", "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", "customer_abandoned", "payment_cancelled", "payment_declined", "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;
+}
+interface BuildTelemetryErrorEventInput extends BuildTelemetryCommonInput {
+    errorCode: TelemetryErrorCode;
+}
+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;
+    durationMode: TelemetryDurationMode;
+}
+interface BuildTelemetryPerformanceEventInput extends BuildTelemetryCommonInput {
+    durationMs: number;
+    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;
+
 /** FloPay environment — determines which billing API URL is used. */
 type FloPayEnvironment = 'staging' | 'production' | 'local';
 /**
@@ -1333,7 +1463,7 @@ declare function getConfiguredBillingApiUrl(): string;
 declare function getFloPayEnvironment(): FloPayEnvironment;
 
 /** Current SDK version. */
-declare const SDK_VERSION = "1.3.4";
+declare const SDK_VERSION = "1.4.1";
 /**
  * HTTP header the SDK sends on `POST /v1/checkouts/sessions` so the backend
  * can decide whether to embed the vault capture block (the hosted PCI card
@@ -1984,4 +2114,4 @@ declare function generateIdempotencyKey(): string | undefined;
  */
 declare function resolveIdempotencyKey(supplied?: string): string | undefined;
 
-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 ButtonsLayoutStyles, type ButtonsLayoutTheme, CA_PROVINCES, COUNTRY_OPTIONS, CURRENCY_MAP, type CardCaptureAdapter, type CardCaptureEventType, type CardCaptureMountOptions, type CardCaptureOutcomeEvent, type CardCaptureProviderId, type CheckoutAccount, type CheckoutButtonMethod, type CheckoutDisplayData, type CheckoutGateway, type CheckoutGateways, type CheckoutItem, type CheckoutMode, type CheckoutModeKind, type CheckoutProcessError, type CheckoutProcessingPending, type CheckoutProduct, type CheckoutProductType, type CheckoutSession, type CheckoutSessionProduct, type CheckoutSessionResult, type CheckoutSubscription, type ConfirmCardPaymentParams, type ConfirmCardPaymentResult, type ConfirmPaymentParams, type CountryOption, type CreateCustomerParams, type CreatePaymentMethodResult, type CreateSessionParams, type CurrencyInfo, type Customer, DEFAULT_API_BASE_URL, DEFAULT_API_VERSION, DEFAULT_APPEARANCE, DEFAULT_CURRENCY, type DeclineEvent, 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 NormalizedCheckoutSession, type NormalizedGatewayEnvironment, 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 StateOption, type StripeMethodEntry, type StripeMethodThemeVariant, THEMES, type TagsData, type ThemeBundle, type ThemeBundleId, type ThemeId, type TokenizedBody, US_STATES, type UpdateCustomerParams, type VaultCaptureBlock, type VaultCaptureResultMessage, type VaultCardFieldKey, type VaultCardThemeColors, type WebhookEvent, apiError, authenticationError, buildCheckoutDisplayData, buildItemPayload, buildProductPayload, buildSubscriptionPayload, configureFlopay, filterStripeMethodsByAmount, filterStripeMethodsByCountry, filterStripeMethodsByCurrency, foldIntoProducts, generateIdempotencyKey, getConfiguredBillingApiUrl, getCountryByCode, getCurrencyByCountry, getFloPayEnvironment, getPostalCodeExample, getPostalCodeLabel, getStateFromPostalCode, getStateLabel, getStateOptions, getStripeMethodDisplayName, hasVendoredStripeMethodLogo, isAVSEnabled, isAVSFieldVisible, isPostalCodeSupported, isSetupIntentClientSecret, isValidPostalCode, isValidPublishableKey, isValidSecretKey, needsStripeMethodExplicitConfirm, networkError, normalizeGatewayEnvironment, partitionStripeMethods, rateLimitError, resolveAVSConfig, resolveBillingApiUrl, resolveButtonsLayoutTheme, resolveIdempotencyKey, resolveSessionCurrency, resolveStripeMethodBrandVariant, resolveTheme, stripeExpressMethodToOptionKey, validationError };
+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 CardCaptureAdapter, type CardCaptureEventType, type CardCaptureMountOptions, type CardCaptureOutcomeEvent, type CardCaptureProviderId, type CardThreeDsLifecycle, type CheckoutAccount, type CheckoutButtonMethod, type CheckoutDisplayData, type CheckoutGateway, type CheckoutGateways, type CheckoutItem, type CheckoutMode, type CheckoutModeKind, type CheckoutProcessError, type CheckoutProcessingPending, type CheckoutProduct, type CheckoutProductType, type CheckoutSession, type CheckoutSessionProduct, type CheckoutSessionResult, type CheckoutSubscription, type ConfirmCardPaymentParams, type ConfirmCardPaymentResult, type ConfirmPaymentParams, type CountryOption, type CreateCustomerParams, type CreatePaymentMethodResult, type CreateSessionParams, type CurrencyInfo, type Customer, DEFAULT_API_BASE_URL, DEFAULT_API_VERSION, DEFAULT_APPEARANCE, DEFAULT_CURRENCY, type DeclineEvent, 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 NormalizedCheckoutSession, type NormalizedGatewayEnvironment, 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 SerializeTelemetryBatchOptions, type StateOption, type StripeMethodEntry, type StripeMethodThemeVariant, TELEMETRY_ERROR_CODES, 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 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, type UpdateCustomerParams, type VaultCaptureBlock, type VaultCaptureResultMessage, type VaultCardFieldKey, type VaultCardThemeColors, type WebhookEvent, apiError, authenticationError, buildCheckoutDisplayData, buildItemPayload, buildProductPayload, buildSubscriptionPayload, buildTelemetryErrorEvent, buildTelemetryLogEvent, buildTelemetryPerformanceEvent, buildTelemetryTerminalEvent, configureFlopay, filterStripeMethodsByAmount, filterStripeMethodsByCountry, filterStripeMethodsByCurrency, foldIntoProducts, generateIdempotencyKey, getConfiguredBillingApiUrl, getCountryByCode, getCurrencyByCountry, getFloPayEnvironment, getPostalCodeExample, getPostalCodeLabel, getStateFromPostalCode, getStateLabel, getStateOptions, getStripeMethodDisplayName, hasVendoredStripeMethodLogo, isAVSEnabled, isAVSFieldVisible, isPostalCodeSupported, isSetupIntentClientSecret, isValidPostalCode, isValidPublishableKey, isValidSecretKey, needsStripeMethodExplicitConfirm, networkError, normalizeGatewayEnvironment, partitionStripeMethods, rateLimitError, resolveAVSConfig, resolveBillingApiUrl, resolveButtonsLayoutTheme, resolveIdempotencyKey, resolveSessionCurrency, resolveStripeMethodBrandVariant, resolveTheme, serializeTelemetryBatch, stripeExpressMethodToOptionKey, validationError };

package/dist/index.d.ts

@@ -413,12 +413,20 @@ interface ConfirmCardPaymentParams {
     clientSecret: string;
     paymentMethodId: string;
 }
+/** Provider-observed 3DS lifecycle for one opaque, attempt-scoped confirmation. */
+interface CardThreeDsLifecycle {
+    /** Opaque in-memory identifier; never derived from payment identifiers. */
+    attemptId: string;
+    status: 'handoff' | 'returned' | 'failed';
+}
 /** Result from confirming a card payment. */
 interface ConfirmCardPaymentResult {
     status: 'succeeded' | 'processing' | 'requires_action' | 'requires_capture' | 'failed';
     paymentIntentId?: string;
     paymentMethodId?: string;
     error?: FloPayError;
+    /** @internal Provider-observed lifecycle used for privacy-safe telemetry. */
+    threeDs?: CardThreeDsLifecycle;
 }
 /** The type of payment element to render. */
 type ElementType = 'payment' | 'card' | 'cardNumber' | 'cardExpiry' | 'cardCvc' | 'address';
@@ -493,6 +501,12 @@ interface FloPayConfig {
     publishableKey: string;
     /** Billing API base URL (e.g. https://api.stage.flopay.com). */
     billingApiUrl?: string;
+    /**
+     * Flo-owned privacy-safe operational telemetry. Enabled by default; set to
+     * `false` to opt out. This intentionally accepts no endpoint, tags, user
+     * context, messages, or custom metadata.
+     */
+    telemetry?: boolean;
     locale?: string;
     appearance?: FloPayAppearance;
     apiVersion?: string;
@@ -1051,6 +1065,8 @@ interface CreateSessionParams {
     billingApiUrl: string;
     /** Base URL of the checkout frontend, e.g. https://checkout.clicktech.com */
     checkoutBaseUrl: string;
+    /** Flo-owned privacy-safe telemetry is enabled by default; set false to opt out. */
+    telemetry?: boolean;
     /** The client ID for the checkout session. */
     clientId: string;
     /**
@@ -1302,6 +1318,120 @@ interface CountryOption {
     flag: string;
 }
 
+/** 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_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];
+/** 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.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_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", "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", "customer_abandoned", "payment_cancelled", "payment_declined", "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;
+}
+interface BuildTelemetryErrorEventInput extends BuildTelemetryCommonInput {
+    errorCode: TelemetryErrorCode;
+}
+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;
+    durationMode: TelemetryDurationMode;
+}
+interface BuildTelemetryPerformanceEventInput extends BuildTelemetryCommonInput {
+    durationMs: number;
+    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;
+
 /** FloPay environment — determines which billing API URL is used. */
 type FloPayEnvironment = 'staging' | 'production' | 'local';
 /**
@@ -1333,7 +1463,7 @@ declare function getConfiguredBillingApiUrl(): string;
 declare function getFloPayEnvironment(): FloPayEnvironment;
 
 /** Current SDK version. */
-declare const SDK_VERSION = "1.3.4";
+declare const SDK_VERSION = "1.4.1";
 /**
  * HTTP header the SDK sends on `POST /v1/checkouts/sessions` so the backend
  * can decide whether to embed the vault capture block (the hosted PCI card
@@ -1984,4 +2114,4 @@ declare function generateIdempotencyKey(): string | undefined;
  */
 declare function resolveIdempotencyKey(supplied?: string): string | undefined;
 
-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 ButtonsLayoutStyles, type ButtonsLayoutTheme, CA_PROVINCES, COUNTRY_OPTIONS, CURRENCY_MAP, type CardCaptureAdapter, type CardCaptureEventType, type CardCaptureMountOptions, type CardCaptureOutcomeEvent, type CardCaptureProviderId, type CheckoutAccount, type CheckoutButtonMethod, type CheckoutDisplayData, type CheckoutGateway, type CheckoutGateways, type CheckoutItem, type CheckoutMode, type CheckoutModeKind, type CheckoutProcessError, type CheckoutProcessingPending, type CheckoutProduct, type CheckoutProductType, type CheckoutSession, type CheckoutSessionProduct, type CheckoutSessionResult, type CheckoutSubscription, type ConfirmCardPaymentParams, type ConfirmCardPaymentResult, type ConfirmPaymentParams, type CountryOption, type CreateCustomerParams, type CreatePaymentMethodResult, type CreateSessionParams, type CurrencyInfo, type Customer, DEFAULT_API_BASE_URL, DEFAULT_API_VERSION, DEFAULT_APPEARANCE, DEFAULT_CURRENCY, type DeclineEvent, 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 NormalizedCheckoutSession, type NormalizedGatewayEnvironment, 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 StateOption, type StripeMethodEntry, type StripeMethodThemeVariant, THEMES, type TagsData, type ThemeBundle, type ThemeBundleId, type ThemeId, type TokenizedBody, US_STATES, type UpdateCustomerParams, type VaultCaptureBlock, type VaultCaptureResultMessage, type VaultCardFieldKey, type VaultCardThemeColors, type WebhookEvent, apiError, authenticationError, buildCheckoutDisplayData, buildItemPayload, buildProductPayload, buildSubscriptionPayload, configureFlopay, filterStripeMethodsByAmount, filterStripeMethodsByCountry, filterStripeMethodsByCurrency, foldIntoProducts, generateIdempotencyKey, getConfiguredBillingApiUrl, getCountryByCode, getCurrencyByCountry, getFloPayEnvironment, getPostalCodeExample, getPostalCodeLabel, getStateFromPostalCode, getStateLabel, getStateOptions, getStripeMethodDisplayName, hasVendoredStripeMethodLogo, isAVSEnabled, isAVSFieldVisible, isPostalCodeSupported, isSetupIntentClientSecret, isValidPostalCode, isValidPublishableKey, isValidSecretKey, needsStripeMethodExplicitConfirm, networkError, normalizeGatewayEnvironment, partitionStripeMethods, rateLimitError, resolveAVSConfig, resolveBillingApiUrl, resolveButtonsLayoutTheme, resolveIdempotencyKey, resolveSessionCurrency, resolveStripeMethodBrandVariant, resolveTheme, stripeExpressMethodToOptionKey, validationError };
+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 CardCaptureAdapter, type CardCaptureEventType, type CardCaptureMountOptions, type CardCaptureOutcomeEvent, type CardCaptureProviderId, type CardThreeDsLifecycle, type CheckoutAccount, type CheckoutButtonMethod, type CheckoutDisplayData, type CheckoutGateway, type CheckoutGateways, type CheckoutItem, type CheckoutMode, type CheckoutModeKind, type CheckoutProcessError, type CheckoutProcessingPending, type CheckoutProduct, type CheckoutProductType, type CheckoutSession, type CheckoutSessionProduct, type CheckoutSessionResult, type CheckoutSubscription, type ConfirmCardPaymentParams, type ConfirmCardPaymentResult, type ConfirmPaymentParams, type CountryOption, type CreateCustomerParams, type CreatePaymentMethodResult, type CreateSessionParams, type CurrencyInfo, type Customer, DEFAULT_API_BASE_URL, DEFAULT_API_VERSION, DEFAULT_APPEARANCE, DEFAULT_CURRENCY, type DeclineEvent, 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 NormalizedCheckoutSession, type NormalizedGatewayEnvironment, 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 SerializeTelemetryBatchOptions, type StateOption, type StripeMethodEntry, type StripeMethodThemeVariant, TELEMETRY_ERROR_CODES, 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 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, type UpdateCustomerParams, type VaultCaptureBlock, type VaultCaptureResultMessage, type VaultCardFieldKey, type VaultCardThemeColors, type WebhookEvent, apiError, authenticationError, buildCheckoutDisplayData, buildItemPayload, buildProductPayload, buildSubscriptionPayload, buildTelemetryErrorEvent, buildTelemetryLogEvent, buildTelemetryPerformanceEvent, buildTelemetryTerminalEvent, configureFlopay, filterStripeMethodsByAmount, filterStripeMethodsByCountry, filterStripeMethodsByCurrency, foldIntoProducts, generateIdempotencyKey, getConfiguredBillingApiUrl, getCountryByCode, getCurrencyByCountry, getFloPayEnvironment, getPostalCodeExample, getPostalCodeLabel, getStateFromPostalCode, getStateLabel, getStateOptions, getStripeMethodDisplayName, hasVendoredStripeMethodLogo, isAVSEnabled, isAVSFieldVisible, isPostalCodeSupported, isSetupIntentClientSecret, isValidPostalCode, isValidPublishableKey, isValidSecretKey, needsStripeMethodExplicitConfirm, networkError, normalizeGatewayEnvironment, partitionStripeMethods, rateLimitError, resolveAVSConfig, resolveBillingApiUrl, resolveButtonsLayoutTheme, resolveIdempotencyKey, resolveSessionCurrency, resolveStripeMethodBrandVariant, resolveTheme, serializeTelemetryBatch, stripeExpressMethodToOptionKey, validationError };