@base44/app-plugin-commerce 0.1.0

package/base44/shared/commerce/shipping.ts

@@ -0,0 +1,215 @@
+/**
+ * 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
+ */
+import { round2 } from "./money.ts";
+import { postcodeMatchesPattern } from "./tax.ts";
+import { continentOf } from "./data/continents.ts";
+
+export interface ShipAddress {
+  country?: string;
+  state?: string;
+  postcode?: string;
+  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
+  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 || ""));
+  }
+  return true;
+}
+
+/**
+ * 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.
+ */
+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;
+  }
+  return sorted.find((z) => !(z.locations || []).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
+  itemsSubtotalAfterDiscount: number; // post-discount, ex tax
+}
+
+export interface AvailableMethod {
+  method: 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)
+
+export interface ShippingSelection {
+  /** The ShippingZoneMethod 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). */
+  stale: boolean;
+}
+
+/**
+ * Decide which shipping method 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
+ *   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.
+ *
+ * Deliberately *not* applied by the totals engine itself: admin orders are
+ * priced through the same engine and must never grow a shipping charge the
+ * operator didn't add.
+ */
+export function resolveShippingSelection(input: {
+  needsShipping: boolean;
+  shippingEnabled?: boolean;
+  chosenMethodId?: string;
+  available: Array<{ id: string }>;
+}): 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 (chosen && available.some((m) => m.id === chosen)) {
+    return { method_id: chosen, state: "chosen", stale: false };
+  }
+  if (available.length === 1) {
+    return { method_id: available[0].id, state: "auto_selected", stale: !!chosen };
+  }
+  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).
+ */
+export function availableMethods(
+  zone: any,
+  methods: 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;
+}

package/base44/shared/commerce/stock.ts

@@ -0,0 +1,227 @@
+/**
+ * Stock management with standard commerce semantics:
+ * - purchasability checks (status, stock/backorders, sold_individually)
+ * - reduce/restore around the order lifecycle, guarded by order.stock_reduced
+ *   (this module mutates the in-memory flag; orders.ts persists it)
+ * - variation-aware: variation.manage_stock "yes" | "no" | "parent"
+ * - threshold-crossing low/out-of-stock notifications
+ * - expired-hold release (a lightweight reserved-stock mechanism; invoked
+ *   opportunistically since Base44 has no cron)
+ */
+import { sendStockEmail } from "./emails.ts";
+import { getSettings } from "./settings.ts";
+
+export interface PurchasableResult {
+  ok: boolean;
+  error?: string;
+  code?: string;
+}
+
+/** Where does stock live for this product/variation combo? */
+function stockTarget(product: any, variation?: any): { entity: string; record: any } | null {
+  if (variation) {
+    const mode = variation.manage_stock ?? "parent";
+    if (mode === "yes") return { entity: "commerce.ProductVariation", record: variation };
+    if (mode === "parent") {
+      return product?.manage_stock ? { entity: "commerce.Product", record: product } : null;
+    }
+    return null; // "no": status-only tracking on the variation
+  }
+  return product?.manage_stock ? { entity: "commerce.Product", record: product } : null;
+}
+
+function effectiveBackorders(product: any, variation?: any): string {
+  if (variation && (variation.manage_stock ?? "parent") === "yes") {
+    return variation.backorders ?? "no";
+  }
+  return product?.backorders ?? "no";
+}
+
+/** Derive stock_status from a quantity. */
+export function deriveStockStatus(qty: number, backorders: string, outOfStockThreshold = 0): string {
+  if (qty <= outOfStockThreshold) {
+    return backorders !== "no" ? "onbackorder" : "outofstock";
+  }
+  return "instock";
+}
+
+/**
+ * Can `qty` of this product/variation be bought right now?
+ * Codes: not_published | variation_required | not_purchasable | sold_individually |
+ * out_of_stock | insufficient_stock
+ */
+export function checkPurchasable(product: any, variation: any | undefined, qty: number, settings: Record<string, any>): PurchasableResult {
+  if (!product || product.status !== "publish") {
+    return { ok: false, code: "not_published", error: "This product is not available." };
+  }
+  if (product.type === "variable" && !variation) {
+    return { ok: false, code: "variation_required", error: "Please choose product options." };
+  }
+  if (variation && variation.status && variation.status !== "publish") {
+    return { ok: false, code: "not_published", error: "This product option is not available." };
+  }
+  if (product.type === "external") {
+    return { ok: false, code: "not_purchasable", error: "This product can only be purchased on an external site." };
+  }
+  const src = variation ?? product;
+  if (src.price === undefined || src.price === null) {
+    return { ok: false, code: "not_purchasable", error: "This product cannot be purchased (no price set)." };
+  }
+  if (product.sold_individually && qty > 1) {
+    return { ok: false, code: "sold_individually", error: "Only one of this product may be purchased per order." };
+  }
+
+  const target = stockTarget(product, variation);
+  const backorders = effectiveBackorders(product, variation);
+  if (target) {
+    const available = Number(target.record.stock_quantity ?? 0);
+    if (qty > available && backorders === "no") {
+      return available <= 0
+        ? { ok: false, code: "out_of_stock", error: "This product is out of stock." }
+        : { ok: false, code: "insufficient_stock", error: `Only ${available} left in stock.` };
+    }
+  } else {
+    const status = (variation?.stock_status ?? product.stock_status) || "instock";
+    if (status === "outofstock") {
+      return { ok: false, code: "out_of_stock", error: "This product is out of stock." };
+    }
+  }
+  return { ok: true };
+}
+
+interface StockOpts {
+  settings?: Record<string, any>;
+}
+
+/**
+ * Reduce stock for every line of an order. No-op if order.stock_reduced.
+ * Mutates order.stock_reduced=true in memory (caller persists), bumps
+ * Product.total_sales, and fires low/out-of-stock notifications on
+ * threshold crossings.
+ */
+export async function reduceStock(sr: any, order: any, opts: StockOpts = {}): Promise<void> {
+  if (order.stock_reduced) return;
+  const settings = opts.settings ?? (await getSettings(sr, "inventory", "emails", "general"));
+  const inv = settings.inventory ?? {};
+  const outThreshold = Number(inv.out_of_stock_threshold ?? 0);
+  const defaultLow = Number(inv.low_stock_threshold ?? 2);
+
+  for (const line of order.line_items || []) {
+    const { product, variation } = await loadLineProducts(sr, line);
+    if (!product) continue;
+
+    const target = stockTarget(product, variation);
+    if (target) {
+      const before = Number(target.record.stock_quantity ?? 0);
+      const after = before - line.quantity;
+      const backorders = effectiveBackorders(product, variation);
+      const status = deriveStockStatus(after, backorders, outThreshold);
+      await sr.entities[target.entity].update(target.record.id, {
+        stock_quantity: after,
+        stock_status: status,
+      });
+      target.record.stock_quantity = after;
+      target.record.stock_status = status;
+
+      // threshold-crossing notifications (once per crossing)
+      const low = Number(target.record.low_stock_amount ?? defaultLow);
+      if (after <= outThreshold && before > outThreshold) {
+        await sendStockEmail(sr, "out_of_stock", { ...product, stock_quantity: after }, { settings });
+      } else if (after <= low && before > low) {
+        await sendStockEmail(sr, "low_stock", { ...product, stock_quantity: after }, { settings });
+      }
+    }
+
+    // units sold live on the parent product regardless of variation
+    await sr.entities["commerce.Product"].update(product.id, {
+      total_sales: (product.total_sales ?? 0) + line.quantity,
+    });
+  }
+  order.stock_reduced = true;
+}
+
+/**
+ * Restore stock for every line (cancel/fail flows). No-op unless
+ * order.stock_reduced. Mutates order.stock_reduced=false in memory.
+ */
+export async function restoreStock(sr: any, order: any, opts: StockOpts = {}): Promise<void> {
+  if (!order.stock_reduced) return;
+  const settings = opts.settings ?? (await getSettings(sr, "inventory"));
+  const outThreshold = Number(settings.inventory?.out_of_stock_threshold ?? 0);
+
+  for (const line of order.line_items || []) {
+    const { product, variation } = await loadLineProducts(sr, line);
+    if (!product) continue;
+    await restoreLineQuantity(sr, product, variation, line.quantity, outThreshold);
+    await sr.entities["commerce.Product"].update(product.id, {
+      total_sales: Math.max(0, (product.total_sales ?? 0) - line.quantity),
+    });
+  }
+  order.stock_reduced = false;
+}
+
+/**
+ * Restock a specific quantity for one line (refund-with-restock flow).
+ * Does NOT touch total_sales or the stock_reduced flag.
+ */
+export async function restockLine(sr: any, line: any, quantity: number, opts: StockOpts = {}): Promise<void> {
+  const settings = opts.settings ?? (await getSettings(sr, "inventory"));
+  const outThreshold = Number(settings.inventory?.out_of_stock_threshold ?? 0);
+  const { product, variation } = await loadLineProducts(sr, line);
+  if (!product) return;
+  await restoreLineQuantity(sr, product, variation, quantity, outThreshold);
+}
+
+async function restoreLineQuantity(sr: any, product: any, variation: any | undefined, quantity: number, outThreshold: number): Promise<void> {
+  const target = stockTarget(product, variation);
+  if (!target) return;
+  const after = Number(target.record.stock_quantity ?? 0) + quantity;
+  const backorders = effectiveBackorders(product, variation);
+  await sr.entities[target.entity].update(target.record.id, {
+    stock_quantity: after,
+    stock_status: deriveStockStatus(after, backorders, outThreshold),
+  });
+  target.record.stock_quantity = after;
+}
+
+async function loadLineProducts(sr: any, line: any): Promise<{ product: any | null; variation?: any }> {
+  let product: any = null;
+  let variation: any = undefined;
+  try {
+    if (line.product_id) product = await sr.entities["commerce.Product"].get(line.product_id);
+  } catch { product = null; }
+  try {
+    if (line.variation_id) variation = await sr.entities["commerce.ProductVariation"].get(line.variation_id);
+  } catch { variation = undefined; }
+  return { product, variation };
+}
+
+/**
+ * Cancel pending orders whose stock hold expired, releasing their stock.
+ * `transitionFn` is orders.ts transitionOrder (passed in to avoid a circular
+ * import). Returns how many orders were released.
+ */
+export async function releaseExpiredHolds(
+  sr: any,
+  settings: Record<string, any> | null,
+  transitionFn: (sr: any, order: any, status: string, opts?: any) => Promise<any>,
+): Promise<number> {
+  const now = Date.now();
+  let released = 0;
+  let skip = 0;
+  while (true) {
+    const page = (await sr.entities["commerce.Order"].filter({ status: "pending", stock_reduced: true }, "-created_date", 200, skip)) ?? [];
+    for (const order of page) {
+      if (order.hold_expires_at && new Date(order.hold_expires_at).getTime() < now) {
+        await transitionFn(sr, order, "cancelled", {
+          note: "Unpaid order — stock hold expired and the order was cancelled automatically.",
+          settings: settings ?? undefined,
+        });
+        released++;
+      }
+    }
+    if (page.length < 200) break;
+    skip += 200;
+  }
+  return released;
+}