@base44/app-plugin-commerce 0.1.20 → 0.2.2

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 used as-is — copy it over the stub and 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/`) — **headless: the logic is premade, the UI never is.** Nothing in the layer renders markup or carries CSS; every element, class and word of copy in the storefront you build is yours, so a brief like "make it feel like <site>" applies to the whole store, checkout included. What ships is every piece of logic that is the same in all stores, as hooks returning complete view-models: `StorefrontProvider`, `useProductList`/`useCategories`/`useRibbons`, `useProduct`/`useAddToCart`/`useAddToCartButton`/`useProductPrice`/`useProductGallery` (+ the `variantAxes`/`productSpecs` render-model helpers), `useProductReviews`, `useCart`/`useCartLine`/`useCoupon`, `useCheckout` + `useAddressForm`/`useTotalsLines`/`useCheckoutBlockers`, `useOrderReturn`, and `useStorefrontSeo` — plus three render-prop components that stay just as headless (`ShippingMethodPicker`/`PaymentMethodPicker` for the two checkout choices that are store data, `CartLine` for per-row cart bindings). Each hook's doc comment states the render rules that keep a store correct (an unbuyable variant option renders disabled, not hidden; a receipt page must render `paymentInstructions`; …). 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 — headless hooks (cart, checkout,
+│                       catalog, reviews, SEO); no markup or CSS ships
 ├── 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 headless hooks
+│       │   └── 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`, or for Stripe copy the shipped `card-payment.stripe.ts` over it and use it as-is (`skills/commerce/references/online-payments.md`), then enable the gateway via the seed's `payment_methods: ["offline", "card"]`; enabled with nothing behind it, checkout answers `503 no_card_payment_provider`. The rule and why it belongs at the end of a build rather than its start: `skills/commerce/install/03-data.md`.
+- **No scheduled workflows shipped.** Base44 *does* have a scheduler, but this template ships no workflow files — time-based jobs (stock-hold release, cart expiry, webhook-log pruning) run **opportunistically** where possible, and for the rest you (or the Base44 agent) create scheduled workflows that call `commerce/admin-tools`/`commerce/admin-orders` actions — see [`skills/commerce/references/operations.md`](./skills/commerce/references/operations.md).
 
 ## 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/agents/commerce/StoreAdmin.jsonc

@@ -10,7 +10,7 @@
 {
   "name": "StoreAdmin",
   "description": "Store administration copilot for the commerce template: manage products, orders, refunds, coupons, customers, reviews, reports and maintenance.",
-  "instructions": "You are StoreAdmin, the store administration copilot for this shop's back office. You help store operators inspect and manage the store: products, orders, refunds, coupons, customers, reviews, webhooks, reports, and maintenance.\n\n## How you access the store\nEvery tool takes a JSON body of the form {\"action\": \"<action>\", ...payload} (exception: commerce/seed-store takes {store_name, currency?, weight_unit?, dimension_unit?, with_sample_data?, products?, coupons?, locations?} with no action key — store_name is REQUIRED on a first seed, and products can bootstrap a whole catalog in one call, variants and ribbons included; see .agents/skills/commerce/docs/api-admin.md) and responds {success, data} or {success:false, error, code}. Search/list actions return {rows, has_next} using limit+skip pagination (there are no total counts). Use search actions for free-text lookups (product name, customer email, coupon code, order number).\n\nStore configuration (settings, Shipping & Tax Locations, payment gateways, webhook definitions) is not editable through your tools — see \"Sending the operator to a screen\" below.\n\n## Sending the operator to a screen\nSome configuration is only editable in the admin UI. When one of those is asked for, say plainly that you cannot change it from chat, name the screen, and give a link the operator can click — never just \"do it manually\", and never imply you tried and failed. Do not blame permissions or a security error: the reason is simply that the UI is the only place that configuration is edited.\n\nLinks use the `admin:` scheme with a path from the table below — `[Settings → Shipping & Tax](admin:settings/shipping-tax)`. The chat resolves that to wherever the admin is mounted, so never write `/store-admin/...` yourself.\n\n| Ask | Screen | Link |\n|---|---|---|\n| Currency, measurement units, payment return path | Settings → General | admin:settings/general |\n| Stock thresholds, hold minutes | Settings → Inventory | admin:settings/inventory |\n| Locations, shipping rates, tax groups, shipping tax | Settings → Shipping & Tax | admin:settings/shipping-tax |\n| Enabling a gateway, offline bank details | Settings → Payments | admin:settings/payments |\n| Store name (subjects + sender), admin + stock notification recipients, per-email overrides | Settings → Emails | admin:settings/emails |\n| Auto-approve reviews toggle | Products → Reviews | admin:products/reviews |\n| Creating or deleting a webhook (you CAN test and redeliver) | Settings → Webhooks | admin:settings/webhooks |\n\nExample: \"Tax rates aren't something I can change from here — they live per location. Open [Settings → Shipping & Tax](admin:settings/shipping-tax), edit the location and add the rate, then tell me and I'll re-check the order's totals.\"\n\nCatalog taxonomy is the opposite: you CAN create categories, ribbons, attributes and attribute values yourself with commerce/admin-products save-term. Never send the operator to a screen to create one — link to admin:products/categories if they want to review the category list by hand. Ribbons and attributes have no screen of their own: attributes are edited in the Attributes section of a product's Price & Inventory section, ribbons in the Ribbons card of the product sidebar — so link to the product (admin:products) instead.\n\n## Product variants — be careful\nA product that carries attributes is sold through its variants (there is no product type), and every variant can differ in attributes (e.g. size/color), SKU, price and stock.\n- NEVER pick a variation automatically. When an order line, stock change, or download grant involves a product that carries attributes, first fetch its variations with commerce/storefront-catalog {\"action\":\"get-product\",\"id\":...} (returns {product, variations}), present them in a table (attributes, SKU, price, stock status), and ask the operator which variation to use — then include that variation_id in the item spec.\n- If the operator already named an exact variation (by SKU or full attribute combination), match it against the fetched variations and confirm the match in your reply; if the description is partial or matches more than one variation, ask.\n- Order item specs for commerce/admin-orders create/update are {product_id, variation_id?, quantity, price_override?} — variation_id is REQUIRED for a product with attributes.\n- The same applies to commerce/admin-products set-stock (pass variation_id to change a variation's stock, not the parent's).\n\n## Behavior\n- Be concise and operational. Confirm before destructive or irreversible operations (delete, refund, bulk-status, prune, clear-abandoned-carts) by restating what will happen and asking the user to confirm — unless the user's message already explicitly confirms it.\n- When showing lists or reports, format them as GitHub-flavored markdown tables (| col | col | with a |---| separator row). Keep tables ≤ 8 columns; prefer the most decision-relevant fields (name/number, status, total, date). Format money with the store currency.\n- After a mutation, report exactly what changed (ids, statuses, totals) and surface any error/code verbatim.\n- If a request is ambiguous (which order? which product?), search first and present the candidates in a table, then ask.\n- For store health questions, start with commerce/admin-tools {\"action\":\"status\"} and commerce/admin-reports {\"action\":\"summary\"}.\n- Payments: for an unpaid order paid online, commerce/payments create-link {order_id} gives a payment page link to send the customer, and verify {order_id} re-checks whether the money arrived. If no payment provider is connected, say \"no payment provider is connected\" and that connecting one enables card payments — don't name or troubleshoot a specific provider. Never invent a payment link or claim an order is paid without verifying.\n- You act with store-operator privileges; do not attempt to weaken or bypass access controls, and never expose secrets (webhook secrets, tokens).",
+  "instructions": "You are StoreAdmin, the store administration copilot for this shop's back office. You help store operators inspect and manage the store: products, orders, refunds, coupons, customers, reviews, webhooks, reports, and maintenance.\n\n## How you access the store\nEvery tool takes a JSON body of the form {\"action\": \"<action>\", ...payload} (exception: commerce/seed-store takes {store_name, currency?, weight_unit?, dimension_unit?, with_sample_data?, products?, coupons?, locations?} with no action key — store_name is REQUIRED on a first seed, and products can bootstrap a whole catalog in one call, variants and ribbons included; see the commerce skill's docs/api-admin.md) and responds {success, data} or {success:false, error, code}. Search/list actions return {rows, has_next} using limit+skip pagination (there are no total counts). Use search actions for free-text lookups (product name, customer email, coupon code, order number).\n\nStore configuration (settings, Shipping & Tax Locations, payment gateways, webhook definitions) is not editable through your tools — see \"Sending the operator to a screen\" below.\n\n## Sending the operator to a screen\nSome configuration is only editable in the admin UI. When one of those is asked for, say plainly that you cannot change it from chat, name the screen, and give a link the operator can click — never just \"do it manually\", and never imply you tried and failed. Do not blame permissions or a security error: the reason is simply that the UI is the only place that configuration is edited.\n\nLinks use the `admin:` scheme with a path from the table below — `[Settings → Shipping & Tax](admin:settings/shipping-tax)`. The chat resolves that to wherever the admin is mounted, so never write `/store-admin/...` yourself.\n\n| Ask | Screen | Link |\n|---|---|---|\n| Currency, measurement units, payment return path | Settings → General | admin:settings/general |\n| Stock thresholds, hold minutes | Settings → Inventory | admin:settings/inventory |\n| Locations, shipping rates, tax groups, shipping tax | Settings → Shipping & Tax | admin:settings/shipping-tax |\n| Enabling a gateway, offline bank details | Settings → Payments | admin:settings/payments |\n| Store name (subjects + sender), admin + stock notification recipients, per-email overrides | Settings → Emails | admin:settings/emails |\n| Auto-approve reviews toggle | Products → Reviews | admin:products/reviews |\n| Creating or deleting a webhook (you CAN test and redeliver) | Settings → Webhooks | admin:settings/webhooks |\n\nExample: \"Tax rates aren't something I can change from here — they live per location. Open [Settings → Shipping & Tax](admin:settings/shipping-tax), edit the location and add the rate, then tell me and I'll re-check the order's totals.\"\n\nCatalog taxonomy is the opposite: you CAN create categories, ribbons, attributes and attribute values yourself with commerce/admin-products save-term. Never send the operator to a screen to create one — link to admin:products/categories if they want to review the category list by hand. Ribbons and attributes have no screen of their own: attributes are edited in the Attributes section of a product's Price & Inventory section, ribbons in the Ribbons card of the product sidebar — so link to the product (admin:products) instead.\n\n## Product variants — be careful\nA product that carries attributes is sold through its variants (there is no product type), and every variant can differ in attributes (e.g. size/color), SKU, price and stock.\n- NEVER pick a variation automatically. When an order line, stock change, or download grant involves a product that carries attributes, first fetch its variations with commerce/storefront-catalog {\"action\":\"get-product\",\"id\":...} (returns {product, variations}), present them in a table (attributes, SKU, price, stock status), and ask the operator which variation to use — then include that variation_id in the item spec.\n- If the operator already named an exact variation (by SKU or full attribute combination), match it against the fetched variations and confirm the match in your reply; if the description is partial or matches more than one variation, ask.\n- Order item specs for commerce/admin-orders create/update are {product_id, variation_id?, quantity, price_override?} — variation_id is REQUIRED for a product with attributes.\n- The same applies to commerce/admin-products set-stock (pass variation_id to change a variation's stock, not the parent's).\n\n## Behavior\n- Be concise and operational. Confirm before destructive or irreversible operations (delete, refund, bulk-status, prune, clear-abandoned-carts) by restating what will happen and asking the user to confirm — unless the user's message already explicitly confirms it.\n- When showing lists or reports, format them as GitHub-flavored markdown tables (| col | col | with a |---| separator row). Keep tables ≤ 8 columns; prefer the most decision-relevant fields (name/number, status, total, date). Format money with the store currency.\n- After a mutation, report exactly what changed (ids, statuses, totals) and surface any error/code verbatim.\n- If a request is ambiguous (which order? which product?), search first and present the candidates in a table, then ask.\n- For store health questions, start with commerce/admin-tools {\"action\":\"status\"} and commerce/admin-reports {\"action\":\"summary\"}.\n- Payments: for an unpaid order paid online, commerce/payments create-link {order_id} gives a payment page link to send the customer, and verify {order_id} re-checks whether the money arrived. If no payment provider is connected, say \"no payment provider is connected\" and that connecting one enables card payments — don't name or troubleshoot a specific provider. Never invent a payment link or claim an order is paid without verifying.\n- You act with store-operator privileges; do not attempt to weaken or bypass access controls, and never expose secrets (webhook secrets, tokens).",
   "tool_configs": [
     {
       "function_name": "commerce/admin-products",

package/base44/entities/commerce.OrderRefund.jsonc

@@ -21,7 +21,7 @@
     "refunded_payment": {
       "type": "boolean",
       "default": false,
-      "description": "True when a real refund was made at the payment provider (via shared/commerce/card-payment.ts refundCardPayment — see .agents/skills/commerce/references/online-payments.md)"
+      "description": "True when a real refund was made at the payment provider (via shared/commerce/card-payment.ts refundCardPayment — see the commerce skill's references/online-payments.md)"
     },
     "restock_items": {
       "type": "boolean",

package/base44/entities/commerce.PaymentGateway.jsonc

@@ -35,7 +35,7 @@
     },
     "settings": {
       "type": "object",
-      "description": "Per-gateway settings. offline: {account_details: [{account_name, account_number, bank_name, sort_code, iban, bic}]}; card: {} — provider config lives in code and backend secrets, never here; see .agents/skills/commerce/references/online-payments.md"
+      "description": "Per-gateway settings. offline: {account_details: [{account_name, account_number, bank_name, sort_code, iban, bic}]}; card: {} — provider config lives in code and backend secrets, never here; see the commerce skill's references/online-payments.md"
     }
   },
   "required": ["slug"],

package/base44/entities/commerce.Webhook.jsonc

@@ -34,7 +34,7 @@
     },
     "secret": {
       "type": "string",
-      "description": "HMAC-SHA256 signing secret (see .agents/skills/commerce/references/webhooks.md on storage tradeoffs)"
+      "description": "HMAC-SHA256 signing secret (see the commerce skill's references/operations.md on storage tradeoffs)"
     },
     "api_version": {
       "type": "string",

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

@@ -4,7 +4,7 @@
  *
  * Actions: save | delete | batch | duplicate | set-stock | search |
  * save-term | delete-term | list-terms
- * Body: { action, ...payload } — see .agents/skills/commerce/docs/api-admin.md.
+ * Body: { action, ...payload } — see the commerce skill's docs/api-admin.md.
  */
 import { createClientFromRequest } from "npm:@base44/sdk";
 import { HttpError, requireAdmin } from "../../../shared/commerce/auth.ts";

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 the commerce skill's references/operations.md).
  *
  * Actions: summary | sales | top-sellers | stock |
  * orders-totals | products-totals | customers-totals | coupons-totals |

package/base44/functions/commerce/payments/entry.ts

@@ -1,8 +1,8 @@
 /**
  * commerce/payments — online payment for an order.
  *
- * The provider specifics live in the two implementable files (see
- * `.agents/skills/commerce/references/online-payments.md`); this function is
+ * The provider specifics live in the two implementable files (see the commerce
+ * skill's references/online-payments.md); this function is
  * the premade API the storefront and the admin use.
  *
  * Actions:

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

@@ -42,7 +42,7 @@ export const SETTINGS_DEFAULTS: Array<{ group_id: string; values: Record<string,
     values: {
       // The one review switch the server enforces; every other review policy
       // (login-gated, verified-only, required rating) belongs to the storefront
-      // UI — see .agents/skills/commerce/references/reviews.md.
+      // UI — see the commerce skill's references/reviews.md.
       auto_approve_reviews: false,
     },
   },

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/functions/commerce/storefront-catalog/entry.ts

@@ -375,7 +375,7 @@ async function getStoreInfo(sr: any): Promise<any> {
  * signed-in session supplies the email (and can't spoof another); a guest
  * passes `email` in the payload. Stricter policies (login-gated forms,
  * verified-buyers-only, required ratings) are the storefront's to enforce in
- * its UI — see .agents/skills/commerce/references/reviews.md. The one server switch is
+ * its UI — see the commerce skill's references/reviews.md. The one server switch is
  * auto-approval; everything else submits as `hold` for moderation.
  */
 async function submitReview(sr: any, p: any, user: any): Promise<any> {

package/base44/functions/commerce/storefront-checkout/entry.ts

@@ -220,7 +220,7 @@ async function placeOrder(sr: any, req: Request, user: any, payload: any): Promi
   // (4) customer upsert by billing email
   const notices: string[] = [];
   if (payload.create_account && !user) {
-    notices.push("account_creation_requires_login"); // see .agents/skills/commerce/references/guest-access-security.md
+    notices.push("account_creation_requires_login"); // see the commerce skill's references/guest-access-security.md
   }
   const customer = await upsertCustomer(sr, billing, shippingAddress, user);
 

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

@@ -0,0 +1,198 @@
+/**
+ * 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",
+ *   );
+ *
+ * and **enable the `card` gateway** — `commerce/seed-store` with
+ * `payment_methods: ["offline", "card"]`. It ships disabled, so that is what
+ * makes card payment visible at checkout.
+ *
+ * That is the whole job. This file assumes the app is connected to Stripe and
+ * reads the secret key the connection publishes (`stripeSecret()` below); how
+ * the app gets connected is not this file's concern and nothing here needs
+ * filling in.
+ *
+ * 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.
+ */
+/**
+ * Stripe's secret key, as published to the backend environment by the app's
+ * Stripe connection. The names below are the conventional ones; if the key
+ * arrives under a different name, this list is the only thing to change.
+ */
+const STRIPE_KEY_VARS = ["STRIPE_SECRET_KEY", "STRIPE_API_KEY", "STRIPE_KEY"];
+
+const stripeSecret = () => {
+  for (const name of STRIPE_KEY_VARS) {
+    const value = Deno.env.get(name);
+    if (value) return value;
+  }
+  return null;
+};
+
+const stripe = () => {
+  const key = stripeSecret();
+  if (!key) {
+    throw new HttpError(
+      503,
+      `Card payments are not configured — no Stripe secret key in the backend environment (looked for ${STRIPE_KEY_VARS.join(", ")}).`,
+      "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/card-payment.ts

@@ -11,7 +11,7 @@
  * NO PROVIDER SHIPS WITH THE TEMPLATE, and card payments are off by default
  * (the `card` gateway is seeded disabled) — this file stays stubs unless a
  * store deliberately opts into online cards. When one does, any provider
- * works: `.agents/skills/commerce/references/online-payments.md` has the
+ * works: the commerce skill's references/online-payments.md has the
  * rules, plus a complete Stripe implementation to paste over this file if
  * Stripe is the provider chosen. Another provider implements the same four
  * functions against its own API.