@base44/app-plugin-commerce 0.1.20 → 0.2.2

package/skills/commerce/docs/entities.md

@@ -0,0 +1,137 @@
+# Entities — the data-model map
+
+Every `commerce.*` entity, what holds what, and who may write it. Read this before **any** direct entity read or write; function-mediated flows never need it.
+
+## Addressing — read this first
+
+Entity names are **dotted and namespaced**, so the SDK accessor is **bracket syntax, always**:
+
+```js
+base44.entities["commerce.PaymentGateway"]      // ✅ the only spelling that resolves
+base44.entities["commerce__PaymentGateway"]     // ❌ 404 Entity schema … not found
+base44.entities["PaymentGateway"]               // ❌ there is no un-namespaced alias
+base44.entities.commerce.PaymentGateway         // ❌ not a nested object
+```
+
+Schema files live at **`base44/entities/commerce.<Name>.jsonc`** — one targeted read when you need a field this page doesn't carry.
+
+`filter` is **exact-match only**; args are `(query, sort, limit, skip)`, `list` is `(sort, limit, skip)`. Plus `.get(id)` · `.create(fields)` · `.update(id, patch)` · `.delete(id)`.
+
+```js
+const gateways = await base44.entities["commerce.PaymentGateway"].list("order", 100);
+const [offline] = await base44.entities["commerce.PaymentGateway"].filter({ slug: "offline" }, undefined, 1);
+await base44.entities["commerce.PaymentGateway"].update(offline.id, { title: "Bank transfer" });
+```
+
+**Never** scan `base44/entities/` to discover names, guess a spelling and retry on 404, or web-search a kit API's shape. This page plus [`api-admin.md`](./api-admin.md) and [`api-storefront.md`](./api-storefront.md) are the answer.
+
+## The catalog — all 20
+
+**RLS is identical on every entity: `admin` on read *and* write**, catalog included. A non-admin call is rejected by the backend whatever the UI does; storefront access goes exclusively through `commerce/storefront-*` (service role, safe projections) — [`../references/guest-access-security.md`](../references/guest-access-security.md). Hence no RLS column: assume admin-only.
+
+**Owned by `<fn>` = never write directly** — the function maintains derived fields, counts, emails and webhooks a raw write skips. Names below are all `commerce/<name>`.
+
+| Entity | Purpose | Key fields | Write path |
+|---|---|---|---|
+| `Product` | Sellable product; sells variants when it carries `attributes` — there is **no `type` field** | `name` `slug` `status` `price` `category_ids` `attributes[]` `images[]` | owned by **`admin-products`** |
+| `ProductVariation` | One purchasable attribute combination of a parent | `product_id` `attributes[]` `sku` `regular_price` `stock_quantity` `status` | owned by **`admin-products`** — `save` diffs them inside the parent call |
+| `ProductCategory` | Hierarchical category (`parent_id` tree) | `name` `slug` `parent_id` `menu_order` `count` | direct CRUD, or **`admin-products` `save-term`** (slug uniqueness, self-parent guard) |
+| `ProductRibbon` | Flat cross-cutting label ("Best Seller") | `name` `count` | direct CRUD, or **`save-term`** — get-or-create by name, so it can't split a ribbon |
+| `ProductAttribute` | Variant axis shared across products (Color, Size) | `name` `code` `order` | direct CRUD, or **`save-term`** (`code` uniqueness; `code` is what a filter URL carries) |
+| `ProductAttributeTerm` | One value of an attribute (Size → M) | `attribute_id` `name` `order` `count` | direct CRUD, or **`save-term`** — products store values **by name**, so a rename rewrites them |
+| `ProductReview` | Moderated customer review | `product_id` `status` `reviewer` `rating` `review` `verified` | owned by **`admin-reviews`** (recomputes the rating); created by `submit-review` |
+| `Order` | Order with embedded line items, shipping/tax/fee/coupon lines, totals | `order_number` `order_key` `status` `line_items[]` `total` `billing` | owned by **`admin-orders`**; created by `place-order` |
+| `OrderNote` | System, private, or customer-facing note | `order_id` `note` `is_customer_note` `added_by` | owned by **`admin-orders`** `add-note`/`delete-note` — a customer note emails the buyer |
+| `OrderRefund` | Full or partial refund | `order_id` `amount` `line_items[]` `restock_items` | owned by **`admin-refunds`** (totals, restock, status) |
+| `Customer` | Customer; guests have no `user_id` | `email` `first_name` `last_name` `is_guest` `billing` `shipping` | owned by **`admin-customers`**; checkout upserts it, `update-my-addresses` is the owner's path |
+| `Coupon` | Discount coupon with restrictions and usage limits | `code` `enabled` `discount_type` `amount` `usage_count` | owned by **`admin-coupons`** (unique lowercased code) |
+| `Cart` | Ephemeral cart + checkout draft keyed by `cart_token`; items hold **no prices** | `cart_token` `items[]` `coupon_codes` `shipping_address` `expires_at` | owned by **`storefront-cart`/`-checkout`** — never write directly |
+| `PaymentGateway` | One checkout method (`offline`, `card`, manual options); no secrets here | `slug` `title` `description` `enabled` `order` `settings` | **mixed**: `enabled` via `seed-store` `payment_methods`; the rest direct CRUD |
+| `ShippingTaxLocation` | A sales location: regions + its shipping rates, tax groups, shipping tax. Empty `regions` = catch-all | `name` `order` `regions[]` `shipping_rates[]` `tax_groups[]` | **direct CRUD** (or `seed-store` `locations`) — mint stable rate `id`s |
+| `StoreSettings` | Config, **one record per `group_id`** (`general` `products` `inventory` `tax` `shipping` `emails`) | `group_id` `values` | **direct CRUD** — patch `values`, never replace the group |
+| `DownloadPermission` | A customer's access to a purchased file | `order_id` `customer_email` `product_id` `downloads_remaining` `access_expires` | owned by the **order lifecycle** (`admin-orders` `grant-download`/`revoke-download`) |
+| `Webhook` | Outgoing webhook definition | `name` `topic` `delivery_url` `secret` `status` | **direct CRUD** (+ `admin-webhooks` `test`/`redeliver`); `failure_count` engine-owned |
+| `WebhookDelivery` | Log of one delivery attempt | `webhook_id` `topic` `response_code` `success` | **engine-owned, read-only**; prune via `admin-tools` |
+| `EmailLog` | Log of transactional emails sent | `email_type` `recipient` `target` `success` `error` | **engine-owned, read-only** |
+
+## Relationships
+
+```
+Product ──< ProductVariation                      one row per stocked combination
+  ├─ category_ids ─> ProductCategory ──< ProductCategory   (parent_id tree)
+  ├─ ribbon_ids   ─> ProductRibbon
+  ├─ attributes[].attribute_id ─> ProductAttribute ──< ProductAttributeTerm
+  └──< ProductReview
+
+Cart ──place-order──> Order ──< OrderNote
+ (cart_token, 48h TTL)  │    ──< OrderRefund
+                        │    ──< DownloadPermission
+                        └─ customer_id ─> Customer
+
+Coupon               referenced by code from Cart.coupon_codes / Order.coupon_lines
+StoreSettings        one record per group_id      PaymentGateway  one row per method
+ShippingTaxLocation  standalone; matched by `order` ascending at pricing time
+Webhook ──< WebhookDelivery                        EmailLog  append-only
+```
+
+## Derived fields — never write these
+
+| Field | Changed instead by |
+|---|---|
+| variant parent's `price` `regular_price` `on_sale` — rolled up from the cheapest publishable variation, which is what makes cards, price sort and price filters agree | `admin-products` `save` / `seed-store`; set prices on the **variations** |
+| `stock_status` (product + variation) — from quantity + `backorders`, or rolled up from variations when the parent doesn't `manage_stock` | `admin-products` `set-stock`/`save`; order stock reduce/restore |
+| `Product.average_rating` `rating_count` — from approved reviews | `admin-reviews`, `storefront-catalog` `submit-review` |
+| `Product.total_sales` — first stock reduction, reversed on restore | the order transition engine |
+| `count` on `ProductCategory` / `ProductRibbon` / `ProductAttributeTerm` | `admin-products`; repair with `admin-tools` `recount-terms` |
+| `Order` totals (`subtotal` `discount_total` `shipping_total` `*_tax` `total`) and per-line totals | `admin-orders` `update`/`recalculate`/`apply-coupon`; `place-order` |
+| `Order` status side effects — `date_paid` `date_completed` `stock_reduced` `coupon_usages_counted` `download_permissions_granted` `emails_sent` `hold_expires_at`; flag-guarded so a re-entered status never double-fires | `admin-orders` `update-status`/`bulk-status` — never a direct `status` write |
+| `Order.total_refunded` | `admin-refunds` |
+| `Customer.orders_count` `total_spent` `is_paying_customer` | `admin-customers` `recalculate-stats` |
+| `Coupon.usage_count` `used_by` | the transition engine; repair with `admin-tools` `recount-coupon-usage` |
+
+## Recipes
+
+**Enable/disable a payment gateway** — not an entity write. One call converges *every* gateway row to the set you name, validates the slugs, and is idempotent. Cards need a provider wired first ([`../install/03-data.md`](../install/03-data.md)):
+```js
+await base44.functions.invoke("commerce/seed-store", { payment_methods: ["offline", "card"] });
+```
+
+**Edit a gateway's copy or position** — ordinary config; direct CRUD, as Settings → Payments does.
+```js
+await base44.entities["commerce.PaymentGateway"].update(id, { title: "Bank transfer", description: "…", order: 1 });
+```
+
+**Read recent orders** — free-text/date search is `admin-orders` `search`; `filter` is exact-match only:
+```js
+const rows = await base44.entities["commerce.Order"].filter({ status: "processing" }, "-created_date", 20);
+```
+
+**Add an order note** — via the function: a customer note emails the buyer.
+```js
+await base44.functions.invoke("commerce/admin-orders", { action: "add-note", order_id, note: "Shipped", is_customer_note: true });
+```
+
+**Adjust a variation's stock** — via the function: it re-derives `stock_status` and sends stock alerts.
+```js
+await base44.functions.invoke("commerce/admin-products", { action: "set-stock", id: product_id, variation_id, quantity: 12 });
+```
+
+**Edit a shipping location** — direct CRUD. Rate `id`s must be **stable** (carts and orders reference the chosen rate by id), so mint one per rate and keep it. Regions and matching: [`../references/shipping-and-tax.md`](../references/shipping-and-tax.md):
+```js
+const loc = await base44.entities["commerce.ShippingTaxLocation"].get(id);
+await base44.entities["commerce.ShippingTaxLocation"].update(id, {
+  shipping_rates: [...loc.shipping_rates, { id: crypto.randomUUID(), name: "Express", cost: 25, free_over: null }],
+});
+```
+
+**Patch a settings group** — merge into `values`; replacing the object drops every other key in the group. Keys per group: [`../references/store-settings.md`](../references/store-settings.md):
+```js
+const [g] = await base44.entities["commerce.StoreSettings"].filter({ group_id: "products" }, undefined, 1);
+await base44.entities["commerce.StoreSettings"].update(g.id, { values: { ...g.values, auto_approve_reviews: true } });
+```
+
+## Where the rest lives
+
+- A function's actions, payloads and error codes → [`api-admin.md`](./api-admin.md) · [`api-storefront.md`](./api-storefront.md)
+- One entity's complete field list, types, enums, defaults → `base44/entities/commerce.<Name>.jsonc` (one read, never a directory scan)
+- Seeding catalog / locations / payment methods in one call → [`api-admin.md#commerceseed-store`](./api-admin.md#commerceseed-store); worked example in [`../install/03-data.md`](../install/03-data.md)

package/skills/commerce/install/01-install.md

@@ -0,0 +1,101 @@
+---
+stage: install/01
+read_when: "The commerce kit's files were just copied into the app, or you are installing it now."
+skip_when: "The admin already mounts at /store-admin/* behind the shipped AuthGuard and / routes somewhere real."
+forget_when: "The checklist at the bottom of this file passes (admin mounts, / routes somewhere real, /order-received exists)."
+carry_forward:
+  - "Admin enforcement is three layers — AuthGuard (UI), admin-only entity RLS, requireAdmin() in every admin function. Never weaken any of them."
+  - "/order-received must exist as a route: every payment link returns there, and confirming is what marks an order paid."
+  - "Interleave: start image generation first → mount admin + build the storefront while images render → seed when the URLs are back → payments last."
+  - "Entities are dotted + bracket-syntax only (`base44.entities[\"commerce.X\"]`); the map is ../docs/entities.md — never scan base44/entities/."
+---
+
+# 01 — Install
+
+What lands in the app, how the admin gets mounted, and the order to do the rest of the work in.
+
+**Inside the Base44 runtime, writing a resource file *is* the deploy** — entities, functions and the `commerce/StoreAdmin` agent go live the moment the files exist. Nothing to push, no build step. If `scripts/install.js` ran, everything below is already in place.
+
+| Copied to | What it is |
+|---|---|
+| `base44/entities/commerce.*.jsonc` | 20 entity schemas, all admin-only RLS |
+| `base44/functions/commerce/` + `shared/` + `agents/` | 16 functions, the engine, the StoreAdmin copilot |
+| `src/commerce/admin/` | the finished admin app — **don't validate it, it ships tested** |
+| `src/commerce/storefront/` + `utils/` | the headless hooks you build the storefront UI on ([`./02-storefront.md`](./02-storefront.md)) |
+| `.agents/skills/commerce/` | these docs |
+
+<details>
+<summary>CLI path (outside the runtime only — as a Base44 agent, skip all of it)</summary>
+
+```bash
+node examples/commerce/scripts/install.js   # copies the table above
+npx base44 entities push && npx base44 functions deploy && npx base44 agents push
+```
+Confirm `base44/config.jsonc`'s `entitiesDir`/`functionsDir` point at those folders (the defaults do). Granting a user the `admin` role is an operator step, not yours.
+</details>
+
+**Dependencies.** Check `package.json` for `sonner`, `recharts` and `react-markdown`, and `npm i` **only** the ones actually absent — all three ship with the default Base44 template, so the normal outcome is installing nothing. Never re-install a package that is already a dependency. The kit needs no other dependency; verify the shadcn primitives listed in `src/commerce/admin/README.md` exist.
+
+## Work order — interleave, don't queue
+
+Image generation is the slowest step of the install and nothing depends on it until seed time. The storefront doesn't wait on live data either — every shape you build against is documented in [`./02-storefront.md`](./02-storefront.md). So:
+
+1. **Start image generation first** — every product image, before anything else.
+2. **Mount the admin (below) and build the storefront** while the images render.
+3. **Seed the moment the image URLs are back** — one `commerce/seed-store` call ([`./03-data.md`](./03-data.md)); don't idle on it, pick the response (slugs) up when you need it.
+4. **Converge**: open the finished pages against the live catalog.
+5. **Payments last, if at all** — cards are off by default and nothing above depends on them ([`./03-data.md`](./03-data.md) decides it).
+
+The only real dependency edges are *image URLs → seed payload* and *seed done → real products on the pages*. Everything else overlaps.
+
+## Mount the admin router
+
+```jsx
+import AdminApp from "@/commerce/admin";
+import { Navigate } from "react-router-dom";
+
+<Route path="/store-admin/*" element={<AdminApp />} />
+<Route path="/" element={<Navigate to="/store-admin" replace />} />   {/* until a storefront exists */}
+<Route path="/order-received" element={<OrderReceived />} />          {/* mandatory — see below */}
+```
+
+- **The `/*` splat is required.** The admin renders nested routes; a bare `path="/store-admin"` matches only the dashboard and every deeper link 404s. Mounting elsewhere: `<AdminApp basePath="/backoffice" />` — the prefix *without* the splat.
+- **Give `/` something.** A blank Base44 app has no `/` route, so after mounting only the admin the app's own URL renders "page not found", which reads exactly like a broken install. Redirect until the storefront exists.
+- **`/order-received` is mandatory**, even for a store that only ever takes offline payments. Every payment link (checkout, the admin's payment link, emails) returns there, and confirming is what marks an order paid — without the route a paying customer hits a 404 and the order stays unpaid. The page is one hook, `useOrderReturn()`, plus your markup for its states ([`./02-storefront.md`](./02-storefront.md)). A different path must be set in Settings → General → *Payment return path*.
+
+## Admin-role enforcement — do not weaken
+
+The shipped `AuthGuard` requires an authenticated user whose `role === "admin"`: not signed in → "Please sign in"; signed in without the role → "Admin access required". Grant it in the Base44 dashboard or with `base44.users.inviteUser(email, "admin")`.
+
+That guard is the **first of three layers**, and all three are load-bearing:
+
+1. **UI guard** — `AuthGuard` around every admin route (client-side; convenience and UX).
+2. **Entity RLS** — every commerce entity carries `"user_condition": { "role": "admin" }` on all operations, so a direct SDK read or write by a non-admin is rejected by the backend.
+3. **Function guard** — every `commerce/admin-*` function and `commerce/seed-store` calls `requireAdmin()` before touching data via the service role: **401** unauthenticated, **403** not an admin.
+
+Bypassing the client guard therefore reaches nothing. Storefront functions are public on purpose and verify per action instead (auth session, `cart_token`, or `order_key`). The StoreAdmin agent has no entity tools and no service role for the same reason: its calls run with the chatting user's own credentials, so layer 3 still authorizes them.
+
+Check the install at any point:
+
+```js
+const { data } = (await base44.functions.invoke("commerce/admin-tools", { action: "status" })).data;
+// → { template_version, seeded, settings_groups, counts: { "commerce.Product": n, … },
+//     checks: { has_payment_gateways, has_default_location } }
+```
+
+## Done — forget this file
+
+- [ ] `/store-admin/*` mounted with the splat, behind the shipped `AuthGuard`; the three enforcement layers untouched.
+- [ ] `/` routes somewhere real — the storefront, or the redirect above.
+- [ ] `/order-received` is a route in the app's `<Routes>`.
+- [ ] `sonner` / `recharts` / `react-markdown` present (installed only if they were missing).
+- [ ] Image generation is already running, or the store has no product images to make.
+
+Then continue: **[`./02-storefront.md`](./02-storefront.md) when you start building UI**, **[`./03-data.md`](./03-data.md) when you start the seed payload**. Do **not** read them now, and do not open any `references/` or `docs/` file during an install — the stage files say when one is genuinely needed, and a file read early costs its size on every later call.
+
+Record these lines in your working notes; do not re-read this file.
+
+- Admin enforcement is three layers — AuthGuard (UI), admin-only entity RLS, requireAdmin() in every admin function. Never weaken any of them.
+- `/order-received` must exist as a route: every payment link returns there, and confirming is what marks an order paid.
+- Interleave: start image generation first → mount admin + build the storefront while images render → seed when the URLs are back → payments last.
+- Entities are dotted + bracket-syntax only (`base44.entities["commerce.X"]`); the map is [`../docs/entities.md`](../docs/entities.md) — never scan `base44/entities/`.