@base44/app-plugin-commerce 0.1.8 → 0.1.12

package/skills/commerce/post-installation.md

@@ -1,6 +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, 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, wire payments, and build the storefront from the quick start below. 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.
 
 ---
 
@@ -46,6 +48,8 @@ Even if the client guard were bypassed, layers 2 and 3 keep the store data safe.
 
 A fresh install has **no settings and no catalog**. One call to `commerce/seed-store` (admin-only, idempotent) initializes both. It always creates the business defaults — the six settings groups (`general`, `products`, `inventory`, `tax`, `shipping`, `emails`; USD, kg/cm, taxes off prices) and the `offline` and `card` payment gateways — and, depending on the payload, the catalog. A fallback "Rest of the world" **Shipping & Tax Location** (one free shipping rate, no tax) is seeded **only when the payload carries no `locations`** — locations you pass are the store's only shipping data, with no seeded fallback beside them. Pass **`currency`** (an ISO code, e.g. `"EUR"`) and/or **`weight_unit`**/**`dimension_unit`** to set the store's currency and measurement units instead of the defaults — explicit values always win, on a first seed and a re-run alike. (Prices are *formatted* with `Intl.NumberFormat` per the viewer's locale — the currency is a value; there are no format settings.)
 
+Pass **`payment_methods`** (gateway slugs, e.g. `["card"]`) when the user restricts how they get paid: the listed gateways are enabled and **every other gateway row is disabled** — "card-only" or "offline-only" is part of the same seed call, with **no `commerce.PaymentGateway` reads or writes of your own**. Explicit values win on re-runs too. Unknown slugs fail as `400 invalid_payload` (the error lists the known ones). Should you ever need direct entity access, names are dotted — bracket syntax only: `base44.entities["commerce.PaymentGateway"]` (`commerce__PaymentGateway` / `PaymentGateway` don't exist).
+
 | Mode | Body | Products created |
 |---|---|---|
 | **Real catalog** | `{ store_name, products: [...] }` (+ optional `coupons`, `locations`) | Yours — categories, ribbons, attributes, variants and all, in this one call |
@@ -68,6 +72,7 @@ Reference everything by **display name** — categories, ribbons, attributes and
 await base44.functions.invoke("commerce/seed-store", {
   store_name: "Aurora Threads",
   currency: "EUR",                             // optional — defaults to USD
+  payment_methods: ["card"],                   // optional — enables ONLY these; omit to keep offline + card
   products: [
     { // simple product
       name: "Classic T-Shirt",
@@ -128,16 +133,142 @@ The response reports everything:
     ]
   },
   "store_name": { "value": "Aurora Threads", "action": "created" },
-  "currency": { "value": "EUR", "action": "created" } }   // "updated" | "unchanged" on re-runs; null when not passed
+  "currency": { "value": "EUR", "action": "created" },   // "updated" | "unchanged" on re-runs; null when not passed
+  "payment_methods": { "enabled": ["card"], "disabled": ["offline"] } }   // null when not passed
 ```
 
-**Images**: every product needs at least one, and the URL you seed is the URL the store serves — there are no placeholders to swap later. So resolve each image to its **final URL before seeding**: use whatever image generation the app has available and store the returned URL, upload real assets with `base44.integrations.Core.UploadFile({ file })` → public URL, or fall back to stable public stock URLs (`base44/functions/commerce/seed-store/sample-data.ts` shows a working Unsplash pattern). Match the image to the product. If an image isn't ready at seed time, seed without it and set it afterwards through the admin API — don't seed a dead path and compensate in the frontend.
+**Images**: every product needs at least one, and the URL you seed is the URL the store serves — there are no placeholders to swap later. So resolve each image to its **final URL before seeding**: use whatever image generation the app has available and store the returned URL, upload real assets with `base44.integrations.Core.UploadFile({ file })` → public URL, or fall back to stable public stock URLs (`base44/functions/commerce/seed-store/sample-data.ts` shows a working Unsplash pattern). Match the image to the product. Image generation is usually the **slowest step of the whole install** — kick all product images off first, do the rest (router mount, payment file, storefront pages) while they render, and seed once the URLs are back. If an image isn't ready at seed time, seed without it and set it afterwards through the admin API — don't seed a dead path and compensate in the frontend.
 
 A successful response means the data is in — the catalog and settings are live exactly as reported. Write any remaining store-specific settings into `commerce.StoreSettings` (direct CRUD, one record per `group_id` — weight/dimension units are the usual ones; patch `values`, don't replace groups you weren't asked about).
 
-### 2.2 Payments
+### 2.2 Payments — one file, any provider (Stripe as the reference)
+
+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.
+
+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).
+
+| Function | Backs |
+|---|---|
+| `createCardPayment` | checkout + payment links (creates the hosted payment page) |
+| `checkCardPaymentPaid` | confirmation — the return page, the webhook and the admin's "Check payment" all verify through it, against the provider's API |
+| `refundCardPayment` | admin refunds with `refund_payment: true` |
+| `parseWebhook` | webhook validation — names the order the event is about; `paid: true` only after signature verification, never from a raw body |
+
+**Stripe is the reference implementation** and ships ready to use — don't write the file yourself; overwrite `base44/shared/commerce/card-payment.ts` with this as-is, **as one whole-file write. Never `find_replace` into the stub**: a partial patch leaves the original stubs behind and breaks every commerce function's deploy with duplicate-export bundle errors (`Multiple exports with the same name "createCardPayment"` → rewrite the file whole). For another provider, implement the same four functions against its API instead (same shape: hosted page in, paid-check and refund by `reference`, event naming an order — rules in [`references/online-payments.md`](./references/online-payments.md)):
+
+```ts
+// base44/shared/commerce/card-payment.ts — Stripe implementation
+import Stripe from "npm:stripe@18";
+import { HttpError } from "./auth.ts";
+
+export interface CardPaymentPage {
+  url: string;        // where the customer goes to pay
+  reference: string;  // the provider's id for this payment, stored on the order
+}
+
+const stripe = () => {
+  const key = Deno.env.get("STRIPE_SECRET_KEY");
+  if (!key) {
+    throw new HttpError(503, "Card payments are not configured — the STRIPE_SECRET_KEY secret is missing.", "no_card_payment_provider");
+  }
+  return new Stripe(key);
+};
+
+// Stripe amounts are in minor units; these currencies have none.
+const ZERO_DECIMAL = new Set(["BIF","CLP","DJF","GNF","JPY","KMF","KRW","MGA","PYG","RWF","UGX","VND","VUV","XAF","XOF","XPF"]);
+const minorUnits = (amount: number, currency: string) =>
+  Math.round(Number(amount) * (ZERO_DECIMAL.has(String(currency).toUpperCase()) ? 1 : 100));
+
+export async function createCardPayment(
+  _sr: any,
+  order: any,
+  opts: { successUrl: string; cancelUrl: string; customerEmail?: string },
+): Promise<CardPaymentPage> {
+  // order_id + order_key in the metadata is how the premade payment-webhook
+  // names the order when Stripe's event arrives — keep it on both objects.
+  const metadata = { order_id: String(order.id), order_key: String(order.order_key) };
+  const session = await stripe().checkout.sessions.create({
+    mode: "payment",
+    line_items: [{
+      quantity: 1,
+      price_data: {
+        currency: String(order.currency || "USD").toLowerCase(),
+        product_data: { name: `Order #${order.order_number}` },
+        unit_amount: minorUnits(order.total, order.currency),
+      },
+    }],
+    customer_email: opts.customerEmail || undefined,
+    metadata,
+    payment_intent_data: { metadata },
+    success_url: opts.successUrl,
+    cancel_url: opts.cancelUrl,
+  });
+  if (!session.url) throw new HttpError(502, "Stripe did not return a payment page URL.", "payment_session_failed");
+  return { url: session.url, reference: session.id };
+}
+
+export async function checkCardPaymentPaid(_sr: any, order: any, reference: string): Promise<boolean> {
+  const session = await stripe().checkout.sessions.retrieve(reference);
+  // The payment must be for THIS order — stops a reference to some other
+  // (paid) session being replayed against a different order.
+  return session.payment_status === "paid" && session.metadata?.order_id === String(order.id);
+}
+
+export async function refundCardPayment(_sr: any, _order: any, opts: {
+  reference: string; amount: number; currency: string; reason?: string;
+}): Promise<{ refund_id: string }> {
+  const session = await stripe().checkout.sessions.retrieve(opts.reference);
+  if (!session.payment_intent) {
+    throw new HttpError(409, "This payment has no charge to refund at Stripe.", "no_charge_to_refund");
+  }
+  const refund = await stripe().refunds.create({
+    payment_intent: String(session.payment_intent),
+    amount: minorUnits(opts.amount, opts.currency),
+  });
+  return { refund_id: refund.id };
+}
+
+/** What parseWebhook distills an event into — the premade webhook's contract. */
+export interface CardWebhookEvent {
+  order_id: string;
+  order_key: string;
+  paid: boolean;       // true only after signature verification — never from a raw body
+  reference?: string;  // only if signature-verified; otherwise the order's stored reference is used
+}
+
+/**
+ * Stripe webhook events. The event body is never trusted: this only names
+ * the order (from the metadata createCardPayment attached) and returns
+ * paid: false, so the premade webhook verifies against Stripe's API through
+ * checkCardPaymentPaid — a forged call can never mark an order paid, and no
+ * signing secret is needed. (Optional fast path that skips the API
+ * round-trip: verify the signature instead — references/online-payments.md.)
+ */
+export async function parseWebhook(_req: Request, payload: string): Promise<CardWebhookEvent | null> {
+  let event: any;
+  try { event = JSON.parse(payload); } catch { return null; }
+  const metadata = event?.data?.object?.metadata;
+  if (!metadata?.order_id || !metadata?.order_key) return null;
+  return { order_id: String(metadata.order_id), order_key: String(metadata.order_key), paid: false };
+}
+```
+
+Then two steps and payments are done (every provider follows this same shape — an API-credential secret, plus registering the premade webhook URL; only the Stripe specifics below vary):
 
-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. The **Credit card** option needs a payment provider, which means implementing exactly two files (`shared/commerce/card-payment.ts` + the payment webhook); until then it answers `503 no_card_payment_provider` at checkout, or can simply be switched off. Details: [`references/online-payments.md`](./references/online-payments.md).
+1. **Secret**: ask the user for their Stripe **secret key** and store it as the `STRIPE_SECRET_KEY` app secret (backend env — never in code, never in an entity). Test keys (`sk_test_…`) work end to end.
+2. **Webhook endpoint** — so orders are confirmed even when the buyer pays and closes the tab: register `https://<app-domain>/functions/commerce/payment-webhook` with Stripe for the `checkout.session.completed` event. There is **no signing secret to store** — events are treated as nudges and verified against Stripe's API. Registration is one call with the same secret key (or the user can do it in the Stripe dashboard):
+
+   ```js
+   await fetch("https://api.stripe.com/v1/webhook_endpoints", {
+     method: "POST",
+     headers: { Authorization: `Bearer ${Deno.env.get("STRIPE_SECRET_KEY")}`, "Content-Type": "application/x-www-form-urlencoded" },
+     body: new URLSearchParams({ url: "https://<app-domain>/functions/commerce/payment-webhook", "enabled_events[]": "checkout.session.completed" }),
+   });
+   ```
+
+That's it — checkout redirect, `/order-received` confirmation, the webhook, the admin's "Check payment" button, payment links and provider refunds all run through this one file. **Nothing else to read or edit**: [`references/online-payments.md`](./references/online-payments.md) is only for *other* providers or signature-verified webhooks.
 
 ---
 
@@ -145,31 +276,36 @@ The order side of payments is **already implemented** (checkout routing, confirm
 
 No visitor UI ships; the storefront **API** is complete. The four chunks below are the whole happy path — product list → product page → cart → checkout — showing what to call, what comes back, and what to carry into the next step. Open [`docs/api-storefront.md`](./docs/api-storefront.md) only for what's beyond them (attribute/price filters, reviews, customer accounts, refunds), and [`references/product-render.md`](./references/product-render.md) for which fields belong in which view.
 
-Every function returns the envelope `{ success, data }`; with the SDK the payload is `res.data.data`, so define one helper and use it everywhere:
+Build on the **shipped API client** — create it once and import that instance everywhere (wrapping it in a React context is fine; never a second copy):
 
 ```js
-const inv = (fn, payload) => base44.functions.invoke(fn, payload).then((r) => r.data.data);
+// src/lib/storefront.js
+import { createStorefront } from "@/commerce/utils";
+import { base44 } from "@/api/base44Client";
+export const store = createStorefront(base44);
 ```
 
-The cart is identified by a **`cart_token`** the backend mints — persist it in `localStorage` and send it with every cart/checkout call. Rolling 48 h expiry, refreshed on every touch.
+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`).
+
+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
 
 ```js
-const info = await inv("commerce/storefront-catalog", { action: "get-store-info" });
+const info = await store.getStoreInfo();   // cached — call it wherever needed
 // info.settings → { store_name, currency, weight_unit, … } — format money with
 // Intl.NumberFormat(undefined, { style: "currency", currency: info.settings.currency })
-// info.payment_gateways → [{ slug, title, description, online }] — you'll need this at checkout
+// info.payment_gateways → [{ slug, title, description, online }] — you'll need this at checkout;
+//   this call is its ONLY source (it is never on the cart view)
 // info.countries / info.currencies → static tables for address forms and money display
 
-const { products, page, per_page, has_next } = await inv("commerce/storefront-catalog", {
-  action: "list-products",
+const { products, page, per_page, has_next } = await store.listProducts({
   page: 1, per_page: 12,           // optional: search, category_id, ribbon_id, featured, on_sale,
   sort: "-created_date",           //   min_price, max_price, in_stock_only
 });                                // sort: -created_date | name | price | -price | popularity | rating
 ```
 
-Each row is a full product record — for a card use `name`, `images[0]?.src`, `price`, `regular_price`, `on_sale`, `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 `{ action: "list-categories" }` (a tree via `parent_id`).
+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.
 
 **Carry forward:** each card links to the product page by **`slug`**.
 
@@ -177,7 +313,7 @@ Each row is a full product record — for a card use `name`, `images[0]?.src`, `
 
 ```js
 const { product, variations, categories, ribbons, reviews } =
-  await inv("commerce/storefront-catalog", { action: "get-product", slug });   // or { id }
+  await store.getProduct(slug);   // or store.getProduct({ id })
 
 // One selector PER product.attributes[] entry — never a flat list of variations.
 import { defaultSelection, selectOption, resolveSelection } from "@/commerce/utils";
@@ -193,43 +329,43 @@ const view = resolveSelection(product, variations, selection);
 // view.addToCart    → { product_id, variation_id } — null until the selection resolves
 ```
 
-Add to cart — `add-item` bootstraps the cart itself: a missing, stale or expired token starts a fresh cart, so the one rule is to **re-persist the `cart_token` from every response** (your cached token may have expired — 48h TTL — or been consumed by a checkout):
+Add to cart — the cart bootstraps itself (a missing, stale or expired token starts a fresh one) and the client does all the token bookkeeping:
 
 ```js
-const cart = await inv("commerce/storefront-cart", {
-  action: "add-item",
-  cart_token: localStorage.getItem("cart_token") || undefined,   // fine if absent/stale
-  ...view.addToCart,
-  quantity: 1,
-});
-localStorage.setItem("cart_token", cart.cart_token);   // ALWAYS — the token may be a new cart's
+const cart = await store.addItem({ ...view.addToCart, quantity: 1 });
 ```
 
-A product with attributes is **rejected without a `variation_id`** (`400 variation_required`) — that is why `view.addToCart` and not a bare `product_id` goes into the call. Show `reviews` (`{ items, has_next, average_rating, rating_count }`) and the `upsells`/`cross_sells` summaries the same response carries. On the other cart actions a `404 cart_not_found|cart_expired` means the cached token went stale — clear it and treat the cart as empty.
+A product with attributes is **rejected without a `variation_id`** (`400 variation_required`) — that is why `view.addToCart` and not a bare `product_id` goes into the call.
+
+**What the page renders — all from this one `get-product` call, no extra reads:** a gallery from `product.images` (`view.display.image` is the variant-selected one; placeholder when empty), name, price from `view.display` (`price`/`regular_price`/`on_sale` → sale badge), one selector per axis, stock state, `short_description` then `description` (**both HTML — render as rich text, don't escape or truncate away the markup**), SKU, `categories` as a breadcrumb, `ribbons` as light labels near the metadata, the `reviews` block (`{ items, has_next, average_rating, rating_count }`), and the `upsells`/`cross_sells` summaries. Descriptive properties (Material, Care…) live in `product.meta_data` — render them as a spec table; they are not attributes and not ribbons. That is the complete product page — [`references/storefront-product-page.md`](./references/storefront-product-page.md) and [`references/product-render.md`](./references/product-render.md) are only for edge cases and for adding fields to the *listing* call.
 
-**Carry forward:** the **`cart_token`** — from the response, every time.
+**Carry forward:** nothing — the client keeps the `cart_token`.
 
 ### 3.3 Cart
 
 **Every cart action returns the same full priced view**, so re-render from whatever the last call returned — no separate refresh:
 
 ```js
-let cart = await inv("commerce/storefront-cart", { action: "get", cart_token });
+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 }]
 // 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
-
-cart = await inv("commerce/storefront-cart", { action: "update-item", cart_token, item_key, quantity }); // ≤0 removes
-cart = await inv("commerce/storefront-cart", { action: "remove-item", cart_token, item_key });
-cart = await inv("commerce/storefront-cart", { action: "apply-coupon", cart_token, code });
+//
+// NOT in the cart view: payment_gateways (store.getStoreInfo() ONLY — cart.payment_gateways
+// is always undefined), the product catalog (listProducts/getProduct), countries/currencies
+// (getStoreInfo). Never dot into the cart for any of those.
+
+cart = await store.updateItem(item_key, quantity);   // ≤0 removes
+cart = await store.removeItem(item_key);
+cart = await store.applyCoupon(code);
 ```
 
 Shipping is chosen **on the cart, before place-order** — this is the step storefronts most often skip, and `place-order` refuses without it (`400 shipping_method_required`). **Call `set-shipping-address` the moment the customer provides an address** — every shipping option and cost is recalculated by that call (never reuse a list fetched earlier), and an address the store doesn't ship to **fails right there** with `400 shipping_not_available`, so the address form is where you surface it:
 
 ```js
 // as soon as the address is entered — this is what (re)calculates shipping options + cost
-cart = await inv("commerce/storefront-cart", { action: "set-shipping-address", cart_token,
-  address: { country, state, postcode, city } });   // 400 shipping_not_available → show it on the address form
+cart = await store.setShippingAddress({ country, state, postcode, city });
+// 400 shipping_not_available → show it on the address form
 // cart.chosen_shipping_method is the rate's ID (a string) — to display it, look
 // it up: cart.available_shipping_methods.find(m => m.id === cart.chosen_shipping_method)
 // and render that entry's title + cost. Never render the id itself.
@@ -239,11 +375,10 @@ switch (cart.shipping_status) {
   case "chosen": break;                 // customer's earlier choice still valid
   case "choice_required":               // several options — MUST render cart.available_shipping_methods
     // [{ id, title, cost }] as a picker, then send the customer's pick:
-    cart = await inv("commerce/storefront-cart", { action: "choose-shipping-method", cart_token,
-      method_id: picked.id });          // the entry's id, not its method_id type
+    cart = await store.chooseShippingMethod(picked.id);   // the entry's id, not its method_id type
     break;
   case "missing_address": break;        // several zones, no address yet — shipping cost is NOT
-                                        // calculated; collect the address and call set-shipping-address
+                                        // calculated; collect the address and call setShippingAddress
   case "not_needed": break;             // fully virtual cart
 }
 ```
@@ -254,12 +389,17 @@ A store with exactly **one shipping zone** shows its options (and, auto-selected
 
 ### 3.4 Checkout & order-received
 
-The checkout page renders **two sets of options that are store data, never hardcoded**: the shipping methods (already resolved on the cart in step 3 — `place-order` refuses with `400 shipping_method_required` until `shipping_status` is `chosen`/`auto_selected`/`not_needed`) and the payment methods, which come from `info.payment_gateways` (step 1) — every gateway the admin has **enabled**:
+The checkout page renders **two sets of options that are store data, never hardcoded**: the shipping methods (already resolved on the cart in step 3 — `place-order` refuses with `400 shipping_method_required` until `shipping_status` is `chosen`/`auto_selected`/`not_needed`) and the payment methods — every gateway the admin has **enabled**:
 
 ```js
-// wiring a card provider = implementing two files — details:
-// .agents/skills/commerce/references/online-payments.md
-const gateways = info.payment_gateways;   // [{ slug, title, description, online }] — admin-owned data
+// card payments = ONE file to implement — §2.2 above has the complete
+// Stripe implementation to paste; no other reading needed
+const { payment_gateways: gateways } = await store.getStoreInfo();
+// ⚠ get-store-info is the ONLY source of payment_gateways — the cart view does
+// NOT include them (cart.payment_gateways is always undefined, which reads as
+// "no methods" and dead-disables the place-order button). If a context caches
+// store-info, read it from there — never from the cart object.
+// gateways → [{ slug, title, description, online }] — admin-owned data
 // several → render a picker using the admin's title/description as the labels
 // exactly ONE → no picker: use it directly, but still show its title so the customer knows how they'll pay
 // none → checkout cannot complete — say so instead of rendering a dead button
@@ -271,12 +411,11 @@ While the store has no card provider implemented, picking the card gateway fails
 `online: true` marks the card/redirect gateway; every other gateway is manual reconciliation. Then one call places the order:
 
 ```js
-const res = await inv("commerce/storefront-checkout", {
-  action: "place-order", cart_token,
+const res = await store.placeOrder({
   payment_method,                                     // the slug chosen above
   billing: { first_name, last_name, address_1, city, country, email },   // the required set; phone, state, postcode optional
-  // shipping: { … } if it differs from billing; customer_note?; return_url: window.location.origin
-});
+  // shipping: { … } if it differs from billing; customer_note?
+});                                // token + return_url handled by the client; the cart is consumed
 // res → { order_id, order_number, order_key, status, totals, order,
 //         payment_instructions,   // manual gateways: { description, account_details } — render them
 //         payment }               // card: { status: "requires_payment", checkout_url, … } | null
@@ -289,13 +428,8 @@ Every payment link returns to **`/order-received`** — the page from §1 step 3
 
 ```js
 // GET /order-received?order_id=…&order_key=…&payment=success|cancel
-const params = new URLSearchParams(window.location.search);
-const { state, order, payment_link, payment_instructions } = await inv("commerce/payments", {
-  action: "complete-return",
-  order_id: params.get("order_id"), order_key: params.get("order_key"),
-  payment: params.get("payment"),        // only a hint — the server verifies with the provider
-  return_url: window.location.origin,
-});
+const { state, order, payment_link, payment_instructions } = await store.completeReturn();
+// (reads the URL params itself; ?payment= is only a hint — the server verifies with the provider)
 // state === "paid"      → thank-you + order summary (order is now marked paid)
 // state === "unpaid"    → card order: offer payment_link.url to pay now;
 //                         manual order: render payment_instructions ({ description, account_details })
@@ -308,6 +442,19 @@ Two shapes to get right when rendering: **`order` carries flat totals** — `ord
 
 ---
 
-## 4. Next
+## 4. Done when
+
+Post-installation is complete when every line below holds — verify against this list instead of re-reading docs:
+
+- [ ] `/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.
+- [ ] Product list renders from `store.listProducts` (cards: image/placeholder, name, price or "From …", sale badge, stars, ribbons) and links by `slug`.
+- [ ] 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.
+
+## 5. Next
 
 Continue with the commerce skill — [`.agents/skills/commerce/SKILL.md`](./SKILL.md) — for day-2 work: UI changes, deeper storefront features ([`references/product-render.md`](./references/product-render.md) for what to render per view, [`references/storefront-product-page.md`](./references/storefront-product-page.md) for variant edge cases, [`references/reviews.md`](./references/reviews.md) for the ready-made reviews backend), payment provider wiring, scheduled maintenance, emails, webhooks, and operational limits.

package/skills/commerce/references/guest-access-security.md

@@ -13,6 +13,6 @@ The storefront functions run as the service role, so RLS is not protecting the c
 
 - **Identity comes from the session, never from the body.** An email in the payload is a claim, not a credential. Use `getCallerUser(base44)` and `requireUser(user)` from `shared/commerce/auth.ts`, and `ownsEmail(user, email)` before writing to anything keyed on someone's address. This is why `submit-review` requires a signed-in customer (a `reviewer_email` field is ignored) and why a guest checkout attaches to an existing `commerce.Customer` without rewriting its saved name and addresses — otherwise knowing a customer's email would be enough to redirect where their next order ships, or to post a review in their name.
 - **Anything a person owns needs authentication, not just an email.** If you add wishlists, loyalty, saved payment details, subscriptions or support tickets, gate the write on `requireUser` and derive the owner from `user.email` / `user.id`. Guest access is only ever by bearer token (`cart_token`, `order_key`) for the *one* record that token names. (Reviews are the deliberate exception — public by email, moderated instead of authenticated; a session email still always beats the payload.)
-- **Only the payment provider can say an order is paid.** Never transition an order to `processing` because a request said so — no `paid: true` flag, no `transaction_id` from a client, no `?payment=success` in a return URL. Go through `confirmCardPayment()`, which asks the provider about the payment reference stored on the order. Wiring a provider means implementing the two payment files (see [`online-payments.md`](./online-payments.md)), never a new "confirm" endpoint.
+- **Only the payment provider can say an order is paid.** Never transition an order to `processing` because a request said so — no `paid: true` flag, no `transaction_id` from a client, no `?payment=success` in a return URL. Go through `confirmCardPayment()`, which asks the provider about the payment reference stored on the order. Wiring a provider means implementing the four functions in `shared/commerce/card-payment.ts` (see [`online-payments.md`](./online-payments.md)), never a new "confirm" endpoint.
 - **A bearer token authorizes one record.** `order_key` gets you *that* order; it is not a licence to name someone else's ids in the same request. Match every id in the payload back to the record the token opened.
 - **Don't return more than the caller asked about.** Serialize customer-facing orders through `serializeOrderForCustomer()`, and don't let a response reveal whether another person's email exists, bought something, or has an account — a boolean in an error body is an enumeration oracle.

package/skills/commerce/references/online-payments.md

@@ -2,31 +2,49 @@
 
 The store ships with a **Credit card** checkout option (`commerce.PaymentGateway` slug `card`) and everything around it already built — order creation, totals, stock holds, the two idempotent confirmation paths (customer return + provider webhook), payment links for unpaid orders, refund records, emails, and the admin's payment panel.
 
-What it does **not** ship with is a payment provider. Wiring one (Stripe, PayPal, Adyen, a local PSP…) means implementing **exactly two files** — nothing else changes, no entity is touched, no caller or UI needs editing:
+What it does **not** ship with is a payment provider. Wiring one (Stripe, PayPal, Adyen, a local PSP…) means implementing **one file** — `base44/shared/commerce/card-payment.ts`, four functions — and nothing else: no entity is touched, no caller or UI needs editing, and the payment webhook *function* is premade (it calls this file's `parseWebhook`).
 
-| # | File | Implement |
-|---|------|-----------|
-| 1 | `base44/shared/commerce/card-payment.ts` | `createCardPayment` (make a hosted payment page for `order.total`, return `{url, reference}`), `checkCardPaymentPaid` (ask the provider whether `reference` was paid), and optionally `refundCardPayment` |
-| 2 | `base44/functions/commerce/payment-webhook/entry.ts` | `parseWebhook` (verify the provider's signature over the raw body, return `{order_id, order_key, paid, reference?}`) |
+| Function | Backs |
+|---|---|
+| `createCardPayment` | checkout + payment links: make a hosted payment page for `order.total`, return `{ url, reference }`, and attach `order.id`/`order.order_key` to the payment's metadata |
+| `checkCardPaymentPaid` | confirmation: ask the provider whether `reference` was paid **and is the payment for this order** — used by the return page, the webhook and the admin's "Check payment" |
+| `refundCardPayment` | admin refunds through the provider (optional — leave the stub to keep refunds manual) |
+| `parseWebhook` | webhook validation: name the order a provider event is about (from the echoed metadata), and vouch `paid: true` **only** after verifying the request signature over the raw body bytes |
 
-Until file 1 is implemented, picking Credit card at checkout answers `503 no_card_payment_provider` (the storefront should offer the other methods); the admin can also just switch the card option off in Settings → Payments to hide it. Every other payment option is **manual**: the order goes on-hold with the option's description as payment instructions, and the operator moves it on once the money arrives — those need no code at all, and the admin can add more of them in Settings → Payments.
+**Wiring Stripe? Don't start here** — [`post-installation.md` §2.2](../post-installation.md#22-payments--one-file-any-provider-stripe-as-the-reference) has the complete implementation of all four functions to paste in, plus the secret and webhook-endpoint steps. This reference is for other providers and for webhook customization.
+
+Until the file is implemented, picking Credit card at checkout answers `503 no_card_payment_provider` (the storefront should offer the other methods); the admin can also switch the card option off in Settings → Payments to hide it. Every other payment option is **manual**: the order goes on-hold with the option's description as payment instructions, and the operator moves it on once the money arrives — those need no code at all, and the admin can add more of them in Settings → Payments.
 
 ## How the premade flow works
 
 1. **Checkout** (`commerce/storefront-checkout` `place-order` with the `card` gateway): the order is created `pending`, `createCardPayment(sr, order, {successUrl, cancelUrl, customerEmail})` is called, the returned `reference` is stored on the order (`_payment_reference` meta), and the customer is redirected to `url`. The return URLs already carry `order_id`, `order_key` and `payment=success|cancel`.
 2. **Confirmation — two idempotent paths**, whichever runs second is a no-op:
    - **Customer return**: the `/order-received` page calls `commerce/payments` `complete-return`, which runs `checkCardPaymentPaid(sr, order, reference)` and, when true, moves the order to `processing` (stock/email/webhook side-effects fire from the transition).
-   - **Webhook**: register `commerce/payment-webhook`'s URL with the provider. Your `parseWebhook` verifies the signature and names the order; `paid: true` from a **verified** event is trusted directly, `paid: false` makes the premade code re-check via `checkCardPaymentPaid`. The event's `order_key` must match the order — attach `order.id` and `order.order_key` to the payment's metadata in `createCardPayment` so the event can carry them back.
+   - **Webhook**: register `commerce/payment-webhook`'s URL with the provider — it covers the buyer who pays and closes the tab. The function is **premade** and never trusts an event body on its own: it hands the raw request to your `parseWebhook`, which names the order from the `order_id`/`order_key` metadata `createCardPayment` attached. A `paid: false` event is an unverified *nudge* — payment is then verified through `checkCardPaymentPaid` against the provider's API, which is why **no signing secret is needed**: a forged event can at worst trigger a re-check, never mark an order paid, and the `order_key` match stops an event being pointed at another order. `paid: true` is trusted directly and is therefore only allowed after real signature verification.
 3. **Payment links**: `commerce/payments` `create-link` mints a fresh page for any unpaid order via the same `createCardPayment` — used by the admin's payment-link button and the order-received page's "Pay now".
 4. **Refunds**: `commerce/admin-refunds` with `refund_payment: true` calls `refundCardPayment` **before** writing the local record (a failed provider refund writes nothing). While unimplemented it answers `501 card_refund_not_implemented` — record the refund without `refund_payment` and return the money from the provider's own dashboard.
 
 ## Implementation rules
 
+- **Replace `card-payment.ts` whole** — one write of the full new file, never a `find_replace` into the shipped stub: a partial patch leaves the original stubs behind and breaks every commerce function's deploy with duplicate-export bundle errors ("Multiple exports with the same name …"); the fix is always to rewrite the file whole.
 - **Credentials** come from backend secrets/env (`Deno.env.get(...)`) — never from an entity, never from the client. On Base44, env vars are injected at deploy time; after adding a secret, redeploy the backend functions so they can see it.
-- **Only the provider can say an order is paid.** `checkCardPaymentPaid` must ask the provider's API about the stored `reference`; never return true because a request claimed it. In `parseWebhook`, set `paid: true` only after verifying the request signature over the raw body bytes.
+- **Which methods the store offers is seed data** — `commerce/seed-store`'s `payment_methods` (e.g. `["card"]`) enables the listed gateways and disables the rest; don't edit `commerce.PaymentGateway` records to turn methods on or off.
+- **Only the provider can say an order is paid.** `checkCardPaymentPaid` must ask the provider's API about the stored `reference`; never return true because a request claimed it. It should also check the payment **names this order** (compare the payment's metadata `order_id` to `order.id`) — that stops a reference to some other, genuinely paid payment being replayed against a different order.
+- **Attach the metadata.** `createCardPayment` must put `order.id` and `order.order_key` on the payment's metadata (Stripe: `metadata` + `payment_intent_data.metadata`) — that echo is how `parseWebhook` names the order, and what the check above compares against.
+- **`parseWebhook` never trusts a raw body.** Return `paid: false` (the verify-via-API nudge) unless you verified the provider's signature over the raw payload bytes; set `reference` only from a verified event, otherwise leave it unset so the premade flow uses the reference stored on the order at checkout.
 - **Amounts**: `order.total` is in display units (e.g. `12.34`) with `order.currency`; convert to the provider's minor units yourself if it needs them.
 - The shared helpers in `base44/shared/commerce/payments.ts` (return-URL building, `confirmCardPayment`, reference bookkeeping) are premade — don't duplicate or bypass them.
 
+## `parseWebhook` in depth
+
+`parseWebhook(req, payload)` lives in `card-payment.ts` with the other three; `commerce/payment-webhook` (the function file) is premade and calls it with the raw request and the raw body — the exact bytes, so signature schemes work. It returns `CardWebhookEvent | null`:
+
+- **The simple, secure default — the nudge**: parse the event, read the `order_id`/`order_key` metadata `createCardPayment` attached, return `{ order_id, order_key, paid: false }`. No signing secret; the premade flow verifies via `checkCardPaymentPaid` against the provider's API, so forgery is impossible by construction. This is what the Stripe reference implementation does.
+- **The signature-verified fast path** (optional): verify the provider's signature over the raw `payload` bytes (Stripe: `constructEventAsync` with a webhook signing secret) and return `paid: true` with the event's `reference` for a verified successful payment; the premade code then trusts it without the API round-trip. `paid: true` from an unverified body is the one way to break this design — never do it.
+- Return **`null`** for events that aren't about a payment for one of this store's orders; the function answers 200 so the provider doesn't retry.
+
+Everything after `parseWebhook` — order lookup, the `order_key` match, idempotent confirmation, order progression — is premade either way.
+
 ## Storefront requirements (unchanged by any of this)
 
 - Redirect to `payment.checkout_url` when `place-order` returns `payment.status === "requires_payment"`.

package/src/commerce/admin/hooks/useAsync.js

@@ -27,7 +27,7 @@ export default function useAsync(fn, deps = []) {
 
   useEffect(() => {
     run();
-    // eslint-disable-next-line -- deps intentionally partial
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- caller-supplied deps; `run` is stable and intentionally omitted
   }, deps);
 
   // Note: `refetch` deliberately takes no arguments, so it stays safe to pass

package/src/commerce/admin/hooks/usePagedList.js

@@ -55,7 +55,7 @@ export default function usePagedList(fetcher, { pageSize = 20, initialSort = "-c
     }
     if (page !== 0) setPage(0);
     else load(0, sort);
-    // eslint-disable-next-line -- deps intentionally partial
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- keyed on depsKey alone; adding page/sort/load would double-fetch
   }, [depsKey]);
 
   useEffect(() => {

package/src/commerce/admin/pages/settings/PaymentsSettings.jsx

@@ -205,12 +205,13 @@ export default function PaymentsSettings() {
               </div>
 
               {/* The "card" option redirects to a provider-hosted payment page.
-                  Wiring a provider means implementing the two payment files —
-                  shared/commerce/card-payment.ts + functions/commerce/payment-webhook,
-                  see .agents/skills/commerce/references/online-payments.md. Until
-                  then, picking it at checkout answers 503 no_card_payment_provider.
-                  Deliberately not shown to the store operator — it's developer
-                  guidance, not store configuration. */}
+                  Wiring a provider means implementing the four functions in
+                  shared/commerce/card-payment.ts (Stripe: paste-in in
+                  .agents/skills/commerce/post-installation.md §2.2; the payment
+                  webhook is premade). Until then, picking it at checkout answers
+                  503 no_card_payment_provider. Deliberately not shown to the
+                  store operator — it's developer guidance, not store
+                  configuration. */}
             </div>
           ))}
         </CardContent>

package/src/commerce/utils/index.js

@@ -6,8 +6,11 @@
  * template, but this logic does — it is the part that is easy to get subtly
  * wrong.
  *
- *   import { resolveSelection, defaultSelection, selectOption } from "@/commerce/utils";
+ *   import { createStorefront, resolveSelection, defaultSelection, selectOption } from "@/commerce/utils";
  *
+ * - `storefront.js` — the API client: cart_token lifecycle, cached store-info
+ *   (payment_gateways live there, never on the cart view), catalog/cart/
+ *   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`.
@@ -15,5 +18,6 @@
  *   "Free shipping over €150" copy states a configured rule, not an invented
  *   number. See `.agents/skills/commerce/docs/api-storefront.md`.
  */
+export * from "./storefront.js";
 export * from "./variants.js";
 export * from "./shipping-promos.js";