@base44/app-plugin-commerce 0.1.20 → 0.2.1

package/README.md

@@ -8,13 +8,13 @@ It provides a full-featured **commerce data model and behavior** (variant-driven
 
 - **20 entities** — Products (a product sells variants when it carries attributes; no type field), variations, categories, ribbons, attributes + values, reviews, orders (embedded line/shipping/tax/fee/coupon lines), order notes, refunds, coupons, customers, Shipping & Tax Locations (shipping rates + tax groups per location), payment gateways, store settings, webhooks + deliveries, carts, download permissions, email log.
 - **16 backend functions** — 9 admin (`commerce/admin-products`, `commerce/admin-orders`, `commerce/admin-refunds`, `commerce/admin-coupons`, `commerce/admin-customers`, `commerce/admin-reviews`, `commerce/admin-webhooks`, `commerce/admin-reports`, `commerce/admin-tools`), 4 storefront (`commerce/storefront-catalog`, `commerce/storefront-cart`, `commerce/storefront-checkout`, `commerce/storefront-account`), 2 payment (`commerce/payments`, `commerce/payment-webhook`), and an idempotent `commerce/seed-store` — one call seeds the business defaults **and the whole catalog** (products with attributes in, variants/categories/taxonomy created internally).
-- **Payments: manual methods work out of the box; online cards are opt-in** — the seed enables the manual `offline` method (bank transfer, cash on delivery, pickup: on-hold + instructions, no code) and leaves the `card` gateway **disabled**. **No payment provider ships with the template.** The order side of card payments *is* premade — checkout routing, payment links for unpaid orders, two idempotent confirmation paths (customer return + webhook) and refund records — so a store that opts in wires any provider (Stripe, PayPal, a local PSP…) by implementing **four functions in one file**, `base44/shared/commerce/card-payment.ts`, and nothing else; enable the gateway only with that done, or checkout answers `503 no_card_payment_provider`. The rule and timing: [`skills/commerce/post-installation.md`](./skills/commerce/post-installation.md) §4.1. Provider rules and a complete Stripe implementation to paste, for that one common choice: [`skills/commerce/references/online-payments.md`](./skills/commerce/references/online-payments.md). The admin can add more manual methods in Settings → Payments.
+- **Payments: manual methods work out of the box; online cards are opt-in** — the seed enables the manual `offline` method (bank transfer, cash on delivery, pickup: on-hold + instructions, no code) and leaves the `card` gateway **disabled**. The order side of card payments *is* premade — checkout routing, payment links for unpaid orders, two idempotent confirmation paths (customer return + webhook) and refund records — so a store that opts in wires a provider by implementing **four functions in one file**, `base44/shared/commerce/card-payment.ts`. **For Stripe there is nothing to write**: `base44/shared/commerce/card-payment.stripe.ts` is a complete implementation — copy it over the stub, store the secret, register the webhook, enable the gateway. Any other provider (PayPal, Adyen, a local PSP) follows the same shape. Enable the gateway only with a provider behind it, or checkout answers `503 no_card_payment_provider`. The rule and timing: [`skills/commerce/install/03-data.md`](./skills/commerce/install/03-data.md); provider mechanics: [`skills/commerce/references/online-payments.md`](./skills/commerce/references/online-payments.md). The admin can add more manual methods in Settings → Payments.
 - **Shared commerce engine** (`base44/shared/commerce/`) — totals, tax, shipping, coupons, stock, order lifecycle, webhook dispatch (HMAC-signed), emails, card-payment plumbing, plus static country/currency/continent data.
 - **Admin UI** (`src/commerce/admin/`) — a React/Tailwind/shadcn admin with a familiar store back-office information architecture: dashboard, orders, products, coupons, customers, reports, and full settings including webhooks. Admin-role gated.
-- **Storefront helpers** (`src/commerce/utils/`) — framework-free, dependency-free modules for the shopfront you build: `storefront.js` is the API client (`createStorefront(base44)` — cart-token lifecycle, cached store-info, catalog/cart/checkout/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).
-- **Storefront React layer** (`src/commerce/storefront/`) — hooks and headless (render-prop) helpers for the parts of a shopfront whose contracts are the same in every store, with **zero visual components** (the look stays yours): `StorefrontProvider` (one client, cached store info, ONE shared cart), `useCart` (shared cart state, serialized mutations), `useCheckout` (guided checkout — automatic debounced shipping/tax recalculation once the address is complete, shipping/payment choice, a `canPlaceOrder` gate with named blockers, redirect-handling `placeOrder`), `ShippingMethodPicker`/`PaymentMethodPicker` (headless), and `useOrderReturn` (the mandatory `/order-received` page in one hook). Needs React and nothing else.
+- **Storefront helpers** (`src/commerce/utils/`) — framework-free, dependency-free modules for the shopfront you build: `storefront.js` is the API client (`createStorefront(base44)` — cart-token lifecycle, cached store-info, catalog/cart/checkout/reviews/return-page calls); `variants.js` maps an attribute selection (Size, Color) onto a `ProductVariation` and back, plus per-option availability and price ranges; `price.js` encodes the from-price and price-range rules; `totals.js` projects a cart *or* an order into one summary shape; `address-spec.js` is the checkout address form as data; `images.js` normalizes catalog images; `shipping-promos.js` reads the store's real free-shipping configuration so "Free shipping over €150" states a configured rule rather than an invented number.
+- **Storefront React layer** (`src/commerce/storefront/`) — **two tiers.** The *identity* surfaces stay yours to design (home, collection grid, product-page layout, product card, theme — the kit ships no markup for them). The *commodity* surfaces ship as **blocks** that inherit your theme and can be restyled, slotted or replaced: `CheckoutBlock`, `CartLinesBlock`, `TotalsBlock`, `CouponFieldBlock`, `QuantityStepper`, `OrderReceivedBlock`, `ReviewsBlock`, `AddressFieldsBlock`, plus the product page's internals (`VariantSelectorBlock`, `AddToCartBlock`, `ProductGalleryBlock`, `ProductSpecsBlock`, `BreadcrumbsBlock`, `ProductStripBlock`). Each is a thin composition of the hooks underneath: `StorefrontProvider`, `useProductList`/`useCategories`/`useRibbons`, `useProduct`/`useAddToCart`/`useProductPrice`/`useProductGallery`, `useProductReviews`, `useCart`/`useCartLine`/`useCoupon`, `useCheckout` + `useAddressForm`/`useTotalsLines`/`useCheckoutBlockers`, the headless `ShippingMethodPicker`/`PaymentMethodPicker`, `useOrderReturn`, and `useStorefrontSeo`. Needs React and nothing else.
 - **StoreAdmin agent + bot** — an AI copilot (`base44/agents/commerce/StoreAdmin.jsonc`, registered as `commerce/StoreAdmin`) with the `commerce/*` functions attached directly as tools (calls run as the chatting user → `requireAdmin()` still applies), variant-aware order editing, plus a chat panel in the admin sidebar with GFM markdown-table rendering.
-- **Docs** — this README plus the commerce skill folder [`skills/commerce/`](./skills/commerce/), 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.
+- **Docs** — this README plus the commerce skill folder [`skills/commerce/`](./skills/commerce/): [`SKILL.md`](./skills/commerce/SKILL.md) is the map every agent starts from (and the only path the platform needs to know); [`install/`](./skills/commerce/install/) holds the three stage files that are the whole install (`01-install` → `02-storefront` → `03-data`, each read at the moment its work starts and dropped when its checklist passes); [`references/`](./skills/commerce/references/) holds per-topic guides opened only on demand; [`docs/`](./skills/commerce/docs/) holds the data-model map ([`entities.md`](./skills/commerce/docs/entities.md)) and the two API references. The whole folder is installed into the app at `.agents/skills/commerce/` so agents pick it up natively.
 
 ## Repo map
 
@@ -31,23 +31,26 @@ base44-commerce-template/
 ├── src/
 │   └── commerce/
 │       ├── admin/      React admin UI (copy into your app's src/commerce/)
-│       ├── utils/      storefront helpers — API client, variant selection, shipping promos
-│       └── storefront/ storefront React layer — shared-cart provider, guided checkout,
-│                       headless pickers, order-received hook (logic only, no visuals)
+│       ├── utils/      storefront helpers — API client, variants, price/totals rules
+│       └── storefront/ storefront React layer — hooks (cart, checkout, catalog,
+│           └── blocks/ reviews, SEO) + default markup for the commodity UI
 ├── scripts/
 │   └── install.js         static installer (run from <app>/examples/commerce/scripts/)
 ├── skills/
 │   └── commerce/          commerce skill — copied into the app's .agents/skills/
 │       │                  so agents know the store natively
-│       ├── SKILL.md       the map: short overview + links to everything below
-│       ├── installation-guidelines.md   installing into an app (scripted or manual)
-│       ├── post-installation.md         embedding the admin pages, seeding, storefront quick start
-│       ├── references/    per-topic guides (product rendering, product page & variants,
-│       │                  online payments, scheduled work, emails, webhooks, media & downloads,
-│       │                  limits, security)
+│       ├── SKILL.md       the map: what to read, when, and what to skip
+│       ├── install/       the whole install, in three staged files
+│       │   ├── 01-install.md     files, admin mount, role gating, the schedule
+│       │   ├── 02-storefront.md  storefront pages on the hooks + blocks
+│       │   └── 03-data.md        seeding, shipping zones, images, payments decision
+│       ├── references/    opened on demand (catalog rendering, shipping & tax,
+│       │                  online payments, reviews, store settings, emails,
+│       │                  admin product form, StoreAdmin agent, security, operations)
 │       └── docs/
-│           ├── api-admin.md       admin function/entity reference
-│           └── api-storefront.md  storefront function reference (build your own shopfront)
+│           ├── entities.md        the data-model map (addressing, all 20 entities)
+│           ├── api-admin.md       admin function reference + the seed contract
+│           └── api-storefront.md  storefront function reference
 └── README.md
 ```
 
@@ -68,7 +71,7 @@ node examples/commerce/scripts/install.js
 
 From your existing Base44 app:
 
-1. **Copy the files** — either copy this whole repo into your app at `examples/commerce/` and run `node examples/commerce/scripts/install.js`, or merge `entities/`, `functions/`, `shared/` into your app's `base44/` directory by hand (see [`skills/commerce/installation-guidelines.md`](./skills/commerce/installation-guidelines.md)). Confirm your `base44/config.jsonc` `entitiesDir`/`functionsDir` point at these folders.
+1. **Copy the files** — either copy this whole repo into your app at `examples/commerce/` and run `node examples/commerce/scripts/install.js`, or merge `entities/`, `functions/`, `shared/` into your app's `base44/` directory by hand (see [`skills/commerce/install/01-install.md`](./skills/commerce/install/01-install.md)). Confirm your `base44/config.jsonc` `entitiesDir`/`functionsDir` point at these folders.
 2. **Push the schema, functions and agent:**
    ```bash
    npx base44 entities push
@@ -89,7 +92,7 @@ From your existing Base44 app:
    <Route path="/store-admin/*" element={<AdminApp />} />
    ```
 6. **Grant yourself the `admin` role** (Base44 dashboard → users, or `users.inviteUser(email, "admin")`). The admin UI refuses non-admins.
-7. **Seed the store.** Either open `/store-admin` and click **Initialize store defaults** on the first-run setup screen, or call `commerce/seed-store` directly — it creates the settings groups, the payment gateway rows (`offline` enabled, `card` off — enable it only with a provider wired) and — unless you pass your own `locations` — a fallback Shipping & Tax Location, plus the catalog: pass `products` (whole products with attributes — variants, categories, ribbons and taxonomy are created internally) or `with_sample_data: true` for the generic demo. Either way pass `store_name` (the app's name) — it is required on a first seed and becomes both the email subject prefix and the sender name. Once the `general` settings group exists the store counts as ready and the first-run screen stops appearing. Payload reference and a worked example: [`skills/commerce/post-installation.md`](./skills/commerce/post-installation.md) §2.
+7. **Seed the store.** Either open `/store-admin` and click **Initialize store defaults** on the first-run setup screen, or call `commerce/seed-store` directly — it creates the settings groups, the payment gateway rows (`offline` enabled, `card` off — enable it only with a provider wired) and — unless you pass your own `locations` — a fallback Shipping & Tax Location, plus the catalog: pass `products` (whole products with attributes — variants, categories, ribbons and taxonomy are created internally) or `with_sample_data: true` for the generic demo. Either way pass `store_name` (the app's name) — it is required on a first seed and becomes both the email subject prefix and the sender name. Once the `general` settings group exists the store counts as ready and the first-run screen stops appearing. Worked example: [`skills/commerce/install/03-data.md`](./skills/commerce/install/03-data.md); the full payload contract: [`skills/commerce/docs/api-admin.md`](./skills/commerce/docs/api-admin.md). Shipping zones are part of the same call — `locations` takes `continents: ["EU"]` and `rest_of_world: true`, so "€20 in Europe, €100 worldwide" is six lines.
 
 ## Quick start (Base44 MCP / hosted apps)
 
@@ -97,17 +100,17 @@ If you build on Base44's hosted platform, use the Base44 agent/MCP to write the
 
 1. Copy this whole repo into the target app at `examples/commerce/` (e.g. download + extract a tarball with `run_command`), then run `node examples/commerce/scripts/install.js` via `run_command` — or use `write_file` to copy every file under `base44/` and `src/commerce/` individually (use `list_directory`/`read_file` to adapt to the app's actual layout — e.g. the `@/api/base44Client` path and your router file).
 2. Wait for the app to build (`get_app_status`), then confirm entities exist (`list_entity_schemas`).
-3. Grant your user the `admin` role, then seed the store's data — one `commerce/seed-store` call takes the whole catalog via `products`, or `with_sample_data: true` for the demo catalog; leave both out for defaults only, or skip the call for the admin's first-run **Initialize store defaults** screen ([`skills/commerce/post-installation.md`](./skills/commerce/post-installation.md) §3).
+3. Grant your user the `admin` role, then seed the store's data — one `commerce/seed-store` call takes the whole catalog via `products`, or `with_sample_data: true` for the demo catalog; leave both out for defaults only, or skip the call for the admin's first-run **Initialize store defaults** screen ([`skills/commerce/install/03-data.md`](./skills/commerce/install/03-data.md)).
 
 ## What's NOT included
 
-- **No visitor/storefront UI.** The storefront **API** is complete (`commerce/storefront-*` functions); building the shopfront is up to you — see [`skills/commerce/docs/api-storefront.md`](./skills/commerce/docs/api-storefront.md). What *does* ship for the storefront is **logic, not looks**: [`src/commerce/utils/`](./src/commerce/utils/) (framework-free API client + variant-selection functions — map a Size/Color selection to a `ProductVariation` and back, per-option availability, variant price ranges) and [`src/commerce/storefront/`](./src/commerce/storefront/) (React hooks + headless pickers for the shared cart, the guided checkout with automatic shipping/tax recalculation, and the `/order-received` page — no visual components), plus [`skills/commerce/references/product-render.md`](./skills/commerce/references/product-render.md) (what to render in a grid vs. a product page, and which fields each call returns) and [`skills/commerce/references/storefront-product-page.md`](./skills/commerce/references/storefront-product-page.md), the variant rules that go with the helpers.
-- **No payment provider — and cards are off by default.** The order side of card payments is premade (see above), but charging a card needs a provider, so `commerce/seed-store` enables the manual **`offline`** method (bank transfer, cash on delivery, pickup — no code, no credentials) and leaves the **`card`** gateway **switched off**. **Enable cards only if a provider is wired, or is about to be** — implement the four functions in `base44/shared/commerce/card-payment.ts` (rules + a Stripe implementation to paste: `skills/commerce/references/online-payments.md`) and enable the gateway via the seed's `payment_methods: ["offline", "card"]`; enabled with nothing behind it, checkout answers `503 no_card_payment_provider`. The rule and why it belongs at the end of a build rather than its start: `skills/commerce/post-installation.md` §4.1.
-- **No scheduled workflows shipped.** Base44 *does* have a scheduler, but this template ships no workflow files — time-based jobs (stock-hold release, cart expiry, webhook-log pruning) run **opportunistically** where possible, and for the rest you (or the Base44 agent) create scheduled workflows that call `commerce/admin-tools`/`commerce/admin-orders` actions — see *Scheduled work* in [`skills/commerce/SKILL.md`](./skills/commerce/SKILL.md).
+- **No storefront *design*.** The parts of a shopfront that carry a brand — the home page, the collection grid, the product card, the product page's layout, the theme — ship as nothing at all, on purpose: that is the work a build should spend its effort on. Everything under those surfaces does ship: the storefront API, the hooks, and default markup for the commodity UI (checkout, cart, totals, coupon field, reviews, order-received, and the product page's internals), all restylable and replaceable — see [`skills/commerce/install/02-storefront.md`](./skills/commerce/install/02-storefront.md) for how the two tiers fit together, [`skills/commerce/references/catalog-rendering.md`](./skills/commerce/references/catalog-rendering.md) for what each catalog call returns, and [`skills/commerce/docs/api-storefront.md`](./skills/commerce/docs/api-storefront.md) for the raw API.
+- **No payment provider — and cards are off by default.** The order side of card payments is premade (see above), but charging a card needs a provider, so `commerce/seed-store` enables the manual **`offline`** method (bank transfer, cash on delivery, pickup — no code, no credentials) and leaves the **`card`** gateway **switched off**. **Enable cards only if a provider is wired, or is about to be** — implement the four functions in `base44/shared/commerce/card-payment.ts` (for Stripe, copy the shipped `card-payment.stripe.ts` over it — see `skills/commerce/references/online-payments.md`) and enable the gateway via the seed's `payment_methods: ["offline", "card"]`; enabled with nothing behind it, checkout answers `503 no_card_payment_provider`. The rule and why it belongs at the end of a build rather than its start: `skills/commerce/install/03-data.md`.
+- **No scheduled workflows shipped.** Base44 *does* have a scheduler, but this template ships no workflow files — time-based jobs (stock-hold release, cart expiry, webhook-log pruning) run **opportunistically** where possible, and for the rest you (or the Base44 agent) create scheduled workflows that call `commerce/admin-tools`/`commerce/admin-orders` actions — see [`skills/commerce/references/operations.md`](./skills/commerce/references/operations.md).
 
 ## Next steps
 
-- **Install into your app:** [`skills/commerce/installation-guidelines.md`](./skills/commerce/installation-guidelines.md)
+- **Install into your app:** [`skills/commerce/install/01-install.md`](./skills/commerce/install/01-install.md)
 - **Operate & extend:** the commerce skill — [`skills/commerce/SKILL.md`](./skills/commerce/SKILL.md)
 - **Build a storefront:** [`skills/commerce/docs/api-storefront.md`](./skills/commerce/docs/api-storefront.md)
 - **Admin automation / alternative admin:** [`skills/commerce/docs/api-admin.md`](./skills/commerce/docs/api-admin.md)

package/base44/functions/commerce/admin-reports/entry.ts

@@ -1,7 +1,7 @@
 /**
  * commerce/admin-reports — on-demand report aggregation over orders.
  * Fine to ~10k orders; larger stores should materialize stats
- * (see .agents/skills/commerce/references/limits-and-performance.md).
+ * (see .agents/skills/commerce/references/operations.md).
  *
  * Actions: summary | sales | top-sellers | stock |
  * orders-totals | products-totals | customers-totals | coupons-totals |

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

@@ -21,6 +21,27 @@
  *         payment_methods?, with_sample_data?, products?, coupons?, locations? }
  * — with_sample_data cannot be combined with the catalog keys.
  *
+ * `locations` are the store's Shipping & Tax Locations, and seeding them here is
+ * THE way to set shipping up — each is
+ *   { name, countries?: ["IL"], continents?: ["EU"], rest_of_world?: true,
+ *     regions?: [{ type, code }], order?, shipping_rates?, tax_groups?,
+ *     shipping_tax? }
+ * with `continents` taking the 7 codes from shared/commerce/data/continents.ts
+ * and `rest_of_world: true` marking the catch-all (no regions — a location
+ * cannot be both). Locations match in `order` asc and `order` defaults to the
+ * array position, so the payload reads as the priority:
+ *
+ *   locations: [
+ *     { name: "Europe", continents: ["EU"], shipping_rates: [{ name: "Standard", cost: 20 }] },
+ *     { name: "Worldwide", rest_of_world: true, shipping_rates: [{ name: "International", cost: 100 }] },
+ *   ]
+ *
+ * A payload carrying `locations` suppresses the seeded fallback (see (3)), so
+ * without a catch-all among them the store ships ONLY to the listed regions —
+ * every other address gets `shipping_not_available` at checkout. That case comes
+ * back in the response's `warnings`, which is always present and empty when
+ * there is nothing to flag.
+ *
  * `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
@@ -218,6 +239,16 @@ Deno.serve(async (req) => {
     // location the merchant never asked for (shadowed while the caller's has a
     // lower `order`, live the moment theirs is deleted or reordered). Only
     // create the default when the payload brings no locations of its own.
+    //
+    // Which makes the missing catch-all a silent trap: locations scoped to
+    // regions (say the 51 European country codes) and no fallback behind them is
+    // a store that ships to Europe and answers shipping_not_available to
+    // everyone else — plausibly intended, so not an error, but never something
+    // to discover from a customer. Say it out loud instead.
+    const warnings: string[] = [];
+    if (catalogSpec?.locations?.length && !catalogSpec.locations.some((l: any) => !l.regions?.length)) {
+      warnings.push("no_catchall_location: addresses outside your locations will get shipping_not_available — add a location with rest_of_world: true if you ship worldwide");
+    }
     if (!catalogSpec?.locations?.length) {
       const fallback = ((await sr.entities["commerce.ShippingTaxLocation"].filter({ name: REST_OF_WORLD_LOCATION.name }, undefined, 1)) ?? [])[0];
       if (!fallback) {
@@ -250,6 +281,9 @@ Deno.serve(async (req) => {
       store_name: { value: storeNameAction === "kept_existing" ? currentName : storeName, action: storeNameAction },
       currency: currencyInfo ? { value: currencyInfo.code, action: currencyAction } : null,
       payment_methods: paymentMethods,
+      // Always present so a caller can read it unconditionally; empty means the
+      // seed has nothing to flag.
+      warnings,
     });
   } catch (e) {
     if (e instanceof HttpError) return fail(e.status, e.message, e.code);

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

@@ -18,6 +18,7 @@
  *     variations?: [{ options: { Size: "S" }, regular_price?, stock_quantity?, sku?, image? }] }
  */
 import { HttpError } from "../../../shared/commerce/auth.ts";
+import { CONTINENTS } from "../../../shared/commerce/data/continents.ts";
 import { getSettings } from "../../../shared/commerce/settings.ts";
 import { scanAll } from "../../../shared/commerce/scan.ts";
 import {
@@ -172,7 +173,8 @@ export function normalizeCatalogPayload(body: any): CatalogSpec | null {
     if (!Number.isFinite(Number(c.amount)) || Number(c.amount) < 0) err(`${path}.amount`, "must be a non-negative number");
   });
 
-  const locations = rawLocations.map((l, i) => normalizeLocation(l, `locations[${i}]`, err)).filter(Boolean);
+  // The index is the location's default `order` — see normalizeLocation.
+  const locations = rawLocations.map((l, i) => normalizeLocation(l, i, `locations[${i}]`, err)).filter(Boolean);
 
   if (errors.length) throw new CatalogPayloadError(errors);
 
@@ -187,15 +189,24 @@ export function normalizeCatalogPayload(body: any): CatalogSpec | null {
 }
 
 /**
- * A caller location is Wix-shaped: countries (ISO codes) or explicit regions,
- * shipping rates, named tax groups and an optional shipping tax:
+ * A caller location is Wix-shaped: a scope (countries as ISO codes, whole
+ * continents, explicit regions, or `rest_of_world` for the catch-all), shipping
+ * rates, named tax groups and an optional shipping tax:
  *
  *   { name: "Israel", countries: ["IL"],
  *     shipping_rates: [{ name: "Standard", cost: 20, free_over: 150 }],
  *     tax_groups: [{ name: "Products", rates: [{ name: "VAT", rate: 18 }] }],
  *     shipping_tax: { type: "percent", value: 18 } }
+ *
+ * Continents spare the caller a 51-code country list, and `rest_of_world: true`
+ * names the catch-all instead of relying on empty-array magic. Locations match
+ * in `order` asc, and `order` defaults to the payload position, so the array
+ * reads as the priority — Europe first, worldwide last:
+ *
+ *   [{ name: "Europe", continents: ["EU"], shipping_rates: [{ name: "Standard", cost: 20 }] },
+ *    { name: "Worldwide", rest_of_world: true, shipping_rates: [{ name: "International", cost: 100 }] }]
  */
-function normalizeLocation(l: any, path: string, err: (p: string, e: string) => void): any | null {
+function normalizeLocation(l: any, index: number, path: string, err: (p: string, e: string) => void): any | null {
   if (!l || typeof l !== "object" || Array.isArray(l)) {
     err(path, "must be an object");
     return null;
@@ -210,9 +221,27 @@ function normalizeLocation(l: any, path: string, err: (p: string, e: string) =>
     const code = String(c ?? "").trim().toUpperCase();
     if (code) regions.push({ type: "country", code });
   }
+  for (const c of l.continents ?? []) {
+    const code = String(c ?? "").trim().toUpperCase();
+    if (!code) continue;
+    if (!CONTINENTS.some((continent) => continent.code === code)) {
+      err(`${path}.continents`, `unknown continent code: ${code} — known: ${CONTINENTS.map((continent) => `${continent.code} (${continent.name})`).join(", ")}`);
+      continue;
+    }
+    regions.push({ type: "continent", code });
+  }
   for (const r of l.regions ?? []) {
     if (r?.type && r?.code) regions.push({ type: String(r.type), code: String(r.code).toUpperCase() });
   }
+  // The catch-all is defined by having NO regions, so a scoped "rest of the
+  // world" is a contradiction, not a merge: silently dropping either half would
+  // ship a store that either over- or under-delivers shipping.
+  if (l.rest_of_world) {
+    if (regions.length) {
+      err(path, "rest_of_world is the catch-all for every address no other location matches — it cannot also be scoped with countries/continents/regions");
+    }
+    regions.length = 0;
+  }
   const slugBase = slugify(name);
   const shippingRates = (Array.isArray(l.shipping_rates) ? l.shipping_rates : []).map((r: any, i: number) => {
     const rate = { id: r?.id || `${slugBase}-${slugify(String(r?.name || `rate-${i + 1}`))}`,
@@ -241,7 +270,12 @@ function normalizeLocation(l: any, path: string, err: (p: string, e: string) =>
     if (!Number.isFinite(value) || value < 0) err(`${path}.shipping_tax.value`, "must be a non-negative number");
     shippingTax = { type, value: Number.isFinite(value) ? value : 0 };
   }
-  return { name, order: Number(l.order) || 0, regions, shipping_rates: shippingRates, tax_groups: taxGroups, shipping_tax: shippingTax };
+  // Payload position IS match priority when `order` is omitted; an explicit
+  // `order` always wins. Positions are 0,1,2… — far below the seeded fallback's
+  // 999, so "Rest of the world" stays the last location checked even when a
+  // caller's locations are added to a store that already has it.
+  const order = l.order != null && Number.isFinite(Number(l.order)) ? Number(l.order) : index;
+  return { name, order, regions, shipping_rates: shippingRates, tax_groups: taxGroups, shipping_tax: shippingTax };
 }
 
 function normalizeProduct(

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

@@ -0,0 +1,178 @@
+/**
+ * Stripe — a READY-TO-USE card payment provider. Nothing to transcribe, nothing
+ * to fill in: this file is a complete implementation of the four functions
+ * `shared/commerce/card-payment.ts` declares, in the exact shape its callers
+ * import (`payments.ts` and the premade `commerce/payment-webhook`).
+ *
+ * WIRE IT BY COPYING IT OVER THE STUB — one call, no editing:
+ *
+ *   fs.copyFileSync(
+ *     "base44/shared/commerce/card-payment.stripe.ts",
+ *     "base44/shared/commerce/card-payment.ts",
+ *   );
+ *
+ * then (1) store the merchant's Stripe **secret key** as the `STRIPE_SECRET_KEY`
+ * app secret and redeploy the backend so the functions see it, (2) register
+ * `https://<app-domain>/functions/commerce/payment-webhook` with Stripe for
+ * `checkout.session.completed` — there is no signing secret to store, see
+ * `parseWebhook` below — and (3) enable the `card` gateway
+ * (`commerce/seed-store` with `payment_methods: ["offline", "card"]`), which is
+ * what makes any of this visible at checkout.
+ *
+ * NEVER patch this file (or the stub it replaces) with partial edits. A
+ * find_replace that leaves the originals behind gives every commerce function a
+ * duplicate-export bundle error ("Multiple exports with the same name …") and
+ * the whole backend stops deploying. The fix is always the whole-file copy
+ * above — which is also why this file exists.
+ *
+ * It lives **beside** the stub rather than in a subfolder precisely so its
+ * relative imports (`./auth.ts`) are valid both here and at the copy's
+ * destination — the copy can never produce a broken specifier, and no function
+ * imports this file while it waits, so it is never bundled.
+ *
+ * A later kit update re-copies `shared/commerce/` over the app and restores the
+ * stub, so re-run the copy after updating the template.
+ *
+ * A different provider (PayPal, Adyen, a local PSP) implements these same four
+ * functions against its own API, and ships the same way —
+ * `card-payment.<provider>.ts` next to the stub. `references/online-payments.md`
+ * has the rules; this file is the worked model.
+ */
+import Stripe from "npm:stripe@18";
+import { HttpError } from "./auth.ts";
+
+/** A hosted payment page for one order. */
+export interface CardPaymentPage {
+  /** Where the customer goes to pay. */
+  url: string;
+  /** Stripe's id for this payment (the Checkout Session id), stored on the
+   * order and handed back to checkCardPaymentPaid / refundCardPayment. */
+  reference: string;
+}
+
+/**
+ * Credentials come from backend env, never an entity and never the client. Read
+ * lazily (per call, not at module load) so a store that has the file but not yet
+ * the secret answers a clean 503 at checkout instead of failing to boot every
+ * commerce function that imports it.
+ */
+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, so ×100 would
+// charge a hundred times the total.
+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));
+
+/**
+ * Create a payment page for `order.total` in `order.currency`. The customer
+ * comes back to successUrl / cancelUrl (both already carry order_id/order_key
+ * for the return page).
+ */
+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, and what checkCardPaymentPaid
+  // compares against — keep it on both objects (the session's own metadata is
+  // not copied to the payment intent).
+  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 };
+}
+
+/**
+ * Has Stripe actually received the money? Asked of Stripe's API — never of the
+ * caller. Runs on the customer-return page, the webhook's unverified path and
+ * the admin's "Check payment" button.
+ */
+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
+  // (genuinely paid) session being replayed against a different order.
+  return session.payment_status === "paid" && session.metadata?.order_id === String(order.id);
+}
+
+/**
+ * Refund `amount` (display units, e.g. 12.34) at Stripe. Called BEFORE the
+ * local refund record is written, so throwing here writes nothing.
+ */
+export async function refundCardPayment(_sr: any, _order: any, opts: {
+  reference: string;
+  amount: number;
+  currency: string;
+  reason?: string;
+}): Promise<{ refund_id: string }> {
+  // The stored reference is the Checkout Session; the refundable object is the
+  // payment intent behind it, which only exists once the session was paid.
+  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 {
+  /** The order the event is about, read from the metadata createCardPayment
+   * attached. */
+  order_id: string;
+  /** Must match the order's key, or the premade webhook rejects the event — so
+   * an event cannot be pointed at another order. */
+  order_key: string;
+  /** True ONLY after verifying the request signature over the raw payload
+   * bytes; false makes the event an unverified nudge, verified against Stripe's
+   * API instead. */
+  paid: boolean;
+  /** Stripe's payment id, ONLY from a signature-verified event; unset means the
+   * premade flow uses the reference stored on the order at checkout. */
+  reference?: string;
+}
+
+/**
+ * Stripe webhook events. The body is never trusted: this only names the order
+ * (from the metadata createCardPayment attached) and returns `paid: false`, so
+ * the premade webhook verifies with Stripe through checkCardPaymentPaid. Hence
+ * NO signing secret to store — a forged call can at worst trigger a re-check,
+ * never mark an order paid. (The optional fast path that skips the API
+ * round-trip verifies the signature and returns `paid: true` —
+ * `references/online-payments.md`.)
+ *
+ * null for anything that isn't a payment event for one of this store's orders;
+ * the premade function answers 200 so Stripe stops retrying.
+ */
+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 };
+}

package/base44/shared/commerce/scan.ts

@@ -2,7 +2,7 @@
  * Full-collection scan helper. Base44's filter() is exact-match with a 5k page
  * cap and no total count, so server-side search/aggregation loops pages of 500.
  * Keep `cap` sane — reports over very large stores should move to a
- * materialized stats entity (see .agents/skills/commerce/references/limits-and-performance.md).
+ * materialized stats entity (see .agents/skills/commerce/references/operations.md).
  */
 
 export interface ScanOpts {

package/base44/shared/commerce/sequence.ts

@@ -4,7 +4,7 @@
  * NOTE ON CONCURRENCY: Base44 has no transactions, so nextOrderNumber() is a
  * read-max-then-increment and two simultaneous checkouts could race. The window
  * is tiny and order ids (not numbers) are the primary key; see
- * .agents/skills/commerce/references/limits-and-performance.md for mitigations.
+ * .agents/skills/commerce/references/operations.md for mitigations.
  */
 
 const ORDER_NUMBER_START = 1001;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44/app-plugin-commerce",
-  "version": "0.1.20",
+  "version": "0.2.1",
   "description": "Base44 Commerce plugin — entities, backend functions, shared commerce engine, admin UI and the commerce skill, shipped as copyable source",
   "keywords": [
     "base44",

package/scripts/install.js

@@ -25,12 +25,11 @@
  * overwritten (so re-running after a template update is safe), everything
  * else in the app is left untouched.
  *
- * This is only the static part of the install. The remaining steps live in
- * ../skills/commerce/installation-guidelines.md (deps, deploy, seeding) and
- * ../skills/commerce/post-installation.md (mounting the /store-admin route, admin
- * role, seeding, the storefront quick start); day-2 guidance starts at
- * ../skills/commerce/SKILL.md. The skill folder carries all of this
- * documentation into the app.
+ * This is only the static part of the install. Everything after it lives in
+ * ../skills/commerce/install/01-install.md (deps, the /store-admin mount, the
+ * admin-role gating), which routes on to 02-storefront.md and 03-data.md at the
+ * right moments; ../skills/commerce/SKILL.md is the map for all later work. The
+ * skill folder carries all of that documentation into the app.
  *
  * Written with dynamic import() and process.argv[1] (instead of require/
  * __dirname) so it runs unchanged whether the host app's package.json is
@@ -132,6 +131,17 @@
     ["src", "commerce", "admin", "pages", "settings", "TaxRatesTable.jsx"],
     ["src", "commerce", "admin", "pages", "settings", "ShippingSettings.jsx"],
     ["src", "commerce", "admin", "pages", "settings", "ShippingZoneEditor.jsx"],
+    // The skill's docs were restructured into stage files (install/01..03) plus a
+    // smaller reference set. Stale guidance is worse than none — agents read
+    // whatever is in .agents/skills/ — so every retired doc goes, by name.
+    [".agents", "skills", "commerce", "post-installation.md"],        // → install/01..03
+    [".agents", "skills", "commerce", "installation-guidelines.md"],  // → install/01-install.md + references/store-admin-agent.md
+    [".agents", "skills", "commerce", "references", "product-render.md"],           // → references/catalog-rendering.md
+    [".agents", "skills", "commerce", "references", "storefront-product-page.md"],  // → references/catalog-rendering.md
+    [".agents", "skills", "commerce", "references", "scheduled-work.md"],           // → references/operations.md
+    [".agents", "skills", "commerce", "references", "limits-and-performance.md"],   // → references/operations.md
+    [".agents", "skills", "commerce", "references", "webhooks.md"],                 // → references/operations.md
+    [".agents", "skills", "commerce", "references", "media-and-downloads.md"],      // → docs/api-storefront.md + install/03-data.md
   ];
   let retiredRemoved = 0;
   for (const parts of RETIRED) {
@@ -186,16 +196,16 @@
     (retiredRemoved ? ` (${retiredRemoved} retired file${retiredRemoved === 1 ? "" : "s"} removed)` : ""),
   );
   console.log(
-    "\nNext steps (see .agents/skills/commerce/installation-guidelines.md + post-installation.md):\n" +
+    "\nNext: read .agents/skills/commerce/install/01-install.md and follow it.\n" +
+    "It is the whole install, and it says when to open 02-storefront.md and\n" +
+    "03-data.md — read nothing else up front.\n" +
+    "\n" +
     "  1. No deps to add: sonner, recharts and react-markdown ship with the default\n" +
-    "     Base44 template — check package.json and npm i only what is truly missing;\n" +
-    "     do not re-install packages already listed as dependencies\n" +
+    "     Base44 template — check package.json and npm i only what is truly missing\n" +
     '  2. Mount the admin router: <Route path="/store-admin/*" element={<AdminApp />} />\n' +
-    "     and implement the payment return page /order-received — one hook,\n" +
-    "     useOrderReturn from @/commerce/storefront (post-installation.md)\n" +
-    "  3. Grant your user the admin role, then seed the store's data — one commerce/seed-store\n" +
-    "     call (store_name required) takes the whole catalog via products, or the demo data\n" +
-    "     via with_sample_data, or defaults only (post-installation.md §3)\n" +
+    "     plus the mandatory /order-received route (<OrderReceivedBlock/>)\n" +
+    "  3. Seed the store — one commerce/seed-store call (store_name required) takes the\n" +
+    "     catalog, currency, shipping locations and payment methods\n" +
     "  4. CLI installs only: npx base44 agents push (the hosted runtime syncs agents on write)"
   );
 })();