@base44/app-plugin-commerce 0.1.12 → 0.1.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44/app-plugin-commerce",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "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/utils/storefront.js

@@ -9,7 +9,7 @@
  *   import { base44 } from "@/api/base44Client";
  *   export const store = createStorefront(base44);
  *
- * It owns the two things hand-rolled clients keep getting wrong:
+ * It owns the things hand-rolled clients keep getting wrong:
  *
  * - The cart_token lifecycle: the token is sent with every cart/checkout call
  *   and re-persisted from every response (a stale token silently starts a
@@ -17,6 +17,11 @@
  * - The store-info split: payment_gateways, currency, countries/currencies
  *   live ONLY on get-store-info — the cart view never carries them.
  *   getStoreInfo() caches the call; read them from there, never off a cart.
+ * - Envelope unwrapping: every method resolves straight to the data you use.
+ *   listCategories() and listRibbons() resolve to ARRAYS — the raw actions'
+ *   { categories } / { ribbons } wrappers are unwrapped here, so never dig
+ *   for `.categories` on the result. Only the raw escape hatch inv(fn,
+ *   payload) returns an action's payload as-is.
  */
 
 /** The stable error code a failed storefront call carries, if any. */
@@ -65,11 +70,13 @@ export function createStorefront(base44, { storageKey = "cart_token", storage }
       const by = typeof ref === "string" ? { slug: ref } : ref;
       return inv("commerce/storefront-catalog", { action: "get-product", ...by });
     },
+    /** ARRAY of root categories, subcategories nested under `children`. */
     listCategories() {
-      return inv("commerce/storefront-catalog", { action: "list-categories" });
+      return inv("commerce/storefront-catalog", { action: "list-categories" }).then((d) => d.categories);
     },
+    /** ARRAY of { id, name, count }. */
     listRibbons() {
-      return inv("commerce/storefront-catalog", { action: "list-ribbons" });
+      return inv("commerce/storefront-catalog", { action: "list-ribbons" }).then((d) => d.ribbons);
     },
 
     // ── cart (token handled internally; every call returns the full view) ─