@base44/app-plugin-commerce 0.1.11 → 0.1.12

package/README.md

@@ -11,7 +11,7 @@ It provides a full-featured **commerce data model and behavior** (variant-driven
 - **Online card payments, order side premade** — checkout routing, payment links for unpaid orders, two idempotent confirmation paths (customer return + webhook, both premade) and refund records are all built. Wiring a provider (Stripe, PayPal, a local PSP…) means implementing **four functions in one file** — `base44/shared/commerce/card-payment.ts` — and nothing else; a complete Stripe implementation to paste in ships in [`skills/commerce/post-installation.md`](./skills/commerce/post-installation.md) §2.2. Every other payment option is manual (on-hold + instructions) and needs no code; the admin can add more in Settings → Payments. See [`skills/commerce/references/online-payments.md`](./skills/commerce/references/online-payments.md).
 - **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 functions for the shopfront you build: `variants.js` maps an attribute selection (Size, Color) onto a `ProductVariation` and back, plus per-option availability and variant price ranges; `shipping-promos.js` reads the store's real free-shipping configuration so "Free shipping over €150" copy states a configured rule rather than an invented number. See [`skills/commerce/references/storefront-product-page.md`](./skills/commerce/references/storefront-product-page.md).
+- **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/return-page calls); `variants.js` maps an attribute selection (Size, Color) onto a `ProductVariation` and back, plus per-option availability and variant price ranges; `shipping-promos.js` reads the store's real free-shipping configuration so "Free shipping over €150" copy states a configured rule rather than an invented number. See [`skills/commerce/references/storefront-product-page.md`](./skills/commerce/references/storefront-product-page.md).
 - **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/), which holds [`SKILL.md`](./skills/commerce/SKILL.md) (the short map agents start from), [`installation-guidelines.md`](./skills/commerce/installation-guidelines.md), [`post-installation.md`](./skills/commerce/post-installation.md), per-topic guides in [`references/`](./skills/commerce/references/) and the API references in [`docs/`](./skills/commerce/docs/) — the whole folder is installed into the app at `.agents/skills/commerce/` so agents pick it up natively.
 

package/base44/functions/commerce/seed-store/entry.ts

@@ -15,9 +15,14 @@
  * best-effort rollback on mid-failure. See seed-catalog.ts for the pipeline.
  *
  * Body: { store_name?, currency?, weight_unit?, dimension_unit?,
- *         with_sample_data?, products?, coupons?, locations? }
+ *         payment_methods?, with_sample_data?, products?, coupons?, locations? }
  * — with_sample_data cannot be combined with the catalog keys.
  *
+ * `payment_methods` (e.g. ["card"]) names the checkout methods the store
+ * offers: listed gateways are enabled, every other gateway row is disabled —
+ * the one call covers "card-only" stores with no entity editing. Explicit
+ * values always win, on first seed and re-runs alike (like `currency`).
+ *
  * `store_name` is required on a first seed: a function's env is only
  * BASE44_APP_ID, so it cannot read the app's name, and subjects need one.
  * `currency` is an ISO code and `weight_unit`/`dimension_unit` are the
@@ -65,6 +70,30 @@ Deno.serve(async (req) => {
     if (dimensionUnit && !DIMENSION_UNITS.includes(dimensionUnit)) {
       unitErrors.push({ path: "dimension_unit", error: `must be one of: ${DIMENSION_UNITS.join(", ")}` });
     }
+    let methodSlugs: string[] | null = null;
+    if (body.payment_methods !== undefined) {
+      const raw = body.payment_methods;
+      if (!Array.isArray(raw) || !raw.length || raw.some((s: unknown) => typeof s !== "string" || !String(s).trim())) {
+        unitErrors.push({ path: "payment_methods", error: `must be a non-empty array of gateway slugs, e.g. ["card"]` });
+      } else {
+        methodSlugs = [...new Set(raw.map((s: string) => s.trim().toLowerCase()))];
+        // Validate against the gateways that will exist after this call — the
+        // seeded defaults plus any rows already in the store ("stripe" rows are
+        // renamed to "card" below). Read-only, so failing here writes nothing.
+        const rows = (await sr.entities["commerce.PaymentGateway"].list(undefined, 100)) ?? [];
+        const known = new Set([
+          ...GATEWAY_DEFAULTS.map((g) => g.slug),
+          ...rows.map((r: any) => String(r.slug === "stripe" ? "card" : r.slug)),
+        ]);
+        const unknown = methodSlugs.filter((s) => !known.has(s));
+        if (unknown.length) {
+          unitErrors.push({
+            path: "payment_methods",
+            error: `unknown gateway slug(s): ${unknown.join(", ")} — known: ${[...known].join(", ")}`,
+          });
+        }
+      }
+    }
     if (unitErrors.length) {
       return fail(400, "Invalid catalog payload — nothing was written.", "invalid_payload", { errors: unitErrors });
     }
@@ -159,10 +188,28 @@ Deno.serve(async (req) => {
     for (const gw of GATEWAY_DEFAULTS) {
       const hits = (await sr.entities["commerce.PaymentGateway"].filter({ slug: gw.slug }, undefined, 1)) ?? [];
       if (hits.length) continue;
-      await sr.entities["commerce.PaymentGateway"].create(gw);
+      await sr.entities["commerce.PaymentGateway"].create(
+        methodSlugs ? { ...gw, enabled: methodSlugs.includes(gw.slug) } : gw,
+      );
       seeded.gateways++;
     }
 
+    // Explicit payment_methods always win, like currency: converge EVERY
+    // gateway row's enabled flag to the requested set, so "card-only" is one
+    // seed call — no entity editing, on first seed and re-runs alike.
+    let paymentMethods: { enabled: string[]; disabled: string[] } | null = null;
+    if (methodSlugs) {
+      const rows = (await sr.entities["commerce.PaymentGateway"].list(undefined, 100)) ?? [];
+      paymentMethods = { enabled: [], disabled: [] };
+      for (const row of rows) {
+        const want = methodSlugs.includes(String(row.slug));
+        if (Boolean(row.enabled) !== want) {
+          await sr.entities["commerce.PaymentGateway"].update(row.id, { enabled: want });
+        }
+        (want ? paymentMethods.enabled : paymentMethods.disabled).push(String(row.slug));
+      }
+    }
+
     // Caller-supplied `locations` ARE the store's shipping story — seeding the
     // free-shipping fallback next to them would leave a second no-region
     // location the merchant never asked for (shadowed while the caller's has a
@@ -199,6 +246,7 @@ Deno.serve(async (req) => {
       catalog: catalogResult,
       store_name: { value: storeNameAction === "kept_existing" ? currentName : storeName, action: storeNameAction },
       currency: currencyInfo ? { value: currencyInfo.code, action: currencyAction } : null,
+      payment_methods: paymentMethods,
     });
   } catch (e) {
     if (e instanceof HttpError) return fail(e.status, e.message, e.code);

package/base44/shared/commerce/card-payment.ts

@@ -12,6 +12,12 @@
  * `.agents/skills/commerce/post-installation.md` §2.2 to paste over this
  * file — another provider implements the same functions against its own API.
  *
+ * REPLACE THIS FILE WHOLE (one write of the full new content). Never
+ * find_replace into these stubs: a partial patch leaves the originals behind
+ * and every commerce function fails to deploy with duplicate-export bundle
+ * errors ("Multiple exports with the same name ...") — the fix is always to
+ * rewrite the file whole.
+ *
  * Everything around these functions is already built: checkout creates the
  * order, prices it, holds stock and routes the customer to the URL you
  * return; the return page and the payment webhook confirm payment

package/package.json

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

@@ -10,6 +10,7 @@ Operational guidance for extending, operating and building on the Base44 Commerc
 > **If you are a Base44 agent working inside the runtime, read this first:**
 > - **Don't read the whole codebase up front.** Start with this file, then open only the files your current task touches plus the matching reference below, pulling in more as you go. Reading everything first just burns context.
 > - **Don't weaken the admin gating.** The UI guard, entity RLS and function guards form three enforcement layers — see [`.agents/skills/commerce/post-installation.md`](./post-installation.md) — keep all of them intact when changing routes or schemas.
+> - **Entity names are dotted — SDK access is bracket syntax only:** `base44.entities["commerce.PaymentGateway"]` (schema file: `base44/entities/commerce.PaymentGateway.jsonc`). `commerce__PaymentGateway` / `PaymentGateway` don't exist. Gateway on/off is seed data anyway: `commerce/seed-store` `payment_methods`.
 
 ## IMPORTANT — first-time installation
 

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

@@ -182,7 +182,7 @@ Actions: `create-link` · `complete-return` · `verify` — the admin side of on
 
 ## commerce/seed-store
 
-Not action-routed. Body `{ store_name?, currency?, weight_unit?, dimension_unit?, with_sample_data?, products?, coupons?, locations? }`. **`store_name` is required** when the `emails` group doesn't exist yet (**400** `store_name_required` otherwise) — pass the app's name **as the platform shows it** — ask the user or read it from the dashboard. `base44/config.jsonc` → `name` is *not* authoritative: it can still say `New App` for an app the platform calls `Canvas`. A backend function can't read either, its environment being only `BASE44_APP_ID`. It lands in `emails.store_name` — one setting serving as both the store name in email subjects and the sender name on every transactional email; a nameless store renders subjects like `[]: New order #1002`, which is why seeding refuses one. Requires admin. Runs a **canary schema check** first — on any incompatibility returns **422** `{ success:false, code:"schema_incompatible", errors:[{ entity, error }] }` and writes nothing. Otherwise seeds defaults idempotently, then the catalog. On an already-seeded store a passed `store_name` fills a **blank** name and never overwrites one the merchant chose. **`currency`** (ISO code, validated against the shared currencies table) and **`weight_unit`/`dimension_unit`** set the `general` group; unknown values fail as **400** `invalid_payload`. Unlike `store_name` they **always win** — there is no blank state to distinguish a merchant's choice from the seeded default, so passing one on a re-run updates the store. Prices are formatted with `Intl.NumberFormat` — the currency is a value, there are no format settings.
+Not action-routed. Body `{ store_name?, currency?, weight_unit?, dimension_unit?, payment_methods?, with_sample_data?, products?, coupons?, locations? }`. **`payment_methods`** (gateway slugs, e.g. `["card"]`) enables exactly the listed gateways and disables every other gateway row — the one-call way to honor "card-only"/"offline-only"; explicit values win on re-runs, unknown slugs fail as `400 invalid_payload`, and the response reports `payment_methods: { enabled, disabled }` (`null` when not passed). **`store_name` is required** when the `emails` group doesn't exist yet (**400** `store_name_required` otherwise) — pass the app's name **as the platform shows it** — ask the user or read it from the dashboard. `base44/config.jsonc` → `name` is *not* authoritative: it can still say `New App` for an app the platform calls `Canvas`. A backend function can't read either, its environment being only `BASE44_APP_ID`. It lands in `emails.store_name` — one setting serving as both the store name in email subjects and the sender name on every transactional email; a nameless store renders subjects like `[]: New order #1002`, which is why seeding refuses one. Requires admin. Runs a **canary schema check** first — on any incompatibility returns **422** `{ success:false, code:"schema_incompatible", errors:[{ entity, error }] }` and writes nothing. Otherwise seeds defaults idempotently, then the catalog. On an already-seeded store a passed `store_name` fills a **blank** name and never overwrites one the merchant chose. **`currency`** (ISO code, validated against the shared currencies table) and **`weight_unit`/`dimension_unit`** set the `general` group; unknown values fail as **400** `invalid_payload`. Unlike `store_name` they **always win** — there is no blank state to distinguish a merchant's choice from the seeded default, so passing one on a re-run updates the store. Prices are formatted with `Intl.NumberFormat` — the currency is a value, there are no format settings.
 
 **`products`** is the one-call catalog bootstrap — the worked example and full semantics are in [`../post-installation.md` §2.1](../post-installation.md#21-the-products-payload). Each entry references categories/ribbons/attributes by **display name** (taxonomy is get-or-created: slugs/codes derived, existing records matched case-insensitively and reused, with the stored casing canonicalized into the product). `attributes: [{ name, options }]` (or `{ <name>: [options] }`) declares the variant axes; `variations: [{ options: { <name>: <option> }, ...overrides }]` lists the stocked combinations — omit it to auto-generate **all** combinations, each inheriting the product-level price/sale fields. A variation with its own `stock_quantity` gets `manage_stock: "yes"`; without one it draws on the parent's pooled stock (`"parent"`). Variation SKUs are synthesized from the parent SKU when absent. Parent `price`/`regular_price`/`on_sale` are rolled up from the cheapest publishable variant, `stock_status` derived, category/ribbon counts maintained — same helpers as `admin-products` `save`, but **no `product.created` webhooks are dispatched** (bootstrap precedes webhook subscribers; use `admin-products` for webhook-visible creates). Payload problems fail before any write as **400** `invalid_payload` with `errors: [{ path, error }]`; an explicit variation SKU already in use is **409** `duplicate_sku`; a mid-write failure rolls back everything the call created (**500** `catalog_seed_failed`) without touching reused taxonomy. **Re-runs converge**: a product whose `sku` (or, without one, derived slug) already exists is skipped and reported, so retries never duplicate. Limits: ≤100 products, ≤50 variations per product, ≤500 variations per call, ≤50 coupons/locations. `coupons` is a thin passthrough (code lowercased, skip-if-exists); **`locations`** creates Shipping & Tax Locations (`{ name, countries?: ["IL"], shipping_rates: [{ name, cost, free_over? }], tax_groups?: [{ name, rates: [{ name, rate }] }], shipping_tax?: { type: "percent"|"fixed", value } }` — the default `Products` tax group is added when missing; skip-if-exists by name). Passing any `locations` suppresses the seeded "Rest of the world" fallback — yours become the store's only locations; without them the free-shipping fallback is seeded. `with_sample_data: true` seeds the template's demo catalog instead (only when the store has zero products) and cannot be combined with the catalog keys.
 

package/skills/commerce/post-installation.md

@@ -48,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 |
@@ -70,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",
@@ -130,7 +133,8 @@ 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. 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.
@@ -141,6 +145,8 @@ A successful response means the data is in — the catalog and settings are live
 
 The order side of payments is **already implemented** (checkout routing, confirmation, payment links, refund records). The `offline` gateway — and any option the admin adds in Settings → Payments — works with nothing to configure: the order goes on-hold with the option's description as instructions.
 
+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 |
@@ -150,7 +156,7 @@ The **Credit card** option needs a payment provider — **any** provider works (
 | `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. 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)):
+**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
@@ -270,31 +276,36 @@ That's it — checkout redirect, `/order-received` confirmation, the webhook, th
 
 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` (**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 `{ action: "list-categories" }` (a tree via `parent_id`). That is the whole card — no other call or reference needed for the list view.
+Each row is a full product record — for a card use `name`, `images[0]?.src` (**may be empty — render a placeholder, never a broken `<img>`**), `price`, `regular_price`, `on_sale` (sale badge), `short_description`, `stock_status`, `average_rating`/`rating_count` (stars cost no extra call) and `ribbons` (`[{ id, name }]`, may be absent — labels like "Best Seller" for the card corner). **There is no product type flag**: `product.attributes?.length > 0` means the product sells variants and its `price` is a *from*-price rolled up from the cheapest variant — render it as "From …". Categories for the nav come from `store.listCategories()` (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`**.
 
@@ -302,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";
@@ -318,45 +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. 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.
@@ -366,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
 }
 ```
@@ -381,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
 // card payments = ONE file to implement — §2.2 above has the complete
 // Stripe implementation to paste; no other reading needed
-const gateways = info.payment_gateways;   // [{ slug, title, description, online }] — admin-owned data
+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
@@ -398,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
@@ -416,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 })
@@ -440,12 +447,13 @@ Two shapes to get right when rendering: **`order` carries flat totals** — `ord
 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.
-- [ ] Product list renders from `list-products` (cards: image/placeholder, name, price or "From …", sale badge, stars, ribbons) and links by `slug`.
-- [ ] Product page renders from `get-product` with one selector per attribute, resolving to `view.addToCart`.
-- [ ] Cart → address (`set-shipping-address`) → shipping choice → `place-order` completes, and the `cart_token` is re-persisted from every response.
-- [ ] `/order-received` calls `complete-return` 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 switched off in Settings → Payments.
+- [ ] `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
 

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

@@ -26,7 +26,9 @@ Until the file is implemented, picking Credit card at checkout answers `503 no_c
 
 ## 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.
+- **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.

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/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";

package/src/commerce/utils/storefront.js

@@ -0,0 +1,139 @@
+/**
+ * Storefront API client — the thin layer between the visitor UI you build and
+ * the commerce/storefront-* functions. Framework-free. Create it ONCE and
+ * import that instance everywhere (wrapping it in a React context is fine —
+ * never create a second copy):
+ *
+ *   // src/lib/storefront.js
+ *   import { createStorefront } from "@/commerce/utils";
+ *   import { base44 } from "@/api/base44Client";
+ *   export const store = createStorefront(base44);
+ *
+ * It owns the two things hand-rolled clients keep getting wrong:
+ *
+ * - The cart_token lifecycle: the token is sent with every cart/checkout call
+ *   and re-persisted from every response (a stale token silently starts a
+ *   fresh cart), and it is cleared when checkout consumes the cart.
+ * - The store-info split: payment_gateways, currency, countries/currencies
+ *   live ONLY on get-store-info — the cart view never carries them.
+ *   getStoreInfo() caches the call; read them from there, never off a cart.
+ */
+
+/** The stable error code a failed storefront call carries, if any. */
+export function storefrontErrorCode(e) {
+  return e?.response?.data?.code ?? e?.data?.code ?? e?.code ?? null;
+}
+
+export function createStorefront(base44, { storageKey = "cart_token", storage } = {}) {
+  const bag = storage ?? (typeof localStorage !== "undefined" ? localStorage : null);
+
+  // Every function returns the envelope { success, data }; with the SDK the
+  // payload is res.data.data. Exposed for calls beyond the methods below.
+  const inv = (fn, payload) =>
+    base44.functions.invoke(fn, payload).then((r) => r.data.data);
+
+  const token = () => bag?.getItem(storageKey) || undefined;
+  const remember = (cart) => {
+    // ALWAYS re-persist — the backend may have started a fresh cart.
+    if (cart?.cart_token && bag) bag.setItem(storageKey, cart.cart_token);
+    return cart;
+  };
+  const forget = () => bag?.removeItem(storageKey);
+
+  const cartAction = (action, payload = {}) =>
+    inv("commerce/storefront-cart", { action, cart_token: token(), ...payload }).then(remember);
+
+  let infoPromise = null;
+
+  return {
+    inv,
+
+    // ── store info (cached) ──────────────────────────────────────────────
+    /** settings, payment_gateways, countries, currencies — this call ONLY. */
+    getStoreInfo() {
+      infoPromise ??= inv("commerce/storefront-catalog", { action: "get-store-info" })
+        .catch((e) => { infoPromise = null; throw e; });
+      return infoPromise;
+    },
+
+    // ── catalog ──────────────────────────────────────────────────────────
+    listProducts(params = {}) {
+      return inv("commerce/storefront-catalog", { action: "list-products", ...params });
+    },
+    /** getProduct("slug") or getProduct({ id }) */
+    getProduct(ref) {
+      const by = typeof ref === "string" ? { slug: ref } : ref;
+      return inv("commerce/storefront-catalog", { action: "get-product", ...by });
+    },
+    listCategories() {
+      return inv("commerce/storefront-catalog", { action: "list-categories" });
+    },
+    listRibbons() {
+      return inv("commerce/storefront-catalog", { action: "list-ribbons" });
+    },
+
+    // ── 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() {
+      if (!token()) return null;
+      try {
+        return await cartAction("get");
+      } catch (e) {
+        if (["cart_not_found", "cart_expired"].includes(storefrontErrorCode(e))) {
+          forget();
+          return null;
+        }
+        throw e;
+      }
+    },
+    /** addItem(view.addToCart) — a product with attributes needs the resolved variation_id. */
+    addItem(item) {
+      return cartAction("add-item", { quantity: 1, ...item });
+    },
+    updateItem(item_key, quantity) {
+      return cartAction("update-item", { item_key, quantity }); // ≤0 removes
+    },
+    removeItem(item_key) {
+      return cartAction("remove-item", { item_key });
+    },
+    applyCoupon(code) {
+      return cartAction("apply-coupon", { code });
+    },
+    removeCoupon() {
+      return cartAction("remove-coupon");
+    },
+    /** Recalculates shipping options + cost; 400 shipping_not_available belongs on the address form. */
+    setShippingAddress(address) {
+      return cartAction("set-shipping-address", { address });
+    },
+    chooseShippingMethod(method_id) {
+      return cartAction("choose-shipping-method", { method_id });
+    },
+
+    // ── checkout & return page ───────────────────────────────────────────
+    /** place-order; on success the cart is consumed, so the stored token is cleared. */
+    async placeOrder(details) {
+      const res = await inv("commerce/storefront-checkout", {
+        action: "place-order",
+        cart_token: token(),
+        return_url: typeof location !== "undefined" ? location.origin : undefined,
+        ...details,
+      });
+      forget();
+      return res;
+    },
+    /** The whole /order-received page in one call — pass nothing to read the URL params. */
+    completeReturn(params) {
+      const q = params ?? (typeof location !== "undefined"
+        ? new URLSearchParams(location.search)
+        : new URLSearchParams());
+      return inv("commerce/payments", {
+        action: "complete-return",
+        order_id: q.get("order_id"),
+        order_key: q.get("order_key"),
+        payment: q.get("payment") ?? undefined,
+        return_url: typeof location !== "undefined" ? location.origin : undefined,
+      });
+    },
+  };
+}