@base44/app-plugin-commerce 0.3.3 → 0.3.4

package/package.json

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

package/skills/commerce/install/03-data.md

@@ -22,7 +22,7 @@ A fresh install has **no settings and no catalog**. One admin-only, idempotent c
 
 **`store_name` is required on a first seed** — the app's name as the platform shows it (`base44/config.jsonc` → `name` can be stale; ask if unsure). **`currency`** is an ISO code (`"EUR"`); formatting follows the viewer's locale, nothing else to set. Explicit values always win, first seed and re-runs alike.
 
-The working call — `name` is the only required product key; give each product the keys its own catalog entry actually has and leave the rest out. The **full key list** (sale windows, downloads, tax, backorders, dimensions…) lives in `api-admin.md` — open it only if the catalog needs one:
+The working call — `name` is the only required product key; give each product the keys its own catalog entry actually has and leave the rest out. The **full key list** (sale windows, downloads, tax, backorders, upsells…) lives in `api-admin.md` — open it only if the catalog needs one:
 
 ```js
 try {
@@ -45,10 +45,14 @@ try {
         categories: ["Shoes"],                     // get-or-created by display name
         ribbons: ["Best Seller"],                  // flat labels, not a hierarchy
 
+        weight: 0.248,                             // real fields, in the store's units —
+        dimensions: { length: 31, width: 12, height: 11 },   // never a meta_data row
+
         // Descriptive spec rows (productSpecs). NOT axes, NOT ribbons; `_` hides.
+        // Qualities only — a weight or a size here is a string nothing can read.
         meta_data: [
           { key: "Material", value: "Recycled knit upper" },
-          { key: "Weight",   value: "248 g" },
+          { key: "Care",     value: "Machine wash cold" },
         ],
 
         attributes: [                              // the axes → one selector each
@@ -57,8 +61,9 @@ try {
         ],
         default_options: { Size: "42", Color: "Black" },
         variations: [                              // omit entirely → all combos auto-generated
-          { options: { Size: "41", Color: "Black" }, stock_quantity: 4 },
+          { options: { Size: "41", Color: "Black" }, stock_quantity: 4, weight: 0.242 },
           { options: { Size: "42", Color: "White" }, regular_price: 94, stock_quantity: 3,
+            weight: 0.254,                          // per variant, never inherited from the parent
             image: "https://…/sneaker-white.jpg" }, // per-variation image for a visual axis
         ],
       },
@@ -136,9 +141,4 @@ Online card payments are **off by default**: the seeded store takes the manual `
 - [ ] `coupons` seeded only if a coupon field exists ([`./02-storefront.md`](./02-storefront.md)).
 - [ ] Cards off, or on with the provider file copied whole.
 
-Record these lines in your working notes; do not re-read this file.
-
-- Product slugs come from the seed response's `catalog.products[]` — link pages by slug, never by a client-side map.
-- Payments: report at handover where they landed (default = offline on, card off) — the owner must never learn it from a customer.
-- Turning card payments on or off later is one more seed call: `{ payment_methods: ["offline", "card"] }`.
-- Seed-time `locations` is THE shipping path; patching `commerce.ShippingTaxLocation` is the day-2 route.
+Then copy this file's `carry_forward` lines (in its front matter) into your working notes, and do not re-read this file.

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

@@ -55,6 +55,8 @@ A kit update re-copies `shared/commerce/` and restores the stub — re-run the c
 
 Checkout (`place-order`, `card` gateway) creates the order `pending`, runs `createCardPayment`, stores its `reference` on the order and redirects to `url`; return URLs carry `order_id`/`order_key`/`payment=`. Confirmation is **two idempotent paths** (the second a no-op): the customer return (`/order-received` → `commerce/payments` `complete-return` → `checkCardPaymentPaid` → `processing` with all side-effects; `useOrderReturn` is that page in one hook) and the webhook (covers the closed tab). `create-link` mints a fresh page for any unpaid order the same way; `admin-refunds` `refund_payment: true` calls `refundCardPayment` **before** writing locally (unimplemented → `501`; record without the flag instead). Gateway enabled with no provider behind it → `503 no_card_payment_provider`; every other payment option is **manual** (on-hold, the option's description as payment instructions) and needs no code.
 
+⚑ **Card payment cannot complete in the preview pane.** Providers serve their payment page `frame-ancestors 'none'`, so the redirect dead-ends in the frame. `useCheckout`'s `placeOrder` refuses up front — `{ ok: false, error: { code: "card_payment_in_preview" } }`, nothing created — because `place-order` takes the order and its stock hold *before* minting the payment page, and an attempt that dies at the redirect would strand an unpayable order. Manual gateways are unaffected. **Test card checkout in the published store**; a card flow that appears to do nothing in preview and works published is this, not broken provider wiring.
+
 ## Implementation rules
 
 For a **custom** provider (the shipped files already obey all of these):

package/src/commerce/storefront/useCheckout.jsx

@@ -9,6 +9,22 @@ import {
   shippingSlice,
 } from "./address";
 
+/**
+ * Card payment cannot complete in the app builder's preview pane. The
+ * provider's payment page is a full-page redirect and providers serve theirs
+ * `frame-ancestors 'none'`, so the redirect navigates the pane, the provider
+ * refuses to render in it, and checkout looks like it silently did nothing. A
+ * storefront runs framed in exactly one place, so "framed" is read as "preview".
+ */
+function inPreview() {
+  if (typeof window === "undefined") return false;
+  try {
+    return window.self !== window.top;
+  } catch {
+    return true;
+  }
+}
+
 const EMPTY_ADDRESS = Object.freeze({
   first_name: "",
   last_name: "",
@@ -70,6 +86,12 @@ function resolvePaymentMethod(gateways, picked) {
  *   handle the result yourself (a manual result carries
  *   `result.payment_instructions`).
  *
+ *   **A card order will not place from the preview pane** — providers refuse to
+ *   be framed, so the redirect can only dead-end there. `placeOrder` resolves
+ *   `{ ok: false, error: { code: "card_payment_in_preview" } }` without
+ *   creating anything; manual gateways are unaffected. Test card checkout in
+ *   the published store.
+ *
  *   Both navigations are **full page loads** (`window.location.assign`): the
  *   provider hop leaves the app, and the receipt boots from the URL alone
  *   (`order_id` + `order_key`), so a reload there is correct and shareable.
@@ -215,6 +237,18 @@ export function useCheckout(options = {}) {
   const placeOrder = useCallback(
     async (extra = {}) => {
       if (placing) return { ok: false, error: { code: "placing", message: "Order already being placed." } };
+      // Refuse a card checkout from the preview pane before the network, not
+      // after it: `place-order` creates the order and takes its stock hold
+      // *before* the payment page exists, so an attempt that can only die at
+      // the redirect would strand a real pending order nobody can pay.
+      if (paymentMethod === "card" && inPreview()) {
+        const error = {
+          code: "card_payment_in_preview",
+          message: "Card payment can't be completed in preview. Open the published store to pay.",
+        };
+        setOrderError(error);
+        return { ok: false, error };
+      }
       // Safe as `onClick={checkout.placeOrder}`: a DOM/React event is not
       // `extra`. Spreading one into the order payload would send a circular
       // SyntheticEvent as order fields — an explicit object still forwards.