@base44/app-plugin-commerce 0.5.0 → 0.6.0

package/README.md

@@ -12,7 +12,7 @@ It provides a full-featured **commerce data model and behavior** (variant-driven
 - **Shared commerce engine** (`base44/shared/commerce/`) — totals, tax, shipping, coupons, stock, order lifecycle, webhook dispatch (HMAC-signed), emails, card-payment plumbing, plus static country/currency/continent data.
 - **Admin UI** (`src/commerce/admin/`) — a React/Tailwind/shadcn admin with a familiar store back-office information architecture: dashboard, orders, products, coupons, customers, reports, and full settings including webhooks. Admin-role gated.
 - **Storefront helpers** (`src/commerce/utils/`) — framework-free, dependency-free modules for the shopfront you build: `storefront.js` is the API client (`createStorefront(base44)` — cart-token lifecycle, cached store-info, catalog/cart/checkout/reviews/return-page calls); `variants.js` maps an attribute selection (Size, Color) onto a `ProductVariation` and back, plus per-option availability and price ranges; `price.js` encodes the from-price and price-range rules; `totals.js` projects a cart *or* an order into one summary shape; `address-spec.js` is the checkout address form as data; `images.js` and `ribbons.js` normalize the two catalog fields that are arrays of objects (`{src, name, alt}` images, `{id, name}` ribbons) rather than strings; `types.js` writes the catalog shapes down as JSDoc typedefs (`StorefrontProduct` and the rest), so what a field holds is answerable from the frontend; `shipping-promos.js` reads the store's real free-shipping configuration so "Free shipping over €150" states a configured rule rather than an invented number.
-- **Storefront React layer** (`src/commerce/storefront/`) — two tiers, and neither ships a look or a sentence. **The catalog tier is headless hooks** — `StorefrontProvider` (+ `useStorefront`/`useStoreInfo`/`useFormatMoney`/`useCountries`), `useProductList`/`useCategories`/`useRibbons`, `useProduct`/`useAddToCart`, `useCart`/`useCartLine`/`CartLine`, `useCheckout`/`CheckoutProvider`, `useOrderReturn`, the `ShippingMethodPicker`/`PaymentMethodPicker` render-prop components, and the framework-free view-model helpers re-exported so one import line covers a page (`variantAxes`, `productPrice`, `productImages`, `productRibbons`, `productSpecs`, `attributesLabel`, `cartTotalsLines`/`orderTotalsLines`, `addressFieldSpec`) — the product list and product page are built from these, entirely in the store's own markup, classes and words. **The commodity tier is parts** — `Cart.*`, `Checkout.*`, `OrderReceived.*` compound components that render each section of the cart contents, checkout and receipt as correct semantic markup carrying **layout geometry and nothing else** (field grids, labels above full-width controls, square thumbnails, label-left/value-right totals — enforced by a release gate to contain no color, type or border), with **zero copy and zero navigation**: the store's page is the layout around them; styling comes via `data-part`/`data-state` selectors or `className`/`classes` props; every word (blocker lines, field labels, button text, aria names) comes from one agent-written copy file passed as `labels` (a missing key renders a visible `⟨copy: …⟩` placeholder — the code has no English fallback); and every navigation affordance (the cart's checkout link, `Checkout.Root`'s required `orderReceivedPath`, `OrderReceived.PaymentLink`'s render-prop child) is the store's own element and route. The **cart drawer stays the store's own surface** — which side it enters from, its width, padding and animation — while `useCartUI()` keeps the state and the fiddly behavior (Esc, close-on-navigate, open-on-add, focus in and back out, inert while closed) and `CartDrawer.Trigger`/`Close` are the two wired buttons. Parts compose the hooks, so replacing one section with a hook-built custom region is a normal move (`useInCheckout()` even lets one shared cart-contents component drop its upsell rail inside the checkout) — and the parts are copied source, editable when a requirement outgrows their props. Needs React and nothing else.
+- **Storefront React layer** (`src/commerce/storefront/`) — **headless: the logic is premade, the UI never is.** Nothing in the layer renders markup or carries CSS; every element, class and word of copy in the storefront you build is yours, so a brief like "make it feel like <site>" applies to the whole store, checkout included. **It ships no customer-facing copy either**: where a state needs words you get the *state* — `buy.state`, a picker's `hint.code`, the checkout's `blockers`, a review's `status` — and write the sentence. What ships is every piece of logic that is the same in all stores: `StorefrontProvider` (+ `useStorefront`/`useStoreInfo`/`useFormatMoney`/`useCountries`), `useProductList`/`useCategories`/`useRibbons`, `useProduct`/`useAddToCart`, `useCart`/`useCartLine` (+ `useCartUI`/`CartUIProvider` for a drawer), `useCheckout`/`CheckoutProvider`/`useCheckoutContext`, `useOrderReturn`/`orderReceivedUrl` — plus three render-prop components that stay just as headless (`ShippingMethodPicker`/`PaymentMethodPicker` for the two checkout choices that are store data, `CartLine` for per-row cart bindings), one deliberately rendered-but-unstyled component (`AddressFields` — the checkout address form, whose state/province and `autoComplete` mechanics are where hand-rolled forms break; it ships no CSS and styles via `data-part` selectors or class props), and the framework-free view-model helpers re-exported so one import line covers a page (`variantAxes`, `productPrice`, `productImages`, `productRibbons`, `productSpecs`, `attributesLabel`, `cartTotalsLines`/`orderTotalsLines`, `addressFieldSpec`). Each hook's doc comment states the render rules that keep a store correct (an unbuyable variant option renders disabled, not hidden; a receipt page must render `paymentInstructions`; …) and names its return type from `storefront/types.js`, so a page reads a field's shape off the hook instead of off a backend function. Needs React and nothing else.
 - **StoreAdmin agent + bot** — an AI copilot (`base44/agents/commerce/StoreAdmin.jsonc`, registered as `commerce/StoreAdmin`) with the `commerce/*` functions attached directly as tools (calls run as the chatting user → `requireAdmin()` still applies), variant-aware order editing, plus a chat panel in the admin sidebar with GFM markdown-table rendering.
 - **Docs** — this README plus the commerce skill folder [`skills/commerce/`](./skills/commerce/): [`SKILL.md`](./skills/commerce/SKILL.md) is the map every agent starts from (and the only path the platform needs to know); [`install/`](./skills/commerce/install/) holds the three stage files that are the whole install (`01-install` → `02-storefront` → `03-data`, each read at the moment its work starts and dropped when its checklist passes); [`references/`](./skills/commerce/references/) holds per-topic guides opened only on demand; [`docs/`](./skills/commerce/docs/) holds the data-model map ([`entities.md`](./skills/commerce/docs/entities.md)) and the two API references. The whole folder is installed into the app at `.agents/skills/commerce/` so agents pick it up natively.
 
@@ -104,7 +104,7 @@ If you build on Base44's hosted platform, use the Base44 agent/MCP to write the
 
 ## What's NOT included
 
-- **No storefront *design*.** The parts of a shopfront that carry a brand — the home page, the collection grid, the product card, the product page's layout, the theme, every customer-facing sentence — ship as nothing at all, on purpose: that is the work a build should spend its effort on. Everything under those surfaces does ship: the storefront API, the hooks that own the catalog's logic, and the commodity-surface parts (cart, drawer, checkout, receipt) that own those sections' *structure* — while their styling, words and layout stay the store's — see [`skills/commerce/install/02-storefront.md`](./skills/commerce/install/02-storefront.md) for how the two tiers fit together, [`skills/commerce/references/catalog-rendering.md`](./skills/commerce/references/catalog-rendering.md) for what each catalog call returns, and [`skills/commerce/docs/api-storefront.md`](./skills/commerce/docs/api-storefront.md) for the raw API.
+- **No storefront *design*.** The parts of a shopfront that carry a brand — the home page, the collection grid, the product card, the product page's layout, the theme — ship as nothing at all, on purpose: that is the work a build should spend its effort on. Everything under those surfaces does ship: the storefront API and the hooks that own the logic of every surface (catalog, product, cart, checkout, order-received, reviews) — the markup, styling and copy on top of them stay yours, including the commodity screens — see [`skills/commerce/install/02-storefront.md`](./skills/commerce/install/02-storefront.md) for how the two tiers fit together, [`skills/commerce/references/catalog-rendering.md`](./skills/commerce/references/catalog-rendering.md) for what each catalog call returns, and [`skills/commerce/docs/api-storefront.md`](./skills/commerce/docs/api-storefront.md) for the raw API.
 - **No payment provider — and cards are off by default.** The order side of card payments is premade (see above), but charging a card needs a provider, so `commerce/seed-store` enables the manual **`offline`** method (bank transfer, cash on delivery, pickup — no code, no credentials) and leaves the **`card`** gateway **switched off**. **Enable cards only if a provider is wired, or is about to be** — implement the four functions in `base44/shared/commerce/card-payment.ts`, or for Stripe copy the shipped `card-payment.stripe.ts` over it and use it as-is (`skills/commerce/references/online-payments.md`), then enable the gateway via the seed's `payment_methods: ["offline", "card"]`; enabled with nothing behind it, checkout answers `503 no_card_payment_provider`. The rule and why it belongs at the end of a build rather than its start: `skills/commerce/install/03-data.md`.
 - **No scheduled workflows shipped.** Base44 *does* have a scheduler, but this template ships no workflow files — time-based jobs (stock-hold release, cart expiry, webhook-log pruning) run **opportunistically** where possible, and for the rest you (or the Base44 agent) create scheduled workflows that call `commerce/admin-tools`/`commerce/admin-orders` actions — see [`skills/commerce/references/operations.md`](./skills/commerce/references/operations.md).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44/app-plugin-commerce",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "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

@@ -1,11 +1,12 @@
 ---
 name: commerce
-description: Base44 Commerce — commerce.* entities, commerce/* backend functions (storefront + admin APIs, payments, webhooks), the shared engine under base44/shared/commerce/, the Store Management UI at /store-admin, and the headless storefront layer (hooks + parts) under src/commerce/. Read before working on store features: installing, building a storefront, seeding a catalog, shipping zones, payments, or the admin.
+description: Base44 Commerce — commerce.* entities, commerce/* backend functions (storefront + admin APIs, payments, webhooks), the shared engine under base44/shared/commerce/, the Store Management UI at /store-admin, and the headless storefront hooks under src/commerce/. Read before working on store features: installing, building a storefront, seeding a catalog, shipping zones, payments, or the admin.
 ---
 
 # Commerce
 
 **This file is the map. It tells you what to read, when, and what you can skip.**
+Nothing else in this skill needs to be open right now.
 
 The kit ships, already written and tested: 20 `commerce.*` entities, the
 `commerce/*` backend functions (storefront API, admin API, payments, webhooks,
@@ -15,14 +16,16 @@ emails), the shared engine, a complete admin back office at `/store-admin`, the
 store's *UI and data*, not the plumbing.
 
 **Paths in this skill** are relative to the skill's folder
-(`.agents/skills/commerce/` in an installed app) wherever they are named;
-resolve them from the skill folder, never from the file that mentioned them.
+(`.agents/skills/commerce/` in an installed app), wherever they are named —
+docs, checklists, code comments. Resolve them from the skill folder, never from
+the file that mentioned them.
 
 ## Installing right now?
 
-Read **[`install/01-install.md`](./install/01-install.md)** and follow it — it
+Read **[`install/01-install.md`](./install/01-install.md)** and follow it. It
 routes you to `install/02-storefront.md` when you start the UI and
-`install/03-data.md` when you seed. Read nothing else up front.
+`install/03-data.md` when you seed the catalog — in that order, at those
+moments. Read nothing else up front.
 
 ## Four things to hold from the start
 
@@ -43,51 +46,54 @@ routes you to `install/02-storefront.md` when you start the UI and
   takes manual (`offline`) payment and works end to end; cards are a late,
   deliberate step ([`install/03-data.md`](./install/03-data.md)).
 
-## The storefront: two tiers
+## The storefront: logic is premade, UI never is
 
-**The catalog surfaces — product list and product page — are fully yours.**
-Their logic ships as headless hooks (`@/commerce/storefront`): plain states
-and handlers, you write every element, class and word. A brief like "make it
-feel like <site>" is your work, done as with no kit; encode that identity
-**once** — design classes in `index.css`, spent across every page —
+**The UI is yours, all of it** — every page, element, class and word of copy.
+The kit deliberately ships **no markup and no CSS anywhere**; a brief like
+"make it feel like <site>" is your work, done as you would with no kit. Encode
+that identity **once** — design classes in `index.css`, spent across every
+page — not as decoration re-typed on every element;
 [`install/02-storefront.md`](./install/02-storefront.md) opens with the
-method. **Never re-implement what a hook does** — that is where storefront
-bugs cluster.
-
-**The commodity surfaces — cart contents, checkout, order-received — are
-placed, not written**: `Cart.*` / `Checkout.*` / `OrderReceived.*` parts render
-each section's correct markup, carrying **layout geometry and nothing else** —
-no color, type or border, no copy, no navigation. Your layout arranges the
-sections, your `index.css` gives them their look (`[data-part]` selectors,
-`className`/`classes` props), and every word comes from **one copy file**
-passed as `labels` — a missing key renders a visible `⟨copy: …⟩`. The kit ships
-no look and no sentence anywhere: a kit sentence rendered into every store is
-how storefronts end up alike. **The cart drawer stays the store's own surface**
-(side, width, padding, animation); `useCartUI()` keeps its state and behavior,
-and `CartDrawer.Trigger`/`Close` are its two wired buttons.
+method.
+
+**The logic ships as headless hooks** (`@/commerce/storefront`) — checkout
+repricing, variant resolution, cart state, coupon redemption, order-return
+verification, cart-drawer state. Each returns **plain states and handlers**
+(`status` to branch on, arrays to map, callbacks) — you write every element and
+attribute from them. **Never re-implement what a hook does** — that is where
+storefront bugs cluster.
+
+One deliberate exception: **the checkout address form ships rendered**, as the
+unstyled `<AddressFields>` component (the state/province field, `autoComplete`
+tokens and address errors are exactly where hand-rolled forms break). Style it
+with your classes; everything around it stays yours.
+
+It ships **no copy**, either: where a state needs words you get the state
+(`buy.state`, `hint.code`, `blockers`) and write the words in the store's voice.
+A kit sentence rendered into every store is how storefronts end up alike.
 
 ```jsx
-import { Cart, CartDrawer, Checkout, OrderReceived, useProduct } from "@/commerce/storefront";
+import { useCart, CartLine } from "@/commerce/storefront";
+const { status, cart } = useCart();   // branch on status, map cart.items into YOUR rows
 ```
 
-The admin UI (`src/commerce/admin/`) is finished and **also yours to change**
-([`docs/api-admin.md`](./docs/api-admin.md) is the backend it talks to). The
-parts are the app's source too — usable from the docs' tables alone, editable
-as a last resort when a user requirement outgrows their props.
+The admin UI (`src/commerce/admin/`) is finished and **also yours to change** —
+restyle it, add pages, rework flows ([`docs/api-admin.md`](./docs/api-admin.md)
+is the backend it talks to).
 
 Four rules the API enforces — a storefront that skips them cannot complete a
-purchase. In React the hooks and parts implement all four; your markup renders
-what they hand back (API-level statements for non-React clients:
+purchase. In React the hooks implement all four; your markup renders what they
+hand back (API-level statements for non-React clients:
 [`docs/api-storefront.md`](./docs/api-storefront.md)):
 
 1. A product with variants needs **one selector per attribute**, resolved to a
    `variation_id` (`useProduct` + `variantAxes`).
 2. Checkout must **recalculate shipping from the address and send a choice**
-   (the `Checkout.*` parts — automatic).
-3. **The order-received route must exist** and render the return state — all
-   five `OrderReceived.*` gates, `PaymentInstructions` placed on unpaid.
+   (`useCheckout` — automatic).
+3. **`/order-received` must exist** and render the return state, including a
+   manual order's payment instructions (`useOrderReturn`).
 4. **Never advertise what isn't configured** — no free-shipping banner without
-   a real rate, no coupon codes without a `CouponField` to redeem them in.
+   a real rate, no coupon codes without a field to redeem them in.
 
 A fifth that breaks nothing but flattens the catalog, and is skipped most often:
 **ribbons belong in both the grid and the product page**, each linking to its
@@ -108,14 +114,12 @@ Open a file when its work starts — not while planning.
 | Topic | Open when | Size |
 |---|---|---|
 | [`install/01-install.md`](./install/01-install.md) | installing — routes you to 02 and 03 | 5K |
-| [`install/02-storefront.md`](./install/02-storefront.md) | building storefront pages | 33K |
+| [`install/02-storefront.md`](./install/02-storefront.md) | building storefront pages | 34K |
 | [`install/03-data.md`](./install/03-data.md) | seeding catalog, shipping rates/zones, payments; re-callable per slice | 11K |
 | [`docs/entities.md`](./docs/entities.md) | any direct entity read/write ("which entity holds X") | 11K |
 | [`references/catalog-rendering.md`](./references/catalog-rendering.md) | field shapes each catalog call returns, variant edge cases | 16K |
 | [`references/shipping-and-tax.md`](./references/shipping-and-tax.md) | zones beyond 03's recipe, taxes, day-2 edits | 8K |
 | [`references/online-payments.md`](./references/online-payments.md) | enabling card payments, or wiring the provider — at install or any time later | 8K |
-| [`references/storefront-parts.md`](./references/storefront-parts.md) | the parts' copy map, CSS selectors and control overrides | 10K |
-| [`references/storefront-custom.md`](./references/storefront-custom.md) | a custom cart row / checkout section on the raw hooks | 8K |
 | [`references/storefront-verification.md`](./references/storefront-verification.md) | driving the storefront from a browser script | 3K |
 | [`references/reviews.md`](./references/reviews.md) | review policies (login-gated, verified buyers), moderation | 5K |
 | [`references/store-settings.md`](./references/store-settings.md) | changing store behavior through settings keys | 5K |
@@ -127,13 +131,16 @@ Open a file when its work starts — not while planning.
 | [`docs/api-storefront.md`](./docs/api-storefront.md) | filters, customer accounts, refunds, a non-React client | 31K |
 | [`docs/api-admin.md`](./docs/api-admin.md) | changing admin pages, automating admin functions, the full seed contract | 24K |
 
-**The read budget.** Content pulled into context is re-billed on every later
-call — open one reference when its task starts, and when a stage's checklist
-passes, record its carry-forward lines and treat the file as gone.
-
-**The install stages are self-contained.** Every shape they build against is
-written out in them — hook results, part contracts, the copy file. Never open
-a file under `src/commerce/` while building; that is the most expensive way to
-answer a question the stage already answers. (The source stays the final
-authority if a doc and the code disagree — report that rather than working
-around it.)
+**The read budget.** Content you pull into context is re-read on every later
+call, so a file opened while planning costs many times what it costs opened at
+the moment it is used. Open one reference when its task starts, take what you
+need, and when a stage's checklist passes, record its carry-forward lines and
+treat the file as gone.
+
+**The install stages are self-contained.** Every request and response shape they
+build against is written out in them — `install/02-storefront.md` carries a table
+of exactly what each storefront hook resolves to. You should not need to open a
+file under `src/commerce/` while building, and doing it mid-build is the most
+expensive way to answer a question the stage already answers. (The source is
+still the final authority if a doc and the code ever disagree — report that
+rather than working around it.)

package/skills/commerce/install/01-install.md

@@ -48,7 +48,7 @@ import { Navigate } from "react-router-dom";
 - **The `/*` splat is required** — without it every nested admin link 404s. Mounting elsewhere: `<AdminApp basePath="/backoffice" />` (prefix without the splat).
 - **Give `/` something** — a blank app has no `/` route, and "page not found" at the app's own URL reads like a broken install.
 - **Link the admin from the storefront header** — otherwise the merchant has no way in but typing the URL. Resolve the signed-in user once (`base44.auth.me()`, rejection/no session = not an admin, never blocking the page) and render a plainly visible "Store manager" link to `/store-admin` in the header when `role === "admin"` — and nothing at all for everyone else.
-- **`/order-received` is mandatory**, even offline-only: every payment link returns there, and confirming is what marks an order paid — without it a paying customer hits a 404 and the order stays unpaid. The page is the `OrderReceived.*` parts ([`./02-storefront.md`](./02-storefront.md)). A different path goes in Settings → General (`general.order_received_path`) *and* `Checkout.Root`'s `orderReceivedPath` — they must agree.
+- **`/order-received` is mandatory**, even offline-only: every payment link returns there, and confirming is what marks an order paid — without it a paying customer hits a 404 and the order stays unpaid. The page is one hook, `useOrderReturn()` ([`./02-storefront.md`](./02-storefront.md)). A different path must be set in Settings → General (`general.order_received_path`).
 
 ## Admin-role enforcement — do not weaken