@flopay/shared 1.3.1 → 1.3.3

package/dist/index.d.cts

@@ -1097,6 +1097,17 @@ interface CreateSessionParams {
     timeoutMs?: number;
     /** UTM and funnel tracking metadata. */
     utmMetadata?: Record<string, string | null | undefined>[];
+    /**
+     * Optional idempotency key identifying exactly **one** logical checkout
+     * creation (TeamFloPay/backend#972). When supplied it is sent unchanged as
+     * the `Idempotency-Key` header and reused across the SDK's transport retries,
+     * so a timeout or lost response cannot mint a second session. Supply this to
+     * keep the key stable across React remounts, multiple SDK instances, or
+     * server retries you control; it **must not** be reused for a new purchase.
+     * When omitted, the SDK generates a fresh, cryptographically random key per
+     * call. Must be non-empty and at most 255 characters.
+     */
+    idempotencyKey?: string;
 }
 /**
  * Parameters for inline session creation via `FloPayCheckout.createSession`.
@@ -1141,6 +1152,16 @@ interface InlineSessionParams {
     tagsData?: TagsData;
     /** UTM and funnel tracking metadata. */
     utmMetadata?: Record<string, string | null | undefined>[];
+    /**
+     * Optional idempotency key identifying exactly **one** logical checkout
+     * creation (TeamFloPay/backend#972). When supplied it is sent unchanged as
+     * the `Idempotency-Key` header and reused across the SDK's transport retries.
+     * Supply this to keep the key stable across React remounts, multiple SDK
+     * instances, or server retries you control; it **must not** be reused for a
+     * new purchase. When omitted, the SDK generates a fresh, cryptographically
+     * random key per create. Must be non-empty and at most 255 characters.
+     */
+    idempotencyKey?: string;
     /** Whether AVS is enabled for this checkout. */
     avsCheck?: boolean;
     /** Checkout type: 'standard_checkout' or 'embedded_checkout'. */
@@ -1312,7 +1333,7 @@ declare function getConfiguredBillingApiUrl(): string;
 declare function getFloPayEnvironment(): FloPayEnvironment;
 
 /** Current SDK version. */
-declare const SDK_VERSION = "1.3.1";
+declare const SDK_VERSION = "1.3.3";
 /**
  * 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
@@ -1746,24 +1767,33 @@ declare function getStateFromPostalCode(country: string, postalCode: string): st
 
 /**
  * True when `validator` has an authoritative postcode pattern for the country
- * (ISO 3166-1 alpha-2, case-insensitive). Supported countries validate the
- * postcode format; unsupported / no-postcode countries fail open.
+ * (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.
+ * 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.
  *
- * - Unsupported / no-postcode country → `true` (fail open; never block).
- * - Supported country → `validator`'s `isPostalCode(zip, locale)` on the
- *   trimmed value. An empty string is not a valid postcode, so a supported
- *   country with an empty value returns `false`; callers that distinguish
- *   "required" (empty) from "malformed" (format) should check emptiness first.
+ * 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;
 /**
- * A curated example postcode for the country (e.g. US `12345 or 12345-6789`,
- * GB `SW1A 1AA`, CA `A1A 1A1`), or `undefined` when there is no curated example
- * (unsupported country, or a supported country not in the map).
+ * 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;
 
@@ -1898,4 +1928,60 @@ declare function isValidSecretKey(key: string): boolean;
  */
 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 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, type InlineSessionDraft, type InlineSessionParams, type InlineSessionPatch, type LineItem, 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, 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, resolveSessionCurrency, resolveStripeMethodBrandVariant, resolveTheme, stripeExpressMethodToOptionKey, validationError };
+/**
+ * HTTP header the SDK sends to make checkout-session creation idempotent
+ * (TeamFloPay/backend#972, paired SDK issue TeamFloPay/sdk#133).
+ *
+ * The backend treats the header as **optional**: when it is absent the legacy,
+ * non-idempotent creation path runs unchanged. When present, every transport
+ * retry of the same logical create reuses the same key so a timeout or lost
+ * response cannot mint a second checkout session.
+ */
+declare const IDEMPOTENCY_KEY_HEADER = "Idempotency-Key";
+/**
+ * Maximum length of an idempotency key accepted by the billing API
+ * (TeamFloPay/backend#972). Mirrors the widely-used 255-character ceiling;
+ * automatically generated keys stay well under it.
+ */
+declare const MAX_IDEMPOTENCY_KEY_LENGTH = 255;
+/**
+ * Backend `code` (TeamFloPay/backend#972) returned when a checkout-create
+ * replay arrives while the first request carrying the same key is still being
+ * processed. It is a **retryable** in-progress response: the caller should
+ * retry with the *same* key after a short backoff, never with a new key. This
+ * is distinct from a payload-conflict (`409`), which is non-retryable.
+ *
+ * Mirrors a backend-defined code the same way the coupon error codes
+ * (`CouponLimitExceeded`, `CouponCurrencyUnsupported`) mirror billing v1.1.2.
+ */
+declare const IDEMPOTENCY_IN_PROGRESS_CODE = "IdempotencyKeyInProgress";
+/**
+ * Generate a cryptographically random, high-entropy idempotency key.
+ *
+ * Prefers `crypto.randomUUID()` and falls back to 16 random bytes from
+ * `crypto.getRandomValues`. Returns `undefined` when no cryptographically
+ * secure RNG is available so the caller falls back to the legacy unkeyed path
+ * rather than emitting a weak or predictable key.
+ *
+ * The key is never derived from request data, customer identity, or time, so
+ * two independent operations never collide by construction.
+ */
+declare function generateIdempotencyKey(): string | undefined;
+/**
+ * Resolve the idempotency key for one logical checkout-create operation.
+ *
+ * - A merchant-supplied key is validated (non-empty, within
+ *   {@link MAX_IDEMPOTENCY_KEY_LENGTH}) and returned **unchanged** so it can be
+ *   preserved across React remounts, multiple SDK instances, or server retries
+ *   the merchant controls.
+ * - Otherwise a fresh cryptographically random key is generated. When no secure
+ *   RNG is available this returns `undefined` and the caller omits the header,
+ *   preserving the legacy path.
+ *
+ * @throws FloPayError('validation_error') when a supplied key is empty,
+ *   whitespace-only, or exceeds the length limit. The offending value is never
+ *   included in the error message.
+ */
+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 };

package/dist/index.d.ts

@@ -1097,6 +1097,17 @@ interface CreateSessionParams {
     timeoutMs?: number;
     /** UTM and funnel tracking metadata. */
     utmMetadata?: Record<string, string | null | undefined>[];
+    /**
+     * Optional idempotency key identifying exactly **one** logical checkout
+     * creation (TeamFloPay/backend#972). When supplied it is sent unchanged as
+     * the `Idempotency-Key` header and reused across the SDK's transport retries,
+     * so a timeout or lost response cannot mint a second session. Supply this to
+     * keep the key stable across React remounts, multiple SDK instances, or
+     * server retries you control; it **must not** be reused for a new purchase.
+     * When omitted, the SDK generates a fresh, cryptographically random key per
+     * call. Must be non-empty and at most 255 characters.
+     */
+    idempotencyKey?: string;
 }
 /**
  * Parameters for inline session creation via `FloPayCheckout.createSession`.
@@ -1141,6 +1152,16 @@ interface InlineSessionParams {
     tagsData?: TagsData;
     /** UTM and funnel tracking metadata. */
     utmMetadata?: Record<string, string | null | undefined>[];
+    /**
+     * Optional idempotency key identifying exactly **one** logical checkout
+     * creation (TeamFloPay/backend#972). When supplied it is sent unchanged as
+     * the `Idempotency-Key` header and reused across the SDK's transport retries.
+     * Supply this to keep the key stable across React remounts, multiple SDK
+     * instances, or server retries you control; it **must not** be reused for a
+     * new purchase. When omitted, the SDK generates a fresh, cryptographically
+     * random key per create. Must be non-empty and at most 255 characters.
+     */
+    idempotencyKey?: string;
     /** Whether AVS is enabled for this checkout. */
     avsCheck?: boolean;
     /** Checkout type: 'standard_checkout' or 'embedded_checkout'. */
@@ -1312,7 +1333,7 @@ declare function getConfiguredBillingApiUrl(): string;
 declare function getFloPayEnvironment(): FloPayEnvironment;
 
 /** Current SDK version. */
-declare const SDK_VERSION = "1.3.1";
+declare const SDK_VERSION = "1.3.3";
 /**
  * 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
@@ -1746,24 +1767,33 @@ declare function getStateFromPostalCode(country: string, postalCode: string): st
 
 /**
  * True when `validator` has an authoritative postcode pattern for the country
- * (ISO 3166-1 alpha-2, case-insensitive). Supported countries validate the
- * postcode format; unsupported / no-postcode countries fail open.
+ * (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.
+ * 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.
  *
- * - Unsupported / no-postcode country → `true` (fail open; never block).
- * - Supported country → `validator`'s `isPostalCode(zip, locale)` on the
- *   trimmed value. An empty string is not a valid postcode, so a supported
- *   country with an empty value returns `false`; callers that distinguish
- *   "required" (empty) from "malformed" (format) should check emptiness first.
+ * 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;
 /**
- * A curated example postcode for the country (e.g. US `12345 or 12345-6789`,
- * GB `SW1A 1AA`, CA `A1A 1A1`), or `undefined` when there is no curated example
- * (unsupported country, or a supported country not in the map).
+ * 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;
 
@@ -1898,4 +1928,60 @@ declare function isValidSecretKey(key: string): boolean;
  */
 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 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, type InlineSessionDraft, type InlineSessionParams, type InlineSessionPatch, type LineItem, 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, 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, resolveSessionCurrency, resolveStripeMethodBrandVariant, resolveTheme, stripeExpressMethodToOptionKey, validationError };
+/**
+ * HTTP header the SDK sends to make checkout-session creation idempotent
+ * (TeamFloPay/backend#972, paired SDK issue TeamFloPay/sdk#133).
+ *
+ * The backend treats the header as **optional**: when it is absent the legacy,
+ * non-idempotent creation path runs unchanged. When present, every transport
+ * retry of the same logical create reuses the same key so a timeout or lost
+ * response cannot mint a second checkout session.
+ */
+declare const IDEMPOTENCY_KEY_HEADER = "Idempotency-Key";
+/**
+ * Maximum length of an idempotency key accepted by the billing API
+ * (TeamFloPay/backend#972). Mirrors the widely-used 255-character ceiling;
+ * automatically generated keys stay well under it.
+ */
+declare const MAX_IDEMPOTENCY_KEY_LENGTH = 255;
+/**
+ * Backend `code` (TeamFloPay/backend#972) returned when a checkout-create
+ * replay arrives while the first request carrying the same key is still being
+ * processed. It is a **retryable** in-progress response: the caller should
+ * retry with the *same* key after a short backoff, never with a new key. This
+ * is distinct from a payload-conflict (`409`), which is non-retryable.
+ *
+ * Mirrors a backend-defined code the same way the coupon error codes
+ * (`CouponLimitExceeded`, `CouponCurrencyUnsupported`) mirror billing v1.1.2.
+ */
+declare const IDEMPOTENCY_IN_PROGRESS_CODE = "IdempotencyKeyInProgress";
+/**
+ * Generate a cryptographically random, high-entropy idempotency key.
+ *
+ * Prefers `crypto.randomUUID()` and falls back to 16 random bytes from
+ * `crypto.getRandomValues`. Returns `undefined` when no cryptographically
+ * secure RNG is available so the caller falls back to the legacy unkeyed path
+ * rather than emitting a weak or predictable key.
+ *
+ * The key is never derived from request data, customer identity, or time, so
+ * two independent operations never collide by construction.
+ */
+declare function generateIdempotencyKey(): string | undefined;
+/**
+ * Resolve the idempotency key for one logical checkout-create operation.
+ *
+ * - A merchant-supplied key is validated (non-empty, within
+ *   {@link MAX_IDEMPOTENCY_KEY_LENGTH}) and returned **unchanged** so it can be
+ *   preserved across React remounts, multiple SDK instances, or server retries
+ *   the merchant controls.
+ * - Otherwise a fresh cryptographically random key is generated. When no secure
+ *   RNG is available this returns `undefined` and the caller omits the header,
+ *   preserving the legacy path.
+ *
+ * @throws FloPayError('validation_error') when a supplied key is empty,
+ *   whitespace-only, or exceeds the length limit. The offending value is never
+ *   included in the error message.
+ */
+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 };

package/dist/index.mjs

@@ -79,7 +79,7 @@ var PAYMENT_METHOD_LOGOS = {
 };
 
 // src/constants.ts
-var SDK_VERSION = "1.3.1";
+var SDK_VERSION = "1.3.3";
 var FLO_SDK_VERSION_HEADER = "x-flo-sdk-version";
 var BILLING_API_URL_STAGING = "https://api.stage.flopay.com";
 var BILLING_API_URL_PRODUCTION = "https://api.flopay.com";
@@ -1868,53 +1868,93 @@ if (typeof isPostalCode !== "function") {
 var SUPPORTED_LOCALES = new Set(
   mod.locales.map((code) => code.toUpperCase())
 );
-var LOCALE_ALIASES = {
-  UK: "GB"
+var COUNTRY_ALIASES = {
+  AUSTRALIA: "AU",
+  BRAZIL: "BR",
+  CANADA: "CA",
+  CH: "CH",
+  DENMARK: "DK",
+  DE: "DE",
+  DEUTSCHLAND: "DE",
+  FRANCE: "FR",
+  GB: "GB",
+  GERMANY: "DE",
+  GREATBRITAIN: "GB",
+  GREAT_BRITAIN: "GB",
+  INDIA: "IN",
+  IRELAND: "IE",
+  ITALY: "IT",
+  JAPAN: "JP",
+  MEXICO: "MX",
+  NETHERLANDS: "NL",
+  NEWZEALAND: "NZ",
+  NORWAY: "NO",
+  POLAND: "PL",
+  PORTUGAL: "PT",
+  SINGAPORE: "SG",
+  SOUTHAFRICA: "ZA",
+  SPAIN: "ES",
+  SWEDEN: "SE",
+  SWITZERLAND: "CH",
+  UK: "GB",
+  UNITEDKINGDOM: "GB",
+  UNITEDSTATES: "US",
+  US: "US",
+  USA: "US",
+  "UNITED STATES": "US",
+  "UNITED KINGDOM": "GB",
+  "GREAT BRITAIN": "GB",
+  ENGLAND: "GB"
 };
-function normalizeCountry(country) {
-  const upper = country.trim().toUpperCase();
-  return LOCALE_ALIASES[upper] ?? upper;
+function normalizeCountryToIso2(country) {
+  const upper = (country ?? "").trim().toUpperCase();
+  if (!upper) return null;
+  if (upper.length === 2) return upper;
+  return COUNTRY_ALIASES[upper] ?? null;
 }
 var POSTAL_CODE_EXAMPLES = {
-  US: "12345 or 12345-6789",
-  GB: "SW1A 1AA",
-  CA: "A1A 1A1",
   AU: "2000",
-  NZ: "6011",
-  IE: "D02 AF30",
+  BR: "01000-000",
+  CA: "A1A 1A1",
+  CH: "8001",
   DE: "10115",
-  FR: "75008",
-  NL: "1011 AB",
+  DK: "1050",
   ES: "28001",
-  IT: "00100",
+  FR: "75008",
+  GB: "SW1A 1AA",
+  IE: "D02 X285",
   IN: "110001",
+  IT: "00118",
   JP: "100-0001",
-  BR: "01310-100",
-  MX: "01000",
-  SE: "114 55",
-  CH: "8001",
+  MX: "06500",
+  NL: "1012 JS",
+  NO: "0150",
+  NZ: "6011",
   PL: "00-001",
-  PT: "1000-001",
-  SG: "570150",
-  ZA: "0001",
-  NO: "0001",
-  DK: "1050",
-  FI: "00100",
-  AT: "1010",
-  BE: "1000",
-  CZ: "100 00"
+  PT: "1100-148",
+  SE: "111 22",
+  SG: "018989",
+  US: "12345 or 12345-6789",
+  ZA: "8001"
 };
 function isPostalCodeSupported(country) {
-  if (!country) return false;
-  return SUPPORTED_LOCALES.has(normalizeCountry(country));
+  const iso2 = normalizeCountryToIso2(country);
+  return iso2 !== null && SUPPORTED_LOCALES.has(iso2);
 }
 function isValidPostalCode(country, postalCode) {
-  if (!isPostalCodeSupported(country)) return true;
-  return isPostalCode(postalCode.trim(), normalizeCountry(country));
+  const trimmed = (postalCode ?? "").trim();
+  if (!trimmed) return true;
+  const iso2 = normalizeCountryToIso2(country);
+  if (iso2 === null || !SUPPORTED_LOCALES.has(iso2)) return true;
+  try {
+    return isPostalCode(trimmed, iso2);
+  } catch {
+    return true;
+  }
 }
 function getPostalCodeExample(country) {
-  if (!country) return void 0;
-  return POSTAL_CODE_EXAMPLES[normalizeCountry(country)];
+  const iso2 = normalizeCountryToIso2(country);
+  return iso2 ? POSTAL_CODE_EXAMPLES[iso2] : void 0;
 }
 
 // src/checkout-payload.ts
@@ -2117,6 +2157,49 @@ function isValidSecretKey(key) {
 function isSetupIntentClientSecret(clientSecret) {
   return typeof clientSecret === "string" && clientSecret.startsWith("seti_");
 }
+
+// src/idempotency.ts
+var IDEMPOTENCY_KEY_HEADER = "Idempotency-Key";
+var MAX_IDEMPOTENCY_KEY_LENGTH = 255;
+var IDEMPOTENCY_IN_PROGRESS_CODE = "IdempotencyKeyInProgress";
+function getSecureRandomSource() {
+  const source = globalThis.crypto;
+  if (!source) return void 0;
+  if (typeof source.randomUUID === "function" || typeof source.getRandomValues === "function") {
+    return source;
+  }
+  return void 0;
+}
+function generateIdempotencyKey() {
+  const source = getSecureRandomSource();
+  if (!source) return void 0;
+  if (typeof source.randomUUID === "function") {
+    return source.randomUUID();
+  }
+  const bytes = new Uint8Array(16);
+  source.getRandomValues(bytes);
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function resolveIdempotencyKey(supplied) {
+  if (supplied === void 0) {
+    return generateIdempotencyKey();
+  }
+  if (typeof supplied !== "string" || supplied.trim() === "") {
+    throw new FloPayError(
+      "idempotencyKey must be a non-empty string identifying exactly one checkout creation.",
+      "validation_error",
+      { code: "InvalidIdempotencyKey", param: "idempotencyKey" }
+    );
+  }
+  if (supplied.length > MAX_IDEMPOTENCY_KEY_LENGTH) {
+    throw new FloPayError(
+      `idempotencyKey must be at most ${MAX_IDEMPOTENCY_KEY_LENGTH} characters.`,
+      "validation_error",
+      { code: "InvalidIdempotencyKey", param: "idempotencyKey" }
+    );
+  }
+  return supplied;
+}
 export {
   BILLING_API_URL,
   BILLING_API_URL_PRODUCTION,
@@ -2146,6 +2229,9 @@ export {
   FloPayError,
   GLASS_DARK_APPEARANCE,
   GLASS_LIGHT_APPEARANCE,
+  IDEMPOTENCY_IN_PROGRESS_CODE,
+  IDEMPOTENCY_KEY_HEADER,
+  MAX_IDEMPOTENCY_KEY_LENGTH,
   MODERN_DARK_APPEARANCE,
   MODERN_LIGHT_APPEARANCE,
   NIGHT_APPEARANCE,
@@ -2169,6 +2255,7 @@ export {
   filterStripeMethodsByCountry,
   filterStripeMethodsByCurrency,
   foldIntoProducts,
+  generateIdempotencyKey,
   getConfiguredBillingApiUrl,
   getCountryByCode,
   getCurrencyByCountry,
@@ -2195,6 +2282,7 @@ export {
   resolveAVSConfig,
   resolveBillingApiUrl,
   resolveButtonsLayoutTheme,
+  resolveIdempotencyKey,
   resolveSessionCurrency,
   resolveStripeMethodBrandVariant,
   resolveTheme,