@base44/app-plugin-commerce 0.1.6 → 0.1.8

package/base44/shared/commerce/settings.ts

@@ -33,21 +33,16 @@ export function getSetting(groups: Record<string, any>, group: string, key: stri
  */
 export function storefrontSafeSettings(groups: Record<string, any>): Record<string, any> {
   const general = groups.general ?? {};
-  const products = groups.products ?? {};
   const tax = groups.tax ?? {};
   const inventory = groups.inventory ?? {};
   return {
     // The one key taken from the emails group: the store's own name is public.
     store_name: groups.emails?.store_name ?? "",
+    // Currency is a value, not a format: render prices with
+    // Intl.NumberFormat(undefined, { style: "currency", currency }).
     currency: general.currency ?? "USD",
-    currency_position: general.currency_position ?? "left",
-    thousand_sep: general.thousand_sep ?? ",",
-    decimal_sep: general.decimal_sep ?? ".",
-    num_decimals: general.num_decimals ?? 2,
-    weight_unit: products.weight_unit ?? "kg",
-    dimension_unit: products.dimension_unit ?? "cm",
-    enable_reviews: products.enable_reviews ?? true,
-    review_rating_required: products.review_rating_required ?? true,
+    weight_unit: general.weight_unit ?? "kg",
+    dimension_unit: general.dimension_unit ?? "cm",
     prices_include_tax: tax.prices_include_tax ?? false,
     display_prices_shop: tax.display_prices_shop ?? "excl",
     display_prices_cart: tax.display_prices_cart ?? "excl",

package/base44/shared/commerce/shipping.ts

@@ -1,14 +1,14 @@
 /**
- * Shipping-zone matching and method cost computation (standard commerce semantics):
- * - zones are checked in `order` asc; the first matching zone wins
- * - region locations (continent/country/state) OR together; postcode locations
- *   act as an AND filter on top (a zone with only postcode locations matches
- *   any region but requires a postcode hit)
- * - a zone with NO locations is the "Rest of the world" fallback, used only
- *   when no located zone matches
+ * Shipping over Shipping & Tax Locations:
+ * - locations are checked in `order` asc; the first whose regions match wins
+ * - regions OR together (continent/country/state — no postcode filters)
+ * - a location with NO regions is the "Rest of the world" fallback, used only
+ *   when no regioned location matches
+ * - a location's shipping_rates are the checkout options; a rate with
+ *   `free_over` costs 0 once the discounted items subtotal reaches it, and a
+ *   free-shipping coupon zeroes every offered rate
  */
 import { round2 } from "./money.ts";
-import { postcodeMatchesPattern } from "./tax.ts";
 import { continentOf } from "./data/continents.ts";
 
 export interface ShipAddress {
@@ -18,78 +18,56 @@ export interface ShipAddress {
   city?: string;
 }
 
-/** Re-export for callers that only import shipping.ts. */
-export function postcodeMatches(pattern: string, postcode: string): boolean {
-  return postcodeMatchesPattern(pattern, postcode);
-}
-
-function zoneMatches(zone: any, addr: ShipAddress): boolean {
-  const locations: any[] = zone.locations || [];
-  if (!locations.length) return false; // fallback zones handled by caller
+function regionsMatch(location: any, addr: ShipAddress): boolean {
+  const regions: any[] = location.regions || [];
+  if (!regions.length) return false; // fallback locations handled by caller
   const country = (addr.country || "").toUpperCase();
   const state = (addr.state || "").toUpperCase();
   const stateCode = country && state ? `${country}:${state}` : "";
 
-  const regions = locations.filter((l) => l.type !== "postcode");
-  const postcodes = locations.filter((l) => l.type === "postcode");
-
-  let regionOk = regions.length === 0; // postcode-only zone: no region restriction
-  for (const loc of regions) {
-    const code = (loc.code || "").toUpperCase();
-    if (loc.type === "continent" && continentOf(country)?.code === code) regionOk = true;
-    if (loc.type === "country" && code === country) regionOk = true;
-    if (loc.type === "state" && code === stateCode) regionOk = true;
-    if (regionOk) break;
-  }
-  if (!regionOk) return false;
-
-  if (postcodes.length) {
-    return postcodes.some((loc) => postcodeMatchesPattern(loc.code || "", addr.postcode || ""));
+  for (const region of regions) {
+    const code = (region.code || "").toUpperCase();
+    if (region.type === "continent" && continentOf(country)?.code === code) return true;
+    if (region.type === "country" && code === country) return true;
+    if (region.type === "state" && code === stateCode) return true;
   }
-  return true;
+  return false;
 }
 
 /**
- * Pick the shipping zone for an address: first located zone (by `order` asc)
- * that matches, else the fallback zone (empty locations — "Rest of the world"),
- * else null.
+ * Pick the Shipping & Tax Location for an address: first regioned location
+ * (by `order` asc) that matches, else the fallback location (no regions —
+ * "Rest of the world"), else null.
  */
-export function matchZone(zones: any[], addr: ShipAddress): any | null {
-  const sorted = [...(zones || [])].sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
-  for (const zone of sorted) {
-    if ((zone.locations || []).length && zoneMatches(zone, addr)) return zone;
+export function matchLocation(locations: any[], addr: ShipAddress): any | null {
+  const sorted = [...(locations || [])].sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+  for (const location of sorted) {
+    if ((location.regions || []).length && regionsMatch(location, addr)) return location;
   }
-  return sorted.find((z) => !(z.locations || []).length) ?? null;
+  return sorted.find((l) => !(l.regions || []).length) ?? null;
 }
 
 export interface PricedCartForShipping {
-  /** Lines with shipping_class_id + discounted totals (ex tax). */
-  lines: Array<{
-    shipping_class_id?: string;
-    virtual?: boolean;
-    quantity: number;
-    subtotal: number;
-    total: number;
-  }>;
-  itemsSubtotal: number;            // pre-discount, ex tax
+  itemsSubtotal: number;              // pre-discount, ex tax
   itemsSubtotalAfterDiscount: number; // post-discount, ex tax
 }
 
-export interface AvailableMethod {
-  method: any;
+export interface AvailableRate {
+  rate: any;
   cost: number;
 }
 
 /** Outcome of {@link resolveShippingSelection}. */
 export type ShippingSelectionState =
   | "not_needed"       // virtual-only cart, or shipping disabled store-wide
-  | "chosen"           // the caller's method is offered for this address
-  | "auto_selected"    // exactly one method is offered — no choice to make
-  | "choice_required"  // several methods are offered and none is chosen yet
-  | "none_available";  // nothing ships to this address (or no zone/method configured)
+  | "chosen"           // the caller's rate is offered for this address
+  | "auto_selected"    // exactly one rate is offered — no choice to make
+  | "choice_required"  // several rates are offered and none is chosen yet
+  | "missing_address"  // options can't be determined until an address is set (several locations defined)
+  | "none_available";  // nothing ships to this address (or no location/rate configured)
 
 export interface ShippingSelection {
-  /** The ShippingZoneMethod id to price with; "" when there is nothing to apply. */
+  /** The shipping rate id to price with; "" when there is nothing to apply. */
   method_id: string;
   state: ShippingSelectionState;
   /** A previously stored choice is no longer offered (address or cart changed). */
@@ -97,19 +75,21 @@ export interface ShippingSelection {
 }
 
 /**
- * Decide which shipping method a **storefront** cart/checkout should use.
+ * Decide which shipping rate a **storefront** cart/checkout should use.
  *
  * Storefronts must not be able to place a shippable order with no shipping
  * line — that silently ships for free — so this collapses the decision to one
  * rule set the cart and checkout both follow:
  *
  * - virtual-only cart, or shipping disabled → nothing to do;
- * - the chosen method is still offered → keep it;
- * - exactly one method offered → **select it automatically**; a single option is
+ * - the chosen rate is still offered → keep it;
+ * - exactly one rate offered → **select it automatically**; a single option is
  *   not a choice, and requiring a round trip for it is the trap that makes
  *   storefronts forget shipping entirely;
  * - several offered, none chosen → the caller must ask the customer;
- * - none offered → the store does not ship to this address.
+ * - none offered, no address yet → the caller must collect an address before the
+ *   options (and the shipping cost) can be calculated (`missing_address`);
+ * - none offered with an address → the store does not ship to this address.
  *
  * Deliberately *not* applied by the totals engine itself: admin orders are
  * priced through the same engine and must never grow a shipping charge the
@@ -120,13 +100,21 @@ export function resolveShippingSelection(input: {
   shippingEnabled?: boolean;
   chosenMethodId?: string;
   available: Array<{ id: string }>;
+  /** Whether a shipping address (country) is known. Defaults to true. */
+  hasAddress?: boolean;
 }): ShippingSelection {
   const chosen = String(input.chosenMethodId || "");
   if (!input.needsShipping || input.shippingEnabled === false) {
     return { method_id: "", state: "not_needed", stale: false };
   }
   const available = input.available ?? [];
-  if (!available.length) return { method_id: "", state: "none_available", stale: !!chosen };
+  if (!available.length) {
+    return {
+      method_id: "",
+      state: input.hasAddress === false ? "missing_address" : "none_available",
+      stale: !!chosen,
+    };
+  }
   if (chosen && available.some((m) => m.id === chosen)) {
     return { method_id: chosen, state: "chosen", stale: false };
   }
@@ -136,80 +124,24 @@ export function resolveShippingSelection(input: {
   return { method_id: "", state: "choice_required", stale: !!chosen };
 }
 
-function flatRateCost(method: any, cart: PricedCartForShipping): number {
-  const s = method.settings || {};
-  let cost = Number(s.cost) || 0;
-  const classCosts: any[] = s.class_costs || [];
-  const noClassCost = Number(s.no_class_cost) || 0;
-  const shippable = cart.lines.filter((l) => !l.virtual);
-  const classesPresent = [...new Set(shippable.filter((l) => l.shipping_class_id).map((l) => l.shipping_class_id))];
-  const hasClassless = shippable.some((l) => !l.shipping_class_id);
-
-  const applicable: number[] = [];
-  for (const clsId of classesPresent) {
-    const entry = classCosts.find((c) => c.shipping_class_id === clsId);
-    if (entry) applicable.push(Number(entry.cost) || 0);
-  }
-  if (hasClassless && noClassCost) applicable.push(noClassCost);
-
-  if ((s.calculation_type || "class") === "class") {
-    // "Charge shipping for each class individually"
-    cost += applicable.reduce((a, b) => a + b, 0);
-  } else if (applicable.length) {
-    // "order": charge based on the most expensive class in the cart
-    cost += Math.max(...applicable);
-  }
-  return round2(cost);
-}
-
-function freeShippingAvailable(method: any, cart: PricedCartForShipping, appliedCoupons: any[]): boolean {
-  const s = method.settings || {};
-  const requires = s.requires || "";
-  if (!requires) return true;
-  const hasCoupon = (appliedCoupons || []).some((c) => c?.free_shipping);
-  const basis = s.ignore_discounts ? cart.itemsSubtotal : cart.itemsSubtotalAfterDiscount;
-  const minOk = basis >= (Number(s.min_amount) || 0);
-  switch (requires) {
-    case "coupon": return hasCoupon;
-    case "min_amount": return minOk;
-    case "either": return hasCoupon || minOk;
-    case "both": return hasCoupon && minOk;
-    default: return true;
-  }
-}
-
 /**
- * Compute the offer-able methods (with costs) for a matched zone.
- * `methods` = the zone's ShippingZoneMethod records (any order); disabled and
- * unmet-requirement methods are excluded. Free-shipping coupons only *enable*
- * the free_shipping method — they never zero out flat rates (intended behavior).
+ * The rates a matched location offers, with live costs: `free_over` zeroes a
+ * rate once the discounted items subtotal reaches it, and a free-shipping
+ * coupon zeroes every rate. Rates keep their configured order.
  */
-export function availableMethods(
-  zone: any,
-  methods: any[],
+export function availableRates(
+  location: any,
   cart: PricedCartForShipping,
-  _settings: Record<string, any>,
   appliedCoupons: any[] = [],
-): AvailableMethod[] {
-  const zoneMethods = (methods || [])
-    .filter((m) => m.zone_id === zone?.id && m.enabled !== false)
-    .sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
-  const out: AvailableMethod[] = [];
-  for (const method of zoneMethods) {
-    switch (method.method_id) {
-      case "flat_rate":
-        out.push({ method, cost: flatRateCost(method, cart) });
-        break;
-      case "free_shipping":
-        if (freeShippingAvailable(method, cart, appliedCoupons)) out.push({ method, cost: 0 });
-        break;
-      case "local_pickup":
-        out.push({ method, cost: round2(Number(method.settings?.cost) || 0) });
-        break;
-      default:
-        // unknown custom method: offer at its configured flat cost
-        out.push({ method, cost: round2(Number(method.settings?.cost) || 0) });
-    }
-  }
-  return out;
+): AvailableRate[] {
+  const couponFree = (appliedCoupons || []).some((c) => c?.free_shipping);
+  return (location?.shipping_rates ?? [])
+    .filter((r: any) => r && r.id)
+    .map((rate: any) => {
+      const threshold = rate.free_over;
+      const thresholdMet = threshold != null && Number.isFinite(Number(threshold)) &&
+        cart.itemsSubtotalAfterDiscount >= Number(threshold);
+      const cost = couponFree || thresholdMet ? 0 : round2(Number(rate.cost) || 0);
+      return { rate, cost };
+    });
 }

package/base44/shared/commerce/tax.ts

@@ -1,9 +1,11 @@
 /**
- * Tax-rate matching and application, following standard commerce tax semantics:
- * - rates match by tax class + location (empty field = wildcard)
- * - rates sort by priority asc; ONE rate applies per priority level
- * - non-compound rates apply on the base amount; compound rates apply on
- *   (base + all previously accumulated tax), in priority order
+ * Tax resolution over Shipping & Tax Locations.
+ *
+ * A location carries named tax groups (default group "Products"); a product
+ * picks its group by name via `tax_group`. A group's tax is simply the sum of
+ * its rates — there are no priorities, no compounding, no per-rate location
+ * filters: the location IS the filter. Shipping tax is the location's own
+ * `shipping_tax` ({type: "percent"|"fixed", value}).
  */
 import { round2 } from "./money.ts";
 
@@ -14,81 +16,36 @@ export interface TaxAddress {
   city?: string;
 }
 
-/** Does `postcode` match `pattern`? Supports exact, `90*` wildcard, `1000...2000` numeric range. */
-export function postcodeMatchesPattern(pattern: string, postcode: string): boolean {
-  const p = (pattern || "").trim().toUpperCase();
-  const pc = (postcode || "").trim().toUpperCase();
-  if (!p) return true; // empty pattern = wildcard
-  if (!pc) return false;
-  if (p.includes("...")) {
-    const [lo, hi] = p.split("...").map((s) => parseInt(s.trim(), 10));
-    const n = parseInt(pc, 10);
-    return !Number.isNaN(lo) && !Number.isNaN(hi) && !Number.isNaN(n) && n >= lo && n <= hi;
-  }
-  if (p.includes("*")) {
-    const re = new RegExp("^" + p.split("*").map(escapeRegex).join(".*") + "$");
-    return re.test(pc);
-  }
-  return p === pc;
-}
-
-function escapeRegex(s: string): string {
-  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
+export const DEFAULT_TAX_GROUP = "Products";
 
-function rateMatchesLocation(rate: any, addr: TaxAddress): boolean {
-  const country = (addr.country || "").toUpperCase();
-  const state = (addr.state || "").toUpperCase();
-  const city = (addr.city || "").toLowerCase();
-  if (rate.country && rate.country.toUpperCase() !== country) return false;
-  if (rate.state && rate.state.toUpperCase() !== state) return false;
-  const postcodes: string[] = rate.postcodes || [];
-  if (postcodes.length && !postcodes.some((p: string) => postcodeMatchesPattern(p, addr.postcode || ""))) return false;
-  const cities: string[] = rate.cities || [];
-  if (cities.length && !cities.some((c: string) => (c || "").toLowerCase() === city)) return false;
-  return true;
+export interface TaxRate {
+  name?: string;
+  rate: number; // percentage, e.g. 18 for 18%
 }
 
 /**
- * Find the applicable rates for a tax class at an address.
- * Sorted by priority asc (menu_order breaks ties); one rate per priority.
+ * The rates a tax group applies at a location. Group names match
+ * case-insensitively; a missing group (or no location) means no tax.
  */
-export function matchTaxRates(allRates: any[], addr: TaxAddress, taxClass: string): any[] {
-  const cls = taxClass || "standard";
-  const candidates = (allRates || [])
-    .filter((r) => (r.tax_class || "standard") === cls && rateMatchesLocation(r, addr))
-    .sort((a, b) => (a.priority ?? 1) - (b.priority ?? 1) || (a.menu_order ?? 0) - (b.menu_order ?? 0));
-  // only the first matching rate per priority level applies
-  const byPriority = new Map<number, any>();
-  for (const r of candidates) {
-    const p = r.priority ?? 1;
-    if (!byPriority.has(p)) byPriority.set(p, r);
-  }
-  return [...byPriority.values()];
+export function taxRatesFor(location: any, groupName?: string): TaxRate[] {
+  const wanted = String(groupName || DEFAULT_TAX_GROUP).toLowerCase();
+  const group = (location?.tax_groups ?? []).find(
+    (g: any) => String(g?.name ?? "").toLowerCase() === wanted,
+  );
+  return (group?.rates ?? [])
+    .map((r: any) => ({ name: r?.name ?? "", rate: Number(r?.rate) || 0 }))
+    .filter((r: TaxRate) => r.rate > 0);
 }
 
 export interface AppliedRate {
-  rate: any;
+  rate: TaxRate;
   amount: number;
 }
 
-/**
- * Apply matched rates (already priority-deduped, priority-ordered) to an
- * ex-tax amount. Non-compound rates each apply on the base; compound rates
- * apply on base + accumulated tax so far.
- */
-export function applyRates(amount: number, rates: any[]): AppliedRate[] {
+/** Apply rates to an ex-tax amount. Every rate applies on the base. */
+export function applyRates(amount: number, rates: TaxRate[]): AppliedRate[] {
   const base = Number(amount) || 0;
-  const out: AppliedRate[] = [];
-  let accumulated = 0;
-  for (const rate of rates || []) {
-    const pct = (Number(rate.rate) || 0) / 100;
-    const taxable = rate.compound ? base + accumulated : base;
-    const tax = round2(taxable * pct);
-    accumulated += tax;
-    out.push({ rate, amount: tax });
-  }
-  return out;
+  return (rates || []).map((rate) => ({ rate, amount: round2(base * ((Number(rate.rate) || 0) / 100)) }));
 }
 
 export interface InclusiveTaxResult {
@@ -98,39 +55,34 @@ export interface InclusiveTaxResult {
 }
 
 /**
- * Extract tax from a tax-INCLUSIVE gross amount (prices_include_tax mode),
- * mirroring standard inclusive-tax extraction: compound rates are unwound from the
- * outside in (last priority first), then the remaining amount is split across
- * the non-compound rates which all share the same net base.
+ * Extract tax from a tax-INCLUSIVE gross amount (prices_include_tax mode).
+ * All rates share the same net base: net = gross / (1 + sum of rates).
  */
-export function extractInclusiveTax(gross: number, rates: any[]): InclusiveTaxResult {
-  let remaining = Number(gross) || 0;
-  const taxesByRate = new Map<any, number>();
-
-  // 1) unwind compound rates, highest priority (applied last) first
-  const compound = (rates || []).filter((r) => r.compound).reverse();
-  for (const rate of compound) {
-    const pct = (Number(rate.rate) || 0) / 100;
-    const tax = round2(remaining - remaining / (1 + pct));
-    taxesByRate.set(rate, tax);
-    remaining -= tax;
-  }
-
-  // 2) the non-compound rates all apply on the same net base
-  const regular = (rates || []).filter((r) => !r.compound);
-  const regularSum = regular.reduce((a, r) => a + (Number(r.rate) || 0) / 100, 0);
-  const net = regularSum > 0 ? remaining / (1 + regularSum) : remaining;
-  for (const rate of regular) {
-    const pct = (Number(rate.rate) || 0) / 100;
-    taxesByRate.set(rate, round2(net * pct));
-  }
-
-  const taxes: AppliedRate[] = (rates || []).map((rate) => ({ rate, amount: taxesByRate.get(rate) ?? 0 }));
+export function extractInclusiveTax(gross: number, rates: TaxRate[]): InclusiveTaxResult {
+  const total = Number(gross) || 0;
+  const sum = (rates || []).reduce((a, r) => a + (Number(r.rate) || 0) / 100, 0);
+  const net = sum > 0 ? total / (1 + sum) : total;
+  const taxes: AppliedRate[] = (rates || []).map((rate) => ({
+    rate,
+    amount: round2(net * ((Number(rate.rate) || 0) / 100)),
+  }));
   const totalTax = round2(taxes.reduce((a, t) => a + t.amount, 0));
-  return { net: round2((Number(gross) || 0) - totalTax), taxes, totalTax };
+  return { net: round2(total - totalTax), taxes, totalTax };
 }
 
 /** Sum of applied-rate amounts, rounded. */
 export function sumTax(applied: AppliedRate[]): number {
   return round2((applied || []).reduce((a, t) => a + t.amount, 0));
 }
+
+/**
+ * The location's tax on a shipping cost: percent of the cost, or a fixed
+ * amount (charged once per order, regardless of the cost).
+ */
+export function shippingTaxFor(location: any, shippingCost: number): number {
+  const cfg = location?.shipping_tax;
+  const value = Number(cfg?.value) || 0;
+  if (!cfg || value <= 0) return 0;
+  if (cfg.type === "fixed") return round2(value);
+  return round2((Number(shippingCost) || 0) * (value / 100));
+}