@flopay/shared 1.3.0 → 1.3.2

package/README.md

@@ -175,3 +175,31 @@ throw validationError('Email is required', 'email');
 | `getCurrencyByCountry(countryCode)` | Returns `CurrencyInfo` for a country code, falls back to USD |
 | `isValidPublishableKey(key)` | Returns `true` if the key matches `pk_(test|live)_...` |
 | `isValidSecretKey(key)` | Returns `true` if the key matches `sk_(test|live)_...` |
+
+### Postal Code Helpers
+
+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 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 |
+
+```ts
+import { isPostalCodeSupported, isValidPostalCode, getPostalCodeExample } from '@flopay/shared';
+
+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

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,7 +17,15 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var __toESM = (mod2, isNodeMode, target) => (target = mod2 != null ? __create(__getProtoOf(mod2)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod2 || !mod2.__esModule ? __defProp(target, "default", { value: mod2, enumerable: true }) : target,
+  mod2
+));
+var __toCommonJS = (mod2) => __copyProps(__defProp({}, "__esModule", { value: true }), mod2);
 
 // src/index.ts
 var index_exports = {};
@@ -75,6 +85,7 @@ __export(index_exports, {
   getCountryByCode: () => getCountryByCode,
   getCurrencyByCountry: () => getCurrencyByCountry,
   getFloPayEnvironment: () => getFloPayEnvironment,
+  getPostalCodeExample: () => getPostalCodeExample,
   getPostalCodeLabel: () => getPostalCodeLabel,
   getStateFromPostalCode: () => getStateFromPostalCode,
   getStateLabel: () => getStateLabel,
@@ -83,7 +94,9 @@ __export(index_exports, {
   hasVendoredStripeMethodLogo: () => hasVendoredStripeMethodLogo,
   isAVSEnabled: () => isAVSEnabled,
   isAVSFieldVisible: () => isAVSFieldVisible,
+  isPostalCodeSupported: () => isPostalCodeSupported,
   isSetupIntentClientSecret: () => isSetupIntentClientSecret,
+  isValidPostalCode: () => isValidPostalCode,
   isValidPublishableKey: () => isValidPublishableKey,
   isValidSecretKey: () => isValidSecretKey,
   needsStripeMethodExplicitConfirm: () => needsStripeMethodExplicitConfirm,
@@ -183,7 +196,7 @@ var PAYMENT_METHOD_LOGOS = {
 };
 
 // src/constants.ts
-var SDK_VERSION = "1.3.0";
+var SDK_VERSION = "1.3.2";
 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";
@@ -1960,6 +1973,107 @@ function getStateFromPostalCode(country, postalCode) {
   }
 }
 
+// src/postal-code-validation.ts
+var isPostalCodeModule = __toESM(require("validator/lib/isPostalCode.js"), 1);
+var mod = isPostalCodeModule;
+var isPostalCode = typeof mod.default === "function" ? mod.default : mod.default?.default;
+if (typeof isPostalCode !== "function") {
+  throw new Error(
+    "validator/lib/isPostalCode.js interop failed: unexpected module shape. This likely means the bundler's CJS/ESM interop changed."
+  );
+}
+var SUPPORTED_LOCALES = new Set(
+  mod.locales.map((code) => code.toUpperCase())
+);
+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 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 = {
+  AU: "2000",
+  BR: "01000-000",
+  CA: "A1A 1A1",
+  CH: "8001",
+  DE: "10115",
+  DK: "1050",
+  ES: "28001",
+  FR: "75008",
+  GB: "SW1A 1AA",
+  IE: "D02 X285",
+  IN: "110001",
+  IT: "00118",
+  JP: "100-0001",
+  MX: "06500",
+  NL: "1012 JS",
+  NO: "0150",
+  NZ: "6011",
+  PL: "00-001",
+  PT: "1100-148",
+  SE: "111 22",
+  SG: "018989",
+  US: "12345 or 12345-6789",
+  ZA: "8001"
+};
+function isPostalCodeSupported(country) {
+  const iso2 = normalizeCountryToIso2(country);
+  return iso2 !== null && SUPPORTED_LOCALES.has(iso2);
+}
+function isValidPostalCode(country, postalCode) {
+  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) {
+  const iso2 = normalizeCountryToIso2(country);
+  return iso2 ? POSTAL_CODE_EXAMPLES[iso2] : void 0;
+}
+
 // src/checkout-payload.ts
 function nonBlank(value) {
   if (typeof value !== "string") return void 0;
@@ -2217,6 +2331,7 @@ function isSetupIntentClientSecret(clientSecret) {
   getCountryByCode,
   getCurrencyByCountry,
   getFloPayEnvironment,
+  getPostalCodeExample,
   getPostalCodeLabel,
   getStateFromPostalCode,
   getStateLabel,
@@ -2225,7 +2340,9 @@ function isSetupIntentClientSecret(clientSecret) {
   hasVendoredStripeMethodLogo,
   isAVSEnabled,
   isAVSFieldVisible,
+  isPostalCodeSupported,
   isSetupIntentClientSecret,
+  isValidPostalCode,
   isValidPublishableKey,
   isValidSecretKey,
   needsStripeMethodExplicitConfirm,