Wix Vibe Headless

references/storefront/seed/seed-store.cjs

// Storefront seed helpers — run at BUILD TIME via exec_tool (NOT shipped in the app).
// The agent requires this and calls the functions with plain data; all Wix Stores
// request/response mechanics (bulk shapes, variant expansion, rich-text descriptions,
// the 409-serial category rule, the re-hosted-image quirk) live here, once.
//
// Usage (build-time exec_tool):
//   const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix");  // Base44
//   const seed = require("/app/.agents/skills/wix-vibe-headless/references/storefront/seed/seed-store.cjs");
//   const ctx = { token: accessToken }; // Installation reads the site ID from the deployed Wix config.
//   await seed.installStoresApp(ctx);
//   const products = await seed.bulkCreateProducts(ctx, [{ name, description, price, quantity, options? }]);
//   const cats = await seed.createCategories(ctx, ["Legends", "Rising Stars"]);
//   await seed.addProductsToCategories(ctx, { [cats[0].id]: products.map(p => p.id) });
//   await seed.attachProductImages(ctx, products.map((p,i) => ({ id:p.id, url:imageUrls[i], altText:p.slug })));
//
// If any call fails with a shape the caller didn't expect, fall back to the documentation skill available in your environment
// (search + read the live Wix API reference) — never guess. Source recipe (authoritative):
// wix-headless/references/inline-recipes/setup-online-store.md.

const API = "https://www.wixapis.com";
const STORES_APP_ID = "215238eb-22a5-4c36-9e7b-e7c08025e04e";
const WIX_CONFIG_PATH = "/app/src/rest/wix-config.js";
let siteId;

function getSiteId() {
  if (siteId) return siteId;
  let source;
  try {
    source = require("fs").readFileSync(WIX_CONFIG_PATH, "utf8");
  } catch {
    throw new Error(`Cannot read ${WIX_CONFIG_PATH}; deploy the Wix config before seeding.`);
  }
  // Base44/deploy writes a named export containing a JSON string literal. Do not execute config.
  const match = source.match(/^export const WIX_METASITE_ID\s*=\s*("(?:[^"\\]|\\.)*")\s*;/m);
  let value;
  try { value = match && JSON.parse(match[1]); } catch { /* invalid config */ }
  if (typeof value !== "string" || !/^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i.test(value)) {
    throw new Error(`Missing or invalid WIX_METASITE_ID in ${WIX_CONFIG_PATH}; deploy the Wix config before seeding.`);
  }
  siteId = value;
  return siteId;
}


async function req(ctx, path, { method = "POST", body, headers = {} } = {}) {
  // Retry while the catalog is still provisioning: right after a fresh Stores install the V3 WRITE
  // path becomes usable a bit later than the V3 read path, so even once waitForCatalogV3 (a read
  // probe) returns, the first bulk-create can still 428. Wait it out (~80s budget); every other
  // error throws on the first try as before.
  for (let attempt = 0; ; attempt++) {
    const res = await fetch(API + path, {
      method,
      headers: {
        Authorization: `Bearer ${ctx.token}`,
        ...headers,
        "Content-Type": "application/json",
      },
      body: body ? JSON.stringify(body) : undefined,
    });
    const json = await res.json().catch(() => ({}));
    if (res.ok) return json;
    if (isProvisioning(res.status, json) && attempt < 40) {
      await sleep(2000);
      continue;
    }
    throw new Error(`${method} ${path} -> ${res.status}: ${JSON.stringify(json).slice(0, 400)}`);
  }
}

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

// A freshly installed catalog isn't writable yet, and Wix has signalled that with two different
// 428s: the older CATALOG_V1_SITE_CALLING_CATALOG_V3_API (site still reports V1) and the current
// CATALOG_V3_SITE_PROVISIONING ("Site is currently being provisioned for CATALOG_V3"). Sites exist
// on both behaviours, so match either. The message check catches a further rename: on this endpoint
// a 428 means "not ready, retry", and treating an unknown one as fatal turns a wait into a failed
// seed — which is exactly how the V3 code slipped through when only the V1 code was matched.
const PROVISIONING_CODES = new Set(["CATALOG_V1_SITE_CALLING_CATALOG_V3_API", "CATALOG_V3_SITE_PROVISIONING"]);

function isProvisioning(status, json) {
  if (PROVISIONING_CODES.has(json?.details?.applicationError?.code)) return true;
  return status === 428 && /provision/i.test(json?.message || "");
}

// A freshly installed Stores catalog 428s on V3 calls until provisioning settles (see
// isProvisioning for the codes). Poll a cheap V3 read until that clears (bounded ~80s), so we don't
// fire the expensive bulk-create repeatedly during the window. This is a pre-gate on the READ path;
// the WRITE path clears slightly later, so the real guarantee is req()'s retry — this just minimizes
// how many times the actual write has to retry.
async function waitForCatalogV3(ctx, { attempts = 40, delayMs = 2000 } = {}) {
  for (let i = 0; i < attempts; i++) {
    const res = await fetch(`${API}/stores/v3/products/query`, {
      method: "POST",
      headers: { Authorization: `Bearer ${ctx.token}`, "Content-Type": "application/json" },
      body: JSON.stringify({ query: { paging: { limit: 1 } } }),
    });
    if (res.ok) return;
    const json = await res.json().catch(() => ({}));
    // Anything that isn't a provisioning signal is a real error — return and let the caller's own
    // request surface it. Matching only one of the two codes here made this exit the wait on the
    // other one, handing the caller straight to a write that then 428'd.
    if (!isProvisioning(res.status, json)) return;
    await sleep(delayMs);
  }
}

// description string -> Wix rich-text node tree.
//
// Descriptions arrive as HTML as often as not: asked to describe a product, a model writes
// <p>…</p><strong>Care:</strong><br/>. The writable field is `description` (Ricos nodes) — the HTML
// `plainDescription` the storefront renders is read-only, derived from them. So markup dropped into
// a single TEXT node is stored as literal text, comes back escaped, and the PDP shows the tags to
// the buyer. Convert the tags a model actually emits; a string with no tags stays one paragraph.
const HTML_ENTITIES = { "&amp;": "&", "&lt;": "<", "&gt;": ">", "&quot;": '"', "&#39;": "'", "&nbsp;": " " };

function decodeEntities(s) {
  return s.replace(/&(?:amp|lt|gt|quot|#39|nbsp);/g, (m) => HTML_ENTITIES[m] ?? m);
}

// One paragraph's inner HTML -> TEXT nodes, carrying bold/italic as Ricos decorations.
function mkTextNodes(html) {
  const nodes = [];
  let bold = 0, italic = 0, last = 0, m;
  const tag = /<(\/?)(strong|b|em|i)\s*\/?>/gi;
  const push = (raw) => {
    const text = decodeEntities(raw.replace(/<[^>]*>/g, ""));
    if (!text) return;
    const decorations = [];
    if (bold > 0) decorations.push({ type: "BOLD" });
    if (italic > 0) decorations.push({ type: "ITALIC" });
    nodes.push({ type: "TEXT", textData: { text, decorations } });
  };
  while ((m = tag.exec(html)) !== null) {
    push(html.slice(last, m.index));
    const step = m[1] ? -1 : 1;
    if (/^(strong|b)$/i.test(m[2])) bold = Math.max(0, bold + step);
    else italic = Math.max(0, italic + step);
    last = tag.lastIndex;
  }
  push(html.slice(last));
  return nodes.length ? nodes : [{ type: "TEXT", textData: { text: "", decorations: [] } }];
}

function mkDesc(text, i) {
  const blocks = String(text ?? "").split(/<\/p\s*>|<br\s*\/?>/i).map((b) => b.trim()).filter(Boolean);
  return {
    nodes: (blocks.length ? blocks : [""]).map((block, n) => ({
      type: "PARAGRAPH", id: `desc-${i}-${n}`,
      nodes: mkTextNodes(block),
      paragraphData: { textStyle: { textAlignment: "AUTO" } },
    })),
    metadata: { version: 1, id: `desc-meta-${i}` },
  };
}

// [{name, type?:"text"|"color", choices:["8","9"] | [{name,colorCode}]}] -> Wix options[]
function buildOptions(options = []) {
  return options.map((o) => {
    const color = o.type === "color";
    return {
      name: o.name,
      optionRenderType: color ? "SWATCH_CHOICES" : "TEXT_CHOICES",
      choicesSettings: {
        choices: o.choices.map((c) =>
          color
            ? { choiceType: "ONE_COLOR", name: c.name, colorCode: c.colorCode }
            : { choiceType: "CHOICE_TEXT", name: typeof c === "string" ? c : c.name }),
      },
    };
  });
}

// Validate the whole batch before installation, uploads, or product creation.
function validateProducts(products) {
  const seen = new Map();
  for (const product of products) {
    // Wix caps a product name at 80 characters and the bulk create rejects the WHOLE batch over it
    // ("name has size 175, expected 80 or less"), so the 81st character costs the entire seed.
    if (typeof product.name === "string" && product.name.length > 80) {
      throw new Error(`Product "${product.name.slice(0, 48)}…": the name is ${product.name.length} characters and Wix allows 80. ` +
        `Shorten it and move the detail into description. No products were created by this call.`);
    }
    if (product.inStock !== undefined && typeof product.inStock !== "boolean") {
      throw new Error(`Product "${product.name}": inStock must be a boolean. No products were created by this call.`);
    }
    if (product.inStock !== undefined && product.quantity !== undefined) {
      throw new Error(`Product "${product.name}": supply either inStock or quantity, not both. No products were created by this call.`);
    }
    if (!product.digitalFileUrl && product.quantity !== undefined &&
        (!Number.isInteger(product.quantity) || product.quantity < 0 || product.quantity > 99999)) {
      throw new Error(`Product "${product.name}": quantity must be an integer from 0 to 99999. ` +
        `For unlimited stock, use inStock: true without quantity. No products were created by this call.`);
    }
    for (const option of product.options ?? []) {
      const choiceNames = new Set();
      for (const choice of option.choices ?? []) {
        const name = typeof choice === "string" ? choice : choice.name;
        const normalized = name.trim().toLowerCase();
        if (choiceNames.has(normalized)) {
          throw new Error(`Duplicate choice "${name}" in option "${option.name}" on product "${product.name}". ` +
            `Each choice name must be unique within an option. No products were created by this call.`);
        }
        choiceNames.add(normalized);
        if (option.type !== "color") continue;
        const key = JSON.stringify([option.name.trim().toLowerCase(), choice.name.trim().toLowerCase()]);
        const code = choice.colorCode?.trim().toLowerCase();
        const previous = seen.get(key);
        if (previous && previous.code !== code) {
          throw new Error(`Conflicting color "${choice.name}" in option "${option.name}": ` +
            `"${previous.product}" uses ${previous.code}, but "${product.name}" uses ${code}. ` +
            `Use one color code for this name across the batch, or distinct names for different shades. No products were created by this call.`);
        }
        seen.set(key, { code, product: product.name });
      }
    }
  }
}

// Choose one inventory tracking mode; downloads retain their default available stock.
function inventoryFor(product) {
  if (product.inStock !== undefined) return { inStock: product.inStock };
  if (product.digitalFileUrl) return { inStock: true };
  return { quantity: product.quantity ?? 0 };
}

// full Cartesian product of variants, each priced/stocked from the product; visible:true baked in
function expandVariants(options = [], product, digitalFileId) {
  const { price, compareAtPrice } = product;
  const inventoryItem = inventoryFor(product);
  const base = {
    price: {
      actualPrice: { amount: String(price) },
      ...(compareAtPrice ? { compareAtPrice: { amount: String(compareAtPrice) } } : {}),
    },
    visible: true,
    ...(digitalFileId
      ? { digitalProperties: { digitalFile: { id: digitalFileId } }, inventoryItem }
      : { physicalProperties: {}, inventoryItem: { ...inventoryItem,
          ...(inventoryItem.quantity !== undefined ? { preorderInfo: { enabled: false } } : {}) } }),
  };
  if (!options.length) return [base];
  let combos = [[]];
  for (const o of options) {
    const rt = o.type === "color" ? "SWATCH_CHOICES" : "TEXT_CHOICES";
    const names = o.choices.map((c) => (typeof c === "string" ? c : c.name));
    combos = combos.flatMap((combo) =>
      names.map((choiceName) => [...combo, { optionChoiceNames: { optionName: o.name, choiceName, renderType: rt } }]));
  }
  return combos.map((choices) => ({ ...base, choices }));
}

// A digital variant is SELLABLE only with BOTH a file and stock: without the file the cart rejects
// it as ITEM_NOT_FOUND_IN_CATALOG, without stock as "exceeds available inventory" — and either way
// the product reads back visible and in the catalog, so nothing surfaces until a buyer tries to buy.
// `digitalFileUrl` is the only way into DIGITAL here, which makes the file-less product unbuildable.
// The bytes are PUT, not imported by url: an uploaded file is READY at once, while an imported one
// stays PENDING and the cart rejects the product until it settles.
const FILE_MIME = { pdf: "application/pdf", zip: "application/zip", epub: "application/epub+zip",
  mp3: "audio/mpeg", wav: "audio/wav", mp4: "video/mp4", png: "image/png", jpg: "image/jpeg" };

async function uploadDigitalFile(ctx, url, fileName) {
  const mimeType = FILE_MIME[(fileName.split(".").pop() || "").toLowerCase()];
  if (!mimeType) throw new Error(`digitalFileName needs one of these extensions (${Object.keys(FILE_MIME).join(", ")}): ${fileName}`);
  const { uploadUrl } = await req(ctx, "/site-media/v1/files/generate-upload-url", { body: { mimeType, fileName } });
  const src = await fetch(url);
  if (!src.ok) throw new Error(`digitalFileUrl ${url} -> ${src.status}. A digital product needs a real, ` +
    `fetchable file — with none at hand, seed this product as physical with inStock: true and tell the user.`);
  const res = await fetch(uploadUrl, {
    method: "PUT", headers: { "Content-Type": mimeType }, body: Buffer.from(await src.arrayBuffer()),
  });
  const json = await res.json().catch(() => ({}));
  const id = (json.file || json)?.id;
  if (!res.ok || !id) throw new Error(`digital file upload failed (${res.status}): ${JSON.stringify(json).slice(0, 200)}`);
  return id;
}

const digitalFileName = (p) =>
  p.digitalFileName || decodeURIComponent(new URL(p.digitalFileUrl).pathname.split("/").pop() || "");

// ---- exported operations ----

async function installStoresApp(ctx) {
  const siteId = getSiteId(); // Fail before the install-error catch if config is missing.
  try {
    await req(ctx, "/apps-installer-service/v1/app-instance/install", { headers: { "wix-site-id": siteId }, body: {
      tenant: { tenantType: "SITE", id: siteId },
      appInstance: { appDefId: STORES_APP_ID, enabled: true },
    } });
  } catch {
    // already installed is fine — the readiness wait below still confirms the V3 catalog is live
  }
  // Do NOT return to the caller until V3 is ready, else the first V3 seed call 428s on CATALOG_V1.
  await waitForCatalogV3(ctx);
}

async function listProducts(ctx) {
  const r = await req(ctx, "/stores/v3/products/query", { body: { query: { paging: { limit: 50 } } } });
  return (r.products ?? []).map((p) => ({ id: p.id, name: p.name }));
}

/**
 * Bulk-create products.
 * @param products [{ name, description, price, compareAtPrice?, quantity?, inStock?,
 *   options?: [{ name, type?:"text"|"color", choices:["8","9"] | [{name,colorCode}] }],
 *   digitalFileUrl?, digitalFileName? }]
 *   digitalFileUrl: makes the product a DIGITAL download — the file is uploaded and the variant
 *   created with both the file and stock (see uploadDigitalFile). `quantity` is ignored.
 *   description: plain text, or simple HTML (`<p>`, `<br/>`, `<strong>`, `<em>`) — converted to
 *   Wix rich text here, so the storefront renders paragraphs and bold rather than tag text.
 *   options = ONLY things the buyer selects-and-buys (Size, Color) -> become variants.
 *   Display-only attributes go in name/category/description, NOT options. Default: no options.
 *   visible/physicalProperties/variant-expansion handled here. `quantity` tracks 0–99999 units (default 0); `inStock` selects availability without a count.
 *   Supply only one. Each variant inherits that stock mode. Downloads default to inStock:true.
 * @returns [{ id, slug, revision }]
 */
async function bulkCreateProducts(ctx, products) {
  validateProducts(products);
  const fileIds = await Promise.all(products.map((p) =>
    p.digitalFileUrl ? uploadDigitalFile(ctx, p.digitalFileUrl, digitalFileName(p)) : null));
  const body = {
    returnEntity: true,
    products: products.map((p, i) => ({
      name: p.name,
      // DIGITAL drops physicalProperties and can't be POS-visible (DIGITAL_PRODUCT_CANNOT_BE_VISIBLE_IN_POS).
      ...(fileIds[i]
        ? { productType: "DIGITAL" }
        : { productType: "PHYSICAL", physicalProperties: {}, visibleInPos: true }),
      visible: true,
      description: mkDesc(p.description, i),
      options: buildOptions(p.options),
      variantsInfo: { variants: expandVariants(p.options, p, fileIds[i]) },
    })),
  };
  const r = await req(ctx, "/stores/v3/bulk/products-with-inventory/create", { body });
  // NB: results nest under productResults.results[].item — NOT a top-level `results`.
  const results = r.productResults?.results ?? [];
  const created = [];
  const failures = [];
  const seen = new Set();
  for (const [position, result] of results.entries()) {
    const index = result.itemMetadata?.originalIndex ?? position;
    seen.add(index);
    if (result.itemMetadata?.success === false || !result.item?.id) {
      failures.push({ index, name: products[index]?.name, ...result.itemMetadata?.error,
        message: result.itemMetadata?.error?.description ?? "Create result has no product ID" });
      continue;
    }
    created.push({
      id: result.item.id, slug: result.item.slug, revision: result.item.revision,
      variantId: result.item.variantsInfo?.variants?.[0]?.id,
      hasOptions: (products[index]?.options?.length ?? 0) > 0,
      isDigital: !!fileIds[index], inventory: inventoryFor(products[index]),
      index, name: products[index]?.name,
    });
  }
  products.forEach((product, index) => {
    if (!seen.has(index)) failures.push({ index, name: product.name, message: "Missing bulk-create result; creation status unknown" });
  });
  if (failures.length) {
    const successes = created.map(({ id, name, index }) => ({ id, name, index }));
    const error = new Error(`Product creation did not fully succeed. ` +
      `Created: ${JSON.stringify(successes)}. Failures: ${JSON.stringify(failures)}. ` +
      `Stopped before stock, categories, or images. Do not rerun the full seed: existing products would be duplicated.`);
    error.createdProducts = successes;
    error.failures = failures;
    throw error;
  }
  created.sort((a, b) => a.index - b.index);
  await stockOptionlessProducts(ctx, created);
  return created.map((p) => ({ id: p.id, slug: p.slug, revision: p.revision }));
}

// products-with-inventory/create stocks a variant via its choices; an OPTION-LESS product has a
// single choiceless (default) variant that the create does NOT stock — it lands OUT_OF_STOCK. So
// set stock on those default variants explicitly (bulk/inventory-items/create). Products WITH options
// are already stocked by the create above, so they're skipped. Backfills the default variantId from a
// query if the create response didn't return it.
async function stockOptionlessProducts(ctx, created) {
  const need = created.filter((p) => !p.hasOptions && !p.isDigital && p.id); // digital variants ship inStock from the create
  if (!need.length) return;
  const missing = need.filter((p) => !p.variantId).map((p) => p.id);
  if (missing.length) {
    const q = await req(ctx, "/stores/v3/products/query", { body: { query: { filter: { id: { $in: missing } }, paging: { limit: missing.length } } } });
    const vById = new Map((q.products ?? []).map((p) => [p.id, p.variantsInfo?.variants?.[0]?.id]));
    need.forEach((p) => { if (!p.variantId) p.variantId = vById.get(p.id); });
  }
  const inventoryItems = need
    .filter((p) => p.variantId)
    .map((p) => ({ productId: p.id, variantId: p.variantId, ...p.inventory }));
  if (inventoryItems.length) {
    await req(ctx, "/stores/v3/bulk/inventory-items/create", { body: { inventoryItems } });
  }
}

// Categories: no bulk create, and MUST be sequential — they share the @wix/stores tree revision,
// so concurrent creates 409. Run after products (catalog can lag right after the Stores install).
async function createCategories(ctx, names) {
  const out = [];
  for (const name of names) {
    const r = await req(ctx, "/categories/v1/categories", {
      body: { category: { name, visible: true }, treeReference: { appNamespace: "@wix/stores", treeKey: null } },
    });
    out.push({ id: r.category?.id, name });
  }
  return out;
}

// mapping: { [categoryId]: [productId, ...] } — also sequential (same shared tree)
async function addProductsToCategories(ctx, mapping) {
  for (const [categoryId, productIds] of Object.entries(mapping)) {
    await req(ctx, `/categories/v1/bulk/categories/${categoryId}/add-items`, {
      body: {
        items: productIds.map((catalogItemId) => ({ catalogItemId, appId: STORES_APP_ID })),
        treeReference: { appNamespace: "@wix/stores", treeKey: null },
      },
    });
  }
}

// Bulk image attach in ONE call. items: [{ id, url, altText }] — NO revision.
// An attach bumps the product's revision, so a caller-supplied revision goes stale between passes
// (INVALID_REVISION); we read each product's CURRENT revision here, right before the update, so the
// caller never manages a revision token — attach any number of times, in any pass. Wix re-hosts the
// image from the url server-side; the re-hosted media can take a little while to appear on read-back
// (propagation) — that's normal, not a failure, so we don't block on it.
// Wix imports the image bytes server-side, so an attach needs an absolute, publicly fetchable url.
const isFetchableImageUrl = (url) => typeof url === "string" && /^https:\/\//.test(url);

async function attachProductImages(ctx, items) {
  if (!items?.length) return;
  if (items.some((it) => !it.id)) throw new Error("Image attachment requires a product ID for every item; no image request was sent.");
  const unfetchable = items.filter((it) => !isFetchableImageUrl(it.url));
  if (unfetchable.length) throw new Error(
    `Image url(s) for [${unfetchable.map((it) => it.altText || it.id).join(", ")}] are not absolute ` +
    `https:// urls, and Wix copies the image bytes at attach time. Re-call attachProductImages once each ` +
    `image has its final url. No image request was sent; products are unaffected.`);
  const ids = items.map((it) => it.id);
  const q = await req(ctx, "/stores/v3/products/query", { body: { query: { filter: { id: { $in: ids } }, paging: { limit: ids.length } } } });
  const revById = new Map((q.products ?? []).map((p) => [p.id, p.revision]));
  return req(ctx, "/stores/v3/bulk/products/update", {
    body: {
      products: items.map((it) => ({
        product: { id: it.id, revision: revById.get(it.id), media: { itemsInfo: { items: [{ url: it.url, altText: it.altText }] } } },
      })),
    },
  });
}

// Site-wide payment currency; product amounts are not converted when this changes.
// https://dev.wix.com/docs/api-reference/business-management/site-properties/skills/change-payment-currency-site-properties.md
async function configureCurrency(ctx, requested) {
  const result = { requested: requested ?? null, actual: null, status: "unchanged", warnings: [] };
  if (requested !== undefined) {
    try {
      if (typeof requested !== "string" || !/^[A-Z]{3}$/.test(requested))
        throw new Error("currency must be a three-letter uppercase ISO currency code");
      await req(ctx, "/site-properties/v4/properties", {
        method: "PATCH",
        body: { properties: { paymentCurrency: requested }, fields: { paths: ["paymentCurrency"] } },
      });
      result.status = "updated";
    } catch (error) {
      result.status = "failed";
      result.warnings.push(`Currency update failed; seeding continued: ${error.message}`);
    }
  }
  try {
    const snapshot = await req(ctx, "/site-properties/v4/properties", { method: "GET" });
    result.actual = snapshot.properties?.paymentCurrency ?? null;
    if (!result.actual) throw new Error("Site Properties returned no paymentCurrency");
    if (requested !== undefined && result.actual !== requested) {
      result.status = "failed";
      result.warnings.push(`Requested currency ${requested}; site currency is ${result.actual}.`);
    }
  } catch (error) {
    result.status = "failed";
    result.warnings.push(`Currency verification failed; seeding continued: ${error.message}`);
  }
  return result;
}

/**
 * ONE-CALL seed: install → create products → categories → attach images, in the correct order,
 * keeping the created ids in memory (no hand-threading of product ids across exec calls). This is
 * the DEFAULT path — call it once instead of the individual functions.
 *
 * @param plan {{
 *   currency?: string, // requested site payment currency; omitted preserves the current setting
 *   products: [{ name, description, price, compareAtPrice?, quantity?, inStock?, options?, imageUrl?, altText?,
 *                digitalFileUrl?, digitalFileName? }],
 *   categories?: { [categoryName]: string[] },   // map of category name -> product NAMES in it
 * }}
 * @returns { products: [{id,slug,revision,name}], categories: [{id,name}], imagesAttached: number,
 *             imagesSkipped?: string[], note?: string, currency: {requested,actual,status,warnings} }
 */
async function setupStore(ctx, { products = [], categories = {}, currency } = {}) {
  validateProducts(products);
  await installStoresApp(ctx); // installs if needed AND waits for the V3 catalog to be ready

  const currencyResult = await configureCurrency(ctx, currency);
  const created = await bulkCreateProducts(ctx, products);
  const withNames = created.map((p, i) => ({ ...p, name: products[i]?.name }));
  const idByName = new Map(withNames.map((p) => [p.name, p.id]));

  const names = Object.keys(categories);
  const cats = names.length ? await createCategories(ctx, names) : [];
  if (cats.length) {
    const mapping = {};
    for (const c of cats) {
      const ids = (categories[c.name] || []).map((n) => idByName.get(n)).filter(Boolean);
      if (ids.length) mapping[c.id] = ids;
    }
    if (Object.keys(mapping).length) await addProductsToCategories(ctx, mapping);
  }

  const imageItems = withNames
    .map((p, i) => ({ id: p.id, url: products[i]?.imageUrl, altText: products[i]?.altText ?? p.slug, name: p.name }))
    .filter((it) => it.url);
  // A url Wix cannot fetch would fail the attach: seed the product imageless and report it,
  // so the caller attaches once the final url exists.
  const readyItems = imageItems.filter((it) => isFetchableImageUrl(it.url));
  const skipped = imageItems.filter((it) => !isFetchableImageUrl(it.url)).map((it) => it.name);
  if (readyItems.length) await attachProductImages(ctx, readyItems);

  const withoutImages = withNames.filter((p, i) => !products[i]?.imageUrl).map((p) => p.name);
  return {
    products: withNames, categories: cats, imagesAttached: readyItems.length,
    ...(skipped.length && {
      imagesSkipped: skipped,
      note: "these products' image urls were not absolute https:// urls — attach them with " +
        "attachProductImages once each image has its final url",
    }),
    ...(withoutImages.length && !skipped.length && {
      productsWithoutImages: withoutImages,
      note: "these products were seeded without an image — once their images have final urls, " +
        "attach them with attachProductImages",
    }),
    currency: currencyResult,
  };
}

module.exports = {
  setupStore,
  installStoresApp, listProducts,
  bulkCreateProducts, createCategories, addProductsToCategories, attachProductImages,
};