@base44/app-plugin-commerce 0.1.0

package/src/commerce/admin/pages/status/WebhookEditor.jsx

@@ -0,0 +1,296 @@
+import React, { useEffect, useState } from "react";
+import { useNavigate, useParams } from "react-router-dom";
+import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import { Badge } from "@/components/ui/badge";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select";
+import { ChevronDown, ChevronRight, Loader2, Send } from "lucide-react";
+import { toast } from "sonner";
+import PageHeader from "../../components/PageHeader";
+import ConfirmDialog from "../../components/ConfirmDialog";
+import { base44, call } from "../../lib/api";
+import useAsync from "../../hooks/useAsync";
+import { useAdminHref } from "../../context/BasePathContext";
+import { WEBHOOK_STATUSES, WEBHOOK_TOPICS } from "../../lib/constants";
+import { formatDateTime } from "../../lib/format";
+
+const blank = {
+  name: "",
+  status: "active",
+  topic: "order.created",
+  delivery_url: "",
+  secret: "",
+  api_version: "v3",
+};
+
+const genSecret = () => {
+  const bytes = new Uint8Array(24);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+};
+
+export default function WebhookEditor() {
+  const { id } = useParams();
+  const isNew = !id || id === "new";
+  const navigate = useNavigate();
+  const href = useAdminHref();
+
+  const [form, setForm] = useState(blank);
+  const [loading, setLoading] = useState(!isNew);
+  const [saving, setSaving] = useState(false);
+  const [confirmDelete, setConfirmDelete] = useState(false);
+  const [deleting, setDeleting] = useState(false);
+  const [testing, setTesting] = useState(false);
+
+  useEffect(() => {
+    if (isNew) return;
+    let cancelled = false;
+    setLoading(true);
+    base44.entities["commerce.Webhook"].get(id)
+      .then((w) => !cancelled && w && setForm({ ...blank, ...w }))
+      .catch((err) => toast.error(err.message || "Failed to load webhook"))
+      .finally(() => !cancelled && setLoading(false));
+    return () => {
+      cancelled = true;
+    };
+  }, [id, isNew]);
+
+  const set = (key, value) => setForm((f) => ({ ...f, [key]: value }));
+
+  const save = async () => {
+    if (!form.name.trim() || !form.delivery_url.trim()) {
+      toast.error("Name and delivery URL are required");
+      return;
+    }
+    setSaving(true);
+    try {
+      const [resource, event] = form.topic.split(".");
+      const payload = {
+        name: form.name,
+        status: form.status,
+        topic: form.topic,
+        resource,
+        event,
+        delivery_url: form.delivery_url,
+        secret: form.secret,
+        api_version: form.api_version || "v3",
+      };
+      if (isNew) {
+        const created = await base44.entities["commerce.Webhook"].create(payload);
+        toast.success("Webhook created");
+        navigate(href(`webhooks/${created.id}`));
+      } else {
+        await base44.entities["commerce.Webhook"].update(id, payload);
+        toast.success("Webhook saved");
+      }
+    } catch (err) {
+      toast.error(err.message || "Failed to save webhook");
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  const remove = async () => {
+    setDeleting(true);
+    try {
+      await base44.entities["commerce.Webhook"].delete(id);
+      toast.success("Webhook deleted");
+      navigate(href("webhooks"));
+    } catch (err) {
+      toast.error(err.message || "Failed to delete");
+      setDeleting(false);
+    }
+  };
+
+  const sendTest = async () => {
+    setTesting(true);
+    try {
+      const res = await call("admin-webhooks", "test", { webhook_id: id });
+      const code = res?.response_code ?? res?.delivery?.response_code;
+      toast.success(code ? `Test delivered — HTTP ${code}` : "Test delivered");
+    } catch {
+      /* call() already toasts */
+    } finally {
+      setTesting(false);
+    }
+  };
+
+  if (loading) {
+    return (
+      <div className="flex justify-center py-12">
+        <Loader2 className="h-6 w-6 animate-spin text-muted-foreground" />
+      </div>
+    );
+  }
+
+  return (
+    <div className="max-w-3xl space-y-4">
+      <PageHeader
+        title={isNew ? "Add webhook" : "Edit webhook"}
+        backHref={href("webhooks")}
+        actions={
+          !isNew && (
+            <>
+              <Button variant="outline" onClick={sendTest} disabled={testing}>
+                {testing ? <Loader2 className="mr-2 h-4 w-4 animate-spin" /> : <Send className="mr-2 h-4 w-4" />}
+                Send test
+              </Button>
+              <Button variant="outline" className="text-destructive" onClick={() => setConfirmDelete(true)}>
+                Delete
+              </Button>
+            </>
+          )
+        }
+      />
+
+      <Card>
+        <CardHeader>
+          <CardTitle>Webhook details</CardTitle>
+        </CardHeader>
+        <CardContent className="grid gap-4 sm:grid-cols-2">
+          <div className="space-y-1.5 sm:col-span-2">
+            <Label>Name</Label>
+            <Input value={form.name} onChange={(e) => set("name", e.target.value)} />
+          </div>
+          <div className="space-y-1.5">
+            <Label>Status</Label>
+            <Select value={form.status} onValueChange={(v) => set("status", v)}>
+              <SelectTrigger><SelectValue /></SelectTrigger>
+              <SelectContent>
+                {WEBHOOK_STATUSES.map((s) => (
+                  <SelectItem key={s.value} value={s.value}>{s.label}</SelectItem>
+                ))}
+              </SelectContent>
+            </Select>
+          </div>
+          <div className="space-y-1.5">
+            <Label>Topic</Label>
+            <Select value={form.topic} onValueChange={(v) => set("topic", v)}>
+              <SelectTrigger><SelectValue /></SelectTrigger>
+              <SelectContent>
+                {WEBHOOK_TOPICS.map((t) => (
+                  <SelectItem key={t} value={t}>{t}</SelectItem>
+                ))}
+              </SelectContent>
+            </Select>
+          </div>
+          <div className="space-y-1.5 sm:col-span-2">
+            <Label>Delivery URL</Label>
+            <Input placeholder="https://example.com/webhooks/incoming" value={form.delivery_url} onChange={(e) => set("delivery_url", e.target.value)} />
+          </div>
+          <div className="space-y-1.5 sm:col-span-2">
+            <Label>Secret</Label>
+            <div className="flex gap-2">
+              <Input value={form.secret} onChange={(e) => set("secret", e.target.value)} placeholder="Used to sign the payload (HMAC-SHA256)" />
+              <Button variant="outline" type="button" onClick={() => set("secret", genSecret())}>Generate</Button>
+            </div>
+          </div>
+          <div className="space-y-1.5">
+            <Label>API version</Label>
+            <Input value={form.api_version} disabled />
+          </div>
+        </CardContent>
+      </Card>
+
+      <div>
+        <Button onClick={save} disabled={saving}>
+          {saving && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
+          {isNew ? "Create webhook" : "Save changes"}
+        </Button>
+      </div>
+
+      {!isNew && <DeliveriesCard webhookId={id} />}
+
+      <ConfirmDialog
+        open={confirmDelete}
+        onOpenChange={setConfirmDelete}
+        title="Delete webhook?"
+        confirmLabel="Delete"
+        loading={deleting}
+        onConfirm={remove}
+      />
+    </div>
+  );
+}
+
+function DeliveriesCard({ webhookId }) {
+  const deliveries = useAsync(
+    () => base44.entities["commerce.WebhookDelivery"].filter({ webhook_id: webhookId }, "-created_date", 20),
+    [webhookId]
+  );
+  const [expanded, setExpanded] = useState(null);
+  const [redelivering, setRedelivering] = useState(null);
+
+  const redeliver = async (deliveryId) => {
+    setRedelivering(deliveryId);
+    try {
+      await call("admin-webhooks", "redeliver", { delivery_id: deliveryId });
+      toast.success("Redelivered");
+      deliveries.refetch();
+    } catch {
+      /* toasted */
+    } finally {
+      setRedelivering(null);
+    }
+  };
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Recent deliveries</CardTitle>
+      </CardHeader>
+      <CardContent className="space-y-2">
+        {deliveries.loading && <Loader2 className="h-5 w-5 animate-spin text-muted-foreground" />}
+        {!deliveries.loading && (deliveries.data || []).length === 0 && (
+          <p className="text-sm text-muted-foreground">No deliveries yet.</p>
+        )}
+        {(deliveries.data || []).map((d) => {
+          const open = expanded === d.id;
+          return (
+            <div key={d.id} className="rounded-md border">
+              <button
+                type="button"
+                className="flex w-full items-center gap-3 px-3 py-2 text-left text-sm"
+                onClick={() => setExpanded(open ? null : d.id)}
+              >
+                {open ? <ChevronDown className="h-4 w-4" /> : <ChevronRight className="h-4 w-4" />}
+                <Badge
+                  variant="outline"
+                  className={d.success ? "bg-green-100 text-green-800 border-green-200" : "bg-red-100 text-red-800 border-red-200"}
+                >
+                  {d.response_code || (d.success ? "OK" : "ERR")}
+                </Badge>
+                <span className="text-muted-foreground">{formatDateTime(d.created_date)}</span>
+                <span className="ml-auto text-xs text-muted-foreground">{d.duration_ms != null ? `${d.duration_ms} ms` : ""}</span>
+              </button>
+              {open && (
+                <div className="space-y-2 border-t px-3 py-2 text-xs">
+                  <div>
+                    <div className="mb-1 font-medium">Request</div>
+                    <pre className="max-h-48 overflow-auto rounded bg-muted p-2">{d.request_body || "—"}</pre>
+                  </div>
+                  <div>
+                    <div className="mb-1 font-medium">Response</div>
+                    <pre className="max-h-48 overflow-auto rounded bg-muted p-2">{d.response_body || "—"}</pre>
+                  </div>
+                  <Button size="sm" variant="outline" disabled={redelivering === d.id} onClick={() => redeliver(d.id)}>
+                    {redelivering === d.id && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
+                    Redeliver
+                  </Button>
+                </div>
+              )}
+            </div>
+          );
+        })}
+      </CardContent>
+    </Card>
+  );
+}

package/src/commerce/admin/pages/status/Webhooks.jsx

@@ -0,0 +1,53 @@
+import React from "react";
+import { useNavigate } from "react-router-dom";
+import { Button } from "@/components/ui/button";
+import { Plus, Webhook as WebhookIcon } from "lucide-react";
+import PageHeader from "../../components/PageHeader";
+import DataTable from "../../components/DataTable";
+import StatusBadge from "../../components/StatusBadge";
+import { base44 } from "../../lib/api";
+import useAsync from "../../hooks/useAsync";
+import { useAdminHref } from "../../context/BasePathContext";
+import { WEBHOOK_STATUSES } from "../../lib/constants";
+import { formatDate } from "../../lib/format";
+
+export default function Webhooks() {
+  const navigate = useNavigate();
+  const href = useAdminHref();
+  const hooks = useAsync(() => base44.entities["commerce.Webhook"].list("-created_date", 200), []);
+
+  const columns = [
+    { key: "name", label: "Name", render: (w) => <span className="font-medium">{w.name}</span> },
+    { key: "status", label: "Status", render: (w) => <StatusBadge status={w.status} map={WEBHOOK_STATUSES} /> },
+    { key: "topic", label: "Topic", render: (w) => <code className="text-xs">{w.topic}</code> },
+    {
+      key: "delivery_url",
+      label: "Delivery URL",
+      render: (w) => <span className="block max-w-xs truncate text-sm text-muted-foreground">{w.delivery_url}</span>,
+    },
+    { key: "failure_count", label: "Failures", render: (w) => w.failure_count ?? 0 },
+    { key: "created_date", label: "Created", render: (w) => formatDate(w.created_date) },
+  ];
+
+  return (
+    <div className="space-y-4">
+      <PageHeader
+        title="Webhooks"
+        description="Notify external services when store events occur."
+        actions={
+          <Button onClick={() => navigate(href("webhooks/new"))}>
+            <Plus className="mr-2 h-4 w-4" />
+            Add webhook
+          </Button>
+        }
+      />
+      <DataTable
+        columns={columns}
+        rows={hooks.data || []}
+        loading={hooks.loading}
+        onRowClick={(w) => navigate(href(`webhooks/${w.id}`))}
+        empty={{ icon: WebhookIcon, title: "No webhooks", description: "Create a webhook to POST event payloads to an external URL." }}
+      />
+    </div>
+  );
+}

package/src/commerce/admin/routes.jsx

@@ -0,0 +1,151 @@
+import React from "react";
+import { Link, Navigate, Route, Routes, useLocation, useParams } from "react-router-dom";
+import { PackageX } from "lucide-react";
+
+import { useAdminHref } from "./context/BasePathContext";
+import { isMountPatternPath } from "./lib/paths";
+
+import Dashboard from "./pages/Dashboard";
+import OrdersList from "./pages/orders/OrdersList";
+import OrderEditor from "./pages/orders/OrderEditor";
+import ProductsList from "./pages/products/ProductsList";
+import ProductEditor from "./pages/products/ProductEditor";
+import Categories from "./pages/products/Categories";
+import Tags from "./pages/products/Tags";
+import Attributes from "./pages/products/Attributes";
+import AttributeTerms from "./pages/products/AttributeTerms";
+import Reviews from "./pages/products/Reviews";
+import CouponsList from "./pages/coupons/CouponsList";
+import CouponEditor from "./pages/coupons/CouponEditor";
+import CustomersList from "./pages/customers/CustomersList";
+import CustomerEditor from "./pages/customers/CustomerEditor";
+import Reports from "./pages/reports/Reports";
+import SettingsLayout from "./pages/settings/SettingsLayout";
+import GeneralSettings from "./pages/settings/GeneralSettings";
+import ProductsSettings from "./pages/settings/ProductsSettings";
+import InventorySettings from "./pages/settings/InventorySettings";
+import TaxSettings from "./pages/settings/TaxSettings";
+import ShippingSettings from "./pages/settings/ShippingSettings";
+import ShippingZoneEditor from "./pages/settings/ShippingZoneEditor";
+import PaymentsSettings from "./pages/settings/PaymentsSettings";
+import EmailsSettings from "./pages/settings/EmailsSettings";
+import Webhooks from "./pages/status/Webhooks";
+import WebhookEditor from "./pages/status/WebhookEditor";
+
+/**
+ * Internal route table (paths relative to the mount point).
+ * Used by the router below and by Topbar breadcrumbs.
+ */
+export const ADMIN_ROUTES = [
+  { path: "", label: "Dashboard" },
+  { path: "orders", label: "Orders" },
+  { path: "orders/new", label: "Add order" },
+  { path: "orders/:id", label: "Order" },
+  { path: "products", label: "Products" },
+  { path: "products/new", label: "Add product" },
+  { path: "products/categories", label: "Categories" },
+  { path: "products/tags", label: "Tags" },
+  { path: "products/attributes", label: "Attributes" },
+  { path: "products/attributes/:id/terms", label: "Terms" },
+  { path: "products/reviews", label: "Reviews" },
+  { path: "products/:id", label: "Edit product" },
+  { path: "coupons", label: "Coupons" },
+  { path: "coupons/new", label: "Add coupon" },
+  { path: "coupons/:id", label: "Edit coupon" },
+  { path: "customers", label: "Customers" },
+  { path: "customers/new", label: "Add customer" },
+  { path: "customers/:id", label: "Customer" },
+  { path: "reports", label: "Reports" },
+  { path: "settings", label: "Settings" },
+  { path: "settings/general", label: "General" },
+  { path: "settings/products", label: "Products" },
+  { path: "settings/inventory", label: "Inventory" },
+  { path: "settings/tax", label: "Tax" },
+  { path: "settings/shipping", label: "Shipping" },
+  { path: "settings/shipping/zones/:zoneId", label: "Shipping zone" },
+  { path: "settings/payments", label: "Payments" },
+  { path: "settings/emails", label: "Emails" },
+  { path: "webhooks", label: "Webhooks" },
+  { path: "webhooks/new", label: "Add webhook" },
+  { path: "webhooks/:id", label: "Webhook" },
+];
+
+function NotFound() {
+  const href = useAdminHref();
+  const { pathname } = useLocation();
+  return (
+    <div className="flex flex-col items-center justify-center py-24 text-center">
+      <PackageX className="mb-3 h-10 w-10 text-muted-foreground/50" />
+      <h2 className="text-lg font-semibold">Page not found</h2>
+      <p className="text-sm text-muted-foreground">
+        <span className="font-mono">{pathname}</span> is not an admin page.
+      </p>
+      <Link to={href()} className="mt-4 text-sm font-medium underline">
+        Back to the dashboard
+      </Link>
+    </div>
+  );
+}
+
+/**
+ * Catch-all. A URL that still contains the *mount pattern* rather than a real
+ * path — `/admin/*` (the `<Route path="/admin/*">` pattern pasted into the
+ * address bar or copied into a nav link), or a leftover `/admin/:id` — is a
+ * wiring artifact, not a page the admin asked for: land on the dashboard
+ * instead of showing a dead end. Anything else is a genuine 404.
+ */
+function UnmatchedRoute() {
+  const href = useAdminHref();
+  const params = useParams();
+  return isMountPatternPath(params["*"]) ? <Navigate to={href()} replace /> : <NotFound />;
+}
+
+/** All admin routes. Rendered inside AdminLayout; mount AdminApp at `/admin/*`. */
+export default function AdminRoutes() {
+  return (
+    <Routes>
+      <Route index element={<Dashboard />} />
+
+      <Route path="orders" element={<OrdersList />} />
+      <Route path="orders/new" element={<OrderEditor />} />
+      <Route path="orders/:id" element={<OrderEditor />} />
+
+      <Route path="products" element={<ProductsList />} />
+      <Route path="products/new" element={<ProductEditor />} />
+      <Route path="products/categories" element={<Categories />} />
+      <Route path="products/tags" element={<Tags />} />
+      <Route path="products/attributes" element={<Attributes />} />
+      <Route path="products/attributes/:id/terms" element={<AttributeTerms />} />
+      <Route path="products/reviews" element={<Reviews />} />
+      <Route path="products/:id" element={<ProductEditor />} />
+
+      <Route path="coupons" element={<CouponsList />} />
+      <Route path="coupons/new" element={<CouponEditor />} />
+      <Route path="coupons/:id" element={<CouponEditor />} />
+
+      <Route path="customers" element={<CustomersList />} />
+      <Route path="customers/new" element={<CustomerEditor />} />
+      <Route path="customers/:id" element={<CustomerEditor />} />
+
+      <Route path="reports" element={<Reports />} />
+
+      <Route path="settings" element={<SettingsLayout />}>
+        <Route index element={<Navigate to="general" replace />} />
+        <Route path="general" element={<GeneralSettings />} />
+        <Route path="products" element={<ProductsSettings />} />
+        <Route path="inventory" element={<InventorySettings />} />
+        <Route path="tax" element={<TaxSettings />} />
+        <Route path="shipping" element={<ShippingSettings />} />
+        <Route path="shipping/zones/:zoneId" element={<ShippingZoneEditor />} />
+        <Route path="payments" element={<PaymentsSettings />} />
+        <Route path="emails" element={<EmailsSettings />} />
+      </Route>
+
+      <Route path="webhooks" element={<Webhooks />} />
+      <Route path="webhooks/new" element={<WebhookEditor />} />
+      <Route path="webhooks/:id" element={<WebhookEditor />} />
+
+      <Route path="*" element={<UnmatchedRoute />} />
+    </Routes>
+  );
+}

package/src/commerce/utils/index.js

@@ -0,0 +1,19 @@
+/**
+ * Storefront helpers shipped with the Base44 Commerce Template.
+ *
+ * Framework-free, dependency-free pure functions for the customer-facing UI you
+ * build on top of the `commerce/storefront-*` API. No visitor UI ships with the
+ * template, but this logic does — it is the part that is easy to get subtly
+ * wrong.
+ *
+ *   import { resolveSelection, defaultSelection, selectOption } from "@/commerce/utils";
+ *
+ * - `variants.js` — variant selection: map attribute selections (Size, Color)
+ *   to a `ProductVariation` and back, per-option availability, variable-product
+ *   price ranges. See `skills/commerce/references/storefront-product-page.md`.
+ * - `shipping-promos.js` — read the store's real free-shipping configuration so
+ *   "Free shipping over €150" copy states a configured rule, not an invented
+ *   number. See `skills/commerce/docs/api-storefront.md`.
+ */
+export * from "./variants.js";
+export * from "./shipping-promos.js";

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

@@ -0,0 +1,99 @@
+/**
+ * Read the store's *actual* free-shipping configuration, so storefront copy
+ * ("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.
+ *
+ * `commerce.ShippingZone` and `commerce.ShippingZoneMethod` are public-read, so
+ * the storefront can load them directly:
+ *
+ * ```js
+ * const [zones, methods] = await Promise.all([
+ *   base44.entities["commerce.ShippingZone"].list("order", 100),
+ *   base44.entities["commerce.ShippingZoneMethod"].list(undefined, 200),
+ * ]);
+ * const rules = freeShippingRules(zones, methods);
+ * // no rules → do not advertise free shipping anywhere.
+ * ```
+ *
+ * Framework-free and dependency-free. See
+ * `skills/commerce/docs/api-storefront.md` for the surrounding rules.
+ */
+
+/**
+ * Normalized free-shipping rules, one per configured `free_shipping` method.
+ *
+ * @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
+ * }>}
+ */
+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,
+      };
+    });
+}
+
+/**
+ * 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.
+ *
+ * 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
+ * `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));
+  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);
+  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.
+ *
+ * @returns {{threshold: number, qualifies: boolean, remaining: number}|null}
+ *   `null` when there is no threshold to talk about.
+ */
+export function freeShippingProgress(threshold, subtotal) {
+  if (threshold == null) return null;
+  const spent = Number(subtotal) || 0;
+  const qualifies = spent >= threshold;
+  return {
+    threshold,
+    qualifies,
+    // Rounded *up* to the cent: a sub-cent gap must not render as
+    // "0.00 away from free shipping" while the order still doesn't qualify.
+    remaining: qualifies ? 0 : Math.ceil((threshold - spent) * 100) / 100,
+  };
+}