@base44/app-plugin-commerce 0.1.4 → 0.1.5

package/README.md

@@ -7,7 +7,7 @@ It provides a full-featured **commerce data model and behavior** (variant-driven
 ## What's included
 
 - **24 entities** — Products (a product sells variants when it carries attributes; no type field), variations, categories, tags, attributes + values, reviews, orders (embedded line/shipping/tax/fee/coupon lines), order notes, refunds, coupons, customers, tax classes/rates, shipping zones/methods, 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`.
+- **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, implemented** — hosted payment page, payment links for unpaid orders, two idempotent confirmation paths (customer return + signed webhook) and refunds through the provider. Wired to **Stripe** out of the box behind a provider-neutral payment utility, so the store takes cards as soon as the connector is connected — no charge flow to write — and moving to another provider means implementing one adapter. 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, payments utility + Stripe adapter, 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.
@@ -38,7 +38,7 @@ base44-commerce-template/
 │       │                  know the store natively
 │       ├── SKILL.md       the map: short overview + links to everything below
 │       ├── installation-guidelines.md   installing into an app (scripted or manual)
-│       ├── post-installation.md         embedding the admin pages + AGENTS.md registration
+│       ├── post-installation.md         embedding the admin pages, seeding, storefront quick start
 │       ├── references/    per-topic guides (product rendering, product page & variants,
 │       │                  Stripe, scheduled work, emails, webhooks, media & downloads,
 │       │                  limits, security)
@@ -86,7 +86,7 @@ From your existing Base44 app:
    <Route path="/store-admin/*" element={<AdminApp />} />
    ```
 6. **Grant yourself the `admin` role** (Base44 dashboard → users, or `users.inviteUser(email, "admin")`). The admin UI refuses non-admins.
-7. **Seed the store.** Either open `/store-admin` and click **Initialize store defaults** on the first-run setup screen, or call `commerce/seed-store` directly — it creates the settings groups, gateways, tax classes and a fallback shipping zone, plus a sample catalog when `with_sample_data: true` and the store is empty. Either way pass `store_name` (the app's name) — it is required on a first seed and becomes both the email subject prefix and the sender name. Once the `general` settings group exists the store counts as ready and the first-run screen stops appearing. If an agent is installing this, it should **ask which data the user wants** first — a generated catalog for their actual business, the generic demo data, or nothing: see [`skills/commerce/post-installation.md`](./skills/commerce/post-installation.md) §2.
+7. **Seed the store.** Either open `/store-admin` and click **Initialize store defaults** on the first-run setup screen, or call `commerce/seed-store` directly — it creates the settings groups, gateways, tax classes and a fallback shipping zone, plus the catalog: pass `products` (whole products with attributes — variants, categories and taxonomy are created internally) or `with_sample_data: true` for the generic demo. Either way pass `store_name` (the app's name) — it is required on a first seed and becomes both the email subject prefix and the sender name. Once the `general` settings group exists the store counts as ready and the first-run screen stops appearing. Payload reference and a worked example: [`skills/commerce/post-installation.md`](./skills/commerce/post-installation.md) §2.
 
 ## Quick start (Base44 MCP / hosted apps)
 
@@ -94,7 +94,7 @@ If you build on Base44's hosted platform, use the Base44 agent/MCP to write the
 
 1. Copy this whole repo into the target app at `examples/commerce/` (e.g. download + extract a tarball with `run_command`), then run `node examples/commerce/scripts/install.js` via `run_command` — or use `write_file` to copy every file under `base44/` and `src/commerce/` individually (use `list_directory`/`read_file` to adapt to the app's actual layout — e.g. the `@/api/base44Client` path and your router file).
 2. Wait for the app to build (`get_app_status`), then confirm entities exist (`list_entity_schemas`).
-3. Grant your user the `admin` role, then settle the store's data with the user — generate a real starter catalog via `commerce/seed-store` + `commerce/admin-products`, seed the demo catalog, or leave it to the admin's first-run **Initialize store defaults** screen ([`skills/commerce/post-installation.md`](./skills/commerce/post-installation.md) §2).
+3. Grant your user the `admin` role, then seed the store's data — one `commerce/seed-store` call takes the whole catalog via `products`, or `with_sample_data: true` for the demo catalog; leave both out for defaults only, or skip the call for the admin's first-run **Initialize store defaults** screen ([`skills/commerce/post-installation.md`](./skills/commerce/post-installation.md) §2).
 
 ## What's NOT included
 

package/base44/agents/commerce/StoreAdmin.jsonc

@@ -10,7 +10,7 @@
 {
   "name": "StoreAdmin",
   "description": "Store administration copilot for the commerce template: manage products, orders, refunds, coupons, customers, reviews, reports and maintenance.",
-  "instructions": "You are StoreAdmin, the store administration copilot for this shop's back office. You help store operators inspect and manage the store: products, orders, refunds, coupons, customers, reviews, webhooks, reports, and maintenance.\n\n## How you access the store\nEvery tool takes a JSON body of the form {\"action\": \"<action>\", ...payload} (exception: commerce/seed-store takes {store_name, with_sample_data?} with no action key — store_name is REQUIRED on a first seed) and responds {success, data} or {success:false, error, code}. Search/list actions return {rows, has_next} using limit+skip pagination (there are no total counts). Use search actions for free-text lookups (product name, customer email, coupon code, order number).\n\nStore configuration (settings, tax rates, shipping zones, payment gateways, webhook definitions) is not editable through your tools — see \"Sending the operator to a screen\" below.\n\n## Sending the operator to a screen\nSome configuration is only editable in the admin UI. When one of those is asked for, say plainly that you cannot change it from chat, name the screen, and give a link the operator can click — never just \"do it manually\", and never imply you tried and failed. Do not blame permissions or a security error: the reason is simply that the UI is the only place that configuration is edited.\n\nLinks use the `admin:` scheme with a path from the table below — `[Settings → Tax](admin:settings/tax)`. The chat resolves that to wherever the admin is mounted, so never write `/store-admin/...` yourself.\n\n| Ask | Screen | Link |\n|---|---|---|\n| Currency and price formatting, payment return path | Settings → General | admin:settings/general |\n| Catalog defaults, review settings | Settings → Products | admin:settings/products |\n| Stock thresholds, hold minutes, inventory recipient | Settings → Inventory | admin:settings/inventory |\n| Tax classes, tax rates, price display | Settings → Tax | admin:settings/tax |\n| Shipping zones, methods, shipping classes | Settings → Shipping | admin:settings/shipping |\n| Enabling a gateway, offline bank details | Settings → Payments | admin:settings/payments |\n| Store name (subjects + sender), admin notification recipients, per-email overrides | Settings → Emails | admin:settings/emails |\n| Creating or deleting a webhook (you CAN test and redeliver) | Settings → Webhooks | admin:settings/webhooks |\n\nExample: \"Tax rates aren't something I can change from here — they live in the store's tax settings. Open [Settings → Tax](admin:settings/tax) to add the rate, then tell me and I'll re-check the order's totals.\"\n\nCatalog taxonomy is the opposite: you CAN create categories, tags, attributes and attribute values yourself with commerce/admin-products save-term. Never send the operator to a screen to create one — link to admin:products/categories if they want to review or reorder categories by hand. Tags and attributes have no screen of their own: attributes are edited in the Attributes section of a product's Price & Inventory tab, tags in the Tags card of the product sidebar — so link to the product (admin:products) instead.\n\n## Product variants — be careful\nA product that carries attributes is sold through its variants (there is no product type), and every variant can differ in attributes (e.g. size/color), SKU, price and stock.\n- NEVER pick a variation automatically. When an order line, stock change, or download grant involves a product that carries attributes, first fetch its variations with commerce/storefront-catalog {\"action\":\"get-product\",\"id\":...} (returns {product, variations}), present them in a table (attributes, SKU, price, stock status), and ask the operator which variation to use — then include that variation_id in the item spec.\n- If the operator already named an exact variation (by SKU or full attribute combination), match it against the fetched variations and confirm the match in your reply; if the description is partial or matches more than one variation, ask.\n- Order item specs for commerce/admin-orders create/update are {product_id, variation_id?, quantity, price_override?} — variation_id is REQUIRED for a product with attributes.\n- The same applies to commerce/admin-products set-stock (pass variation_id to change a variation's stock, not the parent's).\n\n## Behavior\n- Be concise and operational. Confirm before destructive or irreversible operations (delete, refund, bulk-status, prune, clear-abandoned-carts) by restating what will happen and asking the user to confirm — unless the user's message already explicitly confirms it.\n- When showing lists or reports, format them as GitHub-flavored markdown tables (| col | col | with a |---| separator row). Keep tables ≤ 8 columns; prefer the most decision-relevant fields (name/number, status, total, date). Format money with the store currency.\n- After a mutation, report exactly what changed (ids, statuses, totals) and surface any error/code verbatim.\n- If a request is ambiguous (which order? which product?), search first and present the candidates in a table, then ask.\n- For store health questions, start with commerce/admin-tools {\"action\":\"status\"} and commerce/admin-reports {\"action\":\"summary\"}.\n- Payments: for an unpaid order paid online, commerce/payments create-link {order_id} gives a payment page link to send the customer, and verify {order_id} re-checks whether the money arrived. If no payment provider is connected, say \"no payment provider is connected\" and that connecting one enables card payments — don't name or troubleshoot a specific provider. Never invent a payment link or claim an order is paid without verifying.\n- You act with store-operator privileges; do not attempt to weaken or bypass access controls, and never expose secrets (webhook secrets, tokens).",
+  "instructions": "You are StoreAdmin, the store administration copilot for this shop's back office. You help store operators inspect and manage the store: products, orders, refunds, coupons, customers, reviews, webhooks, reports, and maintenance.\n\n## How you access the store\nEvery tool takes a JSON body of the form {\"action\": \"<action>\", ...payload} (exception: commerce/seed-store takes {store_name, with_sample_data?, products?, coupons?, tax_rates?} with no action key — store_name is REQUIRED on a first seed, and products can bootstrap a whole catalog in one call, variants included; see skills/commerce/docs/api-admin.md) and responds {success, data} or {success:false, error, code}. Search/list actions return {rows, has_next} using limit+skip pagination (there are no total counts). Use search actions for free-text lookups (product name, customer email, coupon code, order number).\n\nStore configuration (settings, tax rates, shipping zones, payment gateways, webhook definitions) is not editable through your tools — see \"Sending the operator to a screen\" below.\n\n## Sending the operator to a screen\nSome configuration is only editable in the admin UI. When one of those is asked for, say plainly that you cannot change it from chat, name the screen, and give a link the operator can click — never just \"do it manually\", and never imply you tried and failed. Do not blame permissions or a security error: the reason is simply that the UI is the only place that configuration is edited.\n\nLinks use the `admin:` scheme with a path from the table below — `[Settings → Tax](admin:settings/tax)`. The chat resolves that to wherever the admin is mounted, so never write `/store-admin/...` yourself.\n\n| Ask | Screen | Link |\n|---|---|---|\n| Currency and price formatting, payment return path | Settings → General | admin:settings/general |\n| Catalog defaults, review settings | Settings → Products | admin:settings/products |\n| Stock thresholds, hold minutes, inventory recipient | Settings → Inventory | admin:settings/inventory |\n| Tax classes, tax rates, price display | Settings → Tax | admin:settings/tax |\n| Shipping zones, methods, shipping classes | Settings → Shipping | admin:settings/shipping |\n| Enabling a gateway, offline bank details | Settings → Payments | admin:settings/payments |\n| Store name (subjects + sender), admin notification recipients, per-email overrides | Settings → Emails | admin:settings/emails |\n| Creating or deleting a webhook (you CAN test and redeliver) | Settings → Webhooks | admin:settings/webhooks |\n\nExample: \"Tax rates aren't something I can change from here — they live in the store's tax settings. Open [Settings → Tax](admin:settings/tax) to add the rate, then tell me and I'll re-check the order's totals.\"\n\nCatalog taxonomy is the opposite: you CAN create categories, tags, attributes and attribute values yourself with commerce/admin-products save-term. Never send the operator to a screen to create one — link to admin:products/categories if they want to review or reorder categories by hand. Tags and attributes have no screen of their own: attributes are edited in the Attributes section of a product's Price & Inventory tab, tags in the Tags card of the product sidebar — so link to the product (admin:products) instead.\n\n## Product variants — be careful\nA product that carries attributes is sold through its variants (there is no product type), and every variant can differ in attributes (e.g. size/color), SKU, price and stock.\n- NEVER pick a variation automatically. When an order line, stock change, or download grant involves a product that carries attributes, first fetch its variations with commerce/storefront-catalog {\"action\":\"get-product\",\"id\":...} (returns {product, variations}), present them in a table (attributes, SKU, price, stock status), and ask the operator which variation to use — then include that variation_id in the item spec.\n- If the operator already named an exact variation (by SKU or full attribute combination), match it against the fetched variations and confirm the match in your reply; if the description is partial or matches more than one variation, ask.\n- Order item specs for commerce/admin-orders create/update are {product_id, variation_id?, quantity, price_override?} — variation_id is REQUIRED for a product with attributes.\n- The same applies to commerce/admin-products set-stock (pass variation_id to change a variation's stock, not the parent's).\n\n## Behavior\n- Be concise and operational. Confirm before destructive or irreversible operations (delete, refund, bulk-status, prune, clear-abandoned-carts) by restating what will happen and asking the user to confirm — unless the user's message already explicitly confirms it.\n- When showing lists or reports, format them as GitHub-flavored markdown tables (| col | col | with a |---| separator row). Keep tables ≤ 8 columns; prefer the most decision-relevant fields (name/number, status, total, date). Format money with the store currency.\n- After a mutation, report exactly what changed (ids, statuses, totals) and surface any error/code verbatim.\n- If a request is ambiguous (which order? which product?), search first and present the candidates in a table, then ask.\n- For store health questions, start with commerce/admin-tools {\"action\":\"status\"} and commerce/admin-reports {\"action\":\"summary\"}.\n- Payments: for an unpaid order paid online, commerce/payments create-link {order_id} gives a payment page link to send the customer, and verify {order_id} re-checks whether the money arrived. If no payment provider is connected, say \"no payment provider is connected\" and that connecting one enables card payments — don't name or troubleshoot a specific provider. Never invent a payment link or claim an order is paid without verifying.\n- You act with store-operator privileges; do not attempt to weaken or bypass access controls, and never expose secrets (webhook secrets, tokens).",
   "tool_configs": [
     {
       "function_name": "commerce/admin-products",

package/base44/functions/commerce/admin-products/entry.ts

@@ -14,7 +14,17 @@ import { isVariable } from "../../../shared/commerce/products.ts";
 import { sendStockEmail } from "../../../shared/commerce/emails.ts";
 import { dispatch } from "../../../shared/commerce/webhooks.ts";
 import { pageSlice, scanAll, textMatch } from "../../../shared/commerce/scan.ts";
-import { round2 } from "../../../shared/commerce/money.ts";
+import {
+  adjustTermCounts,
+  assertUniqueSku,
+  bumpCount,
+  derivePricing,
+  deriveStock,
+  ensureUniqueCode,
+  ensureUniqueSlug,
+  rollUpParent,
+  slugify,
+} from "../../../shared/commerce/catalog.ts";
 
 const ok = (data: unknown, status = 200) => Response.json({ success: true, data }, { status });
 const fail = (status: number, error: string, code?: string) =>
@@ -56,87 +66,6 @@ Deno.serve(async (req) => {
   }
 });
 
-// ── derivations ──────────────────────────────────────────────────────────────
-
-function slugify(name: string): string {
-  return String(name || "")
-    .toLowerCase()
-    .trim()
-    .replace(/[^a-z0-9]+/g, "-")
-    .replace(/^-+|-+$/g, "") || "product";
-}
-
-/** price/on_sale from the sale window. Mutates rec. */
-function derivePricing(rec: any): void {
-  const now = Date.now();
-  const from = rec.date_on_sale_from ? new Date(rec.date_on_sale_from).getTime() : -Infinity;
-  const to = rec.date_on_sale_to ? new Date(rec.date_on_sale_to).getTime() : Infinity;
-  const saleActive = rec.sale_price != null && rec.sale_price !== "" && now >= from && now <= to;
-  rec.on_sale = !!saleActive;
-  const effective = saleActive ? rec.sale_price : rec.regular_price;
-  if (effective != null && effective !== "") rec.price = round2(Number(effective));
-}
-
-/** stock_status derivation when stock is managed. Mutates rec. */
-function deriveStock(rec: any, outThreshold: number, managed: boolean): void {
-  if (managed) {
-    rec.stock_status = deriveStockStatus(
-      Number(rec.stock_quantity ?? 0),
-      rec.backorders ?? "no",
-      outThreshold,
-    );
-  } else if (!rec.stock_status) {
-    rec.stock_status = "instock";
-  }
-}
-
-// ── uniqueness ───────────────────────────────────────────────────────────────
-
-async function ensureUniqueSlug(
-  sr: any,
-  slug: string,
-  selfId?: string,
-  entity = "commerce.Product",
-  scope?: Record<string, any>,
-): Promise<string> {
-  let candidate = slug;
-  for (let i = 2; i < 100; i++) {
-    const hits = (await sr.entities[entity].filter({ ...(scope ?? {}), slug: candidate }, undefined, 2)) ?? [];
-    if (!hits.some((p: any) => p.id !== selfId)) return candidate;
-    candidate = `${slug}-${i}`;
-  }
-  return `${slug}-${crypto.randomUUID().slice(0, 6)}`;
-}
-
-/** SKU must be unique across products AND variations. Throws duplicate_sku. */
-async function assertUniqueSku(sr: any, sku: string, opts: { productId?: string; variationId?: string }): Promise<void> {
-  if (!sku) return;
-  const prods = (await sr.entities["commerce.Product"].filter({ sku }, undefined, 2)) ?? [];
-  if (prods.some((p: any) => p.id !== opts.productId)) {
-    throw new HttpError(409, `SKU "${sku}" is already in use by another product.`, "duplicate_sku");
-  }
-  const vars = (await sr.entities["commerce.ProductVariation"].filter({ sku }, undefined, 2)) ?? [];
-  if (vars.some((v: any) => v.id !== opts.variationId)) {
-    throw new HttpError(409, `SKU "${sku}" is already in use by a product variation.`, "duplicate_sku");
-  }
-}
-
-// ── taxonomy counts ──────────────────────────────────────────────────────────
-
-async function adjustTermCounts(sr: any, entity: string, prevIds: string[], nextIds: string[]): Promise<void> {
-  const added = nextIds.filter((id) => !prevIds.includes(id));
-  const removed = prevIds.filter((id) => !nextIds.includes(id));
-  for (const id of added) await bumpCount(sr, entity, id, +1);
-  for (const id of removed) await bumpCount(sr, entity, id, -1);
-}
-
-async function bumpCount(sr: any, entity: string, id: string, delta: number): Promise<void> {
-  try {
-    const rec = await sr.entities[entity].get(id);
-    if (rec) await sr.entities[entity].update(id, { count: Math.max(0, (rec.count ?? 0) + delta) });
-  } catch { /* stale reference — recount-terms repairs */ }
-}
-
 // ── save ─────────────────────────────────────────────────────────────────────
 
 async function save(sr: any, payload: any): Promise<any> {
@@ -214,44 +143,6 @@ async function diffVariations(sr: any, parent: any, incoming: any[], outThreshol
   return out;
 }
 
-/**
- * Roll a variant parent's stock and price up from its variations.
- *
- * Price matters beyond display: `list-products` sorts and filters on
- * `product.price`, so a parent left empty sorts as free and drops out of every
- * price filter. Deriving it removes a number nobody could keep in sync by hand —
- * the parent is simply the cheapest thing a customer can actually buy.
- */
-async function rollUpParent(sr: any, parent: any, variations: any[]): Promise<void> {
-  if (!isVariable(parent)) return;
-  const live = variations.filter((v) => (v.status ?? "publish") === "publish");
-  const patch: Record<string, any> = {};
-
-  // manage_stock on the parent means the merchant tracks one pooled quantity,
-  // and with it off an explicit stock_status is their own choice to keep.
-  if (!parent.manage_stock) {
-    const status = live.length && live.every((v) => v.stock_status === "outofstock")
-      ? "outofstock"
-      : "instock";
-    if (status !== parent.stock_status) patch.stock_status = status;
-  }
-
-  const cheapest = (key: string): number | null => {
-    const values = live.map((v) => Number(v[key])).filter((n) => Number.isFinite(n));
-    return values.length ? round2(Math.min(...values)) : null;
-  };
-  const regular = cheapest("regular_price");
-  const price = cheapest("price") ?? regular;
-  const onSale = live.some((v) => !!v.on_sale);
-  if (regular !== (parent.regular_price ?? null)) patch.regular_price = regular;
-  if (price !== (parent.price ?? null)) patch.price = price;
-  if (onSale !== !!parent.on_sale) patch.on_sale = onSale;
-
-  if (!Object.keys(patch).length) return;
-  await sr.entities["commerce.Product"].update(parent.id, patch);
-  Object.assign(parent, patch);
-}
-
 // ── delete / batch / duplicate ───────────────────────────────────────────────
 
 async function remove(sr: any, id: string): Promise<any> {
@@ -474,17 +365,6 @@ async function saveTerm(sr: any, payload: any): Promise<any> {
   return await sr.entities[entity].create(withCount);
 }
 
-/** `code` is what a storefront filter URL carries, so it has to be unique. */
-async function ensureUniqueCode(sr: any, code: string, selfId?: string): Promise<string> {
-  let candidate = code;
-  for (let i = 2; i < 100; i++) {
-    const hits = (await sr.entities["commerce.ProductAttribute"].filter({ code: candidate }, undefined, 2)) ?? [];
-    if (!hits.some((a: any) => a.id !== selfId)) return candidate;
-    candidate = `${code}-${i}`;
-  }
-  return `${code}-${crypto.randomUUID().slice(0, 6)}`;
-}
-
 /** Rewrite a renamed value across every product and variant that used it. */
 async function renameAttributeValue(sr: any, attributeId: string, from: string, to: string): Promise<void> {
   const products = await scanAll(sr.entities["commerce.Product"]);

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

@@ -1,22 +1,25 @@
 /**
  * commerce/seed-store — idempotent store initialization.
  *
- * Flow: (1) canary schema validation (probe create+delete per entity; abort
- * with 422 schema_incompatible and write nothing on any failure), (2) seed
- * required defaults (settings groups, gateways, tax classes, fallback zone),
- * (3) optional sample catalog (10 products with images and
- * descriptions, three of which carry attributes and ship with variants) — only
- * when with_sample_data=true and the store has zero products, with best-effort
- * rollback on mid-failure.
+ * Flow: (1) validate any catalog payload (pure — 400 invalid_payload with
+ * per-field errors before anything runs), (2) canary schema validation (probe
+ * create+delete per entity; abort with 422 schema_incompatible and write
+ * nothing on any failure), (3) seed required defaults (settings groups,
+ * gateways, tax classes, fallback zone), (4) the catalog: either the caller's
+ * `products`/`coupons`/`tax_rates` (taxonomy get-or-created by name,
+ * variations generated from `attributes` when not given, per-product skip when
+ * the sku/slug already exists) or the generic demo catalog
+ * (with_sample_data=true, only when the store has zero products) — with
+ * best-effort rollback on mid-failure. See seed-catalog.ts for the pipeline.
  *
- * Body: { with_sample_data?: boolean, store_name?: string }
+ * Body: { store_name?, with_sample_data?, products?, coupons?, tax_rates? }
+ * — with_sample_data cannot be combined with the catalog keys.
  *
  * `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.
  */
 import { createClientFromRequest } from "npm:@base44/sdk";
 import { HttpError, requireAdmin } from "../../../shared/commerce/auth.ts";
-import { round2 } from "../../../shared/commerce/money.ts";
 import {
   GATEWAY_DEFAULTS,
   REST_OF_WORLD_EXAMPLE_METHOD,
@@ -24,14 +27,7 @@ import {
   SETTINGS_DEFAULTS,
   TAX_CLASS_DEFAULTS,
 } from "./defaults.ts";
-import {
-  SAMPLE_ATTRIBUTE_TERMS,
-  SAMPLE_ATTRIBUTES,
-  SAMPLE_CATEGORIES,
-  SAMPLE_COUPONS,
-  SAMPLE_PRODUCTS,
-  SAMPLE_TAX_RATES,
-} from "./sample-data.ts";
+import { CatalogPayloadError, normalizeCatalogPayload, sampleCatalog, seedCatalog } from "./seed-catalog.ts";
 
 const ok = (data: unknown, status = 200) => Response.json({ success: true, data }, { status });
 const fail = (status: number, error: string, code?: string, extra?: Record<string, unknown>) =>
@@ -46,8 +42,18 @@ Deno.serve(async (req) => {
     const withSample = !!body.with_sample_data;
     const storeName = String(body.store_name ?? "").trim();
 
+    // ── 0. normalize the catalog payload — pure, so bad input fails before
+    //       canaries or any write ─────────────────────────────────────────────
+    let catalogSpec = null;
+    try {
+      catalogSpec = normalizeCatalogPayload(body);
+    } catch (e) {
+      if (e instanceof CatalogPayloadError) return fail(400, e.message, "invalid_payload", { errors: e.errors });
+      throw e;
+    }
+
     // ── 1. canary schema validation — abort before writing anything real ────
-    const canaryErrors = await runCanaries(sr, withSample);
+    const canaryErrors = await runCanaries(sr, withSample || !!catalogSpec);
     if (canaryErrors.length) {
       return fail(422,
         "Entity schemas have been modified and are incompatible with the seeder.",
@@ -115,21 +121,27 @@ Deno.serve(async (req) => {
       seeded.zone_methods++;
     }
 
-    // ── 3. optional sample catalog ───────────────────────────────────────────
-    let sampleResult: Record<string, number> | null = null;
+    // ── 3. the catalog: caller-supplied, or the demo sample ──────────────────
+    let sampleResult: Record<string, any> | null = null;
     if (withSample) {
       const anyProduct = (await sr.entities["commerce.Product"].list(undefined, 1)) ?? [];
       if (!anyProduct.length) {
-        sampleResult = await seedSampleData(sr);
+        sampleResult = await seedCatalog(sr, sampleCatalog(), { skipExisting: false, errorCode: "sample_seed_failed" });
       }
     }
 
+    let catalogResult: Record<string, any> | null = null;
+    if (catalogSpec) {
+      catalogResult = await seedCatalog(sr, catalogSpec, { skipExisting: true, errorCode: "catalog_seed_failed" });
+    }
+
     const currentName = String(
       (existingSettings.find((r: any) => r.group_id === "emails")?.values?.store_name ?? storeName) || storeName,
     );
     return ok({
       seeded,
       sample_data: sampleResult ?? false,
+      catalog: catalogResult,
       store_name: { value: storeNameAction === "kept_existing" ? currentName : storeName, action: storeNameAction },
     });
   } catch (e) {
@@ -142,7 +154,7 @@ Deno.serve(async (req) => {
 // ── canaries ─────────────────────────────────────────────────────────────────
 
 /** Minimal-valid probe records per entity the seeder writes. */
-function canarySpecs(withSample: boolean): Array<{ entity: string; record: Record<string, any> }> {
+function canarySpecs(needsCatalog: boolean): Array<{ entity: string; record: Record<string, any> }> {
   const base = [
     { entity: "commerce.StoreSettings", record: { group_id: "general", values: { __canary: true } } },
     { entity: "commerce.PaymentGateway", record: { slug: "__canary", title: "Canary", enabled: false, order: 999, settings: {} } },
@@ -150,8 +162,9 @@ function canarySpecs(withSample: boolean): Array<{ entity: string; record: Recor
     { entity: "commerce.ShippingZone", record: { name: "__canary", order: 998, locations: [] } },
     { entity: "commerce.ShippingZoneMethod", record: { zone_id: "__canary", method_id: "flat_rate", title: "Canary", enabled: false, order: 0, settings: { cost: 0 } } },
   ];
-  const sample = [
+  const catalog = [
     { entity: "commerce.ProductCategory", record: { name: "__canary", slug: "__canary", count: 0 } },
+    { entity: "commerce.ProductTag", record: { name: "__canary", count: 0 } },
     { entity: "commerce.ProductAttribute", record: { name: "__canary", code: "__canary", order: 0 } },
     { entity: "commerce.ProductAttributeTerm", record: { attribute_id: "__canary", name: "__canary", order: 0 } },
     { entity: "commerce.Product", record: { name: "__canary", status: "draft", regular_price: 1, price: 1 } },
@@ -159,12 +172,12 @@ function canarySpecs(withSample: boolean): Array<{ entity: string; record: Recor
     { entity: "commerce.Coupon", record: { code: "__canary", discount_type: "percent", amount: 1, usage_count: 0, used_by: [] } },
     { entity: "commerce.TaxRate", record: { country: "ZZ", rate: 1, name: "__canary", priority: 1, compound: false, shipping: true, tax_class: "standard" } },
   ];
-  return withSample ? [...base, ...sample] : base;
+  return needsCatalog ? [...base, ...catalog] : base;
 }
 
-async function runCanaries(sr: any, withSample: boolean): Promise<Array<{ entity: string; error: string }>> {
+async function runCanaries(sr: any, needsCatalog: boolean): Promise<Array<{ entity: string; error: string }>> {
   const errors: Array<{ entity: string; error: string }> = [];
-  for (const spec of canarySpecs(withSample)) {
+  for (const spec of canarySpecs(needsCatalog)) {
     let created: any = null;
     try {
       created = await sr.entities[spec.entity].create(spec.record);
@@ -179,144 +192,3 @@ async function runCanaries(sr: any, withSample: boolean): Promise<Array<{ entity
   return errors;
 }
 
-// ── sample catalog ───────────────────────────────────────────────────────────
-
-/** price/on_sale/stock_status derivation for seeded products (mirrors commerce/admin-products). */
-function deriveSeedProduct(p: any): any {
-  const out = { ...p };
-  out.on_sale = out.sale_price != null;
-  const effective = out.on_sale ? out.sale_price : out.regular_price;
-  if (effective != null) out.price = round2(Number(effective));
-  if (out.manage_stock) {
-    const qty = Number(out.stock_quantity ?? 0);
-    out.stock_status = qty > 0 ? "instock" : (out.backorders && out.backorders !== "no" ? "onbackorder" : "outofstock");
-  } else if (!out.stock_status) {
-    out.stock_status = "instock";
-  }
-  return out;
-}
-
-async function seedSampleData(sr: any): Promise<Record<string, number>> {
-  // rollback ledger — delete in reverse order on failure
-  const created: Array<{ entity: string; id: string }> = [];
-  const track = async (entity: string, record: Record<string, any>) => {
-    const rec = await sr.entities[entity].create(record);
-    created.push({ entity, id: rec.id });
-    return rec;
-  };
-
-  try {
-    // categories
-    const categoryBySlug: Record<string, any> = {};
-    for (const cat of SAMPLE_CATEGORIES) {
-      categoryBySlug[cat.slug] = await track("commerce.ProductCategory", cat);
-    }
-
-    // attributes + values
-    const attributeByCode: Record<string, any> = {};
-    for (const attr of SAMPLE_ATTRIBUTES) {
-      const rec = await track("commerce.ProductAttribute", attr);
-      attributeByCode[attr.code] = rec;
-      for (const value of SAMPLE_ATTRIBUTE_TERMS[attr.code] ?? []) {
-        await track("commerce.ProductAttributeTerm", { ...value, attribute_id: rec.id, count: 0 });
-      }
-    }
-
-    const productByKey: Record<string, any> = {};
-    let variationCount = 0;
-    const specs = SAMPLE_PRODUCTS;
-
-    for (const spec of specs) {
-      const { key, categories, attributes, default_attributes, variations, options: _o, ...fields } = spec;
-      const record: any = deriveSeedProduct({
-        ...fields,
-        slug: fields.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, ""),
-        category_ids: (categories ?? []).map((slug: string) => categoryBySlug[slug]?.id).filter(Boolean),
-        tag_ids: [],
-        images: fields.images ?? [],
-        meta_data: [],
-        total_sales: 0,
-      });
-      if (attributes) {
-        record.attributes = attributes.map((a: any, i: number) => ({
-          attribute_id: attributeByCode[a.code]?.id ?? "",
-          name: attributeByCode[a.code]?.name ?? a.code,
-          position: i,
-          options: a.options ?? [],
-        }));
-      }
-      if (default_attributes) {
-        record.default_attributes = default_attributes.map((d: any) => ({
-          attribute_id: attributeByCode[d.code]?.id ?? "",
-          name: attributeByCode[d.code]?.name ?? d.code,
-          option: d.option,
-        }));
-      }
-      const product = await track("commerce.Product", record);
-      productByKey[key] = product;
-
-      const seededVariations: any[] = [];
-      for (const v of variations ?? []) {
-        const attrs = Object.entries(v.options).map(([code, option]) => ({
-          attribute_id: attributeByCode[code]?.id ?? "",
-          name: attributeByCode[code]?.name ?? code,
-          option,
-        }));
-        seededVariations.push(await track("commerce.ProductVariation", deriveSeedProduct({
-          product_id: product.id,
-          attributes: attrs,
-          status: "publish",
-          sku: `${record.sku}-${Object.values(v.options).join("-").toUpperCase()}`,
-          regular_price: v.regular_price,
-          ...(v.sale_price != null ? { sale_price: v.sale_price } : {}),
-          manage_stock: "yes",
-          stock_quantity: v.stock_quantity,
-          backorders: v.backorders ?? "no",
-          ...(v.image ? { image: v.image } : {}),
-        })));
-        variationCount++;
-      }
-
-      // The parent's price is the cheapest variant. commerce/admin-products
-      // derives this on save, but the seeder writes entities directly — without
-      // this a seeded variant product has no price, so it sorts as free and
-      // drops out of every price filter.
-      if (seededVariations.length) {
-        const cheapest = (key: string) => {
-          const values = seededVariations.map((v) => Number(v[key])).filter((n) => Number.isFinite(n));
-          return values.length ? round2(Math.min(...values)) : null;
-        };
-        const regular = cheapest("regular_price");
-        await sr.entities["commerce.Product"].update(product.id, {
-          regular_price: regular,
-          price: cheapest("price") ?? regular,
-          on_sale: seededVariations.some((v) => !!v.on_sale),
-        });
-      }
-    }
-
-    // taxonomy counts for the seeded catalog
-    for (const cat of Object.values(categoryBySlug) as any[]) {
-      const count = specs.filter((s) => (s.categories ?? []).some((slug: string) => categoryBySlug[slug]?.id === cat.id)).length;
-      await sr.entities["commerce.ProductCategory"].update(cat.id, { count });
-    }
-
-    for (const coupon of SAMPLE_COUPONS) await track("commerce.Coupon", coupon);
-    for (const rate of SAMPLE_TAX_RATES) await track("commerce.TaxRate", rate);
-
-    return {
-      categories: SAMPLE_CATEGORIES.length,
-      attributes: SAMPLE_ATTRIBUTES.length,
-      products: SAMPLE_PRODUCTS.length,
-      variations: variationCount,
-      coupons: SAMPLE_COUPONS.length,
-      tax_rates: SAMPLE_TAX_RATES.length,
-    };
-  } catch (e) {
-    // best-effort rollback, newest first
-    for (const { entity, id } of created.reverse()) {
-      try { await sr.entities[entity].delete(id); } catch { /* leave orphans; commerce/admin-tools can clean */ }
-    }
-    throw new HttpError(500, `Sample data seeding failed and was rolled back: ${(e as Error).message}`, "sample_seed_failed");
-  }
-}