@base44/app-plugin-commerce 0.1.12 → 0.1.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44/app-plugin-commerce",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "Base44 Commerce plugin — entities, backend functions, shared commerce engine, admin UI and the commerce skill, shipped as copyable source",
   "keywords": [
     "base44",

package/skills/commerce/SKILL.md

@@ -14,7 +14,7 @@ Operational guidance for extending, operating and building on the Base44 Commerc
 
 ## IMPORTANT — first-time installation
 
-If the template was just installed (or you are installing it right now), read [`.agents/skills/commerce/post-installation.md`](./post-installation.md) **before anything else — and, unless the user has a special requirement, read nothing else**: it alone covers embedding the admin pages, the three-layer admin-role enforcement (do not weaken), seeding the store's data — **one `commerce/seed-store` call takes the whole catalog** (products with attributes; variants, categories, ribbons and Shipping & Tax Locations created internally — §2) — **card payments in one file** (§2.2: a complete Stripe implementation to paste over `shared/commerce/card-payment.ts`; the payment webhook is premade), and the **storefront quick start** (§3): logic-only chunks for product list → product page → cart → checkout. The references below and the API docs are for requests that go beyond that happy path, not for the install. The full install-from-scratch steps are in [`.agents/skills/commerce/installation-guidelines.md`](./installation-guidelines.md).
+If the template was just installed (or you are installing it right now), read [`.agents/skills/commerce/post-installation.md`](./post-installation.md) **before anything else — and, unless the user has a special requirement, read nothing else**: it alone covers embedding the admin pages, the three-layer admin-role enforcement (do not weaken), seeding the store's data — **one `commerce/seed-store` call takes the whole catalog** (products with attributes; variants, categories, ribbons and Shipping & Tax Locations created internally — §2) — **card payments in one file, wired only if — and whenever in the flow — the store actually needs online payments** (§2.2 opens with that decision, then a complete Stripe implementation to paste over `shared/commerce/card-payment.ts`; the payment webhook is premade), and the **storefront quick start** (§3): logic-only chunks for product list → product page → cart → checkout. The references below and the API docs are for requests that go beyond that happy path, not for the install. The full install-from-scratch steps are in [`.agents/skills/commerce/installation-guidelines.md`](./installation-guidelines.md).
 
 ## Working on the UI
 

package/skills/commerce/post-installation.md

@@ -1,8 +1,8 @@
 # Post-installation
 
-What to do right after the static installation ([`installation-guidelines.md`](./installation-guidelines.md)): embed the admin pages into the app, seed the store's data, wire payments, and build the storefront from the quick start below. Installed into the app at `.agents/skills/commerce/post-installation.md`.
+What to do right after the static installation ([`installation-guidelines.md`](./installation-guidelines.md)): embed the admin pages into the app, seed the store's data, build the storefront from the quick start below, and — **if and when the store needs online payments, a call you make deliberately (§2.2)** — wire a payment provider. Installed into the app at `.agents/skills/commerce/post-installation.md`.
 
-> **This file is intentionally the whole job.** Unless the user has a special requirement (a non-Stripe payment provider, signature-verified webhooks, filters/reviews/accounts beyond the happy path), do **not** open the `references/` guides or the `docs/` API references — everything needed to ship a working store (admin mount, seeding, product list, product page, cart, checkout, order-received, card payments) is on this page, ending with the [Done when](#4-done-when) checklist. Reading more first just burns time.
+> **This file is intentionally the whole job.** Unless the user has a special requirement (a non-Stripe payment provider, signature-verified webhooks, filters/reviews/accounts beyond the happy path), do **not** open the `references/` guides or the `docs/` API references — everything needed to ship a working store (admin mount, seeding, product list, product page, cart, checkout, order-received, and card payments for the stores that need them) is on this page, ending with the [Done when](#4-done-when) checklist. Reading more first just burns time.
 
 ---
 
@@ -145,6 +145,12 @@ A successful response means the data is in — the catalog and settings are live
 
 The order side of payments is **already implemented** (checkout routing, confirmation, payment links, refund records). The `offline` gateway — and any option the admin adds in Settings → Payments — works with nothing to configure: the order goes on-hold with the option's description as instructions.
 
+**Whether the store needs online payments — and when in the install to wire them — is your decision, not a fixed step.** Nothing else on this page depends on this section: the admin, the seed and the entire storefront work with no provider wired (until then the card option answers `503 no_card_payment_provider` at checkout, and §3.4 shows the graceful fallback). Decide from what the user is actually building:
+
+- **The store doesn't take online payments** (cash on delivery, bank transfer, invoicing, pickup, quote-based…) → seed `payment_methods` without `"card"` and skip the rest of this section — the manual gateways are complete as shipped.
+- **The store does take online payments** → this section is the how-to (Stripe below is the reference), but *you* pick the point in the flow. The wiring is self-contained and needs the user's provider secret key, so it usually fits **after** the storefront is standing — asking for a Stripe key before there is anything to sell is premature. What's non-negotiable is only the end state: don't hand over a finished store with the card gateway enabled but no provider behind it (wire one, or disable the gateway).
+- **Unclear from the request** → build everything else first and raise payments with the user at the end, or ask.
+
 Which methods the store offers is **seed data**: pass `payment_methods` to `commerce/seed-store` (§2) — e.g. `["card"]` for a card-only store — instead of ever editing `commerce.PaymentGateway` records yourself.
 
 The **Credit card** option needs a payment provider — **any** provider works (Stripe, PayPal, Adyen, a local PSP…), and whichever one it is, wiring it touches exactly **one file**: `base44/shared/commerce/card-payment.ts` — four functions, each backing a premade flow. `commerce/payment-webhook` (the function) is **premade — do not edit it**: it calls this file's `parseWebhook` to validate each event and **never trusts an event body on its own** — an unverified event only *names* an order, and whether money arrived is asked of the provider itself through `checkCardPaymentPaid`, so a forged webhook call can never mark an order paid and **no signing secret is needed**. Until the file is implemented the card option answers `503 no_card_payment_provider` at checkout (or switch it off in Settings → Payments).
@@ -287,6 +293,19 @@ export const store = createStorefront(base44);
 
 The client owns the two things hand-rolled storefronts keep getting wrong, so **don't reimplement either**: the **`cart_token` lifecycle** (sent with every cart/checkout call, re-persisted from every response — a stale token silently starts a fresh cart; rolling 48 h expiry; cleared when checkout consumes the cart) and the **store-info cache** (`payment_gateways`, currency, countries live **only** on `get-store-info` — the cart view never carries them). For anything beyond its methods, `store.inv(fn, payload)` unwraps the `{ success, data }` envelope (`res.data.data`).
 
+**What each method resolves to** — the client already unwraps every envelope, so take these shapes at face value (no `.data`, and no `.categories` on a list result):
+
+| Method | Resolves to |
+|---|---|
+| `store.getStoreInfo()` | `{ settings, payment_gateways, countries, currencies }` — cached; the **only** source of `payment_gateways` |
+| `store.listProducts(params)` | `{ products, page, per_page, has_next }` — a page object; the array is `products` |
+| `store.getProduct(slug \| { id })` | `{ product, variations, categories, ribbons, reviews }` |
+| `store.listCategories()` | an **array** of root categories, subcategories nested under `children` |
+| `store.listRibbons()` | an **array** of `{ id, name, count }` |
+| `store.getCart()` and every cart mutation | the full cart view (`getCart()` alone may resolve to `null` — no cart yet); `cart.items[n].attributes` is an **array** of `{ name, option }`, never a map |
+| `store.placeOrder(details)` | `{ order_id, order_number, order_key, status, totals, order, payment_instructions, payment }` |
+| `store.completeReturn()` | `{ state, order, payment_link, payment_instructions }` |
+
 Keep the UI in **small focused components** (~2–4K characters each — product card, gallery, cart panel, address step, payment step…), not monolithic page files: smaller files are faster to emit, review and fix.
 
 ### 3.1 Product list
@@ -305,7 +324,7 @@ const { products, page, per_page, has_next } = await store.listProducts({
 });                                // sort: -created_date | name | price | -price | popularity | rating
 ```
 
-Each row is a full product record — for a card use `name`, `images[0]?.src` (**may be empty — render a placeholder, never a broken `<img>`**), `price`, `regular_price`, `on_sale` (sale badge), `short_description`, `stock_status`, `average_rating`/`rating_count` (stars cost no extra call) and `ribbons` (`[{ id, name }]`, may be absent — labels like "Best Seller" for the card corner). **There is no product type flag**: `product.attributes?.length > 0` means the product sells variants and its `price` is a *from*-price rolled up from the cheapest variant — render it as "From …". Categories for the nav come from `store.listCategories()` (a tree via `parent_id`). That is the whole card — no other call or reference needed for the list view.
+Each row is a full product record — for a card use `name`, `images[0]?.src` (**may be empty — render a placeholder, never a broken `<img>`**), `price`, `regular_price`, `on_sale` (sale badge), `short_description`, `stock_status`, `average_rating`/`rating_count` (stars cost no extra call) and `ribbons` (`[{ id, name }]`, may be absent — labels like "Best Seller" for the card corner). **There is no product type flag**: `product.attributes?.length > 0` means the product sells variants and its `price` is a *from*-price rolled up from the cheapest variant — render it as "From …". Categories for the nav come from `store.listCategories()` — an **array** of root categories with subcategories nested under `children` (map over it directly; there is no `{ categories }` wrapper on the result). That is the whole card — no other call or reference needed for the list view.
 
 **Carry forward:** each card links to the product page by **`slug`**.
 
@@ -348,6 +367,8 @@ A product with attributes is **rejected without a `variation_id`** (`400 variati
 ```js
 let cart = await store.getCart();   // null → no cart yet (an expired token self-clears)
 // cart.items  → [{ item_key, name, image, quantity, price, subtotal, total, attributes, purchasable }]
+//               item.attributes is an ARRAY of { name, option } — render "Size: 42" by
+//               mapping it (attributes.map(a => `${a.name}: ${a.option}`)); it is never a map
 // cart.totals → { subtotal, discount_total, shipping_total, cart_tax, total_tax, total, … }
 // cart.coupon_notices / cart.removed_items → tell the customer what auto-dropped and why
 //
@@ -444,7 +465,7 @@ Two shapes to get right when rendering: **`order` carries flat totals** — `ord
 
 ## 4. Done when
 
-Post-installation is complete when every line below holds — verify against this list instead of re-reading docs:
+Post-installation is complete when every line below holds — check against this list instead of re-reading docs. **Do not validate the admin part at all**: everything under `/store-admin` ships finished and already tested — there is nothing there for you to verify.
 
 - [ ] `/store-admin/*` mounted behind the shipped `AuthGuard`; `/` routes somewhere real (storefront or a redirect).
 - [ ] `commerce/seed-store` ran once and reported the catalog — real products, final image URLs; if the user restricted payment methods, `payment_methods` was passed in that same call.
@@ -452,8 +473,7 @@ Post-installation is complete when every line below holds — verify against thi
 - [ ] Product page renders from `store.getProduct` with one selector per attribute, resolving to `view.addToCart`.
 - [ ] The storefront talks to the API through **one `createStorefront` instance** — no hand-rolled `cart_token` handling, and `payment_gateways` read from `getStoreInfo()` only, never off a cart.
 - [ ] `/order-received` calls `completeReturn` and renders `paid` / `unpaid` / `cancelled`.
-- [ ] Card payments: `card-payment.ts` implemented (Stripe: paste §2.2), `STRIPE_SECRET_KEY` secret set, webhook endpoint registered — **or** the card gateway disabled (seed `payment_methods` without `"card"`).
-- [ ] **Verified by driving a real test order end to end** — add to cart → address → shipping → `place-order` → `/order-received` renders the right state — then the test order cancelled/deleted in the admin. Placing and cleaning up a test order is routine install verification, not a destructive action. A button existing is **not** evidence the flow works; only the driven flow is.
+- [ ] Online payments **decided, not defaulted** (§2.2): if the store takes card payments, `card-payment.ts` implemented (Stripe: paste §2.2), `STRIPE_SECRET_KEY` secret set and webhook endpoint registered — wired at whatever point in the flow you judged right; if it doesn't (or not yet), the card gateway disabled (seed `payment_methods` without `"card"`). Either way, checkout never offers a card option with no provider behind it.
 
 ## 5. Next
 

package/src/commerce/admin/pages/products/components/AttributesSection.jsx

@@ -14,6 +14,7 @@ import { ChevronDown, ChevronRight, ChevronUp, Loader2, Plus, Settings2, Trash2
 
 import { base44, call } from "../../../lib/api";
 import SearchSelect from "../../../components/SearchSelect";
+import ConfirmDialog from "../../../components/ConfirmDialog";
 import { slugify } from "../../../lib/product-utils";
 
 /** Sentinel option value for "create the thing I just typed". */
@@ -35,12 +36,16 @@ const fetchValues = (attributeId) =>
  * immediately, while the choice of which values *this* product uses is part of
  * the product form and saves with it.
  */
-export default function AttributesSection({ product, up, refs }) {
+export default function AttributesSection({ product, up, refs, variations = [] }) {
   const attributes = product.attributes || [];
   const globalAttributes = refs.attributes || [];
   const [valuesByAttr, setValuesByAttr] = useState({});
   const [manageOpen, setManageOpen] = useState(false);
   const [busy, setBusy] = useState(false);
+  // Destructive edits (removing a value or an option) confirm before applying,
+  // because the variant list is rebuilt from these and rows are deleted.
+  const [pendingValues, setPendingValues] = useState(null); // {index, options, removed, affected, stock}
+  const [pendingRemoveRow, setPendingRemoveRow] = useState(null); // index
 
   const loadValues = useCallback(async (attributeId) => {
     const rows = await fetchValues(attributeId);
@@ -68,6 +73,17 @@ export default function AttributesSection({ product, up, refs }) {
   const removeRow = (index) =>
     up({ attributes: attributes.filter((_, i) => i !== index).map((a, i) => ({ ...a, position: i })) });
 
+  /** Variants that carry one of the removed values for this option. */
+  const affectedBy = (row, removed) =>
+    variations.filter((v) =>
+      (v.attributes || []).some(
+        (a) =>
+          (a.attribute_id || a.name) === (row.attribute_id || row.name) && removed.includes(a.option)
+      )
+    );
+  const stockOf = (list) =>
+    list.reduce((sum, v) => sum + (v.manage_stock === "yes" ? Number(v.stock_quantity) || 0 : 0), 0);
+
   const moveRow = (index, delta) => {
     const target = index + delta;
     if (target < 0 || target >= attributes.length) return;
@@ -125,20 +141,25 @@ export default function AttributesSection({ product, up, refs }) {
     <div className="space-y-3">
       <div className="flex items-start justify-between gap-4">
         <div>
-          <h3 className="text-sm font-semibold">Attributes</h3>
+          <h3 className="text-sm font-semibold">Options</h3>
           <p className="text-xs text-muted-foreground">
-            What this product varies by. Every attribute is an axis, and the variants below follow
-            the values you pick.
+            What this product comes in — each combination of values becomes a variant below.
           </p>
         </div>
-        <Button type="button" variant="outline" size="sm" onClick={() => setManageOpen(true)}>
-          <Settings2 className="mr-2 h-4 w-4" /> Manage attributes…
+        <Button
+          type="button"
+          variant="ghost"
+          size="icon"
+          title="Manage option catalog (affects all products)"
+          onClick={() => setManageOpen(true)}
+        >
+          <Settings2 className="h-4 w-4 text-muted-foreground" />
         </Button>
       </div>
 
       {attributes.length === 0 && (
         <p className="text-sm text-muted-foreground">
-          None — this product sells as a single item. Add one (Size, Color) to sell variants.
+          No options yet. Add one (Size, Color, Pack…) and pick the values this product comes in.
         </p>
       )}
 
@@ -173,7 +194,11 @@ export default function AttributesSection({ product, up, refs }) {
                 type="button"
                 variant="ghost"
                 size="icon"
-                onClick={() => removeRow(i)}
+                onClick={() =>
+                  (row.options || []).length && variations.length
+                    ? setPendingRemoveRow(i)
+                    : removeRow(i)
+                }
                 title="Remove from this product"
               >
                 <Trash2 className="h-4 w-4 text-muted-foreground" />
@@ -185,8 +210,18 @@ export default function AttributesSection({ product, up, refs }) {
               value={selected.map((o) => ({ value: o, label: o }))}
               onChange={(next) => {
                 const created = next.find((o) => o.value === CREATE);
-                if (created) createAndSelectValue(row, i, createdName(created.label));
-                else setRow(i, { options: next.map((o) => o.value) });
+                if (created) {
+                  createAndSelectValue(row, i, createdName(created.label));
+                  return;
+                }
+                const options = next.map((o) => o.value);
+                const removed = selected.filter((o) => !options.includes(o));
+                const affected = removed.length ? affectedBy(row, removed) : [];
+                if (affected.length) {
+                  setPendingValues({ index: i, options, removed, affected, stock: stockOf(affected) });
+                } else {
+                  setRow(i, { options });
+                }
               }}
               search={async (q) => {
                 const term = (q || "").trim();
@@ -205,7 +240,7 @@ export default function AttributesSection({ product, up, refs }) {
       <div className="flex items-center gap-2">
         <SearchSelect
           className="w-72"
-          placeholder="Add attribute…"
+          placeholder="Add option…"
           value={null}
           onChange={(opt) => {
             if (!opt) return;
@@ -235,6 +270,40 @@ export default function AttributesSection({ product, up, refs }) {
           onChanged={refs.refreshAttributes}
         />
       )}
+
+      {pendingValues && (
+        <ConfirmDialog
+          open
+          onOpenChange={(o) => !o && setPendingValues(null)}
+          title={`Remove ${pendingValues.removed.map((r) => `“${r}”`).join(", ")}?`}
+          description={`This deletes ${pendingValues.affected.length} variant(s)${
+            pendingValues.stock ? ` and their ${pendingValues.stock} units of stock` : ""
+          }. Their prices, stock and SKUs will be lost when you save.`}
+          confirmLabel="Delete variants"
+          onConfirm={() => {
+            setRow(pendingValues.index, { options: pendingValues.options });
+            setPendingValues(null);
+          }}
+        />
+      )}
+
+      {pendingRemoveRow != null && (
+        <ConfirmDialog
+          open
+          onOpenChange={(o) => !o && setPendingRemoveRow(null)}
+          title={`Remove the “${attributes[pendingRemoveRow]?.name}” option?`}
+          description={
+            attributes.length === 1
+              ? `This deletes all ${variations.length} variant(s) with their prices, stock and SKUs.`
+              : `The variant list is rebuilt without it — prices, stock and SKUs of the current ${variations.length} variant(s) may be lost.`
+          }
+          confirmLabel="Remove option"
+          onConfirm={() => {
+            removeRow(pendingRemoveRow);
+            setPendingRemoveRow(null);
+          }}
+        />
+      )}
     </div>
   );
 }
@@ -329,10 +398,10 @@ function ManageAttributesDialog({ attributes, valuesByAttr, loadValues, onClose,
     <Dialog open onOpenChange={(o) => !o && onClose()}>
       <DialogContent className="max-h-[85vh] overflow-y-auto sm:max-w-2xl">
         <DialogHeader>
-          <DialogTitle>Manage attributes</DialogTitle>
+          <DialogTitle>Option catalog</DialogTitle>
         </DialogHeader>
         <p className="-mt-2 text-xs text-muted-foreground">
-          Shared across every product — changes save immediately. To delete an attribute or a value,
+          Shared across every product — changes save immediately. To delete an option or a value,
           remove it from the entity data.
         </p>
 
@@ -398,12 +467,12 @@ function ManageAttributesDialog({ attributes, valuesByAttr, loadValues, onClose,
               )}
             </div>
           ))}
-          {!attributes.length && <p className="text-sm text-muted-foreground">No attributes yet.</p>}
+          {!attributes.length && <p className="text-sm text-muted-foreground">No options yet.</p>}
         </div>
 
         <div className="flex items-end gap-2 border-t pt-3">
           <div className="flex-1 space-y-1.5">
-            <Label>New attribute</Label>
+            <Label>New option</Label>
             <Input
               placeholder="e.g. Fabric"
               value={newName}

package/src/commerce/admin/pages/products/components/ProductDataPanel.jsx

@@ -1,9 +1,7 @@
 import React from "react";
 import { Card, CardContent, CardHeader } from "@/components/ui/card";
 import { Checkbox } from "@/components/ui/checkbox";
-import { Separator } from "@/components/ui/separator";
 
-import { isVariable } from "../../../lib/product-utils";
 import PriceInventoryTab from "./tabs/PriceInventoryTab";
 import ModifiersTab from "./tabs/ModifiersTab";
 import LinkedTab from "./tabs/LinkedTab";
@@ -31,7 +29,7 @@ export default function ProductDataPanel({ product, up, refs, variations, setVar
         />
       ),
     },
-    { id: "modifiers", label: "Modifiers", body: <ModifiersTab product={product} up={up} /> },
+    { id: "modifiers", label: "Specifications", body: <ModifiersTab product={product} up={up} /> },
     ...(product.downloadable
       ? [{ id: "downloads", label: "Downloads", body: <DownloadsTab product={product} up={up} /> }]
       : []),
@@ -68,14 +66,6 @@ export default function ProductDataPanel({ product, up, refs, variations, setVar
             </section>
           ))}
         </div>
-        <Separator />
-        <div className="px-4 py-2 text-xs text-muted-foreground">
-          {isVariable(product)
-            ? `${(product.attributes || []).length} variant attribute(s) · ${(variations || []).length} variant(s)`
-            : "No variants"}
-          {product.virtual ? " · Virtual" : ""}
-          {product.downloadable ? " · Downloadable" : ""}
-        </div>
       </CardContent>
     </Card>
   );

package/src/commerce/admin/pages/products/components/tabs/ModifiersTab.jsx

@@ -4,16 +4,22 @@ import MetaDataEditor from "../../../../components/MetaDataEditor";
 
 /**
  * Descriptive properties — Material, Care, GTIN. They are `meta_data`, never
- * attributes: they don't create variants and never affect price or stock.
+ * options: they don't create variants and never affect price or stock.
  */
 export default function ModifiersTab({ product, up }) {
+  const empty = !(product.meta_data || []).length;
   return (
     <div className="max-w-xl space-y-2">
       <p className="text-xs text-muted-foreground">
-        Shown as product details. They have no effect on price, stock or variants — what a product
-        varies by belongs in Attributes, under Price &amp; Inventory.
+        Descriptive details shown on the product page (e.g. ingredients, allergens, care
+        instructions).
       </p>
       <MetaDataEditor value={product.meta_data || []} onChange={(meta_data) => up({ meta_data })} />
+      {empty && (
+        <p className="text-xs text-muted-foreground">
+          Want the product to vary by something? Add it as an option under Price &amp; Inventory.
+        </p>
+      )}
     </div>
   );
 }