@flopay/shared 1.3.1 → 1.3.3

package/README.md

@@ -178,25 +178,40 @@ throw validationError('Email is required', 'email');
 
 ### Postal Code Helpers
 
-Country-aware postcode format validation, backed by the [`validator`](https://www.npmjs.com/package/validator) package's `isPostalCode` (the same library the billing API uses, so client and server rules agree). `@flopay/react`'s AVS block uses these to block a malformed postcode before the card is captured and to show the expected format inline.
+Country-aware postcode format validation, a **faithful mirror of the billing API's own validator** — `is-valid-postal-code.validator.ts` (TeamFloPay/backend#895), same pinned [`validator`](https://www.npmjs.com/package/validator)`@13.15.35` `isPostalCode`, same country→ISO-2 normalization, same fail-open rules — so the SDK never blocks a postcode the server accepts nor opens its submit gate on one the server's `PATCH …/account` will reject with a 400. `@flopay/react`'s AVS block uses these to block a malformed postcode before the card is captured and to show the expected format inline.
 
 | Export | Description |
 |--------|-------------|
 | `getPostalCodeLabel(countryCode)` | Country-appropriate field label (`'ZIP Code'`, `'Postcode'`, `'Eircode'`, …); defaults to `'Postal Code'` |
-| `isPostalCodeSupported(country)` | `true` when `validator` has a postcode pattern for the (ISO 3166-1 alpha-2, case-insensitive; `UK`→`GB`) country. Unsupported / no-postcode countries return `false` |
-| `isValidPostalCode(country, postalCode)` | `true` when the (trimmed) postcode matches the country's format. **Fails open** — unsupported / no-postcode countries always return `true`, so callers never block them. A supported country with an empty value returns `false`; check emptiness first to distinguish "required" from "malformed" |
-| `getPostalCodeExample(country)` | A curated example postcode for the field hint (US `12345 or 12345-6789`, GB `SW1A 1AA`, CA `A1A 1A1`, …), or `undefined` when there is no curated example |
+| `isPostalCodeSupported(country)` | `true` when `validator` has a postcode pattern for the country. Normalization matches the backend: a **2-letter code is passed straight through** (so `'UK'`, not a `validator` locale, → `false`); non-2-letter names resolve via the backend's `COUNTRY_ALIASES` (`'United Kingdom'` → `GB`). Unresolvable / no-postcode countries return `false` |
+| `isValidPostalCode(country, postalCode)` | `true` when the (trimmed) postcode matches the country's format. **Fails open** in exactly the backend's three cases: blank/whitespace postcode, unresolvable country, or an unsupported `validator` locale. Callers distinguish "required" (empty) from "malformed" by checking emptiness + `isPostalCodeSupported` themselves — an empty value fails open here, as it does server-side |
+| `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';
 
-isPostalCodeSupported('US');            // true
-isPostalCodeSupported('AE');            // false — UAE has no postcodes
-isValidPostalCode('GB', 'SW1A 1AA');    // true
-isValidPostalCode('GB', '12345');       // false — US shape in GB
-isValidPostalCode('AE', '');            // true — fail open, never blocks
-getPostalCodeExample('CA');             // 'A1A 1A1'
+isPostalCodeSupported('US');               // true
+isPostalCodeSupported('AE');               // false — UAE has no postcodes
+isPostalCodeSupported('United Kingdom');   // true  — full name → GB
+isPostalCodeSupported('UK');               // false — 2-letter passthrough (not a validator locale)
+isValidPostalCode('GB', 'SW1A 1AA');       // true
+isValidPostalCode('GB', '12345');          // false — US shape in GB
+isValidPostalCode('AE', '');               // true — fail open, never blocks
+isValidPostalCode('US', '');               // true — blank fails open (enforce "required" separately)
+getPostalCodeExample('CA');                // 'A1A 1A1'
 ```
 
 > **Runtime dependency.** Unlike the rest of `@flopay/shared`, these helpers pull in `validator` (imported via the `validator/lib/isPostalCode.js` submodule so bundlers only include the one check). It installs transitively when you depend on `@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.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";
@@ -1985,53 +1990,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
@@ -2234,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,
@@ -2264,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,
@@ -2287,6 +2378,7 @@ function isSetupIntentClientSecret(clientSecret) {
   filterStripeMethodsByCountry,
   filterStripeMethodsByCurrency,
   foldIntoProducts,
+  generateIdempotencyKey,
   getConfiguredBillingApiUrl,
   getCountryByCode,
   getCurrencyByCountry,
@@ -2313,6 +2405,7 @@ function isSetupIntentClientSecret(clientSecret) {
   resolveAVSConfig,
   resolveBillingApiUrl,
   resolveButtonsLayoutTheme,
+  resolveIdempotencyKey,
   resolveSessionCurrency,
   resolveStripeMethodBrandVariant,
   resolveTheme,