@base44/app-plugin-commerce 0.1.4 → 0.1.6

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

@@ -0,0 +1,717 @@
+/**
+ * commerce/seed-store — catalog seeding pipeline.
+ *
+ * One pipeline serves two callers: the template's demo catalog
+ * (`sampleCatalog()`, over sample-data.ts) and a caller-supplied
+ * `products`/`coupons`/`tax_rates` payload (`normalizeCatalogPayload()`).
+ * Both normalize to the same CatalogSpec, and `seedCatalog()` writes it:
+ * get-or-create taxonomy (never duplicated, never rolled back when it
+ * pre-existed), create products and their variations, roll each variant
+ * parent's price up, then apply term counts in one deferred pass.
+ *
+ * The caller payload is agent-ergonomic — everything is referenced by display
+ * name, and variations are generated from `attributes` when not given:
+ *
+ *   { name, regular_price, sku?, stock_quantity?, images?, categories?, tags?,
+ *     attributes?: [{ name: "Size", options: ["S","M"] }] | { Size: ["S","M"] },
+ *     default_options?: { Size: "M" },
+ *     variations?: [{ options: { Size: "S" }, regular_price?, stock_quantity?, sku?, image? }] }
+ */
+import { HttpError } from "../../../shared/commerce/auth.ts";
+import { getSettings } from "../../../shared/commerce/settings.ts";
+import { scanAll } from "../../../shared/commerce/scan.ts";
+import {
+  assertUniqueSku,
+  bumpCount,
+  derivePricing,
+  deriveStock,
+  ensureUniqueSlug,
+  rollUpParent,
+  slugify,
+} from "../../../shared/commerce/catalog.ts";
+import {
+  SAMPLE_ATTRIBUTE_TERMS,
+  SAMPLE_ATTRIBUTES,
+  SAMPLE_CATEGORIES,
+  SAMPLE_COUPONS,
+  SAMPLE_PRODUCTS,
+  SAMPLE_TAX_RATES,
+} from "./sample-data.ts";
+
+// ── shapes ───────────────────────────────────────────────────────────────────
+
+interface NormalizedVariation {
+  options: Record<string, string>; // attribute code → option (declared casing)
+  fields: Record<string, any>;
+}
+
+interface NormalizedProduct {
+  fields: Record<string, any>; // entity passthrough, images normalized
+  categorySlugs: string[];
+  tagNames: string[];
+  attributes: Array<{ code: string; options: string[] }>;
+  defaultOptions: Record<string, string>;
+  variations: NormalizedVariation[];
+}
+
+export interface CatalogSpec {
+  categories: Array<Record<string, any>>; // full definition records, keyed by slug
+  attributes: Array<{ name: string; code: string; order: number }>;
+  termsByCode: Record<string, Array<{ name: string; order: number }>>;
+  products: NormalizedProduct[];
+  coupons: any[];
+  tax_rates: any[];
+}
+
+/** 400-payload failure carrying every problem at once. Caught in entry.ts. */
+export class CatalogPayloadError extends Error {
+  errors: Array<{ path: string; error: string }>;
+  constructor(errors: Array<{ path: string; error: string }>) {
+    super("Invalid catalog payload — nothing was written.");
+    this.errors = errors;
+  }
+}
+
+// ── limits & allow-lists ─────────────────────────────────────────────────────
+
+const MAX_PRODUCTS = 100;
+const MAX_COUPONS = 50;
+const MAX_TAX_RATES = 50;
+const MAX_VARIATIONS_PER_PRODUCT = 50; // also the cartesian-explosion guard
+const MAX_TOTAL_VARIATIONS = 500; // every variation is a sequential create
+
+const PRODUCT_KEYS = new Set([
+  // spec-only keys
+  "categories", "tags", "attributes", "default_options", "variations",
+  // entity fields
+  "name", "slug", "sku", "status", "regular_price", "sale_price",
+  "date_on_sale_from", "date_on_sale_to", "manage_stock", "stock_quantity",
+  "backorders", "description", "short_description", "images", "featured",
+  "catalog_visibility", "virtual", "downloadable", "downloads",
+  "download_limit", "download_expiry", "tax_status", "tax_class", "weight",
+  "dimensions", "sold_individually", "low_stock_amount", "shipping_class_id",
+  "upsell_ids", "cross_sell_ids", "meta_data",
+]);
+
+const VARIATION_KEYS = new Set([
+  "options", "sku", "status", "regular_price", "sale_price",
+  "date_on_sale_from", "date_on_sale_to", "stock_quantity", "backorders",
+  "image", "description", "weight", "dimensions", "virtual", "downloadable",
+  "downloads", "download_limit", "download_expiry",
+]);
+
+const ENUMS: Record<string, string[]> = {
+  status: ["draft", "pending", "private", "publish"],
+  backorders: ["no", "notify", "yes"],
+  catalog_visibility: ["visible", "catalog", "search", "hidden"],
+  tax_status: ["taxable", "shipping", "none"],
+  discount_type: ["percent", "fixed_cart", "fixed_product"],
+};
+
+const PRICE_KEYS = ["regular_price", "sale_price", "stock_quantity", "low_stock_amount", "weight"];
+
+// ── normalization (pure — no I/O, throws CatalogPayloadError) ────────────────
+
+/**
+ * Normalize the caller's catalog keys into a CatalogSpec, or return null when
+ * the body carries none. Validates everything in one pass so the caller gets
+ * every problem at once, before anything (canaries included) runs.
+ */
+export function normalizeCatalogPayload(body: any): CatalogSpec | null {
+  const hasCatalog = ["products", "coupons", "tax_rates"].some((k) => body[k] != null);
+  if (!hasCatalog) return null;
+
+  const errors: Array<{ path: string; error: string }> = [];
+  const err = (path: string, error: string) => errors.push({ path, error });
+
+  if (body.with_sample_data) {
+    err("with_sample_data", "cannot be combined with products/coupons/tax_rates — seed either the demo catalog or your own, not both");
+  }
+
+  const list = (key: string, cap: number): any[] => {
+    const value = body[key];
+    if (value == null) return [];
+    if (!Array.isArray(value)) {
+      err(key, "must be an array");
+      return [];
+    }
+    if (value.length > cap) err(key, `at most ${cap} entries per call (got ${value.length})`);
+    return value.slice(0, cap);
+  };
+
+  const products = list("products", MAX_PRODUCTS);
+  const coupons = list("coupons", MAX_COUPONS);
+  const taxRates = list("tax_rates", MAX_TAX_RATES);
+
+  // shared definition collectors (deduped across products)
+  const categoryBySlug = new Map<string, Record<string, any>>();
+  const attributeByCode = new Map<string, { name: string; code: string; order: number }>();
+  const termsByCode: Record<string, Array<{ name: string; order: number }>> = {};
+  const seenSkus = new Map<string, string>(); // sku → path that used it
+  const seenSlugs = new Map<string, string>(); // derived slug (no-sku products) → path
+  let totalVariations = 0;
+
+  const normalized: NormalizedProduct[] = [];
+  products.forEach((spec, i) => {
+    const p = normalizeProduct(spec, `products[${i}]`, err, {
+      categoryBySlug, attributeByCode, termsByCode, seenSkus, seenSlugs,
+    });
+    if (p) {
+      totalVariations += p.variations.length;
+      normalized.push(p);
+    }
+  });
+  if (totalVariations > MAX_TOTAL_VARIATIONS) {
+    err("products", `at most ${MAX_TOTAL_VARIATIONS} variations across the call (got ${totalVariations}) — split into multiple calls`);
+  }
+
+  coupons.forEach((c, i) => {
+    const path = `coupons[${i}]`;
+    if (!c || typeof c !== "object") return err(path, "must be an object");
+    if (!String(c.code ?? "").trim()) err(`${path}.code`, "is required");
+    if (c.discount_type != null && !ENUMS.discount_type.includes(c.discount_type)) {
+      err(`${path}.discount_type`, `must be one of: ${ENUMS.discount_type.join(", ")}`);
+    }
+    if (!Number.isFinite(Number(c.amount)) || Number(c.amount) < 0) err(`${path}.amount`, "must be a non-negative number");
+  });
+
+  taxRates.forEach((r, i) => {
+    const path = `tax_rates[${i}]`;
+    if (!r || typeof r !== "object") return err(path, "must be an object");
+    if (!String(r.country ?? "").trim()) err(`${path}.country`, "is required");
+    if (!String(r.name ?? "").trim()) err(`${path}.name`, "is required");
+    if (!Number.isFinite(Number(r.rate)) || Number(r.rate) < 0) err(`${path}.rate`, "must be a non-negative number");
+  });
+
+  if (errors.length) throw new CatalogPayloadError(errors);
+
+  return {
+    categories: [...categoryBySlug.values()],
+    attributes: [...attributeByCode.values()],
+    termsByCode,
+    products: normalized,
+    coupons,
+    tax_rates: taxRates,
+  };
+}
+
+function normalizeProduct(
+  spec: any,
+  path: string,
+  err: (path: string, error: string) => void,
+  shared: {
+    categoryBySlug: Map<string, Record<string, any>>;
+    attributeByCode: Map<string, { name: string; code: string; order: number }>;
+    termsByCode: Record<string, Array<{ name: string; order: number }>>;
+    seenSkus: Map<string, string>;
+    seenSlugs: Map<string, string>;
+  },
+): NormalizedProduct | null {
+  if (!spec || typeof spec !== "object" || Array.isArray(spec)) {
+    err(path, "must be an object");
+    return null;
+  }
+  const name = String(spec.name ?? "").trim();
+  if (!name) err(`${path}.name`, "is required");
+
+  for (const key of Object.keys(spec)) {
+    if (!PRODUCT_KEYS.has(key)) err(`${path}.${key}`, "unknown key — not a product field the seeder accepts");
+  }
+  checkEnumsAndNumbers(spec, path, err);
+
+  // taxonomy references (display names)
+  const categorySlugs = strList(spec.categories, `${path}.categories`, err).map((catName) => {
+    const slug = slugify(catName);
+    if (!shared.categoryBySlug.has(slug)) {
+      shared.categoryBySlug.set(slug, { name: catName, slug, menu_order: shared.categoryBySlug.size });
+    }
+    return slug;
+  });
+  const tagNames = strList(spec.tags, `${path}.tags`, err);
+
+  // attribute axes: array form is canonical, map form accepted (insertion order)
+  const axes: Array<{ name: string; code: string; options: string[] }> = [];
+  if (spec.attributes != null) {
+    let entries: Array<[string, any]> = [];
+    if (Array.isArray(spec.attributes)) {
+      entries = spec.attributes.map((a: any): [string, any] => [String(a?.name ?? ""), a?.options]);
+    } else if (typeof spec.attributes === "object") {
+      entries = Object.entries(spec.attributes);
+    } else {
+      err(`${path}.attributes`, "must be [{ name, options }] or { <name>: [options] }");
+    }
+    entries.forEach(([attrName, options], i) => {
+      const aPath = `${path}.attributes[${i}]`;
+      const trimmed = String(attrName ?? "").trim();
+      if (!trimmed) return err(`${aPath}.name`, "attribute name is required");
+      const opts = strList(options, `${aPath}.options`, err);
+      if (!opts.length) return err(`${aPath}.options`, "at least one option is required");
+      const code = slugify(trimmed);
+      if (axes.some((a) => a.code === code)) return err(aPath, `duplicate attribute "${trimmed}" on this product`);
+      axes.push({ name: trimmed, code, options: opts });
+      if (!shared.attributeByCode.has(code)) {
+        shared.attributeByCode.set(code, { name: trimmed, code, order: shared.attributeByCode.size });
+      }
+      const terms = (shared.termsByCode[code] ??= []);
+      for (const o of opts) {
+        if (!terms.some((t) => t.name.toLowerCase() === o.toLowerCase())) terms.push({ name: o, order: terms.length });
+      }
+    });
+  }
+
+  // resolve an options map ({ Size: "S" } — keys by attribute name or code) to code → option
+  const resolveOptions = (input: any, oPath: string): Record<string, string> | null => {
+    if (!input || typeof input !== "object" || Array.isArray(input)) {
+      err(oPath, "must be an object of { <attribute>: <option> }");
+      return null;
+    }
+    const out: Record<string, string> = {};
+    for (const [key, raw] of Object.entries(input)) {
+      const axis = axes.find((a) => a.code === slugify(key) || a.name.toLowerCase() === String(key).toLowerCase());
+      if (!axis) {
+        err(`${oPath}.${key}`, `"${key}" is not one of this product's attributes`);
+        continue;
+      }
+      const value = String(raw ?? "").trim();
+      const match = axis.options.find((o) => o.toLowerCase() === value.toLowerCase());
+      if (!match) {
+        err(`${oPath}.${key}`, `"${value}" is not one of the declared ${axis.name} options (${axis.options.join(", ")})`);
+        continue;
+      }
+      out[axis.code] = match;
+    }
+    return out;
+  };
+
+  const defaultOptions = spec.default_options != null
+    ? resolveOptions(spec.default_options, `${path}.default_options`) ?? {}
+    : {};
+
+  // variations: explicit list is authoritative; otherwise the full cartesian product
+  const inheritable: Record<string, any> = {};
+  for (const key of ["regular_price", "sale_price", "date_on_sale_from", "date_on_sale_to", "backorders"]) {
+    if (spec[key] !== undefined) inheritable[key] = spec[key];
+  }
+  let variations: NormalizedVariation[] = [];
+  if (spec.variations != null) {
+    if (!axes.length) err(`${path}.variations`, "variations need attributes — declare the product's attributes too");
+    if (!Array.isArray(spec.variations)) {
+      err(`${path}.variations`, "must be an array");
+    } else {
+      if (spec.variations.length > MAX_VARIATIONS_PER_PRODUCT) {
+        err(`${path}.variations`, `at most ${MAX_VARIATIONS_PER_PRODUCT} variations per product (got ${spec.variations.length})`);
+      }
+      const seenCombos = new Set<string>();
+      spec.variations.slice(0, MAX_VARIATIONS_PER_PRODUCT).forEach((v: any, i: number) => {
+        const vPath = `${path}.variations[${i}]`;
+        if (!v || typeof v !== "object") return err(vPath, "must be an object");
+        for (const key of Object.keys(v)) {
+          if (!VARIATION_KEYS.has(key)) err(`${vPath}.${key}`, "unknown key — not a variation field the seeder accepts");
+        }
+        checkEnumsAndNumbers(v, vPath, err);
+        const options = resolveOptions(v.options ?? {}, `${vPath}.options`);
+        if (!options) return;
+        const missing = axes.filter((a) => !(a.code in options));
+        if (missing.length) return err(`${vPath}.options`, `missing ${missing.map((a) => a.name).join(", ")} — every attribute needs a value`);
+        const combo = axes.map((a) => `${a.code}:${options[a.code].toLowerCase()}`).join("|");
+        if (seenCombos.has(combo)) return err(vPath, "duplicate combination — another variation already covers these options");
+        seenCombos.add(combo);
+        const { options: _o, ...fields } = v;
+        variations.push({ options, fields: { ...inheritable, ...compact(fields) } });
+      });
+    }
+  } else if (axes.length) {
+    const combos = axes.reduce((n, a) => n * a.options.length, 1);
+    if (combos > MAX_VARIATIONS_PER_PRODUCT) {
+      err(`${path}.attributes`, `${combos} auto-generated combinations exceed ${MAX_VARIATIONS_PER_PRODUCT} — pass an explicit variations array with the combinations you stock`);
+    } else {
+      variations = axes
+        .reduce<Array<Record<string, string>>>(
+          (acc, a) => acc.flatMap((combo) => a.options.map((o) => ({ ...combo, [a.code]: o }))),
+          [{}],
+        )
+        .map((options) => ({ options, fields: { ...inheritable } }));
+    }
+  }
+
+  // intra-payload duplicates
+  const sku = spec.sku != null ? String(spec.sku).trim() : "";
+  const trackSku = (value: string, sPath: string) => {
+    if (!value) return;
+    const prev = shared.seenSkus.get(value);
+    if (prev) err(sPath, `sku "${value}" already used at ${prev}`);
+    else shared.seenSkus.set(value, sPath);
+  };
+  trackSku(sku, `${path}.sku`);
+  variations.forEach((v, i) => trackSku(String(v.fields.sku ?? "").trim(), `${path}.variations[${i}].sku`));
+  if (!sku && name) {
+    const slug = slugify(String(spec.slug ?? "") || name);
+    const prev = shared.seenSlugs.get(slug);
+    if (prev) err(`${path}.name`, `"${name}" duplicates ${prev} — give the products distinct names or skus`);
+    else shared.seenSlugs.set(slug, path);
+  }
+
+  // entity passthrough fields
+  const fields: Record<string, any> = {};
+  for (const [key, value] of Object.entries(spec)) {
+    if (["categories", "tags", "attributes", "default_options", "variations"].includes(key)) continue;
+    if (PRODUCT_KEYS.has(key) && value !== undefined) fields[key] = value;
+  }
+  if (fields.sku !== undefined) fields.sku = sku;
+  fields.images = normalizeImages(spec.images, name, `${path}.images`, err);
+
+  return {
+    fields,
+    categorySlugs,
+    tagNames,
+    attributes: axes.map((a) => ({ code: a.code, options: a.options })),
+    defaultOptions,
+    variations,
+  };
+}
+
+function checkEnumsAndNumbers(spec: any, path: string, err: (p: string, e: string) => void): void {
+  for (const [key, allowed] of Object.entries(ENUMS)) {
+    if (key === "discount_type") continue; // coupon-only
+    if (spec[key] != null && !allowed.includes(spec[key])) {
+      err(`${path}.${key}`, `must be one of: ${allowed.join(", ")}`);
+    }
+  }
+  for (const key of PRICE_KEYS) {
+    if (spec[key] != null && (!Number.isFinite(Number(spec[key])) || Number(spec[key]) < 0)) {
+      err(`${path}.${key}`, "must be a non-negative number");
+    }
+  }
+}
+
+/** Coerce a names list ("Shoes" entries, tag names, attribute options) to trimmed strings. */
+function strList(value: any, path: string, err: (p: string, e: string) => void): string[] {
+  if (value == null) return [];
+  if (!Array.isArray(value)) {
+    err(path, "must be an array");
+    return [];
+  }
+  const out: string[] = [];
+  value.forEach((entry, i) => {
+    const s = String(entry ?? "").trim();
+    if (!s) err(`${path}[${i}]`, "must be a non-empty string");
+    else if (!out.some((x) => x.toLowerCase() === s.toLowerCase())) out.push(s);
+  });
+  return out;
+}
+
+/** `images` accepts plain URLs or { src, name?, alt? }; normalized to the entity shape. */
+function normalizeImages(value: any, productName: string, path: string, err: (p: string, e: string) => void): any[] {
+  if (value == null) return [];
+  if (!Array.isArray(value)) {
+    err(path, "must be an array of URLs or { src, alt? } objects");
+    return [];
+  }
+  return value.map((entry, position) => {
+    const img = typeof entry === "string" ? { src: entry } : entry;
+    const src = String(img?.src ?? "").trim();
+    if (!src) {
+      err(`${path}[${position}]`, "src is required");
+      return null;
+    }
+    return {
+      src,
+      name: img.name ?? productName,
+      alt: img.alt ?? (position === 0 ? productName : `${productName} — view ${position + 1}`),
+      position,
+    };
+  }).filter(Boolean);
+}
+
+/** Drop undefined values so entity creates never carry them. */
+function compact(record: Record<string, any>): Record<string, any> {
+  return Object.fromEntries(Object.entries(record).filter(([, v]) => v !== undefined));
+}
+
+// ── the demo catalog, as a CatalogSpec ───────────────────────────────────────
+
+export function sampleCatalog(): CatalogSpec {
+  return {
+    categories: SAMPLE_CATEGORIES,
+    attributes: SAMPLE_ATTRIBUTES,
+    termsByCode: SAMPLE_ATTRIBUTE_TERMS,
+    products: SAMPLE_PRODUCTS.map((spec) => {
+      const { key: _key, categories, attributes, default_attributes, variations, ...fields } = spec;
+      return {
+        fields: { ...fields, images: fields.images ?? [] },
+        categorySlugs: categories ?? [],
+        tagNames: [],
+        attributes: (attributes ?? []).map((a: any) => ({ code: a.code, options: a.options ?? [] })),
+        defaultOptions: Object.fromEntries((default_attributes ?? []).map((d: any) => [d.code, d.option])),
+        variations: (variations ?? []).map((v: any) => {
+          const { options, ...vFields } = v;
+          return { options: { ...options }, fields: compact(vFields) };
+        }),
+      };
+    }),
+    coupons: SAMPLE_COUPONS,
+    tax_rates: SAMPLE_TAX_RATES,
+  };
+}
+
+// ── seeding ──────────────────────────────────────────────────────────────────
+
+/**
+ * Write a CatalogSpec. `skipExisting` is the custom-payload mode: a product
+ * whose sku (or, without one, derived slug) already exists is reported as
+ * 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.
+ */
+export async function seedCatalog(
+  sr: any,
+  spec: CatalogSpec,
+  opts: { skipExisting: boolean; errorCode: string },
+): Promise<Record<string, any>> {
+  const created: Array<{ entity: string; id: string }> = [];
+  const track = async (entity: string, record: Record<string, any>) => {
+    const rec = await sr.entities[entity].create(compact(record));
+    created.push({ entity, id: rec.id });
+    return rec;
+  };
+  const counts = {
+    categories: { created: 0, reused: 0 },
+    tags: { created: 0, reused: 0 },
+    attributes: { created: 0, reused: 0 },
+    terms: { created: 0, reused: 0 },
+  };
+
+  try {
+    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) {
+      let skip: Record<string, any> | undefined;
+      if (opts.skipExisting) {
+        const sku = p.fields.sku;
+        if (sku) {
+          const prods = (await sr.entities["commerce.Product"].filter({ sku }, undefined, 1)) ?? [];
+          const hit = prods[0] ?? ((await sr.entities["commerce.ProductVariation"].filter({ sku }, undefined, 1)) ?? [])[0];
+          if (hit) skip = { name: p.fields.name, skipped: true, reason: "sku_exists", existing_id: hit.id };
+        } else {
+          const slug = slugify(p.fields.slug || p.fields.name);
+          const hits = (await sr.entities["commerce.Product"].filter({ slug }, undefined, 1)) ?? [];
+          if (hits.length) skip = { name: p.fields.name, skipped: true, reason: "slug_exists", existing_id: hits[0].id };
+        }
+      }
+      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), {});
+        }
+      }
+      plan.push({ p, skip });
+    }
+
+    // ── taxonomy (get-or-create; reused records are never rolled back) ─────
+    const categoryBySlug: Record<string, any> = {};
+    for (const def of spec.categories) {
+      const hits = (await sr.entities["commerce.ProductCategory"].filter({ slug: def.slug }, undefined, 1)) ?? [];
+      if (hits.length) {
+        categoryBySlug[def.slug] = hits[0];
+        counts.categories.reused++;
+      } else {
+        categoryBySlug[def.slug] = await track("commerce.ProductCategory", { description: "", display: "default", menu_order: 0, ...def, count: 0 });
+        counts.categories.created++;
+      }
+    }
+
+    let allTags: any[] | null = null;
+    const tagByLower: Record<string, any> = {};
+    const resolveTag = async (tagName: string) => {
+      const key = tagName.toLowerCase();
+      if (tagByLower[key]) return tagByLower[key];
+      allTags ??= await scanAll(sr.entities["commerce.ProductTag"], null, "name");
+      let tag = allTags!.find((t: any) => String(t.name ?? "").toLowerCase() === key);
+      if (tag) counts.tags.reused++;
+      else {
+        tag = await track("commerce.ProductTag", { name: tagName, count: 0 });
+        counts.tags.created++;
+      }
+      tagByLower[key] = tag;
+      return tag;
+    };
+
+    let allAttributes: any[] | null = null;
+    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;
+        }
+        terms.push(await track("commerce.ProductAttributeTerm", { attribute_id: attr.id, name: term.name, order: ++maxTermOrder, count: 0 }));
+        counts.terms.created++;
+      }
+      termsByAttrId[attr.id] = terms;
+    }
+
+    // References are by name, so payload casing must never fork an existing
+    // term — the stored casing wins everywhere a name is written.
+    const canonicalOption = (code: string, option: string): string => {
+      const attr = attributeByCode[code];
+      const term = (termsByAttrId[attr?.id] ?? []).find((t: any) => String(t.name ?? "").toLowerCase() === option.toLowerCase());
+      return term ? term.name : option;
+    };
+
+    // ── products + variations ──────────────────────────────────────────────
+    const results: Array<Record<string, any>> = [];
+    const countDeltas = new Map<string, number>(); // "entityid" → +n
+    const bumpLater = (entity: string, id: string) => {
+      const key = `${entity}${id}`;
+      countDeltas.set(key, (countDeltas.get(key) ?? 0) + 1);
+    };
+    let variationsCreated = 0;
+
+    for (const { p, skip } of plan) {
+      if (skip) {
+        results.push(skip);
+        continue;
+      }
+      const record: any = {
+        status: "publish",
+        tag_ids: [],
+        meta_data: [],
+        total_sales: 0,
+        ...p.fields,
+        category_ids: p.categorySlugs.map((slug) => categoryBySlug[slug]?.id).filter(Boolean),
+      };
+      for (const tagName of p.tagNames) record.tag_ids = [...record.tag_ids, (await resolveTag(tagName)).id];
+      record.slug = await ensureUniqueSlug(sr, slugify(record.slug || record.name));
+      if (record.manage_stock === undefined && record.stock_quantity != null) record.manage_stock = true;
+
+      if (p.attributes.length) {
+        record.attributes = p.attributes.map((a, position) => ({
+          attribute_id: attributeByCode[a.code].id,
+          name: attributeByCode[a.code].name,
+          position,
+          options: a.options.map((o) => canonicalOption(a.code, o)),
+        }));
+        const defaults = Object.entries(p.defaultOptions);
+        if (defaults.length) {
+          record.default_attributes = defaults.map(([code, option]) => ({
+            attribute_id: attributeByCode[code].id,
+            name: attributeByCode[code].name,
+            option: canonicalOption(code, option),
+          }));
+        }
+      }
+
+      derivePricing(record);
+      deriveStock(record, outThreshold, !!record.manage_stock);
+      const product = await track("commerce.Product", record);
+
+      const seededVariations: any[] = [];
+      for (const v of p.variations) {
+        const rec: any = {
+          status: "publish",
+          ...v.fields,
+          product_id: product.id,
+          attributes: Object.entries(v.options).map(([code, option]) => ({
+            attribute_id: attributeByCode[code].id,
+            name: attributeByCode[code].name,
+            option: canonicalOption(code, option),
+          })),
+        };
+        if (typeof rec.image === "string") rec.image = { src: rec.image, name: record.name, alt: record.name };
+        if (!rec.sku && record.sku) {
+          // synthesized skus self-heal on collision instead of failing the seed
+          rec.sku = `${record.sku}-${Object.values(v.options).map((o) => String(o).replace(/[^a-z0-9]+/gi, "")).join("-").toUpperCase()}`;
+          try {
+            await assertUniqueSku(sr, rec.sku, {});
+          } catch {
+            rec.sku = `${rec.sku}-${crypto.randomUUID().slice(0, 4).toUpperCase()}`;
+          }
+        }
+        // explicit stock is per-variation; none means the pool on the parent
+        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));
+        variationsCreated++;
+      }
+      if (seededVariations.length) await rollUpParent(sr, product, seededVariations);
+
+      for (const id of record.category_ids) bumpLater("commerce.ProductCategory", id);
+      for (const id of record.tag_ids) bumpLater("commerce.ProductTag", id);
+      results.push({ 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) {
+      const [entity, id] = key.split("");
+      await bumpCount(sr, entity, id, delta);
+    }
+
+    // ── coupons + tax rates (skip-if-exists) ───────────────────────────────
+    const couponCounts = { created: 0, skipped: 0 };
+    for (const c of spec.coupons) {
+      const code = String(c.code).trim().toLowerCase();
+      const hits = (await sr.entities["commerce.Coupon"].filter({ code }, undefined, 1)) ?? [];
+      if (hits.length) {
+        couponCounts.skipped++;
+        continue;
+      }
+      await track("commerce.Coupon", { discount_type: "fixed_cart", usage_count: 0, used_by: [], ...c, code });
+      couponCounts.created++;
+    }
+
+    const taxCounts = { created: 0, skipped: 0 };
+    for (const r of spec.tax_rates) {
+      const hits = (await sr.entities["commerce.TaxRate"].filter({ country: r.country, name: r.name }, undefined, 5)) ?? [];
+      if (hits.some((h: any) => String(h.state ?? "") === String(r.state ?? ""))) {
+        taxCounts.skipped++;
+        continue;
+      }
+      await track("commerce.TaxRate", { state: "", postcodes: [], cities: [], priority: 1, compound: false, shipping: true, tax_class: "standard", menu_order: 0, ...r });
+      taxCounts.created++;
+    }
+
+    return {
+      categories: counts.categories,
+      tags: counts.tags,
+      attributes: counts.attributes,
+      terms: counts.terms,
+      products_created: results.filter((r) => !r.skipped).length,
+      products_skipped: results.filter((r) => r.skipped).length,
+      variations_created: variationsCreated,
+      coupons: couponCounts,
+      tax_rates: taxCounts,
+      products: results,
+    };
+  } 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 */ }
+    }
+    if (e instanceof HttpError) throw e;
+    throw new HttpError(500, `Catalog seeding failed and was rolled back: ${(e as Error).message}`, opts.errorCode);
+  }
+}