@base44/app-plugin-commerce 0.3.4 → 0.4.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/`) — **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), 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.
+- **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.*`, `CartDrawer.*`, `Checkout.*`, `OrderReceived.*` compound components that render each section of the cart, drawer, checkout and receipt as correct semantic markup with **zero CSS, 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. Parts compose the hooks, so replacing one section with a hook-built custom region is a normal move — and the parts are copied source, editable when a requirement outgrows their props. 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 — 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 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 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/base44/functions/commerce/storefront-cart/cart-pricing.ts

@@ -211,6 +211,7 @@ export async function priceCart(sr: any, cart: any, opts: { pricingData?: Pricin
       quantity: r.item.quantity,
       attributes: r.item.attributes ?? [],
       name: r.product.name ?? "",
+      slug: r.product.slug ?? "",
       sku: priced.sku ?? "",
       image: r.variation?.image?.src || r.product.images?.[0]?.src || "",
       price: priced.price ?? Number(src?.price ?? 0),

package/base44/functions/commerce/storefront-checkout/cart-pricing.ts

@@ -211,6 +211,7 @@ export async function priceCart(sr: any, cart: any, opts: { pricingData?: Pricin
       quantity: r.item.quantity,
       attributes: r.item.attributes ?? [],
       name: r.product.name ?? "",
+      slug: r.product.slug ?? "",
       sku: priced.sku ?? "",
       image: r.variation?.image?.src || r.product.images?.[0]?.src || "",
       price: priced.price ?? Number(src?.price ?? 0),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44/app-plugin-commerce",
-  "version": "0.3.4",
+  "version": "0.4.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,12 +1,11 @@
 ---
 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 hooks 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 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.
 ---
 
 # 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,
@@ -16,16 +15,14 @@ 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 —
-docs, checklists, code comments. Resolve them from the skill folder, never from
-the file that mentioned them.
+(`.agents/skills/commerce/` in an installed app) wherever they are named;
+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 the catalog — in that order, at those
-moments. Read nothing else up front.
+`install/03-data.md` when you seed. Read nothing else up front.
 
 ## Four things to hold from the start
 
@@ -46,49 +43,49 @@ moments. Read nothing else up front.
   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: logic is premade, UI never is
+## The storefront: two tiers
 
-**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;
+**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 —
 [`install/02-storefront.md`](./install/02-storefront.md) opens with the
-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.
-
-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.
+method. **Never re-implement what a hook does** — that is where storefront
+bugs cluster.
+
+**The commodity surfaces — cart, cart drawer, checkout, order-received — are
+placed, not written**: `Cart.*` / `CartDrawer.*` / `Checkout.*` /
+`OrderReceived.*` parts render each section's correct markup with **zero CSS,
+zero copy and zero navigation**. Your layout arranges the sections, your
+`index.css` styles them (`[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.
 
 ```jsx
-import { useCart, CartLine } from "@/commerce/storefront";
-const { status, cart } = useCart();   // branch on status, map cart.items into YOUR rows
+import { Cart, CartDrawer, Checkout, OrderReceived, useProduct } from "@/commerce/storefront";
 ```
 
-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).
+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.
 
 Four rules the API enforces — a storefront that skips them cannot complete a
-purchase. In React the hooks implement all four; your markup renders what they
-hand back (API-level statements for non-React clients:
+purchase. In React the hooks and parts 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**
-   (`useCheckout` — automatic).
-3. **`/order-received` must exist** and render the return state, including a
-   manual order's payment instructions (`useOrderReturn`).
+   (the `Checkout.*` parts — automatic).
+3. **The order-received route must exist** and render the return state — all
+   five `OrderReceived.*` gates, `PaymentInstructions` placed on unpaid.
 4. **Never advertise what isn't configured** — no free-shipping banner without
-   a real rate, no coupon codes without a field to redeem them in.
+   a real rate, no coupon codes without a `CouponField` 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
@@ -115,6 +112,7 @@ Open a file when its work starts — not while planning.
 | [`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-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 |
@@ -126,16 +124,13 @@ 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 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.)
+**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.)

package/skills/commerce/docs/api-storefront.md

@@ -136,7 +136,7 @@ Token-scoped cart (guest + member). Every action **except `create`** takes `cart
   "items": [ {
     "item_key": "uuid", "product_id": "...", "variation_id": "", "quantity": 2,
     "attributes": [ { "name": "Color", "option": "Red" } ],
-    "name": "T-Shirt", "sku": "TS-RED-M", "image": "https://...",
+    "name": "T-Shirt", "slug": "t-shirt", "sku": "TS-RED-M", "image": "https://...",
     "price": 20, "subtotal": 40, "total": 36, "total_tax": 3.6,
     "virtual": false, "sold_individually": false,
     "purchasable": { "ok": true }

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

@@ -6,6 +6,7 @@ forget_when: "The checklist at the bottom of this file passes (admin mounts, / r
 carry_forward:
   - "Admin enforcement is three layers — AuthGuard (UI), admin-only entity RLS, requireAdmin() in every admin function. Never weaken any of them."
   - "/order-received must exist as a route: every payment link returns there, and confirming is what marks an order paid."
+  - "The storefront header shows a visible \"Store manager\" link to /store-admin when the signed-in user's role is admin, and nothing for everyone else."
   - "Interleave: start image generation first → mount admin + build the storefront while images render → seed when the URLs are back → payments last."
   - "Entities are dotted + bracket-syntax only (`base44.entities[\"commerce.X\"]`); the map is ../docs/entities.md — never scan base44/entities/."
 ---
@@ -46,7 +47,8 @@ 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.
-- **`/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`).
+- **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.
 
 ## Admin-role enforcement — do not weaken
 
@@ -62,6 +64,7 @@ Storefront functions are public on purpose (per-action verification, above). To
 
 - [ ] `/store-admin/*` mounted with the splat, behind the shipped `AuthGuard`; the three enforcement layers untouched.
 - [ ] `/` routes somewhere real; `/order-received` is a route.
+- [ ] The storefront header shows a visible `/store-admin` link to signed-in admins, and to nobody else.
 - [ ] Anonymous function invocation is allowed in the app's settings.
 - [ ] Missing dependencies (if any) installed; image generation already running.