@base44/app-plugin-commerce 0.1.0

package/base44/shared/commerce/coupons.ts

@@ -0,0 +1,257 @@
+/**
+ * Coupon validation and discount application (standard commerce semantics).
+ * Validation runs the ordered checks from the plan; application supports
+ * percent / fixed_cart / fixed_product with the standard eligibility rules.
+ */
+import { distributeProportionally, round2 } from "./money.ts";
+
+export interface CouponLineInput {
+  line_id: string;
+  product_id: string;
+  variation_id?: string;
+  quantity: number;
+  unit_price: number;   // ex-tax unit price
+  subtotal: number;     // ex-tax pre-discount line total
+  discount: number;     // accumulated so far (mutated by applyCoupons)
+  product?: any;        // resolved Product (category_ids, on_sale)
+  variation?: any;
+}
+
+export interface CouponValidationCtx {
+  lines: CouponLineInput[];
+  itemsSubtotal: number;
+  customerEmail?: string;
+  appliedCoupons?: any[]; // other coupons already in the cart
+}
+
+export interface CouponValidationResult {
+  valid: boolean;
+  error?: string;
+  code?: string;
+}
+
+function emailMatchesRestriction(email: string, patterns: string[]): boolean {
+  const e = (email || "").toLowerCase();
+  return (patterns || []).some((p) => {
+    const pat = (p || "").toLowerCase().trim();
+    if (!pat) return false;
+    const re = new RegExp(
+      "^" + pat.split("*").map((s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join(".*") + "$",
+    );
+    return re.test(e);
+  });
+}
+
+/** Lines a coupon can touch: include-lists intersect, exclude-lists subtract. */
+export function eligibleLines(coupon: any, lines: CouponLineInput[]): CouponLineInput[] {
+  let out = [...(lines || [])];
+  const inclProducts: string[] = coupon.product_ids || [];
+  const exclProducts: string[] = coupon.excluded_product_ids || [];
+  const inclCats: string[] = coupon.product_category_ids || [];
+  const exclCats: string[] = coupon.excluded_product_category_ids || [];
+
+  if (inclProducts.length) {
+    out = out.filter((l) => inclProducts.includes(l.product_id) || (l.variation_id && inclProducts.includes(l.variation_id)));
+  }
+  if (exclProducts.length) {
+    out = out.filter((l) => !exclProducts.includes(l.product_id) && !(l.variation_id && exclProducts.includes(l.variation_id)));
+  }
+  if (inclCats.length) {
+    out = out.filter((l) => (l.product?.category_ids || []).some((c: string) => inclCats.includes(c)));
+  }
+  if (exclCats.length) {
+    out = out.filter((l) => !(l.product?.category_ids || []).some((c: string) => exclCats.includes(c)));
+  }
+  if (coupon.exclude_sale_items) {
+    out = out.filter((l) => !(l.variation?.on_sale ?? l.product?.on_sale));
+  }
+  return out;
+}
+
+/**
+ * The 9 ordered validation checks. Pass `coupon = null` for a lookup miss.
+ * Error codes: not_found | expired | usage_limit_reached |
+ * usage_limit_per_user_reached | individual_use | min_amount_not_met |
+ * max_amount_exceeded | not_applicable | sale_items_excluded | email_restricted
+ */
+export function validateCoupon(coupon: any | null, ctx: CouponValidationCtx): CouponValidationResult {
+  // 1. exists
+  if (!coupon) return { valid: false, code: "not_found", error: "Coupon does not exist." };
+
+  // 2. expiry
+  if (coupon.date_expires && new Date(coupon.date_expires).getTime() < Date.now()) {
+    return { valid: false, code: "expired", error: "This coupon has expired." };
+  }
+
+  // 3. global usage limit
+  if (coupon.usage_limit != null && (coupon.usage_count ?? 0) >= coupon.usage_limit) {
+    return { valid: false, code: "usage_limit_reached", error: "Coupon usage limit has been reached." };
+  }
+
+  // 4. per-user usage limit (usages recorded in used_by, one entry per use)
+  if (coupon.usage_limit_per_user != null && ctx.customerEmail) {
+    const uses = (coupon.used_by || []).filter(
+      (e: string) => (e || "").toLowerCase() === ctx.customerEmail!.toLowerCase(),
+    ).length;
+    if (uses >= coupon.usage_limit_per_user) {
+      return { valid: false, code: "usage_limit_per_user_reached", error: "Coupon usage limit has been reached for your account." };
+    }
+  }
+
+  // 5. individual use — both directions
+  const others = (ctx.appliedCoupons || []).filter((c) => c.code !== coupon.code);
+  if (coupon.individual_use && others.length) {
+    return { valid: false, code: "individual_use", error: "This coupon cannot be used in conjunction with other coupons." };
+  }
+  if (others.some((c) => c.individual_use)) {
+    return { valid: false, code: "individual_use", error: "An applied coupon does not allow other coupons." };
+  }
+
+  // 6. min / max spend (vs items subtotal, ex tax)
+  if (coupon.minimum_amount != null && coupon.minimum_amount > 0 && ctx.itemsSubtotal < coupon.minimum_amount) {
+    return { valid: false, code: "min_amount_not_met", error: `The minimum spend for this coupon is ${coupon.minimum_amount}.` };
+  }
+  if (coupon.maximum_amount != null && coupon.maximum_amount > 0 && ctx.itemsSubtotal > coupon.maximum_amount) {
+    return { valid: false, code: "max_amount_exceeded", error: `The maximum spend for this coupon is ${coupon.maximum_amount}.` };
+  }
+
+  // 7. product/category restrictions must leave something to discount
+  const restricted =
+    (coupon.product_ids || []).length || (coupon.excluded_product_ids || []).length ||
+    (coupon.product_category_ids || []).length || (coupon.excluded_product_category_ids || []).length;
+  const withoutSaleFilter = eligibleLines({ ...coupon, exclude_sale_items: false }, ctx.lines);
+  if (restricted && !withoutSaleFilter.length) {
+    return { valid: false, code: "not_applicable", error: "Sorry, this coupon is not applicable to your cart contents." };
+  }
+
+  // 8. exclude_sale_items must still leave eligible lines
+  if (coupon.exclude_sale_items && withoutSaleFilter.length && !eligibleLines(coupon, ctx.lines).length) {
+    return { valid: false, code: "sale_items_excluded", error: "Sorry, this coupon is not valid for sale items." };
+  }
+
+  // 9. email restrictions
+  if ((coupon.email_restrictions || []).length) {
+    if (!ctx.customerEmail || !emailMatchesRestriction(ctx.customerEmail, coupon.email_restrictions)) {
+      return { valid: false, code: "email_restricted", error: "This coupon is not valid for your email address." };
+    }
+  }
+
+  return { valid: true };
+}
+
+export interface CouponLineTotal {
+  code: string;
+  coupon_id: string;
+  discount: number;
+  discount_tax: number; // filled in by totals.ts after tax
+  free_shipping: boolean;
+}
+
+/**
+ * Apply coupons in order, mutating each line's `.discount`.
+ * `calc_discounts_sequentially` (general settings): when true each coupon sees
+ * the line total minus prior discounts; when false all see the original
+ * subtotal (the default). Line discounts never exceed the line's remaining value.
+ */
+export function applyCoupons(
+  lines: CouponLineInput[],
+  coupons: any[],
+  settings: Record<string, any>,
+): CouponLineTotal[] {
+  const sequential = !!settings?.general?.calc_discounts_sequentially;
+  const couponLines: CouponLineTotal[] = [];
+  const base = (l: CouponLineInput) => Math.max(0, sequential ? l.subtotal - l.discount : l.subtotal);
+  const remaining = (l: CouponLineInput) => Math.max(0, round2(l.subtotal - l.discount));
+
+  for (const coupon of coupons || []) {
+    const eligible = eligibleLines(coupon, lines);
+    const amount = Number(coupon.amount) || 0;
+    let discountTotal = 0;
+    const add = (l: CouponLineInput, d: number) => {
+      const capped = Math.min(round2(d), remaining(l));
+      if (capped <= 0) return;
+      l.discount = round2(l.discount + capped);
+      discountTotal = round2(discountTotal + capped);
+    };
+
+    switch (coupon.discount_type) {
+      case "percent": {
+        for (const l of eligible) add(l, base(l) * (amount / 100));
+        break;
+      }
+      case "fixed_product": {
+        // per-unit discount; limit_usage_to_x_items caps units, priciest first
+        let unitsCap = coupon.limit_usage_to_x_items != null ? Number(coupon.limit_usage_to_x_items) : Infinity;
+        const sorted = [...eligible].sort((a, b) => b.unit_price - a.unit_price);
+        for (const l of sorted) {
+          if (unitsCap <= 0) break;
+          const units = Math.min(l.quantity, unitsCap);
+          const perUnit = Math.min(amount, l.unit_price);
+          add(l, perUnit * units);
+          unitsCap -= units;
+        }
+        break;
+      }
+      case "fixed_cart":
+      default: {
+        // distribute across eligible lines proportionally, cents-exact
+        const weights = eligible.map((l) => base(l));
+        const pool = Math.min(amount, weights.reduce((a, b) => a + b, 0));
+        const shares = distributeProportionally(pool, weights);
+        eligible.forEach((l, i) => add(l, shares[i] ?? 0));
+      }
+    }
+
+    couponLines.push({
+      code: coupon.code,
+      coupon_id: coupon.id ?? "",
+      discount: discountTotal,
+      discount_tax: 0,
+      free_shipping: !!coupon.free_shipping,
+    });
+  }
+  return couponLines;
+}
+
+/**
+ * Record coupon usage for an order (usage_count +1, used_by += billing email
+ * per coupon line). Caller guards/persists order.coupon_usages_counted.
+ */
+export async function countUsage(sr: any, order: any): Promise<void> {
+  const email = (order.billing?.email || "").toLowerCase();
+  for (const cl of order.coupon_lines || []) {
+    const coupon = await findCoupon(sr, cl);
+    if (!coupon) continue;
+    await sr.entities["commerce.Coupon"].update(coupon.id, {
+      usage_count: (coupon.usage_count ?? 0) + 1,
+      used_by: [...(coupon.used_by || []), email],
+    });
+  }
+}
+
+/** Reverse of countUsage (removes ONE used_by entry per coupon line). */
+export async function uncountUsage(sr: any, order: any): Promise<void> {
+  const email = (order.billing?.email || "").toLowerCase();
+  for (const cl of order.coupon_lines || []) {
+    const coupon = await findCoupon(sr, cl);
+    if (!coupon) continue;
+    const usedBy = [...(coupon.used_by || [])];
+    const idx = usedBy.findIndex((e: string) => (e || "").toLowerCase() === email);
+    if (idx >= 0) usedBy.splice(idx, 1);
+    await sr.entities["commerce.Coupon"].update(coupon.id, {
+      usage_count: Math.max(0, (coupon.usage_count ?? 0) - 1),
+      used_by: usedBy,
+    });
+  }
+}
+
+async function findCoupon(sr: any, couponLine: any): Promise<any | null> {
+  if (couponLine.coupon_id) {
+    try {
+      const c = await sr.entities["commerce.Coupon"].get(couponLine.coupon_id);
+      if (c) return c;
+    } catch { /* fall through to code lookup */ }
+  }
+  const matches = await sr.entities["commerce.Coupon"].filter({ code: (couponLine.code || "").toLowerCase() }, undefined, 1);
+  return matches?.[0] ?? null;
+}

package/base44/shared/commerce/data/continents.ts

@@ -0,0 +1,75 @@
+/**
+ * Continent → country-code groupings (reference /data/continents dataset).
+ * Used by shipping-zone location matching (location type "continent").
+ */
+export interface ContinentInfo {
+  code: string;
+  name: string;
+  countries: string[];
+}
+
+export const CONTINENTS: ContinentInfo[] = [
+  {
+    code: "AF",
+    name: "Africa",
+    countries: [
+      "AO", "BF", "BI", "BJ", "BW", "CD", "CF", "CG", "CI", "CM", "CV", "DJ", "DZ", "EG", "EH", "ER",
+      "ET", "GA", "GH", "GM", "GN", "GQ", "GW", "KE", "KM", "LR", "LS", "LY", "MA", "MG", "ML", "MR",
+      "MU", "MW", "MZ", "NA", "NE", "NG", "RE", "RW", "SC", "SD", "SH", "SL", "SN", "SO", "SS", "ST",
+      "SZ", "TD", "TG", "TN", "TZ", "UG", "YT", "ZA", "ZM", "ZW",
+    ],
+  },
+  {
+    code: "AN",
+    name: "Antarctica",
+    countries: ["AQ", "BV", "GS", "HM", "TF"],
+  },
+  {
+    code: "AS",
+    name: "Asia",
+    countries: [
+      "AE", "AF", "AM", "AZ", "BD", "BH", "BN", "BT", "CC", "CN", "CX", "CY", "GE", "HK", "ID", "IL",
+      "IN", "IO", "IQ", "IR", "JO", "JP", "KG", "KH", "KP", "KR", "KW", "KZ", "LA", "LB", "LK", "MM",
+      "MN", "MO", "MV", "MY", "NP", "OM", "PH", "PK", "PS", "QA", "SA", "SG", "SY", "TH", "TJ", "TL",
+      "TM", "TR", "TW", "UZ", "VN", "YE",
+    ],
+  },
+  {
+    code: "EU",
+    name: "Europe",
+    countries: [
+      "AD", "AL", "AT", "AX", "BA", "BE", "BG", "BY", "CH", "CZ", "DE", "DK", "EE", "ES", "FI", "FO",
+      "FR", "GB", "GG", "GI", "GR", "HR", "HU", "IE", "IM", "IS", "IT", "JE", "LI", "LT", "LU", "LV",
+      "MC", "MD", "ME", "MK", "MT", "NL", "NO", "PL", "PT", "RO", "RS", "RU", "SE", "SI", "SJ", "SK",
+      "SM", "UA", "VA",
+    ],
+  },
+  {
+    code: "NA",
+    name: "North America",
+    countries: [
+      "AG", "AI", "AW", "BB", "BL", "BM", "BQ", "BS", "BZ", "CA", "CR", "CU", "CW", "DM", "DO", "GD",
+      "GL", "GP", "GT", "HN", "HT", "JM", "KN", "KY", "LC", "MF", "MQ", "MS", "MX", "NI", "PA", "PM",
+      "PR", "SV", "SX", "TC", "TT", "US", "VC", "VG", "VI",
+    ],
+  },
+  {
+    code: "OC",
+    name: "Oceania",
+    countries: [
+      "AS", "AU", "CK", "FJ", "FM", "GU", "KI", "MH", "MP", "NC", "NF", "NR", "NU", "NZ", "PF", "PG",
+      "PN", "PW", "SB", "TK", "TO", "TV", "UM", "VU", "WF", "WS",
+    ],
+  },
+  {
+    code: "SA",
+    name: "South America",
+    countries: ["AR", "BO", "BR", "CL", "CO", "EC", "FK", "GF", "GY", "PE", "PY", "SR", "UY", "VE"],
+  },
+];
+
+/** Continent containing the given country code, if any. */
+export function continentOf(countryCode: string): ContinentInfo | undefined {
+  const cc = (countryCode || "").toUpperCase();
+  return CONTINENTS.find((c) => c.countries.includes(cc));
+}

package/base44/shared/commerce/data/countries.ts

@@ -0,0 +1,307 @@
+/**
+ * ISO 3166-1 countries with state/province subdivisions for the countries the
+ * template ships with (US, CA, AU — a common default trio;
+ * other countries use a free-text state field). A reference
+ * /data/countries dataset. Extend freely — plain static data.
+ */
+export interface StateInfo {
+  code: string;
+  name: string;
+}
+export interface CountryInfo {
+  code: string;
+  name: string;
+  states?: StateInfo[];
+}
+
+const US_STATES: StateInfo[] = [
+  { code: "AL", name: "Alabama" }, { code: "AK", name: "Alaska" }, { code: "AZ", name: "Arizona" },
+  { code: "AR", name: "Arkansas" }, { code: "CA", name: "California" }, { code: "CO", name: "Colorado" },
+  { code: "CT", name: "Connecticut" }, { code: "DE", name: "Delaware" }, { code: "DC", name: "District of Columbia" },
+  { code: "FL", name: "Florida" }, { code: "GA", name: "Georgia" }, { code: "HI", name: "Hawaii" },
+  { code: "ID", name: "Idaho" }, { code: "IL", name: "Illinois" }, { code: "IN", name: "Indiana" },
+  { code: "IA", name: "Iowa" }, { code: "KS", name: "Kansas" }, { code: "KY", name: "Kentucky" },
+  { code: "LA", name: "Louisiana" }, { code: "ME", name: "Maine" }, { code: "MD", name: "Maryland" },
+  { code: "MA", name: "Massachusetts" }, { code: "MI", name: "Michigan" }, { code: "MN", name: "Minnesota" },
+  { code: "MS", name: "Mississippi" }, { code: "MO", name: "Missouri" }, { code: "MT", name: "Montana" },
+  { code: "NE", name: "Nebraska" }, { code: "NV", name: "Nevada" }, { code: "NH", name: "New Hampshire" },
+  { code: "NJ", name: "New Jersey" }, { code: "NM", name: "New Mexico" }, { code: "NY", name: "New York" },
+  { code: "NC", name: "North Carolina" }, { code: "ND", name: "North Dakota" }, { code: "OH", name: "Ohio" },
+  { code: "OK", name: "Oklahoma" }, { code: "OR", name: "Oregon" }, { code: "PA", name: "Pennsylvania" },
+  { code: "RI", name: "Rhode Island" }, { code: "SC", name: "South Carolina" }, { code: "SD", name: "South Dakota" },
+  { code: "TN", name: "Tennessee" }, { code: "TX", name: "Texas" }, { code: "UT", name: "Utah" },
+  { code: "VT", name: "Vermont" }, { code: "VA", name: "Virginia" }, { code: "WA", name: "Washington" },
+  { code: "WV", name: "West Virginia" }, { code: "WI", name: "Wisconsin" }, { code: "WY", name: "Wyoming" },
+];
+
+const CA_PROVINCES: StateInfo[] = [
+  { code: "AB", name: "Alberta" }, { code: "BC", name: "British Columbia" }, { code: "MB", name: "Manitoba" },
+  { code: "NB", name: "New Brunswick" }, { code: "NL", name: "Newfoundland and Labrador" },
+  { code: "NT", name: "Northwest Territories" }, { code: "NS", name: "Nova Scotia" }, { code: "NU", name: "Nunavut" },
+  { code: "ON", name: "Ontario" }, { code: "PE", name: "Prince Edward Island" }, { code: "QC", name: "Quebec" },
+  { code: "SK", name: "Saskatchewan" }, { code: "YT", name: "Yukon" },
+];
+
+const AU_STATES: StateInfo[] = [
+  { code: "ACT", name: "Australian Capital Territory" }, { code: "NSW", name: "New South Wales" },
+  { code: "NT", name: "Northern Territory" }, { code: "QLD", name: "Queensland" },
+  { code: "SA", name: "South Australia" }, { code: "TAS", name: "Tasmania" },
+  { code: "VIC", name: "Victoria" }, { code: "WA", name: "Western Australia" },
+];
+
+export const COUNTRIES: CountryInfo[] = [
+  { code: "AF", name: "Afghanistan" },
+  { code: "AX", name: "Åland Islands" },
+  { code: "AL", name: "Albania" },
+  { code: "DZ", name: "Algeria" },
+  { code: "AS", name: "American Samoa" },
+  { code: "AD", name: "Andorra" },
+  { code: "AO", name: "Angola" },
+  { code: "AI", name: "Anguilla" },
+  { code: "AQ", name: "Antarctica" },
+  { code: "AG", name: "Antigua and Barbuda" },
+  { code: "AR", name: "Argentina" },
+  { code: "AM", name: "Armenia" },
+  { code: "AW", name: "Aruba" },
+  { code: "AU", name: "Australia", states: AU_STATES },
+  { code: "AT", name: "Austria" },
+  { code: "AZ", name: "Azerbaijan" },
+  { code: "BS", name: "Bahamas" },
+  { code: "BH", name: "Bahrain" },
+  { code: "BD", name: "Bangladesh" },
+  { code: "BB", name: "Barbados" },
+  { code: "BY", name: "Belarus" },
+  { code: "BE", name: "Belgium" },
+  { code: "BZ", name: "Belize" },
+  { code: "BJ", name: "Benin" },
+  { code: "BM", name: "Bermuda" },
+  { code: "BT", name: "Bhutan" },
+  { code: "BO", name: "Bolivia" },
+  { code: "BQ", name: "Bonaire, Sint Eustatius and Saba" },
+  { code: "BA", name: "Bosnia and Herzegovina" },
+  { code: "BW", name: "Botswana" },
+  { code: "BV", name: "Bouvet Island" },
+  { code: "BR", name: "Brazil" },
+  { code: "IO", name: "British Indian Ocean Territory" },
+  { code: "BN", name: "Brunei Darussalam" },
+  { code: "BG", name: "Bulgaria" },
+  { code: "BF", name: "Burkina Faso" },
+  { code: "BI", name: "Burundi" },
+  { code: "CV", name: "Cabo Verde" },
+  { code: "KH", name: "Cambodia" },
+  { code: "CM", name: "Cameroon" },
+  { code: "CA", name: "Canada", states: CA_PROVINCES },
+  { code: "KY", name: "Cayman Islands" },
+  { code: "CF", name: "Central African Republic" },
+  { code: "TD", name: "Chad" },
+  { code: "CL", name: "Chile" },
+  { code: "CN", name: "China" },
+  { code: "CX", name: "Christmas Island" },
+  { code: "CC", name: "Cocos (Keeling) Islands" },
+  { code: "CO", name: "Colombia" },
+  { code: "KM", name: "Comoros" },
+  { code: "CG", name: "Congo" },
+  { code: "CD", name: "Congo, Democratic Republic of the" },
+  { code: "CK", name: "Cook Islands" },
+  { code: "CR", name: "Costa Rica" },
+  { code: "CI", name: "Côte d'Ivoire" },
+  { code: "HR", name: "Croatia" },
+  { code: "CU", name: "Cuba" },
+  { code: "CW", name: "Curaçao" },
+  { code: "CY", name: "Cyprus" },
+  { code: "CZ", name: "Czechia" },
+  { code: "DK", name: "Denmark" },
+  { code: "DJ", name: "Djibouti" },
+  { code: "DM", name: "Dominica" },
+  { code: "DO", name: "Dominican Republic" },
+  { code: "EC", name: "Ecuador" },
+  { code: "EG", name: "Egypt" },
+  { code: "SV", name: "El Salvador" },
+  { code: "GQ", name: "Equatorial Guinea" },
+  { code: "ER", name: "Eritrea" },
+  { code: "EE", name: "Estonia" },
+  { code: "SZ", name: "Eswatini" },
+  { code: "ET", name: "Ethiopia" },
+  { code: "FK", name: "Falkland Islands" },
+  { code: "FO", name: "Faroe Islands" },
+  { code: "FJ", name: "Fiji" },
+  { code: "FI", name: "Finland" },
+  { code: "FR", name: "France" },
+  { code: "GF", name: "French Guiana" },
+  { code: "PF", name: "French Polynesia" },
+  { code: "TF", name: "French Southern Territories" },
+  { code: "GA", name: "Gabon" },
+  { code: "GM", name: "Gambia" },
+  { code: "GE", name: "Georgia" },
+  { code: "DE", name: "Germany" },
+  { code: "GH", name: "Ghana" },
+  { code: "GI", name: "Gibraltar" },
+  { code: "GR", name: "Greece" },
+  { code: "GL", name: "Greenland" },
+  { code: "GD", name: "Grenada" },
+  { code: "GP", name: "Guadeloupe" },
+  { code: "GU", name: "Guam" },
+  { code: "GT", name: "Guatemala" },
+  { code: "GG", name: "Guernsey" },
+  { code: "GN", name: "Guinea" },
+  { code: "GW", name: "Guinea-Bissau" },
+  { code: "GY", name: "Guyana" },
+  { code: "HT", name: "Haiti" },
+  { code: "HM", name: "Heard Island and McDonald Islands" },
+  { code: "VA", name: "Holy See" },
+  { code: "HN", name: "Honduras" },
+  { code: "HK", name: "Hong Kong" },
+  { code: "HU", name: "Hungary" },
+  { code: "IS", name: "Iceland" },
+  { code: "IN", name: "India" },
+  { code: "ID", name: "Indonesia" },
+  { code: "IR", name: "Iran" },
+  { code: "IQ", name: "Iraq" },
+  { code: "IE", name: "Ireland" },
+  { code: "IM", name: "Isle of Man" },
+  { code: "IL", name: "Israel" },
+  { code: "IT", name: "Italy" },
+  { code: "JM", name: "Jamaica" },
+  { code: "JP", name: "Japan" },
+  { code: "JE", name: "Jersey" },
+  { code: "JO", name: "Jordan" },
+  { code: "KZ", name: "Kazakhstan" },
+  { code: "KE", name: "Kenya" },
+  { code: "KI", name: "Kiribati" },
+  { code: "KP", name: "Korea, Democratic People's Republic of" },
+  { code: "KR", name: "Korea, Republic of" },
+  { code: "KW", name: "Kuwait" },
+  { code: "KG", name: "Kyrgyzstan" },
+  { code: "LA", name: "Lao People's Democratic Republic" },
+  { code: "LV", name: "Latvia" },
+  { code: "LB", name: "Lebanon" },
+  { code: "LS", name: "Lesotho" },
+  { code: "LR", name: "Liberia" },
+  { code: "LY", name: "Libya" },
+  { code: "LI", name: "Liechtenstein" },
+  { code: "LT", name: "Lithuania" },
+  { code: "LU", name: "Luxembourg" },
+  { code: "MO", name: "Macao" },
+  { code: "MG", name: "Madagascar" },
+  { code: "MW", name: "Malawi" },
+  { code: "MY", name: "Malaysia" },
+  { code: "MV", name: "Maldives" },
+  { code: "ML", name: "Mali" },
+  { code: "MT", name: "Malta" },
+  { code: "MH", name: "Marshall Islands" },
+  { code: "MQ", name: "Martinique" },
+  { code: "MR", name: "Mauritania" },
+  { code: "MU", name: "Mauritius" },
+  { code: "YT", name: "Mayotte" },
+  { code: "MX", name: "Mexico" },
+  { code: "FM", name: "Micronesia" },
+  { code: "MD", name: "Moldova" },
+  { code: "MC", name: "Monaco" },
+  { code: "MN", name: "Mongolia" },
+  { code: "ME", name: "Montenegro" },
+  { code: "MS", name: "Montserrat" },
+  { code: "MA", name: "Morocco" },
+  { code: "MZ", name: "Mozambique" },
+  { code: "MM", name: "Myanmar" },
+  { code: "NA", name: "Namibia" },
+  { code: "NR", name: "Nauru" },
+  { code: "NP", name: "Nepal" },
+  { code: "NL", name: "Netherlands" },
+  { code: "NC", name: "New Caledonia" },
+  { code: "NZ", name: "New Zealand" },
+  { code: "NI", name: "Nicaragua" },
+  { code: "NE", name: "Niger" },
+  { code: "NG", name: "Nigeria" },
+  { code: "NU", name: "Niue" },
+  { code: "NF", name: "Norfolk Island" },
+  { code: "MK", name: "North Macedonia" },
+  { code: "MP", name: "Northern Mariana Islands" },
+  { code: "NO", name: "Norway" },
+  { code: "OM", name: "Oman" },
+  { code: "PK", name: "Pakistan" },
+  { code: "PW", name: "Palau" },
+  { code: "PS", name: "Palestine, State of" },
+  { code: "PA", name: "Panama" },
+  { code: "PG", name: "Papua New Guinea" },
+  { code: "PY", name: "Paraguay" },
+  { code: "PE", name: "Peru" },
+  { code: "PH", name: "Philippines" },
+  { code: "PN", name: "Pitcairn" },
+  { code: "PL", name: "Poland" },
+  { code: "PT", name: "Portugal" },
+  { code: "PR", name: "Puerto Rico" },
+  { code: "QA", name: "Qatar" },
+  { code: "RE", name: "Réunion" },
+  { code: "RO", name: "Romania" },
+  { code: "RU", name: "Russian Federation" },
+  { code: "RW", name: "Rwanda" },
+  { code: "BL", name: "Saint Barthélemy" },
+  { code: "SH", name: "Saint Helena, Ascension and Tristan da Cunha" },
+  { code: "KN", name: "Saint Kitts and Nevis" },
+  { code: "LC", name: "Saint Lucia" },
+  { code: "MF", name: "Saint Martin (French part)" },
+  { code: "PM", name: "Saint Pierre and Miquelon" },
+  { code: "VC", name: "Saint Vincent and the Grenadines" },
+  { code: "WS", name: "Samoa" },
+  { code: "SM", name: "San Marino" },
+  { code: "ST", name: "Sao Tome and Principe" },
+  { code: "SA", name: "Saudi Arabia" },
+  { code: "SN", name: "Senegal" },
+  { code: "RS", name: "Serbia" },
+  { code: "SC", name: "Seychelles" },
+  { code: "SL", name: "Sierra Leone" },
+  { code: "SG", name: "Singapore" },
+  { code: "SX", name: "Sint Maarten (Dutch part)" },
+  { code: "SK", name: "Slovakia" },
+  { code: "SI", name: "Slovenia" },
+  { code: "SB", name: "Solomon Islands" },
+  { code: "SO", name: "Somalia" },
+  { code: "ZA", name: "South Africa" },
+  { code: "GS", name: "South Georgia and the South Sandwich Islands" },
+  { code: "SS", name: "South Sudan" },
+  { code: "ES", name: "Spain" },
+  { code: "LK", name: "Sri Lanka" },
+  { code: "SD", name: "Sudan" },
+  { code: "SR", name: "Suriname" },
+  { code: "SJ", name: "Svalbard and Jan Mayen" },
+  { code: "SE", name: "Sweden" },
+  { code: "CH", name: "Switzerland" },
+  { code: "SY", name: "Syrian Arab Republic" },
+  { code: "TW", name: "Taiwan" },
+  { code: "TJ", name: "Tajikistan" },
+  { code: "TZ", name: "Tanzania" },
+  { code: "TH", name: "Thailand" },
+  { code: "TL", name: "Timor-Leste" },
+  { code: "TG", name: "Togo" },
+  { code: "TK", name: "Tokelau" },
+  { code: "TO", name: "Tonga" },
+  { code: "TT", name: "Trinidad and Tobago" },
+  { code: "TN", name: "Tunisia" },
+  { code: "TR", name: "Türkiye" },
+  { code: "TM", name: "Turkmenistan" },
+  { code: "TC", name: "Turks and Caicos Islands" },
+  { code: "TV", name: "Tuvalu" },
+  { code: "UG", name: "Uganda" },
+  { code: "UA", name: "Ukraine" },
+  { code: "AE", name: "United Arab Emirates" },
+  { code: "GB", name: "United Kingdom" },
+  { code: "US", name: "United States", states: US_STATES },
+  { code: "UM", name: "United States Minor Outlying Islands" },
+  { code: "UY", name: "Uruguay" },
+  { code: "UZ", name: "Uzbekistan" },
+  { code: "VU", name: "Vanuatu" },
+  { code: "VE", name: "Venezuela" },
+  { code: "VN", name: "Viet Nam" },
+  { code: "VG", name: "Virgin Islands (British)" },
+  { code: "VI", name: "Virgin Islands (U.S.)" },
+  { code: "WF", name: "Wallis and Futuna" },
+  { code: "EH", name: "Western Sahara" },
+  { code: "YE", name: "Yemen" },
+  { code: "ZM", name: "Zambia" },
+  { code: "ZW", name: "Zimbabwe" },
+];
+
+/** Lookup helper: country by ISO code. */
+export function getCountry(code: string): CountryInfo | undefined {
+  return COUNTRIES.find((c) => c.code === (code || "").toUpperCase());
+}