@base44/app-plugin-commerce 0.1.8 → 0.1.12

package/README.md

@@ -8,10 +8,10 @@ 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).
-- **Online card payments, order side premade** — checkout routing, payment links for unpaid orders, two idempotent confirmation paths (customer return + webhook) and refund records are all built. Wiring a provider (Stripe, PayPal, a local PSP…) means implementing **exactly two files** — `base44/shared/commerce/card-payment.ts` and the payment webhook — and nothing else. Every other payment option is manual (on-hold + instructions) and needs no code; the admin can add more in Settings → Payments. See [`skills/commerce/references/online-payments.md`](./skills/commerce/references/online-payments.md).
+- **Online card payments, order side premade** — checkout routing, payment links for unpaid orders, two idempotent confirmation paths (customer return + webhook, both premade) and refund records are all built. Wiring a provider (Stripe, PayPal, a local PSP…) means implementing **four functions in one file** — `base44/shared/commerce/card-payment.ts` — and nothing else; a complete Stripe implementation to paste in ships in [`skills/commerce/post-installation.md`](./skills/commerce/post-installation.md) §2.2. Every other payment option is manual (on-hold + instructions) and needs no code; the admin can add more in Settings → Payments. See [`skills/commerce/references/online-payments.md`](./skills/commerce/references/online-payments.md).
 - **Shared commerce engine** (`base44/shared/commerce/`) — totals, tax, shipping, coupons, stock, order lifecycle, webhook dispatch (HMAC-signed), emails, card-payment plumbing, plus static country/currency/continent data.
 - **Admin UI** (`src/commerce/admin/`) — a React/Tailwind/shadcn admin with a familiar store back-office information architecture: dashboard, orders, products, coupons, customers, reports, and full settings including webhooks. Admin-role gated.
-- **Storefront helpers** (`src/commerce/utils/`) — framework-free, dependency-free functions for the shopfront you build: `variants.js` maps an attribute selection (Size, Color) onto a `ProductVariation` and back, plus per-option availability and variant price ranges; `shipping-promos.js` reads the store's real free-shipping configuration so "Free shipping over €150" copy states a configured rule rather than an invented number. See [`skills/commerce/references/storefront-product-page.md`](./skills/commerce/references/storefront-product-page.md).
+- **Storefront helpers** (`src/commerce/utils/`) — framework-free, dependency-free modules for the shopfront you build: `storefront.js` is the API client (`createStorefront(base44)` — cart-token lifecycle, cached store-info, catalog/cart/checkout/return-page calls); `variants.js` maps an attribute selection (Size, Color) onto a `ProductVariation` and back, plus per-option availability and variant price ranges; `shipping-promos.js` reads the store's real free-shipping configuration so "Free shipping over €150" copy states a configured rule rather than an invented number. See [`skills/commerce/references/storefront-product-page.md`](./skills/commerce/references/storefront-product-page.md).
 - **StoreAdmin agent + bot** — an AI copilot (`base44/agents/commerce/StoreAdmin.jsonc`, registered as `commerce/StoreAdmin`) with the `commerce/*` functions attached directly as tools (calls run as the chatting user → `requireAdmin()` still applies), variant-aware order editing, plus a chat panel in the admin sidebar with GFM markdown-table rendering.
 - **Docs** — this README plus the commerce skill folder [`skills/commerce/`](./skills/commerce/), which holds [`SKILL.md`](./skills/commerce/SKILL.md) (the short map agents start from), [`installation-guidelines.md`](./skills/commerce/installation-guidelines.md), [`post-installation.md`](./skills/commerce/post-installation.md), per-topic guides in [`references/`](./skills/commerce/references/) and the API references in [`docs/`](./skills/commerce/docs/) — the whole folder is installed into the app at `.agents/skills/commerce/` so agents pick it up natively.
 
@@ -99,7 +99,7 @@ If you build on Base44's hosted platform, use the Base44 agent/MCP to write the
 ## 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 **helper logic**: [`src/commerce/utils/`](./src/commerce/utils/) — framework-free variant-selection functions (map a Size/Color selection to a `ProductVariation` and back, per-option availability, variant price ranges) — 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** — the order side of card payments is premade (see above), but charging a card needs a provider: implement the two payment files to wire one. Until then the card option answers "card payments are not available yet" at checkout (or switch it off in Settings → Payments), and the manual gateways (bank transfer, cash on delivery, anything the admin adds) carry checkout.
+- **No payment provider** — the order side of card payments is premade (see above), but charging a card needs a provider: implement the four functions in `base44/shared/commerce/card-payment.ts` to wire one (Stripe: paste-in in `skills/commerce/post-installation.md` §2.2). Until then the card option answers "card payments are not available yet" at checkout (or switch it off in Settings → Payments), and the manual gateways (bank transfer, cash on delivery, anything the admin adds) carry checkout.
 - **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).
 
 ## Next steps

package/base44/entities/commerce.Order.jsonc

@@ -84,7 +84,7 @@
     },
     "payment_method": {
       "type": "string",
-      "description": "PaymentGateway slug (e.g. offline|stripe)"
+      "description": "PaymentGateway slug (e.g. offline|card)"
     },
     "payment_method_title": {
       "type": "string",

package/base44/entities/commerce.OrderRefund.jsonc

@@ -21,7 +21,7 @@
     "refunded_payment": {
       "type": "boolean",
       "default": false,
-      "description": "True when a real gateway refund was made (Stripe wiring placeholder — 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 .agents/skills/commerce/references/online-payments.md)"
     },
     "restock_items": {
       "type": "boolean",

package/base44/entities/commerce.PaymentGateway.jsonc

@@ -1,12 +1,12 @@
 {
   "name": "commerce.PaymentGateway",
   "type": "object",
-  "description": "Payment gateway configuration. Seeded: offline (settled outside the store) and stripe (processed by commerce/payments + commerce/payment-webhook). Secrets are never stored here; use Base44 secrets.",
+  "description": "Payment gateway configuration. Seeded: offline (settled outside the store) and card (processed by commerce/payments + commerce/payment-webhook via shared/commerce/card-payment.ts). Secrets are never stored here; use Base44 secrets.",
   "properties": {
     "slug": {
       "type": "string",
       "minLength": 1,
-      "description": "Unique gateway id, e.g. offline | stripe"
+      "description": "Unique gateway id, e.g. offline | card"
     },
     "title": {
       "type": "string",
@@ -35,7 +35,7 @@
     },
     "settings": {
       "type": "object",
-      "description": "Per-gateway settings. offline: {account_details: [{account_name, account_number, bank_name, sort_code, iban, bic}]}; stripe: {connector: \"stripe\"} — 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 .agents/skills/commerce/references/online-payments.md"
     }
   },
   "required": ["slug"],

package/base44/functions/commerce/payment-webhook/entry.ts

@@ -1,66 +1,52 @@
 /**
- * commerce/payment-webhook — file 2 of 2 to implement when wiring a payment
- * provider. File 1 is `base44/shared/commerce/card-payment.ts`.
+ * commerce/payment-webhook — the provider's server-to-server payment callback.
+ * PREMADE: wiring a payment provider does NOT mean editing this file. All
+ * provider-specific logic — including validating the incoming event — lives
+ * in `base44/shared/commerce/card-payment.ts` (`parseWebhook`), the one file
+ * to implement.
  *
- * This is the provider's server-to-server callback — the confirmation path
- * that covers the buyer who pays and closes the tab (the other path is the
- * customer returning to the storefront, which calls `commerce/payments`
- * `complete-return`; both are idempotent, whichever arrives second does
- * nothing).
+ * Trust model: an event body is never believed on its own. `parseWebhook`
+ * names the order (from the metadata `createCardPayment` attached) and only
+ * vouches `paid: true` after real signature verification; otherwise the event
+ * is a nudge and whether money arrived is asked of the provider itself
+ * through `checkCardPaymentPaid`. Either way a forged call can never mark an
+ * order paid, and the `order_key` match below stops an event being pointed
+ * at another order.
  *
- * Implement ONLY `parseWebhook` below. Everything after it is premade: the
- * order lookup, the order_key check, the idempotent confirmation and the
- * order progression (stock, emails, download permissions, store webhooks).
+ * This is one of the two idempotent confirmation paths — it covers the buyer
+ * who pays and closes the tab; the other is the customer returning to the
+ * storefront, which calls `commerce/payments` `complete-return`. Whichever
+ * runs second is a no-op. Register this function's URL with the provider
+ * (e.g. a Stripe webhook endpoint for `checkout.session.completed`).
  *
  * Unlike every other function here this takes the provider's **raw body**
  * rather than an `{action, ...}` envelope, because webhook signatures are
  * computed over those exact bytes.
  *
- * Until implemented, every request answers 400 `webhook_not_implemented`.
+ * Until `parseWebhook` is implemented, every request answers
+ * 400 `webhook_not_implemented`.
  */
 import { createClientFromRequest } from "npm:@base44/sdk";
+import { HttpError } from "../../../shared/commerce/auth.ts";
 import { getSettings } from "../../../shared/commerce/settings.ts";
 import { confirmCardPayment } from "../../../shared/commerce/payments.ts";
+import { parseWebhook } from "../../../shared/commerce/card-payment.ts";
 
 /** Providers retry on non-2xx; answer 200 for anything we deliberately ignore. */
 const ok = (data: unknown, status = 200) => Response.json({ success: true, data }, { status });
 const fail = (status: number, error: string, code: string) =>
   Response.json({ success: false, error, code }, { status });
 
-interface CardWebhookEvent {
-  /** The order the event is about — read it from the event's metadata. */
-  order_id: string;
-  /** Must match the order's key; attach both to the payment when creating it. */
-  order_key: string;
-  /**
-   * Set true ONLY when you verified the request signature AND the event says
-   * the payment succeeded. When false, the event is treated as a nudge naming
-   * an order, and whether money arrived is asked of the provider through
-   * `checkCardPaymentPaid` — useful when no signing secret is available.
-   */
-  paid: boolean;
-  /** The provider's payment id, if the event carries one. */
-  reference?: string;
-}
-
-/**
- * ← IMPLEMENT THIS for your provider: verify the signature (over the raw
- * `payload` bytes) and pull out the order reference. Return null for events
- * that aren't about a payment for one of this store's orders.
- */
-async function parseWebhook(_req: Request, _payload: string): Promise<CardWebhookEvent | null> {
-  return null;
-}
-
 Deno.serve(async (req: Request) => {
   try {
     const payload = await req.text();
 
     const event = await parseWebhook(req, payload);
-    if (!event) {
-      return fail(400, "This store's payment webhook is not implemented.", "webhook_not_implemented");
+    // Not about one of this store's orders — acknowledge so the provider
+    // doesn't retry.
+    if (!event || !event.order_id) {
+      return ok({ ignored: true, reason: "no_order_reference" });
     }
-    if (!event.order_id) return ok({ ignored: true, reason: "no_order_reference" });
 
     const base44 = createClientFromRequest(req);
     const sr = base44.asServiceRole;
@@ -89,6 +75,9 @@ Deno.serve(async (req: Request) => {
       status: result.order.status,
     });
   } catch (e) {
+    if (e instanceof HttpError) {
+      return fail(e.status, e.message, e.code ?? "error");
+    }
     // 500 makes the provider retry, which is what we want for a transient failure.
     console.error("commerce/payment-webhook error:", e);
     return fail(500, (e as Error)?.message ?? "Internal error", "internal_error");

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

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

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

@@ -1,14 +1,31 @@
 /**
- * Card payments — file 1 of 2 to implement when wiring a payment provider
- * (Stripe, PayPal, Adyen, a local PSP…). File 2 is the webhook:
- * `base44/functions/commerce/payment-webhook/entry.ts`.
+ * Card payments — the ONE file to implement when wiring a payment provider
+ * (Stripe, PayPal, Adyen, a local PSP…). Implement the four functions below;
+ * no other file changes:
  *
- * Everything around these three functions is already built: checkout creates
- * the order, prices it, holds stock and routes the customer to the URL you
- * return; the webhook and the return page confirm payment idempotently and
- * move the order to processing (stock, emails, download permissions, webhooks
- * all fire from there); admin refunds write the refund record and restock.
- * Implement ONLY the provider calls below — no other file needs to change.
+ *   createCardPayment    → checkout + payment links (hosted payment page)
+ *   checkCardPaymentPaid → confirmation (return page, webhook, admin "Check payment")
+ *   refundCardPayment    → admin refunds through the provider
+ *   parseWebhook         → validate the provider's server-to-server event
+ *
+ * Any provider works; a ready-made reference implementation (Stripe) is in
+ * `.agents/skills/commerce/post-installation.md` §2.2 to paste over this
+ * file — another provider implements the same functions against its own API.
+ *
+ * REPLACE THIS FILE WHOLE (one write of the full new content). Never
+ * find_replace into these stubs: a partial patch leaves the originals behind
+ * and every commerce function fails to deploy with duplicate-export bundle
+ * errors ("Multiple exports with the same name ...") — the fix is always to
+ * rewrite the file whole.
+ *
+ * Everything around these functions is already built: checkout creates the
+ * order, prices it, holds stock and routes the customer to the URL you
+ * return; the return page and the payment webhook confirm payment
+ * idempotently and move the order to processing (stock, emails, download
+ * permissions, webhooks all fire from there); admin refunds write the refund
+ * record and restock. `commerce/payment-webhook` (the function) is PREMADE —
+ * it calls `parseWebhook` from here and never trusts an event that this file
+ * hasn't vouched for.
  *
  * Until implemented, the Credit Card checkout option answers
  * 503 `no_card_payment_provider`.
@@ -34,9 +51,9 @@ export interface CardPaymentPage {
  * Create a payment page for `order.total` in `order.currency`.
  *
  * Send the customer back to `successUrl` / `cancelUrl` after they pay or give
- * up (both already carry order_id/order_key for the return page). If your
- * provider supports metadata, attach `order.id` and `order.order_key` so the
- * webhook can name the order.
+ * up (both already carry order_id/order_key for the return page). Attach
+ * `order.id` and `order.order_key` to the payment's metadata — that is how
+ * the premade webhook names the order when the provider's event comes in.
  */
 export async function createCardPayment(
   _sr: any,
@@ -78,3 +95,46 @@ export async function refundCardPayment(_sr: any, _order: any, _opts: {
     "card_refund_not_implemented",
   );
 }
+
+/** What `parseWebhook` distills a provider's webhook event into. */
+export interface CardWebhookEvent {
+  /** The order the event is about — read it from the event's metadata
+   * (`createCardPayment` attached it). */
+  order_id: string;
+  /** Must match the order's key; the premade webhook rejects the event
+   * otherwise, so a forged event can't be pointed at another order. */
+  order_key: string;
+  /**
+   * Set true ONLY when you verified the request signature over the raw
+   * payload bytes AND the event says the payment succeeded. When false, the
+   * event is treated as an unverified *nudge* naming an order: whether money
+   * actually arrived is then asked of the provider itself through
+   * `checkCardPaymentPaid`. `paid: false` therefore needs no signing secret
+   * and is already forgery-proof — never return true from an unverified body.
+   */
+  paid: boolean;
+  /**
+   * The provider's payment id, ONLY if the event is signature-verified.
+   * Leave unset otherwise — the premade flow then verifies the reference
+   * stored on the order at checkout, so a forged event can't smuggle in a
+   * reference to some other (paid) payment.
+   */
+  reference?: string;
+}
+
+/**
+ * Validate an incoming provider webhook event (raw request + raw body — the
+ * exact bytes, for signature schemes) and name the order it is about. Called
+ * by the premade `commerce/payment-webhook` function on every delivery; the
+ * verification that money actually arrived happens after this, against the
+ * provider, per the `paid` contract above. Return null for events that
+ * aren't about a payment for one of this store's orders (answered 200 so the
+ * provider doesn't retry).
+ */
+export async function parseWebhook(_req: Request, _payload: string): Promise<CardWebhookEvent | null> {
+  throw new HttpError(
+    400,
+    "This store's payment webhook is not implemented.",
+    "webhook_not_implemented",
+  );
+}

package/base44/shared/commerce/payments.ts

@@ -1,18 +1,20 @@
 /**
  * Card payment plumbing — the premade order-side half of online payments.
  *
- * The provider-specific half lives in exactly two files an agent implements
- * when wiring a provider (see `.agents/skills/commerce/references/online-payments.md`):
- *
- *   1. `shared/commerce/card-payment.ts` — create a payment page, check it was
- *      paid, refund it.
- *   2. `functions/commerce/payment-webhook/entry.ts` — parse the provider's
- *      server-to-server event.
+ * The provider-specific half lives in exactly ONE file an agent implements
+ * when wiring a provider: `shared/commerce/card-payment.ts` — four functions
+ * (create a payment page, check it was paid, refund it, validate a webhook
+ * event). Any provider works;
+ * a reference implementation (Stripe) is in
+ * `.agents/skills/commerce/post-installation.md` §2.2, and the
+ * provider-agnostic rules are in
+ * `.agents/skills/commerce/references/online-payments.md`.
  *
  * Everything here — return URLs, storing the payment reference on the order,
  * idempotent confirmation that moves the order to processing, refund routing —
  * is already wired into checkout, the payments function, the webhook and admin
- * refunds. None of it needs touching to add a provider.
+ * refunds. The payment webhook (`functions/commerce/payment-webhook`) is
+ * premade too. None of it needs touching to add a provider.
  */
 import { HttpError } from "./auth.ts";
 import { round2 } from "./money.ts";

package/package.json

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

package/scripts/install.js

@@ -96,8 +96,9 @@
     // remove the old copy so agents don't keep reading the stale one.
     ["skills", "commerce"],
     [".agents", "skills", "commerce", "references", "stripe-payments.md"], // → references/online-payments.md
-    // Payments moved to the two-file model (card-payment.ts + the webhook);
-    // the Stripe adapter and the provider-status hook are gone.
+    // Payments moved to the card-payment.ts model (one file to implement;
+    // the webhook is premade). The old Stripe adapter and the provider-status
+    // hook are gone.
     ["base44", "shared", "commerce", "stripe.ts"],
     ["src", "commerce", "admin", "hooks", "usePaymentProvider.js"],
     // Attributes and their values are edited in the Attributes section of the

package/skills/commerce/SKILL.md

@@ -10,10 +10,11 @@ Operational guidance for extending, operating and building on the Base44 Commerc
 > **If you are a Base44 agent working inside the runtime, read this first:**
 > - **Don't read the whole codebase up front.** Start with this file, then open only the files your current task touches plus the matching reference below, pulling in more as you go. Reading everything first just burns context.
 > - **Don't weaken the admin gating.** The UI guard, entity RLS and function guards form three enforcement layers — see [`.agents/skills/commerce/post-installation.md`](./post-installation.md) — keep all of them intact when changing routes or schemas.
+> - **Entity names are dotted — SDK access is bracket syntax only:** `base44.entities["commerce.PaymentGateway"]` (schema file: `base44/entities/commerce.PaymentGateway.jsonc`). `commerce__PaymentGateway` / `PaymentGateway` don't exist. Gateway on/off is seed data anyway: `commerce/seed-store` `payment_methods`.
 
 ## IMPORTANT — first-time installation
 
-If the template was just installed (or you are installing it right now), read [`.agents/skills/commerce/post-installation.md`](./post-installation.md) **before anything else**: embedding the admin pages, the three-layer admin-role enforcement (do not weaken), seeding the store's data — **one `commerce/seed-store` call takes the whole catalog** (products with attributes; variants, categories, ribbons and Shipping & Tax Locations created internally — §2) — and the **storefront quick start** (§3): logic-only chunks for product list → product page → cart → checkout that make reading the full API docs unnecessary for the happy path. The full install-from-scratch steps are in [`.agents/skills/commerce/installation-guidelines.md`](./installation-guidelines.md).
+If the template was just installed (or you are installing it right now), read [`.agents/skills/commerce/post-installation.md`](./post-installation.md) **before anything else — and, unless the user has a special requirement, read nothing else**: it alone covers embedding the admin pages, the three-layer admin-role enforcement (do not weaken), seeding the store's data — **one `commerce/seed-store` call takes the whole catalog** (products with attributes; variants, categories, ribbons and Shipping & Tax Locations created internally — §2) — **card payments in one file** (§2.2: a complete Stripe implementation to paste over `shared/commerce/card-payment.ts`; the payment webhook is premade), and the **storefront quick start** (§3): logic-only chunks for product list → product page → cart → checkout. The references below and the API docs are for requests that go beyond that happy path, not for the install. The full install-from-scratch steps are in [`.agents/skills/commerce/installation-guidelines.md`](./installation-guidelines.md).
 
 ## Working on the UI
 
@@ -34,7 +35,7 @@ Agents keep shipping storefronts that miss these, and each one breaks buying out
 
 2. **Checkout must present shipping options and send a choice.** Call `set-shipping-address` **as soon as the customer provides an address** — it recalculates the options and cost, and fails with `400 shipping_not_available` when the store doesn't ship there. Then read `shipping_status` on the returned cart: `auto_selected` (one option, already applied) · `chosen` · `choice_required` → **you must show `available_shipping_methods` and call `choose-shipping-method`** · `missing_address` → collect the address first (a single-location store shows its options even before one). `place-order` refuses with `400 shipping_method_required` until then — that is not a bug to work around. (`chosen_shipping_method` on the cart is the rate **id**, a string — display the choice by looking it up in `available_shipping_methods` for its `title`/`cost`, never by rendering the id or dotting into it.)
 
-3. **Handle card payments, and build `/order-received`.** Choosing the card gateway returns `payment.checkout_url` — redirect there (until a payment provider is implemented it answers `503 no_card_payment_provider`; offer the other methods). Every payment link comes back to `/order-received`, which **you must implement**: call `commerce/payments` `complete-return` with the query params and render its `state`. Without that page a customer pays into a 404 and the order is never marked paid. Also persist the `cart_token` from **every** cart response — `add-item` silently starts a fresh cart when the stored token is stale.
+3. **Handle card payments, and build `/order-received`.** Choosing the card gateway returns `payment.checkout_url` — redirect there (until a payment provider is implemented — one file, Stripe paste-in in [`post-installation.md` §2.2](./post-installation.md#22-payments--one-file-any-provider-stripe-as-the-reference) — it answers `503 no_card_payment_provider`; offer the other methods). Every payment link comes back to `/order-received`, which **you must implement**: call `commerce/payments` `complete-return` with the query params and render its `state`. Without that page a customer pays into a 404 and the order is never marked paid. Also persist the `cart_token` from **every** cart response — `add-item` silently starts a fresh cart when the stored token is stale.
 
 4. **Never advertise what isn't configured.** "Free shipping over €150" must come from a real shipping rate that is free or carries a `free_over` threshold on a Shipping & Tax Location. Locations are admin-only data, so a storefront cannot read them: the live answer is the cart's `available_shipping_methods` after `set-shipping-address`, and `shipping-promos.js` normalizes the rules wherever the records *are* in hand. No rule means no banner.
 
@@ -55,7 +56,7 @@ Open the matching file under `.agents/skills/commerce/references/` only when a t
 | Variant selection | attribute-level selectors, resolving a selection to a variation, availability states, incomplete-selection pricing, add-to-cart contract | [`references/storefront-product-page.md`](./references/storefront-product-page.md) |
 | Reviews | stars on cards and the product page, the review list + submit form (public by email, backend ships complete), the auto-approve toggle, UI-enforced policies (login-gated, verified-only, required rating) | [`references/reviews.md`](./references/reviews.md) |
 | Admin product form | changing the product editor — its stacked sections are **Price & Inventory** (tax group, then the attributes, then a row per variant, or a single *Base price* row when there are none), **Modifiers** (`meta_data`), **Downloads**, **Linked products**; one **Visible** toggle drives `status`. Variants reconcile from the attribute values automatically: no generate step, no per-variant delete. Weight and dimensions are per variant. | [`references/admin-product-form.md`](./references/admin-product-form.md) |
-| Online payments | **any storefront or checkout work** — the order side (checkout, confirmation, payment links, refund records) is premade; wiring a provider means implementing exactly two files (`shared/commerce/card-payment.ts` + the payment webhook) | [`references/online-payments.md`](./references/online-payments.md) |
+| Online payments | **any storefront or checkout work** — the order side (checkout, confirmation, payment links, refund records) *and* the payment webhook are premade; wiring a provider means implementing the four functions in one file (`shared/commerce/card-payment.ts`; Stripe = paste [`post-installation.md` §2.2](./post-installation.md#22-payments--one-file-any-provider-stripe-as-the-reference)) | [`references/online-payments.md`](./references/online-payments.md) |
 | Scheduled work | recurring maintenance — stock-hold release, abandoned-cart cleanup, webhook-log pruning, counter-drift repair | [`references/scheduled-work.md`](./references/scheduled-work.md) |
 | Emails | transactional order emails, per-type overrides, deliverability, the email log | [`references/emails.md`](./references/emails.md) |
 | Webhooks | outbound webhooks, HMAC signing, delivery log, auto-disable behavior | [`references/webhooks.md`](./references/webhooks.md) |

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

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

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

@@ -36,7 +36,7 @@ The backend is considerably richer than a minimal "grid → cart → pay" shop.
 | **Digital products** | entitlement-checked downloads with remaining-count, expiry, and signed URLs for private files | [`get-download`](#commercestorefront-account) |
 | **Store config** | currency (format it with `Intl.NumberFormat`), units, catalog/cart price display — read it and honour it instead of hardcoding | [`get-store-info`](#get-store-info) |
 
-Two things that are **not** in the backend and are yours to build: the visitor UI itself, and the payment provider integration — two files to implement (see [`references/online-payments.md`](../references/online-payments.md)). Payment methods and the currency are admin-owned data — always render them from `get-store-info` rather than a hardcoded list, and format prices with `Intl.NumberFormat(undefined, { style: "currency", currency })`.
+Two things that are **not** in the backend and are yours to build: the visitor UI itself, and the payment provider integration — four functions in one file (Stripe = paste [`post-installation.md` §2.2](../post-installation.md#22-payments--one-file-any-provider-stripe-as-the-reference); other providers: [`references/online-payments.md`](../references/online-payments.md)). Payment methods and the currency are admin-owned data — always render them from `get-store-info` rather than a hardcoded list, and format prices with `Intl.NumberFormat(undefined, { style: "currency", currency })`.
 
 ## Conventions
 
@@ -312,7 +312,7 @@ Separate function, same guest-bearer rule (`order_id` + `order_key`; an admin ma
 
 > **You must build the `/order-received` page** — it is mandatory for payment links to work. No storefront UI ships with the template, and without that route a paying customer lands on a 404 *and* the order never gets marked paid. It only needs to call `complete-return` and render its three states: see [`../references/online-payments.md`](../references/online-payments.md).
 
-Provider callbacks land on `commerce/payment-webhook` (server-to-server) — the second confirmation path, for buyers who pay and close the tab. Whichever path runs second is a no-op. Wiring a payment provider means implementing two files; see [`../references/online-payments.md`](../references/online-payments.md).
+Provider callbacks land on `commerce/payment-webhook` (server-to-server) — the second confirmation path, for buyers who pay and close the tab. Whichever path runs second is a no-op. The webhook function is premade (it verifies through the provider's API, so no signing secret); wiring a payment provider means implementing four functions in one file — see [`../references/online-payments.md`](../references/online-payments.md).
 
 ### `confirm-payment`
 Post-payment hook for an order on the card gateway. **Payload:** `{ order_id, order_key }`.

package/skills/commerce/installation-guidelines.md

@@ -85,7 +85,7 @@ The template ships an AI copilot for store operators:
 
 ## 4. Building on it — the four storefront requirements
 
-If your work includes a customer-facing shopfront, read **[`SKILL.md` → *If you build a storefront, these four are not optional*](./SKILL.md)** before writing it, and [`docs/api-storefront.md`](./docs/api-storefront.md)'s *Required behaviors* table. In short: attribute-level variant selectors resolved to a `variation_id`; shipping options presented and chosen; card payment redirect plus an `/order-received` page; and no offers the store isn't configured for. The API enforces the first three — a storefront that skips them cannot complete a purchase.
+If your work includes a customer-facing shopfront, the quick start in [`post-installation.md` §3](./post-installation.md#3-storefront-quick-start--logic-only) already walks all four requirements — you don't need any other reading. In short: attribute-level variant selectors resolved to a `variation_id`; shipping options presented and chosen; card payment redirect plus an `/order-received` page; and no offers the store isn't configured for. The API enforces the first three — a storefront that skips them cannot complete a purchase. (Day-2 deep dives: [`SKILL.md` → *these four are not optional*](./SKILL.md) and [`docs/api-storefront.md`](./docs/api-storefront.md)'s *Required behaviors* table.)
 
 ## 5. Next steps