@base44/app-plugin-commerce 0.1.15 → 0.1.16

package/README.md

@@ -8,10 +8,11 @@ It provides a full-featured **commerce data model and behavior** (variant-driven
 
 - **20 entities** — Products (a product sells variants when it carries attributes; no type field), variations, categories, ribbons, attributes + values, reviews, orders (embedded line/shipping/tax/fee/coupon lines), order notes, refunds, coupons, customers, Shipping & Tax Locations (shipping rates + tax groups per location), 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` — one call seeds the business defaults **and the whole catalog** (products with attributes in, variants/categories/taxonomy created internally).
-- **Online card payments, order side premade** — checkout routing, payment links for unpaid orders, two idempotent confirmation paths (customer return + webhook, both premade) and refund records are all built. Wiring a provider (Stripe, PayPal, a local PSP…) means implementing **four functions in one file** — `base44/shared/commerce/card-payment.ts` — and nothing else; a complete Stripe implementation to paste in ships in [`skills/commerce/post-installation.md`](./skills/commerce/post-installation.md) §2.2. Every other payment option is manual (on-hold + instructions) and needs no code; the admin can add more in Settings → Payments. See [`skills/commerce/references/online-payments.md`](./skills/commerce/references/online-payments.md).
+- **Online card payments, order side premade** — checkout routing, payment links for unpaid orders, two idempotent confirmation paths (customer return + webhook, both premade) and refund records are all built. Wiring a provider (Stripe, PayPal, a local PSP…) means implementing **four functions in one file** — `base44/shared/commerce/card-payment.ts` — and nothing else; a complete Stripe implementation to paste in ships in [`skills/commerce/post-installation.md`](./skills/commerce/post-installation.md) §4. Every other payment option is manual (on-hold + instructions) and needs no code; the admin can add more in Settings → Payments. 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, card-payment plumbing, 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.
 - **Storefront helpers** (`src/commerce/utils/`) — framework-free, dependency-free modules for the shopfront you build: `storefront.js` is the API client (`createStorefront(base44)` — cart-token lifecycle, cached store-info, catalog/cart/checkout/return-page calls); `variants.js` maps an attribute selection (Size, Color) onto a `ProductVariation` and back, plus per-option availability and variant price ranges; `shipping-promos.js` reads the store's real free-shipping configuration so "Free shipping over €150" copy states a configured rule rather than an invented number. See [`skills/commerce/references/storefront-product-page.md`](./skills/commerce/references/storefront-product-page.md).
+- **Storefront React layer** (`src/commerce/storefront/`) — hooks and headless (render-prop) helpers for the parts of a shopfront whose contracts are the same in every store, with **zero visual components** (the look stays yours): `StorefrontProvider` (one client, cached store info, ONE shared cart), `useCart` (shared cart state, serialized mutations), `useCheckout` (guided checkout — automatic debounced shipping/tax recalculation once the address is complete, shipping/payment choice, a `canPlaceOrder` gate with named blockers, redirect-handling `placeOrder`), `ShippingMethodPicker`/`PaymentMethodPicker` (headless), and `useOrderReturn` (the mandatory `/order-received` page in one hook). Needs React and nothing else.
 - **StoreAdmin agent + bot** — an AI copilot (`base44/agents/commerce/StoreAdmin.jsonc`, registered as `commerce/StoreAdmin`) with the `commerce/*` functions attached directly as tools (calls run as the chatting user → `requireAdmin()` still applies), variant-aware order editing, plus a chat panel in the admin sidebar with GFM markdown-table rendering.
 - **Docs** — this README plus the commerce skill folder [`skills/commerce/`](./skills/commerce/), which holds [`SKILL.md`](./skills/commerce/SKILL.md) (the short map agents start from), [`installation-guidelines.md`](./skills/commerce/installation-guidelines.md), [`post-installation.md`](./skills/commerce/post-installation.md), per-topic guides in [`references/`](./skills/commerce/references/) and the API references in [`docs/`](./skills/commerce/docs/) — the whole folder is installed into the app at `.agents/skills/commerce/` so agents pick it up natively.
 
@@ -29,8 +30,10 @@ base44-commerce-template/
 │       └── commerce/ commerce engine + static data (bundled into every function)
 ├── src/
 │   └── commerce/
-│       ├── admin/    React admin UI (copy into your app's src/commerce/)
-│       └── utils/    storefront helpers — variant selection, shipping promos
+│       ├── admin/      React admin UI (copy into your app's src/commerce/)
+│       ├── utils/      storefront helpers — API client, variant selection, shipping promos
+│       └── storefront/ storefront React layer — shared-cart provider, guided checkout,
+│                       headless pickers, order-received hook (logic only, no visuals)
 ├── scripts/
 │   └── install.js         static installer (run from <app>/examples/commerce/scripts/)
 ├── skills/
@@ -72,7 +75,7 @@ From your existing Base44 app:
    npx base44 functions deploy
    npx base44 agents push
    ```
-3. **Copy the UI files:** `src/commerce/admin/` → `src/commerce/admin/` and `src/commerce/utils/` → `src/commerce/utils/`.
+3. **Copy the UI files:** `src/commerce/admin/` → `src/commerce/admin/`, `src/commerce/utils/` → `src/commerce/utils/` and `src/commerce/storefront/` → `src/commerce/storefront/`.
 4. **Confirm UI deps** — `sonner`, `recharts` and `react-markdown` all ship with the default Base44 template and are the only ones the admin needs, so usually there is **nothing to install**. Read your app's `package.json` first and install *only* the names missing from it — never re-install a package that is already a dependency:
    ```bash
    grep -E '"(sonner|recharts|react-markdown)"' package.json   # all three listed → skip the install
@@ -94,12 +97,12 @@ 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 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).
+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) §3).
 
 ## What's NOT included
 
-- **No visitor/storefront UI.** The storefront **API** is complete (`commerce/storefront-*` functions); building the shopfront is up to you — see [`skills/commerce/docs/api-storefront.md`](./skills/commerce/docs/api-storefront.md). What *does* ship for the storefront is **helper logic**: [`src/commerce/utils/`](./src/commerce/utils/) — framework-free variant-selection functions (map a Size/Color selection to a `ProductVariation` and back, per-option availability, variant price ranges) — plus [`skills/commerce/references/product-render.md`](./skills/commerce/references/product-render.md) (what to render in a grid vs. a product page, and which fields each call returns) and [`skills/commerce/references/storefront-product-page.md`](./skills/commerce/references/storefront-product-page.md), the variant rules that go with the helpers.
-- **No payment provider** — the order side of card payments is premade (see above), but charging a card needs a provider: implement the four functions in `base44/shared/commerce/card-payment.ts` to wire one (Stripe: paste-in in `skills/commerce/post-installation.md` §2.2). Until then the card option answers "card payments are not available yet" at checkout (or switch it off in Settings → Payments), and the manual gateways (bank transfer, cash on delivery, anything the admin adds) carry checkout.
+- **No visitor/storefront UI.** The storefront **API** is complete (`commerce/storefront-*` functions); building the shopfront is up to you — see [`skills/commerce/docs/api-storefront.md`](./skills/commerce/docs/api-storefront.md). What *does* ship for the storefront is **logic, not looks**: [`src/commerce/utils/`](./src/commerce/utils/) (framework-free API client + variant-selection functions — map a Size/Color selection to a `ProductVariation` and back, per-option availability, variant price ranges) and [`src/commerce/storefront/`](./src/commerce/storefront/) (React hooks + headless pickers for the shared cart, the guided checkout with automatic shipping/tax recalculation, and the `/order-received` page — no visual components), plus [`skills/commerce/references/product-render.md`](./skills/commerce/references/product-render.md) (what to render in a grid vs. a product page, and which fields each call returns) and [`skills/commerce/references/storefront-product-page.md`](./skills/commerce/references/storefront-product-page.md), the variant rules that go with the helpers.
+- **No payment provider** — the order side of card payments is premade (see above), but charging a card needs a provider: implement the four functions in `base44/shared/commerce/card-payment.ts` to wire one (Stripe: paste-in in `skills/commerce/post-installation.md` §4). Until then the card option answers "card payments are not available yet" at checkout (or switch it off in Settings → Payments), and the manual gateways (bank transfer, cash on delivery, anything the admin adds) carry checkout.
 - **No scheduled workflows shipped.** Base44 *does* have a scheduler, but this template ships no workflow files — time-based jobs (stock-hold release, cart expiry, webhook-log pruning) run **opportunistically** where possible, and for the rest you (or the Base44 agent) create scheduled workflows that call `commerce/admin-tools`/`commerce/admin-orders` actions — see *Scheduled work* in [`skills/commerce/SKILL.md`](./skills/commerce/SKILL.md).
 
 ## Next steps

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

@@ -12,7 +12,10 @@
  * 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.
+ * best-effort rollback on mid-failure. Independent writes run in parallel at
+ * every stage (canaries, defaults, and the whole catalog pipeline), so the
+ * call is bounded by its longest dependency chain rather than its call count.
+ * See seed-catalog.ts for the pipeline and the concurrency caps.
  *
  * Body: { store_name?, currency?, weight_unit?, dimension_unit?,
  *         payment_methods?, with_sample_data?, products?, coupons?, locations? }
@@ -130,16 +133,16 @@ Deno.serve(async (req) => {
     if (weightUnit) generalPatch.weight_unit = weightUnit;
     if (dimensionUnit) generalPatch.dimension_unit = dimensionUnit;
 
-    for (const group of SETTINGS_DEFAULTS) {
-      if (existingGroups.has(group.group_id)) continue;
+    const missingGroups = SETTINGS_DEFAULTS.filter((group) => !existingGroups.has(group.group_id));
+    await Promise.all(missingGroups.map((group) => {
       const values = group.group_id === "emails"
         ? { ...group.values, store_name: storeName }
         : group.group_id === "general"
         ? { ...group.values, ...generalPatch }
         : group.values;
-      await sr.entities["commerce.StoreSettings"].create({ ...group, values });
-      seeded.settings_groups++;
-    }
+      return sr.entities["commerce.StoreSettings"].create({ ...group, values });
+    }));
+    seeded.settings_groups = missingGroups.length;
 
     // Explicit currency/units always win — unlike store_name there is no
     // "blank" to distinguish a merchant's choice from the seeded default, and a
@@ -185,14 +188,14 @@ Deno.serve(async (req) => {
       });
     }
 
-    for (const gw of GATEWAY_DEFAULTS) {
+    await Promise.all(GATEWAY_DEFAULTS.map(async (gw) => {
       const hits = (await sr.entities["commerce.PaymentGateway"].filter({ slug: gw.slug }, undefined, 1)) ?? [];
-      if (hits.length) continue;
+      if (hits.length) return;
       await sr.entities["commerce.PaymentGateway"].create(
         methodSlugs ? { ...gw, enabled: methodSlugs.includes(gw.slug) } : gw,
       );
       seeded.gateways++;
-    }
+    }));
 
     // Explicit payment_methods always win, like currency: converge EVERY
     // gateway row's enabled flag to the requested set, so "card-only" is one
@@ -201,13 +204,13 @@ Deno.serve(async (req) => {
     if (methodSlugs) {
       const rows = (await sr.entities["commerce.PaymentGateway"].list(undefined, 100)) ?? [];
       paymentMethods = { enabled: [], disabled: [] };
-      for (const row of rows) {
-        const want = methodSlugs.includes(String(row.slug));
+      await Promise.all(rows.map(async (row: any) => {
+        const want = methodSlugs!.includes(String(row.slug));
         if (Boolean(row.enabled) !== want) {
           await sr.entities["commerce.PaymentGateway"].update(row.id, { enabled: want });
         }
-        (want ? paymentMethods.enabled : paymentMethods.disabled).push(String(row.slug));
-      }
+        (want ? paymentMethods!.enabled : paymentMethods!.disabled).push(String(row.slug));
+      }));
     }
 
     // Caller-supplied `locations` ARE the store's shipping story — seeding the
@@ -276,20 +279,22 @@ function canarySpecs(needsCatalog: boolean): Array<{ entity: string; record: Rec
   return needsCatalog ? [...base, ...catalog] : base;
 }
 
+/** Probes are independent, so they all run concurrently — the canary stage
+ * costs one create+delete round-trip instead of one per entity. */
 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(needsCatalog)) {
+  const outcomes = await Promise.all(canarySpecs(needsCatalog).map(async (spec) => {
     let created: any = null;
     try {
       created = await sr.entities[spec.entity].create(spec.record);
+      return null;
     } catch (e) {
-      errors.push({ entity: spec.entity, error: String((e as Error)?.message ?? e) });
+      return { entity: spec.entity, error: String((e as Error)?.message ?? e) };
     } finally {
       if (created?.id) {
         try { await sr.entities[spec.entity].delete(created.id); } catch { /* orphaned canary is harmless */ }
       }
     }
-  }
-  return errors;
+  }));
+  return outcomes.filter(Boolean) as Array<{ entity: string; error: string }>;
 }
 

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

@@ -25,7 +25,6 @@ import {
   bumpCount,
   derivePricing,
   deriveStock,
-  ensureUniqueSlug,
   rollUpParent,
   slugify,
 } from "../../../shared/commerce/catalog.ts";
@@ -77,7 +76,7 @@ const MAX_PRODUCTS = 100;
 const MAX_COUPONS = 50;
 const MAX_LOCATIONS = 50;
 const MAX_VARIATIONS_PER_PRODUCT = 50; // also the cartesian-explosion guard
-const MAX_TOTAL_VARIATIONS = 500; // every variation is a sequential create
+const MAX_TOTAL_VARIATIONS = 500; // every variation is its own create call
 
 const PRODUCT_KEYS = new Set([
   // spec-only keys
@@ -504,6 +503,48 @@ export function sampleCatalog(): CatalogSpec {
   };
 }
 
+// ── parallelism ──────────────────────────────────────────────────────────────
+
+/**
+ * Concurrency-limited map that NEVER abandons in-flight work: when a task
+ * fails, the remaining workers stop picking up new items, every call already
+ * started settles, and only then does the first error throw. seedCatalog's
+ * rollback depends on this — it must see every record that was actually
+ * created before it starts deleting. Results keep input order.
+ */
+async function pMap<T, R>(items: T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]> {
+  const out = new Array<R>(items.length);
+  let next = 0;
+  let failed = false;
+  let firstError: unknown;
+  const workers = Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, async () => {
+    while (!failed) {
+      const i = next++;
+      if (i >= items.length) return;
+      try {
+        out[i] = await fn(items[i], i);
+      } catch (e) {
+        if (!failed) {
+          failed = true;
+          firstError = e;
+        }
+        return;
+      }
+    }
+  });
+  await Promise.all(workers); // workers never reject — they record the first error
+  if (failed) throw firstError;
+  return out;
+}
+
+// Each stage runs its independent API calls concurrently: seeding time is
+// dominated by call round-trips, and almost none of them depend on each other.
+// The caps keep a big catalog from opening hundreds of simultaneous requests:
+// at most PRODUCT_CONCURRENCY × VARIATION_CONCURRENCY calls are in flight.
+const SEED_CONCURRENCY = 8; // reads/creates within a flat stage
+const PRODUCT_CONCURRENCY = 4; // products in flight (each fans out its variations)
+const VARIATION_CONCURRENCY = 5; // variation creates in flight per product
+
 // ── seeding ──────────────────────────────────────────────────────────────────
 
 /**
@@ -512,9 +553,13 @@ export function sampleCatalog(): CatalogSpec {
  * skipped instead of duplicated, so a retrying caller converges. The sample
  * path passes false — it only ever runs against a store with zero products.
  *
- * On mid-write failure every record this call created is deleted (newest
- * first) and the error surfaces as `errorCode`; taxonomy that pre-existed is
- * never touched by the rollback.
+ * Writes are parallelized per stage (see the concurrency caps above); records
+ * that must not race — same-name slugs, shared ribbons — are claimed in-call
+ * before any await, so parallel product tasks can never double-create them.
+ *
+ * On mid-write failure every record this call created is deleted and the
+ * error surfaces as `errorCode`; taxonomy that pre-existed is never touched
+ * by the rollback.
  */
 export async function seedCatalog(
   sr: any,
@@ -538,9 +583,8 @@ export async function seedCatalog(
     const inventory = (await getSettings(sr, "inventory")).inventory ?? {};
     const outThreshold = Number(inventory.out_of_stock_threshold ?? 0);
 
-    // ── decide per product before writing anything ─────────────────────────
-    const plan: Array<{ p: NormalizedProduct; skip?: Record<string, any> }> = [];
-    for (const p of spec.products) {
+    // ── decide per product before writing anything (read-only, parallel) ───
+    const plan = await pMap(spec.products, SEED_CONCURRENCY, async (p) => {
       let skip: Record<string, any> | undefined;
       if (opts.skipExisting) {
         const sku = p.fields.sku;
@@ -556,16 +600,15 @@ export async function seedCatalog(
       }
       if (!skip) {
         // explicit variation skus fail as 409 duplicate_sku here, before any write
-        for (const v of p.variations) {
-          if (v.fields.sku) await assertUniqueSku(sr, String(v.fields.sku), {});
-        }
+        const withSku = p.variations.filter((v) => v.fields.sku);
+        await pMap(withSku, VARIATION_CONCURRENCY, (v) => assertUniqueSku(sr, String(v.fields.sku), {}));
       }
-      plan.push({ p, skip });
-    }
+      return { p, skip };
+    });
 
     // ── taxonomy (get-or-create; reused records are never rolled back) ─────
     const categoryBySlug: Record<string, any> = {};
-    for (const def of spec.categories) {
+    await pMap(spec.categories, SEED_CONCURRENCY, async (def) => {
       const hits = (await sr.entities["commerce.ProductCategory"].filter({ slug: def.slug }, undefined, 1)) ?? [];
       if (hits.length) {
         categoryBySlug[def.slug] = hits[0];
@@ -574,50 +617,68 @@ export async function seedCatalog(
         categoryBySlug[def.slug] = await track("commerce.ProductCategory", { description: "", display: "default", menu_order: 0, ...def, count: 0 });
         counts.categories.created++;
       }
-    }
+    });
 
-    let allRibbons: any[] | null = null;
+    // Ribbons are resolved up front — the products below write in parallel, so
+    // a lazy get-or-create would let two products race the same new ribbon
+    // into duplicates. One name, one record, resolved exactly once.
     const ribbonByLower: Record<string, any> = {};
-    const resolveRibbon = async (ribbonName: string) => {
-      const key = ribbonName.toLowerCase();
-      if (ribbonByLower[key]) return ribbonByLower[key];
-      allRibbons ??= await scanAll(sr.entities["commerce.ProductRibbon"], null, "name");
-      let ribbon = allRibbons!.find((t: any) => String(t.name ?? "").toLowerCase() === key);
-      if (ribbon) counts.ribbons.reused++;
-      else {
-        ribbon = await track("commerce.ProductRibbon", { name: ribbonName, count: 0 });
-        counts.ribbons.created++;
+    const ribbonNames = new Map<string, string>(); // lower → declared casing (first wins)
+    for (const { p, skip } of plan) {
+      if (skip) continue;
+      for (const name of p.ribbonNames) {
+        if (!ribbonNames.has(name.toLowerCase())) ribbonNames.set(name.toLowerCase(), name);
       }
-      ribbonByLower[key] = ribbon;
-      return ribbon;
-    };
+    }
+    if (ribbonNames.size) {
+      const allRibbons = await scanAll(sr.entities["commerce.ProductRibbon"], null, "name");
+      await pMap([...ribbonNames.values()], SEED_CONCURRENCY, async (name) => {
+        const key = name.toLowerCase();
+        const existing = allRibbons.find((t: any) => String(t.name ?? "").toLowerCase() === key);
+        if (existing) {
+          ribbonByLower[key] = existing;
+          counts.ribbons.reused++;
+        } else {
+          ribbonByLower[key] = await track("commerce.ProductRibbon", { name, count: 0 });
+          counts.ribbons.created++;
+        }
+      });
+    }
 
-    let allAttributes: any[] | null = null;
+    // Attributes and terms: `order` values are pre-assigned from one read, so
+    // the creates themselves can run concurrently without racing the counter.
     const attributeByCode: Record<string, any> = {};
     const termsByAttrId: Record<string, any[]> = {};
-    for (const def of spec.attributes) {
-      allAttributes ??= await scanAll(sr.entities["commerce.ProductAttribute"], null, "order");
-      let attr = allAttributes!.find((a: any) => a.code === def.code);
-      if (attr) counts.attributes.reused++;
-      else {
-        const maxOrder = allAttributes!.reduce((m: number, a: any) => Math.max(m, Number(a.order ?? 0)), -1);
-        attr = await track("commerce.ProductAttribute", { name: def.name, code: def.code, order: maxOrder + 1 });
-        allAttributes!.push(attr);
-        counts.attributes.created++;
-      }
-      attributeByCode[def.code] = attr;
-
-      const terms = (await sr.entities["commerce.ProductAttributeTerm"].filter({ attribute_id: attr.id }, undefined, 500)) ?? [];
-      let maxTermOrder = terms.reduce((m: number, t: any) => Math.max(m, Number(t.order ?? 0)), -1);
-      for (const term of spec.termsByCode[def.code] ?? []) {
-        if (terms.some((t: any) => String(t.name ?? "").toLowerCase() === term.name.toLowerCase())) {
-          counts.terms.reused++;
-          continue;
+    if (spec.attributes.length) {
+      const allAttributes = await scanAll(sr.entities["commerce.ProductAttribute"], null, "order");
+      let nextOrder = allAttributes.reduce((m: number, a: any) => Math.max(m, Number(a.order ?? 0)), -1) + 1;
+      const missingAttrs: Array<{ def: { name: string; code: string }; order: number }> = [];
+      for (const def of spec.attributes) {
+        const attr = allAttributes.find((a: any) => a.code === def.code);
+        if (attr) {
+          attributeByCode[def.code] = attr;
+          counts.attributes.reused++;
+        } else {
+          missingAttrs.push({ def, order: nextOrder++ });
         }
-        terms.push(await track("commerce.ProductAttributeTerm", { attribute_id: attr.id, name: term.name, order: ++maxTermOrder, count: 0 }));
-        counts.terms.created++;
       }
-      termsByAttrId[attr.id] = terms;
+      await pMap(missingAttrs, SEED_CONCURRENCY, async ({ def, order }) => {
+        attributeByCode[def.code] = await track("commerce.ProductAttribute", { name: def.name, code: def.code, order });
+        counts.attributes.created++;
+      });
+
+      await pMap(spec.attributes, SEED_CONCURRENCY, async (def) => {
+        const attr = attributeByCode[def.code];
+        const terms = (await sr.entities["commerce.ProductAttributeTerm"].filter({ attribute_id: attr.id }, undefined, 500)) ?? [];
+        const maxTermOrder = terms.reduce((m: number, t: any) => Math.max(m, Number(t.order ?? 0)), -1);
+        const wanted = spec.termsByCode[def.code] ?? [];
+        const missing = wanted.filter((term) => !terms.some((t: any) => String(t.name ?? "").toLowerCase() === term.name.toLowerCase()));
+        counts.terms.reused += wanted.length - missing.length;
+        const createdTerms = await pMap(missing, VARIATION_CONCURRENCY, (term, i) =>
+          track("commerce.ProductAttributeTerm", { attribute_id: attr.id, name: term.name, order: maxTermOrder + 1 + i, count: 0 }));
+        counts.terms.created += createdTerms.length;
+        termsByAttrId[attr.id] = [...terms, ...createdTerms];
+      });
     }
 
     // References are by name, so payload casing must never fork an existing
@@ -628,8 +689,23 @@ export async function seedCatalog(
       return term ? term.name : option;
     };
 
-    // ── products + variations ──────────────────────────────────────────────
-    const results: Array<Record<string, any>> = [];
+    // Slugs are claimed in-call before any await, so two same-named products
+    // seeding concurrently can never race `ensureUniqueSlug` to one slug.
+    const takenSlugs = new Set<string>();
+    const claimSlug = async (base: string): Promise<string> => {
+      for (let i = 1; i < 100; i++) {
+        const candidate = i === 1 ? base : `${base}-${i}`;
+        if (takenSlugs.has(candidate)) continue;
+        takenSlugs.add(candidate); // claim synchronously, then verify against the DB
+        const hits = (await sr.entities["commerce.Product"].filter({ slug: candidate }, undefined, 1)) ?? [];
+        if (!hits.length) return candidate;
+      }
+      const fallback = `${base}-${crypto.randomUUID().slice(0, 6)}`;
+      takenSlugs.add(fallback);
+      return fallback;
+    };
+
+    // ── products + variations (parallel; results keep payload order) ───────
     const countDeltas = new Map<string, number>(); // "entity|id" → +n
     const bumpLater = (entity: string, id: string) => {
       const key = `${entity}|${id}`;
@@ -637,21 +713,17 @@ export async function seedCatalog(
     };
     let variationsCreated = 0;
 
-    for (const { p, skip } of plan) {
-      if (skip) {
-        results.push(skip);
-        continue;
-      }
+    const results = await pMap(plan, PRODUCT_CONCURRENCY, async ({ p, skip }) => {
+      if (skip) return skip;
       const record: any = {
         status: "publish",
-        ribbon_ids: [],
+        ribbon_ids: p.ribbonNames.map((name) => ribbonByLower[name.toLowerCase()]?.id).filter(Boolean),
         meta_data: [],
         total_sales: 0,
         ...p.fields,
         category_ids: p.categorySlugs.map((slug) => categoryBySlug[slug]?.id).filter(Boolean),
       };
-      for (const ribbonName of p.ribbonNames) record.ribbon_ids = [...record.ribbon_ids, (await resolveRibbon(ribbonName)).id];
-      record.slug = await ensureUniqueSlug(sr, slugify(record.slug || record.name));
+      record.slug = await claimSlug(slugify(record.slug || record.name));
       if (record.manage_stock === undefined && record.stock_quantity != null) record.manage_stock = true;
 
       if (p.attributes.length) {
@@ -675,8 +747,7 @@ export async function seedCatalog(
       deriveStock(record, outThreshold, !!record.manage_stock);
       const product = await track("commerce.Product", record);
 
-      const seededVariations: any[] = [];
-      for (const v of p.variations) {
+      const seededVariations = await pMap(p.variations, VARIATION_CONCURRENCY, async (v) => {
         const rec: any = {
           status: "publish",
           ...v.fields,
@@ -701,46 +772,47 @@ export async function seedCatalog(
         rec.manage_stock = rec.stock_quantity != null ? "yes" : "parent";
         derivePricing(rec);
         deriveStock(rec, outThreshold, rec.manage_stock === "yes");
-        seededVariations.push(await track("commerce.ProductVariation", rec));
+        const createdVariation = await track("commerce.ProductVariation", rec);
         variationsCreated++;
-      }
+        return createdVariation;
+      });
       if (seededVariations.length) await rollUpParent(sr, product, seededVariations);
 
       for (const id of record.category_ids) bumpLater("commerce.ProductCategory", id);
       for (const id of record.ribbon_ids) bumpLater("commerce.ProductRibbon", id);
-      results.push({ name: product.name, id: product.id, slug: product.slug, sku: product.sku ?? "", variation_count: seededVariations.length });
-    }
+      return { name: product.name, id: product.id, slug: product.slug, sku: product.sku ?? "", variation_count: seededVariations.length };
+    });
 
     // deferred so a mid-creation rollback never leaves counts drifted;
     // a failure from here on is count-only and recount-terms repairs it
-    for (const [key, delta] of countDeltas) {
+    await pMap([...countDeltas], SEED_CONCURRENCY, ([key, delta]) => {
       const [entity, id] = key.split("|");
-      await bumpCount(sr, entity, id, delta);
-    }
+      return bumpCount(sr, entity, id, delta);
+    });
 
-    // ── coupons + tax rates (skip-if-exists) ───────────────────────────────
+    // ── coupons + locations (skip-if-exists; codes/names are payload-unique) ─
     const couponCounts = { created: 0, skipped: 0 };
-    for (const c of spec.coupons) {
+    await pMap(spec.coupons, SEED_CONCURRENCY, async (c) => {
       const code = String(c.code).trim().toLowerCase();
       const hits = (await sr.entities["commerce.Coupon"].filter({ code }, undefined, 1)) ?? [];
       if (hits.length) {
         couponCounts.skipped++;
-        continue;
+        return;
       }
       await track("commerce.Coupon", { discount_type: "fixed_cart", usage_count: 0, used_by: [], ...c, code });
       couponCounts.created++;
-    }
+    });
 
     const locationCounts = { created: 0, skipped: 0 };
-    for (const loc of spec.locations) {
+    await pMap(spec.locations, SEED_CONCURRENCY, async (loc) => {
       const hits = (await sr.entities["commerce.ShippingTaxLocation"].filter({ name: loc.name }, undefined, 1)) ?? [];
       if (hits.length) {
         locationCounts.skipped++;
-        continue;
+        return;
       }
       await track("commerce.ShippingTaxLocation", loc);
       locationCounts.created++;
-    }
+    });
 
     return {
       categories: counts.categories,
@@ -755,7 +827,8 @@ export async function seedCatalog(
       products: results,
     };
   } catch (e) {
-    // best-effort rollback, newest first
+    // Best-effort rollback, most-recently-created first. pMap drains every
+    // in-flight create before the error reaches here, so `created` is complete.
     for (const { entity, id } of created.reverse()) {
       try {
         await sr.entities[entity].delete(id);

package/base44/shared/commerce/card-payment.ts

@@ -9,7 +9,7 @@
  *   parseWebhook         → validate the provider's server-to-server event
  *
  * Any provider works; a ready-made reference implementation (Stripe) is in
- * `.agents/skills/commerce/post-installation.md` §2.2 to paste over this
+ * `.agents/skills/commerce/post-installation.md` §4 to paste over this
  * file — another provider implements the same functions against its own API.
  *
  * REPLACE THIS FILE WHOLE (one write of the full new content). Never

package/base44/shared/commerce/payments.ts

@@ -6,7 +6,7 @@
  * (create a payment page, check it was paid, refund it, validate a webhook
  * event). Any provider works;
  * a reference implementation (Stripe) is in
- * `.agents/skills/commerce/post-installation.md` §2.2, and the
+ * `.agents/skills/commerce/post-installation.md` §4, and the
  * provider-agnostic rules are in
  * `.agents/skills/commerce/references/online-payments.md`.
  *

package/package.json

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

package/scripts/install.js

@@ -18,6 +18,7 @@
  *   ../base44/agents/commerce/           →  ../../../base44/agents/commerce/
  *   ../src/commerce/admin/               →  ../../../src/commerce/admin/
  *   ../src/commerce/utils/               →  ../../../src/commerce/utils/
+ *   ../src/commerce/storefront/          →  ../../../src/commerce/storefront/
  *   ../skills/commerce/                  →  ../../../.agents/skills/commerce/
  *
  * Merge semantics: directories are merged — files owned by the template are
@@ -164,6 +165,10 @@
     // Storefront helpers (variant selection) — framework-free, for the
     // customer-facing UI the app builds itself.
     { label: "utils", from: ["src", "commerce", "utils"], to: ["src", "commerce", "utils"] },
+    // Storefront React layer — shared-cart provider, guided-checkout hook,
+    // headless shipping/payment pickers, order-received hook. Logic only, no
+    // visual components: the shopfront's look stays the app's to design.
+    { label: "storefront", from: ["src", "commerce", "storefront"], to: ["src", "commerce", "storefront"] },
     // Commerce skill — SKILL.md, install/post-install guides, references/
     // and docs/, the guidance agents read before working on the store.
     { label: "skills", from: ["skills", "commerce"], to: [".agents", "skills", "commerce"] },
@@ -186,10 +191,11 @@
     "     Base44 template — check package.json and npm i only what is truly missing;\n" +
     "     do not re-install packages already listed as dependencies\n" +
     '  2. Mount the admin router: <Route path="/store-admin/*" element={<AdminApp />} />\n' +
-    "     and implement the payment return page /order-received (post-installation.md)\n" +
+    "     and implement the payment return page /order-received — one hook,\n" +
+    "     useOrderReturn from @/commerce/storefront (post-installation.md)\n" +
     "  3. Grant your user the admin role, then seed the store's data — one commerce/seed-store\n" +
     "     call (store_name required) takes the whole catalog via products, or the demo data\n" +
-    "     via with_sample_data, or defaults only (post-installation.md §2)\n" +
+    "     via with_sample_data, or defaults only (post-installation.md §3)\n" +
     "  4. CLI installs only: npx base44 agents push (the hosted runtime syncs agents on write)"
   );
 })();