@wix/agent-skills 1.20.1 → 1.22.0

package/skills/wix-headless-fast/references/storefront/rest/cart.ts

@@ -1,132 +0,0 @@
-// Cart + checkout over REST (Wix eCom Cart V2) — the twin of app/wix/storefront/cart.ts. Same
-// exports, same Cart/CartLine DTOs; rules and mappers from cart-core (the SAME file the SDK
-// transport uses, deployed flat next to this one). The request shapes are
-// exact and rewriting them is how carts break. Failures are loud: out-of-stock lines, an empty cart
-// at checkout, a missing required selection all throw — surface the message to the buyer.
-// All calls run with the visitor token: the cart is the token's (see ../shared/client).
-// docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart-v2/add-line-items-to-current-cart.md
-// docs: https://dev.wix.com/docs/api-reference/business-management/headless/redirects/create-redirect-session.md
-import { WixApiError, wixRequest } from "./client.js";
-import { imgSrc } from "./media.js";
-import { WIX_STORES_APP_ID, addOptions, assertAdded, assertCheckoutable, rawId, summaryTotals, toCart } from "./cart-core.js";
-import type { Raw } from "./catalog-core.js";
-import type { Cart } from "./types.js";
-
-const CART = "/ecom/v2/carts/current";
-
-export interface AddToCartExtras {
-  /** Choice modifiers: modifier key → chosen choice key (options.options — MODIFIERS only, never Size/Color). */
-  modifierChoices?: Record<string, string>;
-  /** Free-text modifiers: freeTextSettings.key → the buyer's text. */
-  customTextFields?: Record<string, string>;
-  /** A chosen recurring plan; omit for a one-time purchase. */
-  subscriptionOptionId?: string;
-  /** The resolved variant is out of stock but pre-orderable → preOrderRequested. */
-  preorder?: boolean;
-}
-
-// A line's attributes.image comes back absent right after an add (verified live) — join the
-// products' main images by catalogItemId, once per product, cached for the session.
-// POST /stores/v3/products/query  { query: { filter: { id: { $in: [...] } } } }
-const lineImageCache = new Map<string, string>();
-async function fillLineImages(cart: Cart, raws: Raw[]): Promise<void> {
-  const wanted = new Map<string, number[]>();
-  raws.forEach((raw, i) => {
-    if (cart.lines[i].imageUrl) return;
-    const pid = raw.source?.catalogReference?.catalogItemId;
-    if (!pid) return;
-    const cached = lineImageCache.get(pid);
-    if (cached !== undefined) { cart.lines[i].imageUrl = cached; return; }
-    wanted.set(pid, [...(wanted.get(pid) ?? []), i]);
-  });
-  if (!wanted.size) return;
-  try {
-    const res = await wixRequest<Raw>("/stores/v3/products/query", { body: { query: { filter: { id: { $in: [...wanted.keys()] } }, cursorPaging: { limit: 100 } } } });
-    for (const p of (res?.products ?? []) as Raw[]) {
-      const url = imgSrc(p.media?.main, 300, 300);
-      lineImageCache.set(rawId(p), url);
-      for (const i of wanted.get(rawId(p)) ?? []) cart.lines[i].imageUrl = url;
-    }
-  } catch {
-    /* images are a nicety — the cart stays correct without them */
-  }
-}
-
-async function readCartWithSubtotal(raw: Raw | null): Promise<Cart> {
-  // Only estimate a cart WITH lines — on an absent/empty cart the endpoint returns 404.
-  if (!raw?.lineItems?.length) return toCart(raw, "", "", imgSrc);
-  // The after-discount subtotal and the CART-level discount come from the estimate, never from
-  // hand-summing lines. Its delivery/tax/fees read "0" when nothing was calculated — never render
-  // those as "Free"; shipping and tax resolve at checkout.   POST /ecom/v2/carts/current/estimate
-  let totals = { subtotal: "", discount: "" };
-  try {
-    totals = summaryTotals(await wixRequest<Raw>(`${CART}/estimate`, { body: {} }), raw);
-  } catch {
-    /* the estimate is a display nicety — the cart itself is still valid */
-  }
-  const cart = toCart(raw, totals.subtotal, totals.discount, imgSrc);
-  await fillLineImages(cart, raw.lineItems as Raw[]);
-  return cart;
-}
-
-// GET /ecom/v2/carts/current — a 404 (CURRENT_CART_NOT_FOUND / OWNED_CART_NOT_FOUND) means no cart yet.
-async function getCurrentCartRaw(): Promise<Raw | null> {
-  try {
-    return (await wixRequest<Raw>(CART, { method: "GET" }))?.cart ?? null;
-  } catch (e) {
-    if (e instanceof WixApiError && e.status === 404) return null;
-    throw e;
-  }
-}
-
-/** The visitor's current cart. An empty Cart (not an error) when none exists yet. */
-export async function fetchCart(): Promise<Cart> {
-  return readCartWithSubtotal(await getCurrentCartRaw());
-}
-
-/**
- * Add a product. `variantId` is REQUIRED for any product with options — resolve it first
- * (resolveVariant); a refused add still returns 200, so the returned line is checked.
- * POST /ecom/v2/carts/current/add-line-items  { catalogItems: [{ quantity, catalogReference: { appId, catalogItemId, options } }] }
- */
-export async function addToCart(productId: string, variantId?: string | null, quantity = 1, extras: AddToCartExtras = {}): Promise<Cart> {
-  const options = addOptions({ variantId, ...extras });
-  const res = await wixRequest<Raw>(`${CART}/add-line-items`, {
-    body: { catalogItems: [{ quantity, catalogReference: { catalogItemId: productId, appId: WIX_STORES_APP_ID, ...(Object.keys(options).length ? { options } : {}) } }] },
-  });
-  assertAdded(res?.cart, productId, variantId);
-  return readCartWithSubtotal(res?.cart ?? null);
-}
-
-/**
- * Change a line's quantity. `lineItemId` is CartLine.lineItemId, never the product id; a flat
- * { id, quantity } is a 400.  POST /ecom/v2/carts/current/update-line-items  { lineItems: [{ lineItemId, quantity: { newQuantity } }] }
- */
-export async function updateQuantity(lineItemId: string, quantity: number): Promise<Cart> {
-  const res = await wixRequest<Raw>(`${CART}/update-line-items`, { body: { lineItems: [{ lineItemId, quantity: { newQuantity: quantity } }] } });
-  return readCartWithSubtotal(res?.cart ?? null);
-}
-
-/** Remove a line by CartLine.lineItemId.  POST /ecom/v2/carts/current/remove-line-items  { lineItemIds } */
-export async function removeLine(lineItemId: string): Promise<Cart> {
-  const res = await wixRequest<Raw>(`${CART}/remove-line-items`, { body: { lineItemIds: [lineItemId] } });
-  return readCartWithSubtotal(res?.cart ?? null);
-}
-
-/**
- * Start the Wix-hosted checkout and return the URL to navigate the FULL document to. The cart's id
- * IS the checkout id. `origin` must be the site's real https origin as registered on the OAuth
- * app's allowed domains (browser: window.location.origin; server: the public https host, never
- * the request's internal origin) — an unlisted or http origin 403s on return.
- * POST /headless/v1/redirect-session  { ecomCheckout: { checkoutId }, callbacks: { postFlowUrl, thankYouPageUrl } }
- */
-export async function checkoutUrl(origin: string = typeof window !== "undefined" ? window.location.origin : ""): Promise<string> {
-  const raw = await getCurrentCartRaw();
-  assertCheckoutable(raw);
-  const res = await wixRequest<Raw>("/headless/v1/redirect-session", {
-    body: { ecomCheckout: { checkoutId: rawId(raw) }, callbacks: origin ? { postFlowUrl: `${origin}/`, thankYouPageUrl: `${origin}/` } : {} },
-  });
-  const url = res?.redirectSession?.fullUrl;
-  if (!url) throw new Error("Checkout couldn't start: no redirect URL returned.");
-  return url;
-}

package/skills/wix-headless-fast/references/storefront/rest/catalog.ts

@@ -1,123 +0,0 @@
-// Catalog reads over REST — the twin of app/wix/storefront/catalog.ts. Same exports, same DTOs; the
-// rules and mappers come from catalog-core (the SAME file the SDK transport uses, deployed flat next
-// to this one by deploy.mjs --stack static), so this file is only the transport: one fetch with a
-// literal body per function. Every call here is safe from a
-// browser with a visitor token. Porting: keep the paths, keep the bodies, port the core once.
-// docs: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/search-products.md
-// docs: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/categories/get-category-by-slug.md
-import { WixApiError, wixRequest } from "./client.js";
-import { imgSrc, mediaKey } from "./media.js";
-import {
-  CATALOG_SORTS,
-  DETAIL_FIELDS,
-  LIST_FIELDS,
-  catalogFilter,
-  resolveVariant,
-  searchQuery,
-  sellingPrice,
-  toCategory,
-  toDetail,
-  toFacetData,
-  toSummary,
-  type CatalogSearchOptions,
-  type CatalogSort,
-  type Raw,
-} from "./catalog-core.js";
-import type { Category, FacetData, ProductDetail, ProductSummary } from "./types.js";
-
-export { CATALOG_SORTS, resolveVariant, sellingPrice, type CatalogSearchOptions, type CatalogSort };
-
-const STORES_TREE = { appNamespace: "@wix/stores", treeKey: null };
-const notFound = (e: unknown): boolean => e instanceof WixApiError && e.status === 404;
-
-/**
- * The gallery query: sort, filter, facets, search, and cursor paging, all applied by Wix across the
- * whole catalog — never on a page already in hand. `total` is issued with the first page only.
- * POST /stores/v3/products/search  { fields, search: { filter, sort, search, cursorPaging } }
- */
-export async function searchCatalog(o: CatalogSearchOptions = {}): Promise<{ products: ProductSummary[]; nextCursor: string | null; total: number | null }> {
-  const search = searchQuery(o);
-  const res = await wixRequest<Raw>("/stores/v3/products/search", { body: { fields: LIST_FIELDS, search } });
-  let total: number | null = null;
-  if (!o.cursor) {
-    try {
-      const c = await wixRequest<Raw>("/stores/v3/products/count", { body: { filter: search.filter } });
-      total = typeof c?.count === "number" ? c.count : null;
-    } catch {
-      /* the count is a nicety — the page is still valid */
-    }
-  }
-  return {
-    products: ((res?.products ?? []) as Raw[]).map((p) => toSummary(p, imgSrc, mediaKey)),
-    nextCursor: res?.pagingMetadata?.cursors?.next ?? null,
-    total,
-  };
-}
-
-/** Facets and price bounds of a scope from one 100-product read. Non-fatal: empty on failure. */
-export async function fetchFacetData({ categoryId }: { categoryId?: string | null } = {}): Promise<FacetData> {
-  try {
-    const res = await wixRequest<Raw>("/stores/v3/products/search", {
-      body: { fields: ["CURRENCY"], search: { filter: catalogFilter({ categoryId }), cursorPaging: { limit: 100 } } },
-    });
-    return toFacetData((res?.products ?? []) as Raw[]);
-  } catch {
-    return { facets: [], priceRange: null };
-  }
-}
-
-export async function fetchProducts({ limit = 24 } = {}): Promise<ProductSummary[]> {
-  return (await searchCatalog({ limit })).products;
-}
-
-export async function fetchProductsByCategory(categoryId: string, { limit = 24 } = {}): Promise<ProductSummary[]> {
-  return (await searchCatalog({ limit, categoryId })).products;
-}
-
-/**
- * One complete product for the PDP; null when the slug doesn't resolve — a real 404, never a
- * fallback to another product.  GET /stores/v3/products/slug/{slug}?fields=…&fields=…
- */
-export async function fetchProductBySlug(slug: string): Promise<ProductDetail | null> {
-  try {
-    const res = await wixRequest<Raw>(`/stores/v3/products/slug/${encodeURIComponent(slug)}`, { method: "GET", query: { fields: DETAIL_FIELDS } });
-    return res?.product ? toDetail(res.product, imgSrc, mediaKey) : null;
-  } catch (e) {
-    if (notFound(e)) return null;
-    throw e;
-  }
-}
-
-/**
- * The live category tree for navigation — never a seeded list. The filter must be non-empty;
- * `visible` is not filterable (dropped client-side); the auto-created "all-products" system
- * category is skipped. Non-fatal: [] on failure.  POST /categories/v1/categories/query
- */
-export async function fetchCategories(): Promise<Category[]> {
-  try {
-    const res = await wixRequest<Raw>("/categories/v1/categories/query", {
-      body: { treeReference: STORES_TREE, query: { filter: { name: { $exists: true } }, cursorPaging: { limit: 100 } } },
-    });
-    return ((res?.categories ?? []) as Raw[]).filter((c) => c.visible !== false && c.slug !== "all-products").map(toCategory);
-  } catch {
-    return [];
-  }
-}
-
-/**
- * One category by URL slug (its id feeds searchCatalog). The response is WRAPPED: { category }.
- * null when missing or hidden → a real 404.  GET /categories/v1/categories/slug/{slug}
- */
-export async function fetchCategoryBySlug(slug: string): Promise<Category | null> {
-  try {
-    const res = await wixRequest<Raw>(`/categories/v1/categories/slug/${encodeURIComponent(slug)}`, {
-      method: "GET",
-      query: { "treeReference.appNamespace": "@wix/stores" },
-    });
-    const raw: Raw | undefined = res?.category;
-    return raw && raw.visible !== false ? toCategory(raw) : null;
-  } catch (e) {
-    if (notFound(e)) return null;
-    throw e;
-  }
-}

package/skills/wix-headless-fast/references/storefront/seed/SEED.md

@@ -1,124 +0,0 @@
-# Storefront — seeding
-
-Seed the Wix Stores catalog by **running `seed-store.mjs` with a plan file** — don't hand-write
-the REST calls. The script mints its own site token via the Wix CLI (requires a logged-in CLI
-session and a `wix.config.json` in the working directory), installs the Stores app if needed,
-waits for the V3 catalog, and creates everything in the right order.
-
-**Set each product's type by what the buyer receives** — physical (shipped, has `quantity`) or
-digital (a file they keep, `digitalFilePath`/`digitalFileUrl`, no `quantity`); the plan below shows
-both. *Access* — a membership or an online course/program the buyer enrolls in — is Pricing Plans,
-not a store product.
-
-```bash
-# from the project root (where wix.config.json lives):
-node <SKILL_ROOT>/references/storefront/seed/seed-store.mjs plan.json
-```
-
-Run this way, the result is the process itself: exit code `0` and the JSON on stdout (redirect it
-to a file if you want it later). `.seed-exit` and `seed-result.json` are written by
-`install/fast-path.mjs` when IT starts the seed — don't wait for them after a manual run.
-
-`plan.json` is plain data — write it from the brief:
-
-```json
-{
-  "products": [
-    { "name": "The Glam Rocker", "description": "Sequin-studded velvet legend…",
-      "price": 49.99, "quantity": 12, "imageUrl": "https://…" },
-    { "name": "The Understudy", "description": "…", "price": 245, "quantity": 8,
-      "options": [{ "name": "Color", "type": "color",
-                    "choices": [{ "name": "Ink", "colorCode": "#1B1B2F" },
-                                { "name": "Bone", "colorCode": "#EDE6D6" }] }] },
-    { "name": "Encore Jacket", "description": "…", "price": 68, "compareAtPrice": 129,
-      "quantity": 5 },
-    { "name": "Backstage Guide", "description": "…", "price": 12,
-      "digitalFilePath": "/Users/me/guide.pdf" }
-  ],
-  "categories": { "Legends": ["The Glam Rocker"], "Rising Stars": [] },
-  "currency": "EUR"
-}
-```
-
-- `description` — plain text or simple HTML (`<p>`, `<br/>`, `<strong>`, `<em>`); converted to
-  Wix rich text so the storefront renders paragraphs and bold, not tag text.
-- `options` — ONLY things the buyer selects-and-buys (Size, Color); they become variants.
-  `type: "color"` renders as real swatches (give every color choice a `colorCode`); anything
-  else renders as text pills. Variants are expanded automatically (full cross-product, each
-  carrying the product's price/compareAtPrice/quantity) — keep option counts small.
-- `compareAtPrice` (> `price`) — the "was" price: strikethrough on the PDP, sale badge data on
-  the tile.
-- **Give every product an image** (a store without product images looks broken: gray boxes on
-  tiles, PDP, and cart) — the default is an `imagePrompt` (AI-generated, ~1 Wix AI credit
-  per image, account-billed): brand-contextual — subject, aesthetic/mood, palette, lighting —
-  always ending "no text, no watermarks". At least one image in the set shows the real subject of the business — the actual product/space/service, not abstract decoration. For an asset the user actually supplied use `imagePath` (a file on
-  this machine — uploaded to Wix Media) or `imageUrl` (their own hosted URL; verify it with
-  `curl -sI` → 200) — never a stock-photo or guessed URL. Images resolve in parallel and never block the seed; a failed image leaves
-  that product text-only. Seed text-only only when the user explicitly asks.
-- `digitalFilePath` (a file on this machine) or `digitalFileUrl` — makes the product a digital
-  download, uploaded and created with both the file and stock (`quantity` is ignored). It's also the
-  only way in: a file-less digital product is created successfully, reads back healthy, and is then
-  rejected at add-to-cart as `ITEM_NOT_FOUND_IN_CATALOG`. **No real file in hand?** Don't invent a
-  URL and don't ship the product as digital — seed it physical with stock (drop
-  `digitalFilePath`/`digitalFileUrl`, add `inStock` or a `quantity`) and tell the user the
-  download needs a real file before it can be sold.
-- `categories` — category name → product NAMES. Omit when the brief names none.
-- `quantity` — tracked stock, a non-negative integer. For stock that isn't counted (made to
-  order, print on demand, unlimited) use `"inStock": true` **instead** of `quantity`; sending
-  both is rejected.
-- `currency` — 3-letter ISO code. Set it **only when the brief names one** ("prices in euros",
-  "a German store charging EUR"). Do **not** infer it from a language, a country, or an address
-  — an unrequested switch silently reprices the whole catalog. The seed applies it before
-  creating anything, because a product's price is stored in the site currency at create time.
-  For a few seconds afterwards product reads can still report the old currency; that lag is
-  expected and self-resolves, so don't re-verify it or retry.
-
-**Default to 3 products** when you draft the catalog yourself — the seed shows the shape, not a
-full inventory; the owner adds the rest in the dashboard. **Make those 3 exercise the shipped
-UI**: give at least one product a color option and put one product on sale — truthfully to the
-business (a ceramics studio has glaze colors; a bakery doesn't).
-
-## Supplied content
-
-The general rules are in `references/shared/SUPPLIED-CONTENT.md`. For a store, each product the user
-lists is one entry, whatever form the list arrives in. Its name, description and price become
-`name`, `description` and `price`. A "was", "regular" or "compare at" price becomes `compareAtPrice`
-when it is higher than the price. A stock count becomes `quantity`; "unlimited" or "made to order"
-becomes `"inStock": true`. A category, collection or type becomes an entry in `categories`. A set of
-choices the buyer picks from ("Small / Large", "S, M, L") becomes one `options` entry named after
-what it is (Size, Flavor), `type: "text"`; use `type: "color"` only when the source gives color codes.
-Their image becomes `imageUrl`. If a product has a separate price per size, seed it once at the
-lowest price and tell the user the per-variant prices are set in the dashboard. If a product has no
-price, ask; never invent one. Ribbons ("New", "Best Seller") and SKU codes are not seeded — say so.
-
-**Seeding is additive — never delete or overwrite existing content.** No cleanup, no removing
-"sample" data, no resets — not even on a site created a minute ago. The Stores install adds its
-own sample products to a new catalog; they stay, and the owner removes them in the dashboard
-(the Manage products link is in your summary). If a cleanup genuinely seems needed, ask the user
-first. Categories are idempotent by name — a re-run reuses "Donuts" instead of creating a second one.
-
-**A bulk create can partially succeed.** The result carries `failures: [{ name, error }]` next
-to `products` — read it. A non-empty `failures` means those products are genuinely absent, not
-mis-mapped, so the rest of the catalog is fine to build on. To retry, re-run the **same** plan:
-creation is idempotent by name, so products that already exist are skipped rather than
-duplicated. Never hand-patch ids to "fill the gap".
-
-Two things this module does not seed (dashboard-only — tell the merchant):
-**ribbons** ("New", "Best Seller") and **per-choice linked media** (color choice → gallery photo).
-
-## Escape hatch — individual functions
-
-`setupStore` is built from exported steps; import them only for a partial re-seed or custom
-ordering: `installStoresApp`, `bulkCreateProducts`, `createCategories`,
-`addProductsToCategories`, `attachProductImages` — plus `makeCtx()` for the auth context.
-
-## Reference
-
-If a call returns an unexpected shape or you need an operation this module doesn't cover, read
-the live Wix API reference — never guess. The authoritative source recipe is
-`wix-headless/references/inline-recipes/setup-online-store.md`. Key pages:
-
-- Bulk Create Products With Inventory: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/bulk-create-products-with-inventory.md
-- Create Category: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/categories/create-category.md
-- Bulk Add Items To Category: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/categories/bulk-add-items-to-category.md
-- Bulk Update Products (image attach): https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/bulk-update-products.md