@flopay/shared 1.3.2 → 1.3.3

package/README.md

@@ -188,6 +188,18 @@ Country-aware postcode format validation, a **faithful mirror of the billing API
 | `getPostalCodeExample(country)` | The example postcode the backend embeds in its 400 message (US `12345 or 12345-6789`, GB `SW1A 1AA`, CA `A1A 1A1`, …), or `undefined` when there is none. Kept verbatim in sync with the backend's `POSTAL_CODE_EXAMPLES` so the SDK's inline hint and the server's rejection message never contradict |
 | `getStateFromPostalCode(country, postalCode)` | Derives a US state / CA province code from a postcode for AVS enrichment; `null` for other countries or a malformed code |
 
+### Idempotency Helpers
+
+Primitives for the stable checkout-create `Idempotency-Key` (TeamFloPay/backend#972). `@flopay/js` and `@flopay/react` use these automatically; import them only if you build your own create flow.
+
+| Export | Description |
+|--------|-------------|
+| `IDEMPOTENCY_KEY_HEADER` | The header name (`'Idempotency-Key'`) the SDK sends on `POST /v1/checkouts/sessions`. Optional on the backend — absent means the legacy, non-idempotent path. |
+| `MAX_IDEMPOTENCY_KEY_LENGTH` | `255` — the documented max length a supplied key may have. |
+| `IDEMPOTENCY_IN_PROGRESS_CODE` | Backend `code` (`'IdempotencyKeyInProgress'`) marking a **retryable** in-progress replay: retry with the *same* key. Distinct from a payload-conflict (`409`), which is non-retryable. |
+| `generateIdempotencyKey()` | Returns a cryptographically random, high-entropy key (`crypto.randomUUID()`, else 16 random bytes). Returns `undefined` when no secure RNG exists, so callers omit the header rather than emit a weak key. Never derived from request data. |
+| `resolveIdempotencyKey(supplied?)` | Returns a supplied key unchanged after validating it is non-empty and ≤ `MAX_IDEMPOTENCY_KEY_LENGTH` (throws `FloPayError('validation_error')` otherwise, never echoing the value), or a freshly generated key when none is supplied. |
+
 ```ts
 import { isPostalCodeSupported, isValidPostalCode, getPostalCodeExample } from '@flopay/shared';
 

package/dist/index.cjs

@@ -58,6 +58,9 @@ __export(index_exports, {
   FloPayError: () => FloPayError,
   GLASS_DARK_APPEARANCE: () => GLASS_DARK_APPEARANCE,
   GLASS_LIGHT_APPEARANCE: () => GLASS_LIGHT_APPEARANCE,
+  IDEMPOTENCY_IN_PROGRESS_CODE: () => IDEMPOTENCY_IN_PROGRESS_CODE,
+  IDEMPOTENCY_KEY_HEADER: () => IDEMPOTENCY_KEY_HEADER,
+  MAX_IDEMPOTENCY_KEY_LENGTH: () => MAX_IDEMPOTENCY_KEY_LENGTH,
   MODERN_DARK_APPEARANCE: () => MODERN_DARK_APPEARANCE,
   MODERN_LIGHT_APPEARANCE: () => MODERN_LIGHT_APPEARANCE,
   NIGHT_APPEARANCE: () => NIGHT_APPEARANCE,
@@ -81,6 +84,7 @@ __export(index_exports, {
   filterStripeMethodsByCountry: () => filterStripeMethodsByCountry,
   filterStripeMethodsByCurrency: () => filterStripeMethodsByCurrency,
   foldIntoProducts: () => foldIntoProducts,
+  generateIdempotencyKey: () => generateIdempotencyKey,
   getConfiguredBillingApiUrl: () => getConfiguredBillingApiUrl,
   getCountryByCode: () => getCountryByCode,
   getCurrencyByCountry: () => getCurrencyByCountry,
@@ -107,6 +111,7 @@ __export(index_exports, {
   resolveAVSConfig: () => resolveAVSConfig,
   resolveBillingApiUrl: () => resolveBillingApiUrl,
   resolveButtonsLayoutTheme: () => resolveButtonsLayoutTheme,
+  resolveIdempotencyKey: () => resolveIdempotencyKey,
   resolveSessionCurrency: () => resolveSessionCurrency,
   resolveStripeMethodBrandVariant: () => resolveStripeMethodBrandVariant,
   resolveTheme: () => resolveTheme,
@@ -196,7 +201,7 @@ var PAYMENT_METHOD_LOGOS = {
 };
 
 // src/constants.ts
-var SDK_VERSION = "1.3.2";
+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";
@@ -2274,6 +2279,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;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BILLING_API_URL,
@@ -2304,6 +2352,9 @@ function isSetupIntentClientSecret(clientSecret) {
   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,
@@ -2327,6 +2378,7 @@ function isSetupIntentClientSecret(clientSecret) {
   filterStripeMethodsByCountry,
   filterStripeMethodsByCurrency,
   foldIntoProducts,
+  generateIdempotencyKey,
   getConfiguredBillingApiUrl,
   getCountryByCode,
   getCurrencyByCountry,
@@ -2353,6 +2405,7 @@ function isSetupIntentClientSecret(clientSecret) {
   resolveAVSConfig,
   resolveBillingApiUrl,
   resolveButtonsLayoutTheme,
+  resolveIdempotencyKey,
   resolveSessionCurrency,
   resolveStripeMethodBrandVariant,
   resolveTheme,