@base44/app-plugin-commerce 0.1.19 → 0.2.1

package/skills/commerce/references/product-render.md

@@ -1,89 +0,0 @@
-# Rendering products: list view and product page
-
-What to show for a product, and **which view can show it**. Both storefront surfaces render the same catalog record from a different call:
-
-| View | Call | Returns |
-|---|---|---|
-| Listing / grid / search results / ribbon & category pages | `commerce/storefront-catalog` `list-products` | `{ products: [row...], page, per_page, has_next }` |
-| Product page | `commerce/storefront-catalog` `get-product` | `{ product, variations, categories, ribbons, reviews, upsells, cross_sells }` |
-
-Request/response shapes: [`../docs/api-storefront.md`](../docs/api-storefront.md). Variant selection mechanics (axes, resolving a selection to a variation, unavailable combinations): [`storefront-product-page.md`](./storefront-product-page.md).
-
-You choose what belongs in each view — but you can only render what the call returns. The table below is the boundary.
-
----
-
-## 1. Field availability
-
-A listing **row** is the product record itself (minus paywalled fields), plus resolved `ribbons`. `get-product` adds everything that needs a second read.
-
-| Data | `list-products` row | `get-product` | Notes |
-|---|---|---|---|
-| `id`, `name`, `slug`, `status` | ✅ | ✅ | There is no `type` field — a product sells variants when `attributes[]` is non-empty |
-| `price`, `regular_price`, `sale_price`, `on_sale` | ✅ | ✅ | With variants the parent `price` is a starting point, not the truth — see §3 |
-| `images[]`, `featured`, `short_description`, `description` | ✅ | ✅ | Cards normally use `images[0]` + `short_description`. Every entry is an **object** `{ src, name, alt, position }` — render `images[0]?.src`, never the entry itself (an object passed as `src` fails the load and your fallback shows a placeholder despite the image existing). Sub-fields aren't guaranteed on raw entries — the `normalizeImage` helper (`@/commerce/utils`) returns `{src, name, alt}` with a non-empty `src` or `null`. `images` can also be genuinely **empty** — render a placeholder, don't leave a broken `img` (on the product page `resolveSelection`'s `display.image` is `null` in that same case, already normalized) |
-| `sku`, `stock_status`, `stock_quantity`, `manage_stock`, `backorders` | ✅ | ✅ | |
-| `average_rating`, `rating_count`, `total_sales` | ✅ | ✅ | Enough for stars on a card; the reviews themselves are not in a row |
-| `downloadable`, `virtual`, `weight`, `dimensions`, `attributes[]`, `meta_data` | ✅ | ✅ | `attributes[]` is the variant axes; `meta_data` is the descriptive properties the admin calls **modifiers** |
-| **`ribbons`** (resolved `{id, name}`) | ✅ | ✅ | `get-product` returns the full ribbon records; rows carry the short form |
-| `ribbon_ids`, `category_ids` | ✅ | ✅ | Raw ids |
-| **`categories`** (resolved) | ❌ *ids only* | ✅ | See §5 to add |
-| **`variations[]`** (per-variant price/stock/image/attributes) | ❌ | ✅ | The reason a product with variants can't be fully priced from a row |
-| **`reviews`** (paged items + `average_rating`/`rating_count`) | ❌ | ✅ | Row still has the aggregate numbers |
-| **`upsells`, `cross_sells`** (summaries) | ❌ | ✅ | `{id, name, slug, price, on_sale, image}` |
-| `downloads[]`, `download_limit`, `download_expiry` | ❌ | ❌ | **Never** exposed publicly — paywalled. Gated by `commerce/storefront-account` `get-download` |
-
-## 2. Ribbons — render them in **both** views
-
-Ribbons are flat, cross-cutting labels ("Best Seller", "New", "Gift"); categories are the hierarchical spine. Generated storefronts routinely omit ribbons entirely. Don't.
-
-- **Listing rows carry resolved `ribbons`** (`{id, name}`), so a card can render them with no extra call. One or two per card is useful (a corner label like "Best Seller"); more is noise. Hide the block when the array is empty — never a dangling "Ribbons:" label.
-- **On the product page**, render `product.ribbons` (the top-level `ribbons` array) as labels near the metadata, visually lighter than the category breadcrumb.
-- **Every ribbon can link to a filtered listing** — `list-products` with `ribbon_id` — never a dead label. A ribbon has no slug, so key the URL on its id (`/shop?ribbon=<ribbon_id>`) so the page is shareable and survives reload. Use `list-ribbons` for a name to label it with.
-- **Offer ribbons as a listing filter** from `list-ribbons`, which hides ribbons no published product carries and gives a `count` for labels like "Gift (12)". `ribbon_id` stacks with `category_id`, price, `on_sale`, `featured`, `in_stock_only`.
-- **Ribbon landing page:** `list-products` filtered by `ribbon_id`, with the ribbon's `name` as the heading.
-- Don't put ribbons in the breadcrumb, and don't use them as variant options — a size or colour is an `attribute`, not a ribbon.
-- Descriptive properties (Material, Care) are **modifiers** in `meta_data`, not ribbons and not attributes. Render them as a spec table on the product page.
-
-## 3. Product shapes in each view
-
-There are only two shapes, and **`attributes[]` tells them apart** — there is no `type` field:
-
-| Shape | Test | Card | Product page |
-|---|---|---|---|
-| **Single item** | `attributes` is empty | price, **Add to cart** straight from the card if you want one | single **Add to cart** — `resolveSelection` returns no axes, `complete: true`, a ready `addToCart` |
-| **Has variants** | `attributes` is non-empty | price **range or `From €19`** (see below), never selectors — link through | one selector per attribute: [`storefront-product-page.md`](./storefront-product-page.md) |
-
-A product with attributes is **only** sellable through a variant: `add-item` without a `variation_id` is `400 variation_required`, and there is no fall-back to the parent. So one with attributes but no variations is unsellable by design, not by accident.
-
-Downloadable/virtual products are either shape with `downloadable: true` — see [`media-and-downloads.md`](./media-and-downloads.md).
-
-### A variant parent's `price` is its *from* price
-
-`admin-products` rolls both **stock** and **price** up from the variations: a parent's `regular_price`, `price` and `on_sale` are derived from the cheapest publishable variant on every save. So the parent price is real and safe to sort and filter on — but it is the **lowest** price, not *the* price.
-
-A listing row has no `variations`, so a card still cannot compute the full range from a row alone: render `From {product.price}`, never the parent price presented as *the* price. On the product page you have `variations`, so show the real range via `priceRange` from the variant helpers.
-
-## 4. Sensible defaults per view
-
-**Card:** image, name, price (or range), sale badge from `on_sale`, stars from `average_rating`/`rating_count`, out-of-stock state from `stock_status`, one or two ribbons. Link the whole card to the product page.
-
-**Product page:** gallery, name, price, variant selectors, stock, `short_description` then `description`, SKU, categories breadcrumb, ribbons, reviews, then upsells/cross-sells.
-
-## 5. Adding a `get-product`-only field to the list view
-
-If a customer asks for something the row doesn't carry — resolved categories are the common one — resolve it in the listing call rather than firing `get-product` per card (that's N requests for one grid).
-
-`list-products` resolves its page slice through a helper in `base44/functions/commerce/storefront-catalog/entry.ts`:
-
-```ts
-const pageItems = await withRibbons(sr, products.slice(start, start + perPage).map(publicProduct));
-```
-
-`withRibbons` reads the taxonomy **once per request** and maps ids on the rows — not once per row. Extend that pattern: read the entity for the whole page, build an id→record `Map`, attach the short shape each card needs. Keep it to the fields the UI renders; a listing payload is served on every browse.
-
-What not to do:
-
-- Don't call `get-product` per card.
-- Don't add `variations` to every row — that is the heaviest read in the catalog and a grid does not need it. If cards must show real price ranges, add a precomputed `price_min`/`price_max` instead.
-- Don't relax entity RLS to read the catalog from the client: `commerce.Product` and the taxonomy entities are admin-only by design ([`guest-access-security.md`](./guest-access-security.md)). Widen the function's response instead.

package/skills/commerce/references/scheduled-work.md

@@ -1,19 +0,0 @@
-# Scheduled work (workflows)
-
-Base44 **has** a scheduler — the recurring maintenance below is run by **scheduled workflows**, and the Base44 agent can create them for you. **This template ships no workflow/schedule files on purpose**: don't look for them under `base44/` and don't add them here — create the workflows directly in the target app.
-
-**Instruct the agent (or set up yourself): create one scheduled workflow per row below.** Each workflow does one thing — invoke the given function action on the chosen cadence:
-
-```js
-await base44.functions.invoke("commerce/admin-tools", { action: "clear-abandoned-carts", older_than_days: 2 });
-```
-
-| Workflow to create | What it does | Action to invoke | Payload | Suggested cadence |
-|---|---|---|---|---|
-| Release expired stock holds | Frees stock held by unpaid orders past `hold_stock_minutes`. `commerce/storefront-checkout` `place-order` already runs this at the start of every checkout, so the schedule mainly covers quiet periods. | `commerce/admin-orders` `release-expired-holds` | — | every 5–15 min |
-| Abandoned cart cleanup | Marks carts past the 48 h TTL as `abandoned`. Also happens lazily on next cart access. | `commerce/admin-tools` `clear-abandoned-carts` | `{ older_than_days: 2 }` | hourly–daily |
-| Prune webhook delivery log | Deletes old `commerce.WebhookDelivery` rows so the log doesn't grow unbounded. **No opportunistic fallback — this one genuinely needs a schedule.** | `commerce/admin-tools` `prune-webhook-deliveries` | `{ keep_days: 30 }` | daily–weekly |
-
-**Optional — drift repair.** Denormalized counters can drift without transactions (see [`limits-and-performance.md`](./limits-and-performance.md)). If you want them self-healing, add a nightly/weekly workflow that calls the `commerce/admin-tools` recount actions: `recount-terms`, `recount-coupon-usage`, `recalculate-customer-stats-all`, `regenerate-download-permissions`.
-
-Every action above is guarded by `requireAdmin()`, so each scheduled workflow must run with **admin privileges** (an admin identity / service context), not as an anonymous caller.

package/skills/commerce/references/storefront-product-page.md

@@ -1,83 +0,0 @@
-# Variant selection on the product page
-
-The one interaction agents reliably get wrong: turning a product with variants into controls a customer can buy from. Everything else about the page — what to show, and which fields each call returns — is [`product-render.md`](./product-render.md); request/response shapes are [`docs/api-storefront.md`](../docs/api-storefront.md).
-
-The logic ships: **`src/commerce/utils/variants.js`** (framework-free, no I/O, full JSDoc on every export — read it for signatures). Import it and spend your effort on the markup.
-
----
-
-## 1. The model, and the rule
-
-`get-product` returns `{ product, variations }`. **Every** `product.attributes[]` entry is an **axis**, in `position` order; each `variations[]` record is one combination. There is no product type and no per-attribute flag — carrying attributes is what makes a product sell variants. Descriptive properties are `meta_data` (the admin calls them modifiers) — a spec table, **never** a selector.
-
-**One control per axis. Never one option per variation.** Do not flatten `variations[]` into `Red / S`, `Red / M`, `Blue / S`, … — that is `n × m` noise, it hides the product's structure, and it stops scaling immediately.
-
-```
-Size    ( ○ S  )( ● M   )( ○ L )      ← one control per attribute
-Color   ( ● Red )( ○ Blue )
-                                      → resolved variation: Red / M · $21.99 · 10 in stock
-```
-
-Pick the control by option count: swatches for colours, pills for a few short options, a `Select` for many or long labels. The axis label is `attribute.name`.
-
-## 2. One call gives you the whole view
-
-```jsx
-import { resolveSelection, defaultSelection, selectOption } from "@/commerce/utils";
-
-const [selection, setSelection] = useState(() => defaultSelection(product, variations));
-const view = resolveSelection(product, variations, selection);
-const pick = (axisKey, option) =>
-  setSelection((prev) => selectOption(product, variations, prev, axisKey, option));
-```
-
-Bind the UI to `view` — not to `product.*` — so a selection actually changes the page:
-
-| `view` field | Binds to |
-|---|---|
-| `axes` | the controls: `[{ key, name, attribute_id, options[] }]`, dead options already dropped |
-| `display` | image, price, `regular_price`, `on_sale`, SKU, stock, weight/dimensions, description — variation-first with parent fallback. `display.image` is an **object** — always the normalized `{src, name, alt}` (`src` guaranteed non-empty, `alt` defaulted; stored entries are not uniform, so never read `variation.image`/`product.images` raw when this field exists), or **`null` when neither the variation nor the product has a renderable image** (the one case needing a placeholder in the UI). Render `display.image?.src` / `display.image?.alt`; **passing the object itself to an `<img src>` or Image component fails the load and shows the placeholder for every product**. For galleries, run raw entries through the exported `normalizeImage`: `product.images.map(normalizeImage).filter(Boolean)` |
-| `availability[axisKey][option]` | per-option state: `"available"` / `"out_of_stock"` / `"unavailable"` — §3 |
-| `priceRange` | `{ min, max, on_sale, count }` while the selection is incomplete — §3 |
-| `complete` / `missingAxes` | the button label: `Select a ${view.missingAxes[0]?.name}` |
-| `purchasable` | gate **Add to cart** on this (resolved *and* buyable) |
-| `addToCart` | `{ product_id, variation_id }` to spread into the cart call, or `null` |
-
-`view.variation` and `view.candidates` are there when you need the record itself or the variations still reachable. For a product with no attributes `resolveSelection` returns no axes, `complete: true` and a ready `addToCart` — the same code path; it branches on whether there are axes, so `variations` can be `[]`.
-
-A **product with attributes but no usable variations** — the state attaching an attribute and stopping leaves you in — is deliberately *not* given a parent fallback, because `add-item` would reject it. You get axes whose `options` arrays are empty, `purchasable: false` and `addToCart: null`. Render it as unavailable rather than painting selector groups with no buttons, and guard the "Select a …" label: with no attributes at all, `missingAxes` is empty and `view.missingAxes[0]?.name` is `undefined`.
-
-The other exports cover what the view model doesn't: `selectionForVariation` (variation → selection, to hydrate controls from a cart line or `?variation=` link), `selectionToParams`/`selectionFromParams` (URL round-trip), `priceRange`, and the individual pieces if you build your own view model. Signatures and edge cases are in the JSDoc; two behaviors are easy to miss when hand-rolling: non-publishable variations never leak an option into the UI, and an empty `option` on an axis means **"any"**.
-
-## 3. The three UI decisions the helpers can't make for you
-
-- **Unavailable vs out of stock.** `"unavailable"` (no such combination) → **disable, don't hide**; options that vanish and reappear as the customer clicks are disorienting. `"out_of_stock"` → keep it visible and label it. `onbackorder` counts as available and purchasable — label it ("Ships in 2–3 weeks"), don't disable it.
-- **Incomplete selection.** Show `view.priceRange` (`$21.99 – $23.99`, or `From $21.99`) — never `$0`, and never the parent `price`, which for a product with variants is not its price ([`product-render.md` §3](./product-render.md#3-product-shapes-in-each-view)). Keep **Add to cart** disabled with a hint at what's missing.
-- **Initial state and linkability.** Start from `defaultSelection` (honours the merchant's `default_attributes`, preselects single-option axes). Mirror the selection into the URL with `selectionToParams` and hydrate with `selectionFromParams`, so a chosen variant is shareable and survives a refresh.
-
-Route every click through `selectOption` and dead ends take care of themselves: it keeps the just-picked option and clears only conflicting axes (Red/L → click Blue → `{ Color: Blue }`, size re-open) instead of leaving the customer on a combination that resolves to nothing.
-
-## 4. Add to cart
-
-```js
-await base44.functions.invoke("commerce/storefront-cart", {
-  action: "add-item",
-  cart_token,
-  ...view.addToCart,   // { product_id, variation_id } — variation_id is REQUIRED once a product has attributes
-  quantity,
-});
-```
-
-Handle `400 variation_required` (empty `variation_id` on a product with attributes — the page has a bug), the stock codes (`out_of_stock`, `insufficient_stock`, …), and `404 variation_not_found` (catalog changed underneath the page: refetch `get-product`). `product.sold_individually` caps the quantity control at 1.
-
-## 5. Checklist
-
-- [ ] One control per axis in `view.axes` — no combination list anywhere in the UI.
-- [ ] `meta_data` modifiers render as specs, not selectors.
-- [ ] Image, price, SKU and availability all come from `view.display`; the image is rendered from `display.image.src` (it's an object, not a URL string), with a placeholder **only** for `display.image === null`.
-- [ ] Incomplete selection shows `view.priceRange` — never `$0`, never the parent `price`.
-- [ ] `"unavailable"` disabled, `"out_of_stock"` labelled; every click routed through `selectOption`.
-- [ ] Initial state from `defaultSelection`; selection mirrored into the URL.
-- [ ] **Add to cart** gated on `view.purchasable`, sending `view.addToCart`.
-- [ ] A product with empty `axes[].options` shows as unavailable — no empty selector groups, no "Select a undefined".
-- [ ] Ribbons, ratings, upsells and the rest per [`product-render.md`](./product-render.md).

package/skills/commerce/references/webhooks.md

@@ -1,10 +0,0 @@
-# Webhooks
-
-Managed in the admin at **Settings → Webhooks** (`settings/webhooks`; the source still lives under `pages/status/`).
-
-`webhooks.ts` `dispatch()` fires on `order.*`, `product.*`, `customer.*`, `coupon.*` (created/updated/deleted, note that `restored` is selectable on a webhook but **never emitted** — nothing dispatches it). Each active `commerce.Webhook` matching the topic receives an HTTP POST with headers `X-Commerce-Webhook-Topic/-Resource/-Event/-ID/-Delivery-ID/-Signature`. The signature is **base64 HMAC-SHA256** of the body, keyed by the webhook's `secret` (Web Crypto).
-
-- Every attempt is logged as a `commerce.WebhookDelivery` (request/response bodies truncated to 32 KB). Prune with `commerce/admin-tools` `prune-webhook-deliveries`.
-- `failure_count` increments on non-2xx/timeout and resets on success; a webhook auto-disables after **5** consecutive failures.
-- The `secret` is stored on the (admin-only-RLS) `commerce.Webhook` entity. For higher assurance, move it to Base44 secrets and read it in `dispatch()`.
-- Verify deliveries on the receiver by recomputing the HMAC over the raw body with your secret.