@flopay/shared 1.3.2 → 1.3.4

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.2";
+declare const SDK_VERSION = "1.3.4";
 /**
  * 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
@@ -1907,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.2";
+declare const SDK_VERSION = "1.3.4";
 /**
  * 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
@@ -1907,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.2";
+var SDK_VERSION = "1.3.4";
 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";
@@ -2157,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,
@@ -2186,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,
@@ -2209,6 +2255,7 @@ export {
   filterStripeMethodsByCountry,
   filterStripeMethodsByCurrency,
   foldIntoProducts,
+  generateIdempotencyKey,
   getConfiguredBillingApiUrl,
   getCountryByCode,
   getCurrencyByCountry,
@@ -2235,6 +2282,7 @@ export {
   resolveAVSConfig,
   resolveBillingApiUrl,
   resolveButtonsLayoutTheme,
+  resolveIdempotencyKey,
   resolveSessionCurrency,
   resolveStripeMethodBrandVariant,
   resolveTheme,