@base44/app-plugin-commerce 0.1.0

package/src/commerce/admin/lib/order-utils.js

@@ -0,0 +1,147 @@
+/** Client-side helpers for order display and refund math. */
+
+export const round2 = (n) => Math.round((Number(n) || 0) * 100) / 100;
+
+/** Statuses in which line items are editable (intended behavior). */
+export function canEditLines(order) {
+  return ["pending", "on-hold"].includes(order?.status);
+}
+
+/** Aggregate display totals for the TotalsBox. */
+export function orderTotals(order) {
+  if (!order) return null;
+  const fees = (order.fee_lines || []).reduce((s, f) => s + (f.total || 0), 0);
+  const refunded = order.total_refunded || 0;
+  return {
+    itemsSubtotal: order.subtotal || 0,
+    discount: order.discount_total || 0,
+    fees: round2(fees),
+    shipping: order.shipping_total || 0,
+    taxLines: order.tax_lines || [],
+    taxTotal: order.total_tax || 0,
+    total: order.total || 0,
+    refunded,
+    net: round2((order.total || 0) - refunded),
+  };
+}
+
+/** Quantity of a line still refundable, given existing refunds. */
+export function refundableQty(order, refunds, lineId) {
+  const line = (order?.line_items || []).find((l) => l.line_id === lineId);
+  if (!line) return 0;
+  const refundedQty = (refunds || []).reduce(
+    (sum, r) =>
+      sum +
+      (r.line_items || [])
+        .filter((rl) => rl.line_id === lineId)
+        .reduce((s, rl) => s + (rl.quantity || 0), 0),
+    0
+  );
+  return Math.max(0, (line.quantity || 0) - refundedQty);
+}
+
+/** Max amount still refundable on the order. */
+export function refundableAmount(order) {
+  return round2((order?.total || 0) - (order?.total_refunded || 0));
+}
+
+/** Human line for a shipping/billing address. */
+export function shortAddress(addr) {
+  if (!addr) return "—";
+  return [addr.city, addr.state, addr.country].filter(Boolean).join(", ") || "—";
+}
+
+/**
+ * Patch keys whose value the backend has to re-price (tax, coupons, shipping,
+ * totals). The order editor sends exactly these to `admin-orders` `preview` to
+ * show live totals for unsaved edits.
+ */
+export const PRICED_PATCH_KEYS = ["items", "fees", "shipping_lines", "billing", "shipping"];
+
+/** An address with nothing filled in — safe to overwrite from a customer record. */
+export function isBlankAddress(address) {
+  return !Object.values(address || {}).some((v) => String(v ?? "").trim() !== "");
+}
+
+/**
+ * Build the `admin-orders` `update` patch for an edited order.
+ *
+ * @param {object} draft  the editor's working copy
+ * @param {object} before the same shape taken from the loaded order
+ * @returns {object} patch containing only what actually changed
+ *
+ * Line-level edits go out as **intent specs** (`items`/`fees`/`shipping_lines`),
+ * never raw line arrays: the server re-prices them through the totals engine so
+ * tax and coupons stay authoritative. Shared by save and the totals preview, so
+ * a preview is priced from exactly what saving would send.
+ */
+export function buildOrderPatch(draft, before) {
+  const changed = (key) => JSON.stringify(draft[key]) !== JSON.stringify(before[key]);
+  const patch = {};
+
+  // Passthrough fields the server stores verbatim.
+  for (const key of ["status", "customer_id", "billing", "shipping", "meta_data"]) {
+    if (changed(key)) patch[key] = draft[key];
+  }
+  if (changed("line_items")) {
+    patch.items = (draft.line_items || []).map((l) => ({
+      product_id: l.product_id,
+      variation_id: l.variation_id || undefined,
+      quantity: l.quantity,
+      // pre-discount unit price so the engine re-applies coupons exactly once
+      price_override: l.quantity ? round2((l.subtotal ?? l.price * l.quantity) / l.quantity) : l.price,
+      attributes: l.attributes,
+      meta_data: l.meta_data,
+    }));
+  }
+  if (changed("fee_lines")) {
+    patch.fees = (draft.fee_lines || []).map((f) => ({
+      name: f.name,
+      amount: f.total,
+      tax_class: f.tax_class,
+      tax_status: f.tax_status,
+    }));
+  }
+  if (changed("shipping_lines")) {
+    // Manual admin shipping lines (title + cost); server folds them into totals.
+    patch.shipping_lines = (draft.shipping_lines || []).map((s) => ({
+      method_title: s.method_title,
+      total: s.total,
+      total_tax: s.total_tax,
+    }));
+  }
+  return patch;
+}
+
+/** The subset of a patch that changes pricing — `{}` when nothing does. */
+export function pricedPatchOf(patch) {
+  const priced = {};
+  for (const key of PRICED_PATCH_KEYS) {
+    if (patch?.[key] !== undefined) priced[key] = patch[key];
+  }
+  return priced;
+}
+
+/**
+ * Fold a server-priced preview's per-line figures onto the draft's lines, so the
+ * items table's Tax/Total columns agree with the totals box before saving.
+ * Keeps the draft's own `line_id`s (the preview mints new ones) and copies only
+ * display figures; falls back to the draft lines if the shapes don't line up.
+ */
+export function mergePricedLines(draftLines, pricedLines) {
+  const lines = draftLines || [];
+  if (!pricedLines || pricedLines.length !== lines.length) return lines;
+  return lines.map((l, i) => ({
+    ...l,
+    subtotal: pricedLines[i].subtotal ?? l.subtotal,
+    total: pricedLines[i].total ?? l.total,
+    total_tax: pricedLines[i].total_tax ?? l.total_tax,
+    taxes: pricedLines[i].taxes ?? l.taxes,
+  }));
+}
+
+export function customerName(order) {
+  const b = order?.billing || {};
+  const name = [b.first_name, b.last_name].filter(Boolean).join(" ");
+  return name || b.email || "Guest";
+}

package/src/commerce/admin/lib/paths.js

@@ -0,0 +1,35 @@
+/**
+ * Mount-path handling for the admin app.
+ *
+ * The admin is mounted with a splat route — `<Route path="/admin/*">` — and both
+ * halves of that pattern leak into places they shouldn't: the `basePath` prop
+ * gets the pattern pasted in verbatim, and the literal URL `/admin/*` gets
+ * opened (pattern copied into the address bar, or a nav link built from the
+ * route table). Neither is a real page, so both are normalized here rather than
+ * dead-ending the admin.
+ */
+
+/** Strip a trailing route splat and slashes: "/admin/*" → "/admin". */
+export function normalizeBasePath(value, fallback = "/admin") {
+  const clean = String(value ?? "")
+    .replace(/\/+\*+$/, "")
+    .replace(/\/+$/, "");
+  return clean || fallback;
+}
+
+/**
+ * Is this leftover path (the `*` param of the catch-all route) nothing but
+ * route-*pattern* segments — `*`, its percent-encoded form, or `:param`?
+ *
+ * `/admin/*` → true (send them to the dashboard)
+ * `/admin/ordrs` → false (a genuine 404)
+ */
+export function isMountPatternPath(rest) {
+  const segments = String(rest ?? "")
+    .split("/")
+    .filter(Boolean);
+  return (
+    segments.length > 0 &&
+    segments.every((s) => s === "*" || s.toLowerCase() === "%2a" || s.startsWith(":"))
+  );
+}

package/src/commerce/admin/lib/product-utils.js

@@ -0,0 +1,55 @@
+/** Client-side helpers for products and variations. */
+
+export function slugify(name) {
+  return String(name || "")
+    .normalize("NFKD")
+    .replace(/[̀-ͯ]/g, "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+export const isSimple = (p) => p?.type === "simple";
+export const isGrouped = (p) => p?.type === "grouped";
+export const isExternal = (p) => p?.type === "external";
+export const isVariable = (p) => p?.type === "variable";
+
+/**
+ * Cartesian product of all attributes flagged `variation: true`.
+ * Returns [{attributes: [{attribute_id, name, option}]}] — one entry per combo.
+ * Returns [] when no variation attributes with options exist.
+ */
+export function generateVariationCombos(attributes) {
+  const varAttrs = (attributes || []).filter(
+    (a) => a.variation && (a.options || []).length > 0
+  );
+  if (!varAttrs.length) return [];
+  const combos = varAttrs.reduce(
+    (acc, attr) =>
+      acc.flatMap((combo) =>
+        attr.options.map((option) => [
+          ...combo,
+          { attribute_id: attr.attribute_id || "", name: attr.name, option },
+        ])
+      ),
+    [[]]
+  );
+  return combos.map((attrs) => ({ attributes: attrs }));
+}
+
+/** Display label for a variation, e.g. "Color: Red / Size: M". */
+export function variationLabel(variation) {
+  return (variation?.attributes || [])
+    .map((a) => `${a.name}: ${a.option}`)
+    .join(" / ") || "Any";
+}
+
+/** True when two variations have the same attribute combo. */
+export function sameCombo(a, b) {
+  const key = (v) =>
+    (v?.attributes || [])
+      .map((x) => `${(x.name || "").toLowerCase()}=${(x.option || "").toLowerCase()}`)
+      .sort()
+      .join("|");
+  return key(a) === key(b);
+}

package/src/commerce/admin/pages/Dashboard.jsx

@@ -0,0 +1,245 @@
+import React from "react";
+import { Link, useNavigate } from "react-router-dom";
+import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
+import { Button } from "@/components/ui/button";
+import { Badge } from "@/components/ui/badge";
+import { Skeleton } from "@/components/ui/skeleton";
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from "@/components/ui/table";
+import { BarChart3, PackagePlus, Plus, ShoppingCart, TicketPercent, TrendingUp, AlertTriangle } from "lucide-react";
+
+import { call, base44 } from "../lib/api";
+import useAsync from "../hooks/useAsync";
+import useRealtime from "../hooks/useRealtime";
+import useMoney from "../hooks/useMoney";
+import { useAdminHref } from "../context/BasePathContext";
+import { formatDate } from "../lib/format";
+import { ORDER_STATUSES } from "../lib/constants";
+import { customerName } from "../lib/order-utils";
+import StatusBadge from "../components/StatusBadge";
+import EmptyState from "../components/EmptyState";
+
+/** Pull a number out of a summary value that may be a number or {net, gross, …}. */
+function asMoneyNumber(v) {
+  if (v == null) return 0;
+  if (typeof v === "number") return v;
+  return v.net_sales ?? v.net ?? v.total ?? 0;
+}
+
+function StatCard({ icon: Icon, label, value, hint, loading }) {
+  return (
+    <Card>
+      <CardContent className="flex items-center gap-4 p-5">
+        <div className="rounded-lg bg-muted p-2.5">
+          <Icon className="h-5 w-5 text-muted-foreground" />
+        </div>
+        <div className="min-w-0">
+          <p className="text-xs text-muted-foreground">{label}</p>
+          {loading ? (
+            <Skeleton className="mt-1 h-6 w-20" />
+          ) : (
+            <p className="truncate text-xl font-semibold">{value}</p>
+          )}
+          {hint && !loading && <p className="text-xs text-muted-foreground">{hint}</p>}
+        </div>
+      </CardContent>
+    </Card>
+  );
+}
+
+export default function Dashboard() {
+  const href = useAdminHref();
+  const navigate = useNavigate();
+  const { format } = useMoney();
+
+  const summary = useAsync(() => call("admin-reports", "summary", {}, { silent: true }), []);
+  const stock = useAsync(() => call("admin-reports", "stock", {}, { silent: true }), []);
+  const latest = useAsync(() => base44.entities["commerce.Order"].list("-created_date", 8), []);
+
+  // A dashboard that needs a manual refresh to show a new order isn't much of a
+  // dashboard. Orders/refunds move the sales + status tiles and the latest-orders
+  // table; products move the low-stock list.
+  // The summary/stock actions scan orders, so the no-push fallback polls slowly.
+  useRealtime(
+    ["commerce.Order", "commerce.OrderRefund", "commerce.Product"],
+    () => {
+      summary.refetchQuiet();
+      stock.refetchQuiet();
+      latest.refetchQuiet();
+    },
+    { fallbackPollMs: 60000 },
+  );
+
+  const s = summary.data || {};
+  const ordersByStatus = s.orders_by_status || {};
+  const lowStock = (stock.data?.low_stock || []).slice(0, 6);
+  const processingCount = ordersByStatus.processing || 0;
+
+  return (
+    <div className="space-y-6">
+      <div className="flex flex-wrap items-center justify-between gap-3">
+        <div>
+          <h1 className="text-xl font-semibold tracking-tight">Dashboard</h1>
+          <p className="text-sm text-muted-foreground">Your store at a glance.</p>
+        </div>
+        <div className="flex gap-2">
+          <Button variant="outline" size="sm" asChild>
+            <Link to={href("products/new")}>
+              <PackagePlus className="mr-1.5 h-4 w-4" /> Add product
+            </Link>
+          </Button>
+          <Button variant="outline" size="sm" asChild>
+            <Link to={href("coupons/new")}>
+              <TicketPercent className="mr-1.5 h-4 w-4" /> Create coupon
+            </Link>
+          </Button>
+          <Button variant="outline" size="sm" asChild>
+            <Link to={href("reports")}>
+              <BarChart3 className="mr-1.5 h-4 w-4" /> View reports
+            </Link>
+          </Button>
+        </div>
+      </div>
+
+      <div className="grid grid-cols-1 gap-4 sm:grid-cols-2 xl:grid-cols-4">
+        <StatCard
+          icon={TrendingUp}
+          label="Net sales today"
+          value={format(asMoneyNumber(s.sales_today))}
+          loading={summary.loading}
+        />
+        <StatCard
+          icon={BarChart3}
+          label="Net sales this month"
+          value={format(asMoneyNumber(s.sales_month))}
+          loading={summary.loading}
+        />
+        <StatCard
+          icon={ShoppingCart}
+          label="Awaiting processing"
+          value={processingCount}
+          hint="orders to fulfill"
+          loading={summary.loading}
+        />
+        <StatCard
+          icon={AlertTriangle}
+          label="Low stock"
+          value={s.low_stock_count ?? lowStock.length}
+          hint="products at or below threshold"
+          loading={summary.loading && stock.loading}
+        />
+      </div>
+
+      {/* Orders by status */}
+      <div className="flex flex-wrap gap-2">
+        {ORDER_STATUSES.map((st) => (
+          <Link key={st.value} to={href(`orders?status=${st.value}`)}>
+            <Badge variant="outline" className={`${st.color} cursor-pointer`}>
+              {st.label}: {ordersByStatus[st.value] || 0}
+            </Badge>
+          </Link>
+        ))}
+      </div>
+
+      <div className="grid grid-cols-1 gap-6 xl:grid-cols-3">
+        {/* Latest orders */}
+        <Card className="xl:col-span-2">
+          <CardHeader className="pb-2">
+            <CardTitle className="text-base">Latest orders</CardTitle>
+          </CardHeader>
+          <CardContent className="p-0">
+            {latest.loading ? (
+              <div className="space-y-2 p-4">
+                {Array.from({ length: 4 }).map((_, i) => (
+                  <Skeleton key={i} className="h-8 w-full" />
+                ))}
+              </div>
+            ) : (latest.data || []).length === 0 ? (
+              <div className="py-10">
+                <EmptyState
+                  icon={ShoppingCart}
+                  title="No orders yet"
+                  description="Orders will appear here as soon as they come in."
+                />
+              </div>
+            ) : (
+              <Table>
+                <TableHeader>
+                  <TableRow>
+                    <TableHead>Order</TableHead>
+                    <TableHead>Date</TableHead>
+                    <TableHead>Status</TableHead>
+                    <TableHead>Customer</TableHead>
+                    <TableHead className="text-right">Total</TableHead>
+                  </TableRow>
+                </TableHeader>
+                <TableBody>
+                  {(latest.data || []).map((o) => (
+                    <TableRow
+                      key={o.id}
+                      className="cursor-pointer"
+                      onClick={() => navigate(href(`orders/${o.id}`))}
+                    >
+                      <TableCell className="font-medium">#{o.order_number || o.id}</TableCell>
+                      <TableCell>{formatDate(o.created_date)}</TableCell>
+                      <TableCell>
+                        <StatusBadge status={o.status} />
+                      </TableCell>
+                      <TableCell>{customerName(o)}</TableCell>
+                      <TableCell className="text-right">{format(o.total || 0)}</TableCell>
+                    </TableRow>
+                  ))}
+                </TableBody>
+              </Table>
+            )}
+          </CardContent>
+        </Card>
+
+        {/* Low stock */}
+        <Card>
+          <CardHeader className="pb-2">
+            <CardTitle className="text-base">Low on stock</CardTitle>
+          </CardHeader>
+          <CardContent className="p-0">
+            {stock.loading ? (
+              <div className="space-y-2 p-4">
+                {Array.from({ length: 3 }).map((_, i) => (
+                  <Skeleton key={i} className="h-8 w-full" />
+                ))}
+              </div>
+            ) : lowStock.length === 0 ? (
+              <div className="py-10">
+                <EmptyState icon={Plus} title="All stocked up" description="No products are low on stock." />
+              </div>
+            ) : (
+              <ul className="divide-y">
+                {lowStock.map((p) => (
+                  <li key={p.id}>
+                    <Link
+                      to={href(`products/${p.product_id || p.id}`)}
+                      className="flex items-center justify-between px-4 py-2.5 hover:bg-muted/50"
+                    >
+                      <span className="min-w-0">
+                        <span className="block truncate text-sm font-medium">{p.name}</span>
+                        {p.sku && <span className="text-xs text-muted-foreground">SKU: {p.sku}</span>}
+                      </span>
+                      <Badge variant="outline" className="ml-2 shrink-0 bg-amber-100 text-amber-800 border-amber-200">
+                        {p.stock_quantity ?? 0} left
+                      </Badge>
+                    </Link>
+                  </li>
+                ))}
+              </ul>
+            )}
+          </CardContent>
+        </Card>
+      </div>
+    </div>
+  );
+}