@base44/app-plugin-commerce 0.1.6 → 0.1.8

package/src/commerce/utils/shipping-promos.js

@@ -3,87 +3,83 @@
  * ("Free shipping over €150", "You're €30 away from free shipping") states a
  * real rule instead of an invented number.
  *
- * A free-shipping claim is only true if a `free_shipping` shipping-zone method
- * exists and its requirement is met — the totals engine offers that method
- * exactly when `min_amount`/coupon conditions hold, so anything the UI promises
- * outside these rules is a promise the checkout will not keep.
+ * A free-shipping claim is only true if a Shipping & Tax Location carries a
+ * shipping rate that is free — `cost: 0` — or becomes free at a threshold
+ * (`free_over`). The totals engine zeroes the rate exactly when the discounted
+ * items subtotal reaches `free_over`, so anything the UI promises outside
+ * these rules is a promise the checkout will not keep.
  *
- * **Zones are admin-only data.** `commerce.ShippingZone` and
- * `commerce.ShippingZoneMethod` are `read: {role: "admin"}` like every entity, so
- * a visitor cannot list them — these helpers run where the records are already in
- * hand: a backend function, an admin screen, or a storefront action you add that
- * projects the rules itself.
+ * **Locations are admin-only data.** `commerce.ShippingTaxLocation` is
+ * `read: {role: "admin"}` like every entity, so a visitor cannot list them —
+ * these helpers run where the records are already in hand: a backend function,
+ * an admin screen, or a storefront action you add that projects the rules.
  *
  * ```js
- * const rules = freeShippingRules(zones, methods);
+ * const rules = freeShippingRules(locations);
  * // no rules → do not advertise free shipping anywhere.
  * ```
  *
  * For the *live* answer on a real cart, use the cart view's
- * `available_shipping_methods` after `set-shipping-address` — that is computed by
- * the same engine and needs no extra exposure.
+ * `available_shipping_methods` after `set-shipping-address` — that is computed
+ * by the same engine and needs no extra exposure.
  *
  * Framework-free and dependency-free. See
- * `skills/commerce/docs/api-storefront.md` for the surrounding rules.
+ * `.agents/skills/commerce/docs/api-storefront.md` for the surrounding rules.
  */
 
 /**
- * Normalized free-shipping rules, one per configured `free_shipping` method.
+ * Normalized free-shipping rules, one per rate that is free or has a
+ * `free_over` threshold.
  *
  * @returns {Array<{
- *   zone_id: string, zone_name: string, method_id: string, title: string,
- *   requires: "" | "coupon" | "min_amount" | "either" | "both",
- *   min_amount: number|null, needs_coupon: boolean, ignore_discounts: boolean,
- *   unconditional: boolean
+ *   location_id: string, location_name: string, rate_id: string, title: string,
+ *   min_amount: number|null, unconditional: boolean
  * }>}
  */
-export function freeShippingRules(zones, methods) {
-  const zoneById = new Map((zones ?? []).map((z) => [z.id, z]));
-  return (methods ?? [])
-    .filter((m) => m?.method_id === "free_shipping" && m.enabled !== false)
-    .map((m) => {
-      const s = m.settings ?? {};
-      const requires = s.requires ?? "";
-      const min = Number(s.min_amount);
-      return {
-        zone_id: m.zone_id ?? "",
-        zone_name: zoneById.get(m.zone_id)?.name ?? "",
-        method_id: m.id,
-        title: m.title || "Free shipping",
-        requires,
-        min_amount: ["min_amount", "either", "both"].includes(requires) && Number.isFinite(min) ? min : null,
-        needs_coupon: ["coupon", "either", "both"].includes(requires),
-        ignore_discounts: !!s.ignore_discounts,
-        unconditional: !requires,
-      };
-    });
+export function freeShippingRules(locations) {
+  const out = [];
+  for (const location of locations ?? []) {
+    for (const rate of location?.shipping_rates ?? []) {
+      const threshold = Number(rate?.free_over);
+      const free = Number(rate?.cost ?? 0) === 0;
+      const hasThreshold = rate?.free_over != null && Number.isFinite(threshold);
+      if (!free && !hasThreshold) continue;
+      out.push({
+        location_id: location.id ?? "",
+        location_name: location.name ?? "",
+        rate_id: rate.id ?? "",
+        title: rate.name || "Free shipping",
+        min_amount: free ? null : threshold,
+        unconditional: free,
+      });
+    }
+  }
+  return out;
 }
 
 /**
  * The threshold to advertise, or `null` when the store has none — in which case
  * **say nothing about free shipping**. Picks the lowest configured threshold
- * (the one a shopper can actually reach); an unconditional free-shipping method
- * yields `0`, i.e. "free shipping" with no threshold at all.
+ * (the one a shopper can actually reach); an always-free rate yields `0`,
+ * i.e. "free shipping" with no threshold at all.
  *
- * Thresholds are per shipping zone, so a global banner is only honest when the
- * rule covers the customer's zone — pass `zoneId` once you know it (after
+ * Thresholds are per location, so a global banner is only honest when the rule
+ * covers the customer's location — pass `locationId` once you know it (after
  * `set-shipping-address`, the cart's `available_shipping_methods` is the
  * authoritative answer for that address).
  */
-export function freeShippingThreshold(rules, zoneId = null) {
-  const scoped = (rules ?? []).filter((r) => (zoneId ? r.zone_id === zoneId : true));
+export function freeShippingThreshold(rules, locationId = null) {
+  const scoped = (rules ?? []).filter((r) => (locationId ? r.location_id === locationId : true));
   if (!scoped.length) return null;
   if (scoped.some((r) => r.unconditional)) return 0;
-  const amounts = scoped
-    .filter((r) => !r.needs_coupon && r.min_amount != null)
-    .map((r) => r.min_amount);
+  const amounts = scoped.filter((r) => r.min_amount != null).map((r) => r.min_amount);
   return amounts.length ? Math.min(...amounts) : null;
 }
 
 /**
  * Progress toward a threshold, for a "spend X more" nudge. `subtotal` should be
- * the cart's `totals.subtotal` — or `subtotal - discount_total` when the rule
- * does not `ignore_discounts`, matching how the engine evaluates it.
+ * the cart's `totals.subtotal - totals.discount_total` — the engine compares
+ * `free_over` against the discounted items subtotal.
  *
  * @returns {{threshold: number, qualifies: boolean, remaining: number}|null}
  *   `null` when there is no threshold to talk about.

package/src/commerce/utils/variants.js

@@ -12,7 +12,7 @@
  * Framework-free, dependency-free, no I/O — feed them the `{ product,
  * variations }` pair from `commerce/storefront-catalog` `get-product` (the
  * admin's variation editor can use them too). See
- * `skills/commerce/references/storefront-product-page.md` for the UI rules.
+ * `.agents/skills/commerce/references/storefront-product-page.md` for the UI rules.
  *
  * A `selection` throughout is a plain object keyed by axis key (see
  * `attributeKey`): `{ "<color-attr-id>": "Red", "<size-attr-id>": "M" }`.

package/base44/entities/commerce.ShippingClass.jsonc

@@ -1,30 +0,0 @@
-{
-  "name": "commerce.ShippingClass",
-  "type": "object",
-  "description": "Shipping class assignable to products; flat-rate methods can charge per class.",
-  "properties": {
-    "name": {
-      "type": "string",
-      "minLength": 1
-    },
-    "slug": {
-      "type": "string",
-      "description": "Unique slug (enforced in admin UI / functions)"
-    },
-    "description": {
-      "type": "string"
-    },
-    "count": {
-      "type": "integer",
-      "default": 0,
-      "description": "Derived product count. Maintained by commerce/admin-products; repair via commerce/admin-tools recount-terms."
-    }
-  },
-  "required": ["name"],
-  "rls": {
-    "read": { "user_condition": { "role": "admin" } },
-    "create": { "user_condition": { "role": "admin" } },
-    "update": { "user_condition": { "role": "admin" } },
-    "delete": { "user_condition": { "role": "admin" } }
-  }
-}

package/base44/entities/commerce.ShippingZone.jsonc

@@ -1,41 +0,0 @@
-{
-  "name": "commerce.ShippingZone",
-  "type": "object",
-  "description": "Geographic shipping zone. Zones are matched by 'order' ascending; the seeded 'Rest of the world' zone (order 999, no locations) catches unmatched addresses.",
-  "properties": {
-    "name": {
-      "type": "string",
-      "minLength": 1
-    },
-    "order": {
-      "type": "integer",
-      "default": 0,
-      "description": "Match priority, ascending"
-    },
-    "locations": {
-      "type": "array",
-      "description": "Zone locations; empty = matches everything (fallback zone)",
-      "items": {
-        "type": "object",
-        "properties": {
-          "type": {
-            "type": "string",
-            "enum": ["country", "state", "postcode", "continent"],
-            "description": "Location type"
-          },
-          "code": {
-            "type": "string",
-            "description": "Country code (US), state code (US:CA), postcode pattern (90*, 1000...2000), or continent code (EU)"
-          }
-        }
-      }
-    }
-  },
-  "required": ["name"],
-  "rls": {
-    "read": { "user_condition": { "role": "admin" } },
-    "create": { "user_condition": { "role": "admin" } },
-    "update": { "user_condition": { "role": "admin" } },
-    "delete": { "user_condition": { "role": "admin" } }
-  }
-}

package/base44/entities/commerce.ShippingZoneMethod.jsonc

@@ -1,84 +0,0 @@
-{
-  "name": "commerce.ShippingZoneMethod",
-  "type": "object",
-  "description": "A shipping method instance attached to a zone. The settings object shape depends on method_id.",
-  "properties": {
-    "zone_id": {
-      "type": "string",
-      "description": "ShippingZone id"
-    },
-    "method_id": {
-      "type": "string",
-      "enum": ["flat_rate", "free_shipping", "local_pickup"],
-      "description": "Method type"
-    },
-    "title": {
-      "type": "string",
-      "description": "Customer-facing method title"
-    },
-    "enabled": {
-      "type": "boolean",
-      "default": true
-    },
-    "order": {
-      "type": "integer",
-      "default": 0,
-      "description": "Display order within the zone"
-    },
-    "settings": {
-      "type": "object",
-      "description": "Per-method settings. flat_rate: {cost, tax_status, class_costs, no_class_cost, calculation_type}; free_shipping: {requires, min_amount, ignore_discounts}; local_pickup: {cost, tax_status}",
-      "properties": {
-        "cost": {
-          "type": "number",
-          "description": "flat_rate/local_pickup base cost"
-        },
-        "tax_status": {
-          "type": "string",
-          "enum": ["taxable", "none"],
-          "description": "flat_rate/local_pickup"
-        },
-        "class_costs": {
-          "type": "array",
-          "description": "flat_rate: additional cost per shipping class present in the cart",
-          "items": {
-            "type": "object",
-            "properties": {
-              "shipping_class_id": { "type": "string" },
-              "cost": { "type": "number" }
-            }
-          }
-        },
-        "no_class_cost": {
-          "type": "number",
-          "description": "flat_rate: cost applied for items without a shipping class"
-        },
-        "calculation_type": {
-          "type": "string",
-          "enum": ["class", "order"],
-          "description": "flat_rate: charge per class present (class) or most expensive class only (order)"
-        },
-        "requires": {
-          "type": "string",
-          "enum": ["", "coupon", "min_amount", "either", "both"],
-          "description": "free_shipping: requirement for the method to be offered"
-        },
-        "min_amount": {
-          "type": "number",
-          "description": "free_shipping: minimum items subtotal"
-        },
-        "ignore_discounts": {
-          "type": "boolean",
-          "description": "free_shipping: compare min_amount against pre-discount subtotal"
-        }
-      }
-    }
-  },
-  "required": ["zone_id", "method_id"],
-  "rls": {
-    "read": { "user_condition": { "role": "admin" } },
-    "create": { "user_condition": { "role": "admin" } },
-    "update": { "user_condition": { "role": "admin" } },
-    "delete": { "user_condition": { "role": "admin" } }
-  }
-}

package/base44/entities/commerce.TaxClass.jsonc

@@ -1,23 +0,0 @@
-{
-  "name": "commerce.TaxClass",
-  "type": "object",
-  "description": "Tax class grouping products for rate matching. Seeded: standard, reduced-rate, zero-rate.",
-  "properties": {
-    "slug": {
-      "type": "string",
-      "minLength": 1,
-      "description": "Unique slug (enforced in admin UI / seed)"
-    },
-    "name": {
-      "type": "string",
-      "minLength": 1
-    }
-  },
-  "required": ["slug", "name"],
-  "rls": {
-    "read": { "user_condition": { "role": "admin" } },
-    "create": { "user_condition": { "role": "admin" } },
-    "update": { "user_condition": { "role": "admin" } },
-    "delete": { "user_condition": { "role": "admin" } }
-  }
-}

package/base44/entities/commerce.TaxRate.jsonc

@@ -1,68 +0,0 @@
-{
-  "name": "commerce.TaxRate",
-  "type": "object",
-  "description": "A tax rate matched by location and tax class. Applied by shared/tax per priority/compound rules.",
-  "properties": {
-    "country": {
-      "type": "string",
-      "default": "",
-      "description": "ISO 3166-1 alpha-2 country code; empty = any"
-    },
-    "state": {
-      "type": "string",
-      "default": "",
-      "description": "State/province code; empty = any"
-    },
-    "postcodes": {
-      "type": "array",
-      "items": { "type": "string" },
-      "description": "Postcode patterns; supports wildcard (90*) and numeric range (1000...2000); empty = any"
-    },
-    "cities": {
-      "type": "array",
-      "items": { "type": "string" },
-      "description": "City names; empty = any"
-    },
-    "rate": {
-      "type": "number",
-      "description": "Percentage rate, e.g. 20 for 20%"
-    },
-    "name": {
-      "type": "string",
-      "minLength": 1,
-      "description": "Label, e.g. VAT"
-    },
-    "priority": {
-      "type": "integer",
-      "default": 1,
-      "description": "Only one matching rate per priority is applied; lower priorities apply first"
-    },
-    "compound": {
-      "type": "boolean",
-      "default": false,
-      "description": "Applied on top of previously accumulated taxes"
-    },
-    "shipping": {
-      "type": "boolean",
-      "default": true,
-      "description": "Rate also applies to shipping"
-    },
-    "tax_class": {
-      "type": "string",
-      "default": "standard",
-      "description": "TaxClass slug this rate belongs to"
-    },
-    "menu_order": {
-      "type": "integer",
-      "default": 0,
-      "description": "Tie-breaker among rates of the same priority"
-    }
-  },
-  "required": ["rate", "name"],
-  "rls": {
-    "read": { "user_condition": { "role": "admin" } },
-    "create": { "user_condition": { "role": "admin" } },
-    "update": { "user_condition": { "role": "admin" } },
-    "delete": { "user_condition": { "role": "admin" } }
-  }
-}