@base44/app-plugin-commerce 0.1.19 → 0.2.1

package/src/commerce/utils/index.js

@@ -13,17 +13,29 @@
  *   checkout/return-page calls. Create ONE instance and import it everywhere.
  * - `variants.js` — variant selection: map attribute selections (Size, Color)
  *   to a `ProductVariation` and back, per-option availability, variant price
- *   ranges. See `.agents/skills/commerce/references/storefront-product-page.md`.
+ *   ranges. See `.agents/skills/commerce/references/catalog-rendering.md`.
  * - `shipping-promos.js` — read the store's real free-shipping configuration so
  *   "Free shipping over €150" copy states a configured rule, not an invented
  *   number. See `.agents/skills/commerce/docs/api-storefront.md`.
+ * - `price.js` — `productPrice`: the from-price and price-range rules, encoded
+ *   once so a card and a product page cannot disagree.
+ * - `totals.js` — `cartTotalsLines` / `orderTotalsLines` / `orderLines` /
+ *   `attributesLabel`: one summary shape for the cart, the checkout and the
+ *   confirmation (a cart's totals are nested, an order's are flat).
+ * - `address-spec.js` — `addressFieldSpec`: the checkout address form as data,
+ *   with country/state options that are always arrays.
+ * - `images.js` — `productImages`: images normalized to `{src, name, alt}`.
  *
- * Building the storefront in React? `@/commerce/storefront` layers hooks on
- * top of this module — a shared-cart provider, the guided-checkout hook
- * (automatic shipping/tax recalculation on address changes), headless
- * shipping/payment pickers and the order-received hook. Prefer those for cart
- * and checkout; use this module directly for catalog views and non-React code.
+ * Building the storefront in React? **Prefer `@/commerce/storefront`** — it
+ * layers hooks and ready-made UI blocks on top of this module, and a hook that
+ * pre-composes these helpers is the difference between a rule that holds and a
+ * rule you have to remember. Use this module directly for non-React code, and
+ * inside your own custom logic.
  */
 export * from "./storefront.js";
 export * from "./variants.js";
 export * from "./shipping-promos.js";
+export * from "./price.js";
+export * from "./totals.js";
+export * from "./address-spec.js";
+export * from "./images.js";

package/src/commerce/utils/price.js

@@ -0,0 +1,95 @@
+/**
+ * Price presentation — the one place the store's pricing *rules* turn into
+ * strings. Framework-free; `useProductPrice` binds it to the store currency.
+ *
+ * Two rules live here, and both are easy to get wrong in one view while
+ * getting them right in another:
+ *
+ * - **A variant parent's `price` is a *from* price** (rolled up from the
+ *   cheapest publishable variant), so a card must render "From €19.99" — not
+ *   "€19.99". Pass a `list-products` row and you get the "From" prefix for
+ *   free; the alternative is remembering `product.attributes?.length` at every
+ *   call site.
+ * - **An incomplete variant selection has a range, not a price.** Pass a
+ *   `resolveSelection` view and an unresolved selection renders
+ *   "€19.99 – €23.99" instead of silently showing the parent's from-price as
+ *   if the customer had chosen it.
+ *
+ * Same call for both, so neither view can drift from the other:
+ *
+ *   productPrice(row,  { formatMoney })   // a card in a grid
+ *   productPrice(view, { formatMoney })   // the product page, any selection
+ */
+
+/** Is this a `resolveSelection` result rather than a raw product row? */
+function isView(input) {
+  return Boolean(input) && typeof input === "object" && "display" in input && "isVariable" in input;
+}
+
+const money = (fn, n) => (typeof fn === "function" ? fn(n) : String(n ?? ""));
+
+/**
+ * The rendered price of a product row **or** a resolved selection view.
+ *
+ * @param {object} rowOrView a `list-products`/`get-product` product, or a
+ *   `resolveSelection` view
+ * @param {{formatMoney?: (n: number) => string}} [opts]
+ * @returns {{label: string, compareAtLabel: string|null, onSale: boolean,
+ *   isFrom: boolean, isRange: boolean, min: number|null, max: number|null}}
+ *   `label` is what to render as the price; `compareAtLabel` is the
+ *   struck-through original, or null when the product is not on sale.
+ */
+export function productPrice(rowOrView, { formatMoney } = {}) {
+  const fmt = (n) => money(formatMoney, n);
+  const blank = {
+    label: "", compareAtLabel: null, onSale: false, isFrom: false,
+    isRange: false, min: null, max: null,
+  };
+  if (!rowOrView) return blank;
+
+  if (isView(rowOrView)) {
+    const { display, priceRange, complete, isVariable } = rowOrView;
+    // An unresolved variant selection genuinely has a range of prices. Showing
+    // the parent's from-price here reads as "this is the price" — the single
+    // most common variant-pricing bug.
+    if (isVariable && !complete && priceRange && priceRange.min !== priceRange.max) {
+      return {
+        label: `${fmt(priceRange.min)} – ${fmt(priceRange.max)}`,
+        compareAtLabel: null,
+        onSale: Boolean(priceRange.on_sale),
+        isFrom: false,
+        isRange: true,
+        min: priceRange.min,
+        max: priceRange.max,
+      };
+    }
+    const price = display?.price ?? priceRange?.min ?? null;
+    const onSale = Boolean(display?.on_sale);
+    return {
+      label: price == null ? "" : fmt(price),
+      compareAtLabel: onSale && display?.regular_price != null ? fmt(display.regular_price) : null,
+      onSale,
+      isFrom: false,
+      isRange: false,
+      min: price,
+      max: price,
+    };
+  }
+
+  // A raw product row. `attributes` non-empty is the ONLY signal that a
+  // product sells variants (there is no product-type field), and it is what
+  // makes `price` a from-price.
+  const row = rowOrView;
+  const isFrom = Array.isArray(row.attributes) && row.attributes.length > 0;
+  const price = row.price ?? null;
+  const onSale = Boolean(row.on_sale);
+  return {
+    label: price == null ? "" : isFrom ? `From ${fmt(price)}` : fmt(price),
+    compareAtLabel: onSale && row.regular_price != null ? fmt(row.regular_price) : null,
+    onSale,
+    isFrom,
+    isRange: false,
+    min: price,
+    max: price,
+  };
+}

package/src/commerce/utils/storefront.js

@@ -72,10 +72,14 @@ export function createStorefront(base44, { storageKey = "cart_token", storage }
     listProducts(params = {}) {
       return inv("commerce/storefront-catalog", { action: "list-products", ...params });
     },
-    /** getProduct("slug") or getProduct({ id }) */
-    getProduct(ref) {
+    /**
+     * getProduct("slug") or getProduct({ id }). Optional `params` pass through
+     * to the action — `{ reviews_page, reviews_per_page }` page the reviews
+     * block that rides along with the product.
+     */
+    getProduct(ref, params = {}) {
       const by = typeof ref === "string" ? { slug: ref } : ref;
-      return inv("commerce/storefront-catalog", { action: "get-product", ...by });
+      return inv("commerce/storefront-catalog", { action: "get-product", ...by, ...params });
     },
     /** ARRAY of root categories, subcategories nested under `children`. */
     listCategories() {
@@ -86,6 +90,46 @@ export function createStorefront(base44, { storageKey = "cart_token", storage }
       return inv("commerce/storefront-catalog", { action: "list-ribbons" }).then((d) => d.ribbons);
     },
 
+    // ── reviews (public: anyone can review with an email) ─────────────────
+    /**
+     * One page of a product's approved reviews plus its aggregates. Reviews
+     * ride along on `get-product`, so this is that call with the review
+     * paging params — use it to page the list without re-rendering the page.
+     *
+     * @returns {Promise<{items: object[], page: number, per_page: number,
+     *   has_next: boolean, average_rating: number, rating_count: number}>}
+     */
+    getProductReviews(ref, { page = 1, per_page = 10 } = {}) {
+      const by = typeof ref === "string" ? { slug: ref } : ref;
+      return inv("commerce/storefront-catalog", {
+        action: "get-product",
+        ...by,
+        reviews_page: page,
+        reviews_per_page: per_page,
+      }).then((d) => d.reviews);
+    },
+    /**
+     * Submit a review. `email` is required for a guest and ignored for a
+     * signed-in caller (the session's email always wins, so nobody can
+     * review as someone else). `rating` is optional, 0–5.
+     *
+     * Resolves to `{ review_id, status, verified }` — **`status` is
+     * `"approved"` or `"hold"` depending on the store's `auto_approve_reviews`
+     * setting, so derive the confirmation copy from it** instead of assuming
+     * moderation. Rejects with `email_required` | `review_incomplete` |
+     * `invalid_rating` | `not_found`.
+     */
+    submitReview({ product_id, review, rating, reviewer, email } = {}) {
+      return inv("commerce/storefront-catalog", {
+        action: "submit-review",
+        product_id,
+        review,
+        ...(rating == null ? {} : { rating }),
+        ...(reviewer ? { reviewer } : {}),
+        ...(email ? { email } : {}),
+      });
+    },
+
     // ── cart (token handled internally; every call returns the full view) ─
     /** The current cart view, or null when there is none (an expired token self-clears). */
     async getCart() {

package/src/commerce/utils/totals.js

@@ -0,0 +1,110 @@
+/**
+ * Totals and line projections — one shape rendered by the cart page, the
+ * checkout summary AND the order-received page, so the three can't disagree.
+ *
+ * Why this exists: hand-written totals blocks reliably omit the lines that are
+ * usually zero. A summary that renders subtotal → shipping → total looks
+ * correct until the store issues a coupon or charges tax, at which point it
+ * silently stops adding up. Here `discount` and `tax` are always *produced*
+ * and merely flagged `hidden` when zero — a renderer that maps over the array
+ * cannot drop them, and one that wants to show a zero discount can.
+ *
+ * The other trap this absorbs: **a cart's totals are nested
+ * (`cart.totals.total`) and an order's are flat (`order.total`)** — there is no
+ * `order.totals`. `cartTotalsLines` and `orderTotalsLines` return the same
+ * shape from both, so one component renders either.
+ */
+
+const num = (v) => (Number.isFinite(Number(v)) ? Number(v) : 0);
+const money = (fn, n) => (typeof fn === "function" ? fn(n) : String(n ?? ""));
+
+/**
+ * `[{ name, option }]` → `"Size: 42 · Color: Ivory"`. Cart lines and order
+ * lines both carry `attributes` as an **array of objects**, never a map — this
+ * is the label every cart, summary and confirmation needs, derived once.
+ *
+ * @param {Array<{name?: string, option?: string}>} attributes
+ * @param {{separator?: string}} [opts]
+ * @returns {string} empty for a product with no attributes
+ */
+export function attributesLabel(attributes, { separator = " · " } = {}) {
+  if (!Array.isArray(attributes)) return "";
+  return attributes
+    .map((a) => (a?.name ? `${a.name}: ${a.option ?? ""}` : String(a?.option ?? "")))
+    .filter(Boolean)
+    .join(separator);
+}
+
+function line(key, label, amount, { formatMoney, emphasis = false, hideWhenZero = false }) {
+  const value = num(amount);
+  return {
+    key,
+    label,
+    amount: value,
+    formatted: money(formatMoney, value),
+    emphasis,
+    hidden: hideWhenZero && value === 0,
+  };
+}
+
+/**
+ * The priced cart's summary lines.
+ *
+ * @param {object} cart the cart view (`cart.totals` is where the numbers live)
+ * @param {{formatMoney?: (n: number) => string, labels?: object}} [opts]
+ * @returns {Array<{key: string, label: string, amount: number,
+ *   formatted: string, emphasis: boolean, hidden: boolean}>}
+ *   keys, in order: `subtotal` `discount` `shipping` `tax` `total`
+ */
+export function cartTotalsLines(cart, { formatMoney, labels = {} } = {}) {
+  const t = cart?.totals ?? {};
+  const opt = { formatMoney };
+  return [
+    line("subtotal", labels.subtotal ?? "Subtotal", t.subtotal, opt),
+    line("discount", labels.discount ?? "Discount", -Math.abs(num(t.discount_total)), { ...opt, hideWhenZero: true }),
+    line("shipping", labels.shipping ?? "Shipping", t.shipping_total, opt),
+    line("tax", labels.tax ?? "Tax", t.total_tax, { ...opt, hideWhenZero: true }),
+    line("total", labels.total ?? "Total", t.total, { ...opt, emphasis: true }),
+  ];
+}
+
+/**
+ * The same lines for a placed order. **An order carries flat totals** —
+ * `order.total`, `order.shipping_total`, `order.total_tax`, `order.subtotal`,
+ * `order.discount_total` — with no `totals` object to dot into.
+ *
+ * @param {object} order
+ * @param {{formatMoney?: (n: number) => string, labels?: object}} [opts]
+ * @returns {Array<object>} same shape as `cartTotalsLines`
+ */
+export function orderTotalsLines(order, { formatMoney, labels = {} } = {}) {
+  const o = order ?? {};
+  const opt = { formatMoney };
+  return [
+    line("subtotal", labels.subtotal ?? "Subtotal", o.subtotal, opt),
+    line("discount", labels.discount ?? "Discount", -Math.abs(num(o.discount_total)), { ...opt, hideWhenZero: true }),
+    line("shipping", labels.shipping ?? "Shipping", o.shipping_total, opt),
+    line("tax", labels.tax ?? "Tax", o.total_tax, { ...opt, hideWhenZero: true }),
+    line("total", labels.total ?? "Total", o.total, { ...opt, emphasis: true }),
+  ];
+}
+
+/**
+ * An order's line items in the same shape as decorated cart lines, so one
+ * component renders the bag, the checkout summary and the confirmation.
+ *
+ * @param {object} order
+ * @returns {Array<{name: string, attributesLabel: string, quantity: number,
+ *   total: number, image: object|null, sku: string}>}
+ */
+export function orderLines(order) {
+  return (order?.line_items ?? []).map((it) => ({
+    ...it,
+    name: it.name ?? "",
+    attributesLabel: attributesLabel(it.attributes ?? it.meta_data),
+    quantity: num(it.quantity),
+    total: num(it.total ?? it.subtotal),
+    image: it.image ?? null,
+    sku: it.sku ?? "",
+  }));
+}

package/src/commerce/utils/variants.js

@@ -12,7 +12,7 @@
  * Framework-free, dependency-free, no I/O — feed them the `{ product,
  * variations }` pair from `commerce/storefront-catalog` `get-product` (the
  * admin's variation editor can use them too). See
- * `.agents/skills/commerce/references/storefront-product-page.md` for the UI rules.
+ * `.agents/skills/commerce/references/catalog-rendering.md` for the UI rules.
  *
  * A `selection` throughout is a plain object keyed by axis key (see
  * `attributeKey`): `{ "<color-attr-id>": "Red", "<size-attr-id>": "M" }`.
@@ -271,10 +271,18 @@ export function priceRange(product, variations, selection = {}) {
  * `{src, name, alt}` with a non-empty `src`, or `null` when there is nothing
  * renderable. Run gallery entries through it too: `product.images.map(normalizeImage)`.
  *
- * @param {object|null|undefined} img a stored image entry (`product.images[n]` or `variation.image`)
+ * A bare URL string is accepted too — `seed-store` takes `images: ["https://…"]`,
+ * so both shapes turn up in code that moves catalog data around.
+ *
+ * @param {object|string|null|undefined} img a stored image entry
+ *   (`product.images[n]` or `variation.image`), or a URL string
  * @returns {{src: string, name: string, alt: string}|null}
  */
 export function normalizeImage(img) {
+  if (typeof img === "string") {
+    const src = img.trim();
+    return src ? { src, name: "", alt: "" } : null;
+  }
   const src = typeof img?.src === "string" ? img.src.trim() : "";
   if (!src) return null;
   const name = img.name ?? "";

package/skills/commerce/installation-guidelines.md

@@ -1,93 +0,0 @@
-# Installation Guidelines
-
-How to install the Base44 Commerce Template into an existing Base44 app. This file lives inside the **commerce skill** folder and is installed into the app at `.agents/skills/commerce/installation-guidelines.md`. Once the files are in place, continue with [`post-installation.md`](./post-installation.md) (embedding the admin pages, seeding the store's data, the storefront quick start); day-2 guidance lives in [`.agents/skills/commerce/SKILL.md`](./SKILL.md), alongside the API references in [`.agents/skills/commerce/docs/`](./docs/).
-
-> **If you are a Base44 agent working inside the runtime, read this first:**
-> - **Skip the `npx base44` commands.** The runtime deploys functions and pushes entities automatically the moment you write the files — writing a resource file *is* the deploy.
-> - **Don't grant admin roles.** Granting a user the `admin` role is not an install step for you; instead, validate that the admin-role gating (see [`post-installation.md`](./post-installation.md)) is preserved when you merge the admin routes into the app's router.
-> - **Don't read the whole codebase up front.** Copy the files, wire the router, and open only what your current task touches.
-
----
-
-## 1. Static installation (copying the files)
-
-**Scripted.** Copy this entire repository into the target app at `examples/commerce/`, then run from the app root:
-
-```bash
-node examples/commerce/scripts/install.js
-```
-
-Relative to the script's own folder (`examples/commerce/scripts/`), it copies:
-
-| From (template) | To (app) |
-|---|---|
-| `../base44/entities/commerce.*.jsonc` | `../../../base44/entities/` |
-| `../base44/functions/commerce/` | `../../../base44/functions/commerce/` |
-| `../base44/shared/commerce/` | `../../../base44/shared/commerce/` |
-| `../base44/agents/commerce/` | `../../../base44/agents/commerce/` |
-| `../src/commerce/admin/` | `../../../src/commerce/admin/` |
-| `../src/commerce/utils/` | `../../../src/commerce/utils/` |
-| `../src/commerce/storefront/` | `../../../src/commerce/storefront/` |
-| `../skills/commerce/` | `../../../.agents/skills/commerce/` |
-
-Directories are merged: files owned by the template are overwritten (re-running after a template update is safe); everything else in your app is left untouched. Files the template has since **renamed or retired** are deleted on install (it reports each one) — otherwise stale guidance would sit in `.agents/skills/` forever, and agents read whatever is there. The skill folder carries all the documentation — `SKILL.md`, this file, `post-installation.md`, the topic references in `references/` and the API docs in `docs/` — so the installed app gets it at `.agents/skills/commerce/` where agents pick it up natively; the template repo itself also stays under `examples/commerce/` for reference.
-
-**Manual.** Equivalently, copy by hand:
-
-1. Copy `base44/entities/commerce.*`, `base44/functions/commerce/*`, `base44/shared/commerce/*` and `base44/agents/commerce/*` into your app's `base44/` dir (merge, don't overwrite unrelated files). `shared/` is bundled into every function at deploy time.
-2. Copy `src/commerce/admin/` → `src/commerce/admin/`, `src/commerce/utils/` → `src/commerce/utils/` (framework-free storefront helpers — API client, variant selection; no deps) and `src/commerce/storefront/` → `src/commerce/storefront/` (the storefront React layer — shared-cart provider, guided-checkout hook, headless pickers; needs React only).
-3. Copy `skills/commerce/` → `.agents/skills/commerce/` (the commerce skill — `SKILL.md`, this file, `post-installation.md`, the `references/` topic guides and the `docs/` API references — for agents working on the app).
-
-Confirm your `base44/config.jsonc` `entitiesDir`/`functionsDir` point at these folders (the defaults do).
-
-## 2. Deploy and wire up
-
-1. `npx base44 entities push` — creates/updates the 20 entity schemas. *(CLI path only — the Base44 runtime deploys on write.)*
-2. `npx base44 functions deploy` — deploys the 16 functions. *(CLI path only.)*
-3. `npx base44 agents push` — registers the `commerce/StoreAdmin` agent (§3). *(CLI path only.)*
-4. Check the app's `package.json` for `sonner`, `recharts` and `react-markdown`, and run `npm i` **only** for the ones actually absent — all three ship with the default Base44 template, so the normal outcome is no install at all. Do not re-install a package that is already a dependency. Nothing else is needed. Verify the shadcn primitives listed in [`src/commerce/admin/README.md`](../../src/commerce/admin/README.md) exist in your app.
-5. Mount the admin router (see [`post-installation.md`](./post-installation.md)).
-6. Grant your user the `admin` role.
-7. Seed the store's data — one `commerce/seed-store` call creates the business defaults and, via its `products` payload, the whole catalog (or `with_sample_data: true` for the generic demo; or neither for defaults only). The defaults include payment methods: the manual **`offline`** option enabled and **`card` switched off**. Cards are optional and not part of installing — enable them only with a payment provider wired, or about to be, or checkout answers `503 no_card_payment_provider` ([`post-installation.md`](./post-installation.md) §4.1). Skipping the call entirely leaves the operator the **Initialize store defaults** first-run screen. See [`post-installation.md`](./post-installation.md) §3; any seed call marks the business as ready and the first-run screen never appears.
-
-Check the install at any time:
-
-```js
-const { data } = (await base44.functions.invoke("commerce/admin-tools", { action: "status" })).data;
-// → { template_version, seeded, settings_groups, counts: { "commerce.Product": n, ... },
-//     checks: { has_payment_gateways, has_default_location } }
-```
-
-`commerce/seed-store` is **idempotent** and starts with a **canary schema check**: it probe-writes one record per entity it will touch and deletes it. If you've modified an entity schema incompatibly, it aborts with HTTP 422 `schema_incompatible` and writes nothing:
-
-```json
-{ "success": false, "code": "schema_incompatible",
-  "errors": [{ "entity": "commerce.Product", "error": "..." }] }
-```
-
-The admin setup screen surfaces these errors verbatim. Sample catalog data is only created when `with_sample_data: true` **and** the store has zero products; a caller-supplied `products` catalog runs regardless, skipping (not duplicating) products whose SKU or slug already exists — see [`docs/api-admin.md`](./docs/api-admin.md#commerceseed-store).
-
----
-
-## 3. The StoreAdmin agent (admin copilot)
-
-The template ships an AI copilot for store operators:
-
-- **Agent definition** — [`base44/agents/commerce/StoreAdmin.jsonc`](../../base44/agents/commerce/StoreAdmin.jsonc), registered as **`commerce/StoreAdmin`** (the folder namespaces the agent, exactly like functions). The hosted runtime registers it when the file lands; on the CLI path run `npx base44 agents push`.
-- **Tools** — the `commerce/*` backend functions attached directly (`commerce/admin-products`, `commerce/admin-orders`, …, `commerce/seed-store`, plus read-only `commerce/storefront-catalog` for enumerating product variations). Tool calls run **with the chatting user's credentials**, so `requireAdmin()` in every admin function still authorizes the actual user — the agent has no entity tools and no service-role shortcut; a non-admin chatting with it gets `401/403` from every admin operation.
-- **No `model` field, on purpose.** The platform's default-model path accepts slash-namespaced tool names; explicitly setting a `model` currently rejects them (LLM tool names must match `^[a-zA-Z0-9_-]{1,128}$`). If you set a model, the bot fails at message time with a `tools.0.custom.name` error.
-- **Variant safety** — the agent is instructed to never auto-pick a variation: for a product carrying attributes it fetches `{product, variations}` via `commerce/storefront-catalog get-product`, presents the variants as a table, and asks the operator which `variation_id` to use before touching an order, stock, or download grant.
-- **Bot UI** — `src/commerce/admin/bot/` (chat panel; "StoreAdmin bot" launcher at the bottom of the admin sidebar). Responses render as markdown via `react-markdown`, with the agent's GFM tables (`| col |` with `|---|` separators) rendered by the template's own `bot/pipe-tables.js` — no markdown plugin dependency. The panel lives behind the same `AuthGuard` as the rest of the admin.
-- **Config it can't change, it links to.** Store settings, Shipping & Tax Locations, gateways and webhook definitions have no function tool, so the agent is instructed to name the screen and emit an `admin:`-scheme link (`[Settings → Shipping & Tax](admin:settings/shipping-tax)`) rather than telling the operator to "do it manually". `bot/Markdown.jsx` resolves `admin:` through `useAdminHref()`, so links follow your actual mount point (`basePath`) and navigate in-app instead of opening a tab. If you add screens, add the path to the table in the agent's instructions.
-
-**Do not weaken the tool set.** The agent's power comes only from the admin functions' own `requireAdmin()` layer — don't add entity tools or service-role calls to the agent config, and keep `commerce/storefront-*` tools limited to the read-only catalog.
-
----
-
-## 4. Building on it — the four storefront requirements
-
-If your work includes a customer-facing shopfront, the quick start in [`post-installation.md` §2](./post-installation.md#2-storefront-quick-start--logic-only) already walks all four requirements — you don't need any other reading. In short: attribute-level variant selectors resolved to a `variation_id`; shipping options presented and chosen; the payment methods the store actually enables rendered from `get-store-info` (a default store offers `offline` only — cards are off unless enabled with a provider wired, [`post-installation.md`](./post-installation.md) §4.1) with the card redirect handled if they're on, plus an `/order-received` page; and no offers the store isn't configured for. In a React app the shipped `@/commerce/storefront` hooks implement the shipping and order-received requirements outright — build on them rather than re-deriving the flow. The API enforces the first three — a storefront that skips them cannot complete a purchase. (Day-2 deep dives: [`SKILL.md` → *these four are not optional*](./SKILL.md) and [`docs/api-storefront.md`](./docs/api-storefront.md)'s *Required behaviors* table.)
-
-## 5. Next steps
-
-Continue with [`post-installation.md`](./post-installation.md): embedding the admin pages (router mount, admin-role enforcement), seeding the store's data, and the logic-only storefront quick start. After that, [`.agents/skills/commerce/SKILL.md`](./SKILL.md) is the map for all day-2 work.