@base44/app-plugin-commerce 0.2.5 → 0.2.6

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

@@ -12,41 +12,23 @@ carry_forward:
 
 # 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** — the 20 `commerce.*` entities, the 16 `commerce/*` functions + shared engine, the StoreAdmin agent, the finished admin app (`src/commerce/admin/` — don't validate it, it ships tested) and the storefront hooks (`src/commerce/storefront/` + `utils/`) are live the moment the files exist. If `scripts/install.js` ran, all of that is already in place; there is no build step and nothing to push.
 
-**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.
+**Anonymous function calls must be allowed** in the app's settings — the storefront functions are public by design (they verify per action: auth session, `cart_token`, or `order_key`). If the app blocks unauthenticated invocation, every guest hits errors on the entire storefront.
 
-| 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.
+**Dependencies.** `sonner`, `recharts`, `react-markdown` — all three ship with the default Base44 template, so check `package.json` and `npm i` only what is actually absent (the normal outcome is installing nothing).
 
 ## 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:
+Image generation is the slowest step and nothing depends on it until seed time; the storefront doesn't wait on live data either.
 
 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.
+2. **Mount the admin (below) and build the storefront** while images render.
+3. **Seed the moment the image URLs are back** — one `commerce/seed-store` call ([`./03-data.md`](./03-data.md)).
 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).
+5. **Payments last, if at all** — cards are off by default; [`./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.
+The only dependency edges are *image URLs → seed payload* and *seed done → real products on the pages*.
 
 ## Mount the admin router
 
@@ -59,39 +41,28 @@ import { Navigate } from "react-router-dom";
 <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*.
+- **The `/*` splat is required** — without it every nested admin link 404s. Mounting elsewhere: `<AdminApp basePath="/backoffice" />` (prefix without the splat).
+- **Give `/` something** — a blank app has no `/` route, and "page not found" at the app's own URL reads like a broken install.
+- **`/order-received` is mandatory**, even offline-only: every payment link returns there, and confirming is what marks an order paid — without it a paying customer hits a 404 and the order stays unpaid. The page is one hook, `useOrderReturn()` ([`./02-storefront.md`](./02-storefront.md)). A different path must be set in Settings → General (`general.order_received_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")`.
+Three layers, all load-bearing; keep every one when touching routes or schemas:
 
-That guard is the **first of three layers**, and all three are load-bearing:
+1. **UI guard** — the shipped `AuthGuard` (requires `role === "admin"`; grant via the dashboard or `base44.users.inviteUser(email, "admin")`).
+2. **Entity RLS** — every commerce entity is admin-only on all operations.
+3. **Function guard** — every `commerce/admin-*` function and `commerce/seed-store` calls `requireAdmin()`: **401** unauthenticated, **403** not admin.
 
-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 } }
-```
+Storefront functions are public on purpose (per-action verification, above). To check install state at any point: `commerce/admin-tools` `{ action: "status" }` ([`../docs/api-admin.md`](../docs/api-admin.md)).
 
 ## 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.
+- [ ] `/` routes somewhere real; `/order-received` is a route.
+- [ ] Anonymous function invocation is allowed in the app's settings.
+- [ ] Missing dependencies (if any) installed; image generation already running.
 
-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.
+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 open no `references/` or `docs/` file during an install — a file read early costs its size on every later call.
 
 Record these lines in your working notes; do not re-read this file.