@wix/agent-skills 1.17.0 → 1.18.0

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

@@ -0,0 +1,215 @@
+// Catalog reads (Wix Stores Catalog V3) — the only file that touches raw catalog entities.
+// Everything it returns is a plain DTO from ./types: images resolved, prices formatted,
+// variants normalized. Copy as-is; extend by adding functions, not by editing these.
+// 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/products-v3/get-product-by-slug.md
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/categories/query-categories.md
+import { productsV3 } from "@wix/stores";
+import { categories as categoriesModule } from "@wix/categories";
+import { wixModule } from "../sdk";
+import { imgSrc } from "../media";
+import type {
+  Category,
+  ProductDetail,
+  ProductOption,
+  ProductModifier,
+  ProductSummary,
+  ProductVariant,
+  Availability,
+} from "./types";
+
+const products = wixModule(productsV3);
+const categories = wixModule(categoriesModule);
+
+// Requested on every product read. CURRENCY populates formattedAmount (without it, prices render
+// as bare unlocalized numbers); MEDIA_ITEMS_INFO populates the gallery; the detail read adds
+// PLAIN_DESCRIPTION and VARIANT_OPTION_CHOICE_NAMES (which populates variantsInfo.variants).
+const LIST_FIELDS = ["CURRENCY", "MEDIA_ITEMS_INFO"];
+const DETAIL_FIELDS = [...LIST_FIELDS, "PLAIN_DESCRIPTION", "VARIANT_OPTION_CHOICE_NAMES"];
+
+type RawProduct = Record<string, any>;
+
+function toAvailability(raw: RawProduct): Availability {
+  const status = raw.inventory?.availabilityStatus;
+  return status === "OUT_OF_STOCK" || status === "PARTIALLY_OUT_OF_STOCK"
+    ? status
+    : "IN_STOCK";
+}
+
+function toSummary(raw: RawProduct): ProductSummary {
+  const options: RawProduct[] = raw.options ?? [];
+  const galleryItems: RawProduct[] = raw.media?.itemsInfo?.items ?? [];
+  const mainUrl = imgSrc(raw.media?.main, 800, 800);
+  const hover = galleryItems
+    .map((m) => imgSrc(m.image ?? m, 800, 800))
+    .filter((u) => u && u !== mainUrl);
+  const availability = toAvailability(raw);
+  const preorder = raw.inventory?.preorderStatus === "ENABLED" && availability === "OUT_OF_STOCK";
+  const optionsSummary = options
+    .map((o) => {
+      const visible = (o.choicesSettings?.choices ?? []).filter((c: RawProduct) => c.visible !== false);
+      return `${visible.length} ${String(o.name ?? "").toLowerCase()}${visible.length === 1 ? "" : "s"}`;
+    })
+    .join(" · ");
+  return {
+    id: raw._id ?? "",
+    slug: raw.slug ?? "",
+    name: raw.name ?? "",
+    price: raw.actualPriceRange?.minValue?.formattedAmount ?? "",
+    maxPrice: raw.actualPriceRange?.maxValue?.formattedAmount ?? "",
+    compareAtPrice: raw.compareAtPriceRange?.minValue?.formattedAmount ?? null,
+    ribbon: raw.ribbon?.name ?? null,
+    availability,
+    preorder,
+    imageUrl: mainUrl,
+    hoverImageUrl: hover[0] ?? "",
+    optionsSummary,
+    quickAddable: options.length === 0 && availability === "IN_STOCK",
+  };
+}
+
+function toOptions(raw: RawProduct): ProductOption[] {
+  return (raw.options ?? []).map((o: RawProduct) => {
+    const isColor = o.optionRenderType === "SWATCH_CHOICES" || o.optionRenderType === "COLOR_CHOICES";
+    return {
+      id: o._id ?? o.id ?? o.name ?? "",
+      name: o.name ?? "",
+      isColor,
+      choices: (o.choicesSettings?.choices ?? [])
+        .filter((c: RawProduct) => c.visible !== false)
+        .map((c: RawProduct) => ({
+          choiceId: c.choiceId ?? "",
+          name: c.name ?? "",
+          colorCode: c.colorCode ?? null,
+          inStock: c.inStock !== false,
+        })),
+    };
+  });
+}
+
+function toModifiers(raw: RawProduct): ProductModifier[] {
+  return (raw.modifiers ?? []).map((m: RawProduct) => ({
+    key: m.key ?? m.freeTextSettings?.key ?? m.name ?? "",
+    name: m.name ?? "",
+    mandatory: m.mandatory === true,
+    type: m.modifierRenderType === "FREE_TEXT" ? ("text" as const) : ("choices" as const),
+    choices: (m.choicesSettings?.choices ?? []).map((c: RawProduct) => ({
+      key: c.key ?? c.name ?? "",
+      name: c.name ?? "",
+    })),
+  }));
+}
+
+function toVariants(raw: RawProduct): ProductVariant[] {
+  return (raw.variantsInfo?.variants ?? []).map((v: RawProduct) => {
+    const choices: Record<string, string> = {};
+    for (const c of v.choices ?? []) {
+      const names = c.optionChoiceNames;
+      if (names?.optionName) choices[names.optionName] = names.choiceName ?? "";
+    }
+    return {
+      variantId: v._id ?? v.variantId ?? "",
+      choices,
+      price: v.price?.actualPrice?.formattedAmount ?? "",
+      compareAtPrice: v.price?.compareAtPrice?.formattedAmount ?? null,
+      inStock: v.inventoryStatus?.inStock !== false,
+    };
+  });
+}
+
+function toDetail(raw: RawProduct): ProductDetail {
+  const summary = toSummary(raw);
+  const gallery = [
+    summary.imageUrl,
+    ...(raw.media?.itemsInfo?.items ?? []).map((m: RawProduct) => imgSrc(m.image ?? m, 1200, 1200)),
+  ].filter((u, i, arr) => u && arr.indexOf(u) === i);
+  return {
+    ...summary,
+    descriptionHtml: raw.plainDescription ?? "",
+    gallery,
+    options: toOptions(raw),
+    modifiers: toModifiers(raw),
+    variants: toVariants(raw),
+  };
+}
+
+/** List visible products (newest catalog order), mapped to grid-ready DTOs. */
+export async function fetchProducts({ limit = 100 } = {}): Promise<ProductSummary[]> {
+  const res = await products
+    .queryProducts({ fields: LIST_FIELDS as any })
+    .limit(limit)
+    .find();
+  return (res.items ?? []).map((p) => toSummary(p as RawProduct));
+}
+
+/**
+ * List visible products in a category, server-side-filtered by the live category id.
+ * Category filtering MUST go through searchProducts (the field is not filterable in
+ * queryProducts) with the $matchItems operator — this is encoded here so callers never
+ * reconstruct it.
+ */
+export async function fetchProductsByCategory(
+  categoryId: string,
+  { limit = 100 } = {},
+): Promise<ProductSummary[]> {
+  const res: RawProduct = await products.searchProducts(
+    {
+      filter: { "allCategoriesInfo.categories": { $matchItems: [{ id: categoryId }] } },
+      cursorPaging: { limit },
+    },
+    { fields: LIST_FIELDS as any },
+  );
+  return (res.products ?? []).map((p: RawProduct) => toSummary(p));
+}
+
+/** Fetch one product by its URL slug, with options/modifiers/variants. Null when not found. */
+export async function fetchProductBySlug(slug: string): Promise<ProductDetail | null> {
+  try {
+    const res = await products.getProductBySlug(slug, { fields: DETAIL_FIELDS as any });
+    return res.product ? toDetail(res.product as RawProduct) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * List the store's categories for nav/filter UI, minus Wix's auto-created "all-products"
+ * system category. The query must carry a filter condition (`.exists("name", true)` — a
+ * tautology): a bare .find() serializes an empty filter that the API rejects on the
+ * visitor-client path. Treat a failure as "no category nav", not a fatal error.
+ */
+export async function fetchCategories(): Promise<Category[]> {
+  try {
+    const res = await categories
+      .queryCategories({ treeReference: { appNamespace: "@wix/stores" } })
+      .exists("name", true)
+      .find();
+    return (res.items ?? [])
+      .map((c) => ({
+        id: (c as RawProduct)._id ?? "",
+        slug: (c as RawProduct).slug ?? "",
+        name: (c as RawProduct).name ?? "",
+      }))
+      .filter((c) => c.slug !== "all-products");
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Resolve the variant for the buyer's selections (optionName -> choiceName).
+ * A product with no options resolves to its single variant; with options, every option
+ * must be selected and match. Returns null while the selection is incomplete.
+ */
+export function resolveVariant(
+  detail: ProductDetail,
+  selections: Record<string, string>,
+): ProductVariant | null {
+  if (detail.options.length === 0) return detail.variants[0] ?? null;
+  if (!detail.options.every((o) => selections[o.name])) return null;
+  return (
+    detail.variants.find((v) =>
+      detail.options.every((o) => v.choices[o.name] === selections[o.name]),
+    ) ?? null
+  );
+}

package/skills/wix-headless-fast/references/storefront/app/wix/storefront/types.ts

@@ -0,0 +1,109 @@
+// Storefront DTOs — the serializable shapes every hook, component, and page consumes.
+// These are plain JSON: safe to pass as Astro island props or across a server/client
+// boundary. Image values are already-resolved https URLs (never wix:image://), and every
+// displayable price is a ready formatted string.
+
+export type Availability = "IN_STOCK" | "OUT_OF_STOCK" | "PARTIALLY_OUT_OF_STOCK";
+
+/** A product as a listing/grid tile needs it. */
+export interface ProductSummary {
+  id: string;
+  slug: string;
+  name: string;
+  /** Lowest price, formatted with currency symbol (e.g. "€34.99"). */
+  price: string;
+  /** Highest price, formatted — differs from `price` when variants are priced differently. */
+  maxPrice: string;
+  /** Strikethrough "was" price, formatted; null when not on sale. */
+  compareAtPrice: string | null;
+  /** Merchant-set badge ("New", "Best Seller"); null when none. */
+  ribbon: string | null;
+  availability: Availability;
+  /** OUT_OF_STOCK but pre-orderable — label "Pre-order", not "Sold out". */
+  preorder: boolean;
+  /** Resolved https URL of the main image ("" when the product has none). */
+  imageUrl: string;
+  /** Resolved https URL of the second gallery image ("" when there is only one). */
+  hoverImageUrl: string;
+  /** e.g. "2 colors · 3 sizes"; "" for a single-variant product. */
+  optionsSummary: string;
+  /** True when the product can be added to the cart with no choices (single variant, in stock). */
+  quickAddable: boolean;
+}
+
+export interface OptionChoice {
+  choiceId: string;
+  name: string;
+  /** Hex color for swatch rendering; null for text choices. */
+  colorCode: string | null;
+  inStock: boolean;
+}
+
+export interface ProductOption {
+  id: string;
+  name: string;
+  /** Render choices as color swatches (true) or text pills (false). */
+  isColor: boolean;
+  choices: OptionChoice[];
+}
+
+export interface ProductModifier {
+  key: string;
+  name: string;
+  mandatory: boolean;
+  /** "choices" renders pills; "text" renders a free-text input. */
+  type: "choices" | "text";
+  choices: { key: string; name: string }[];
+}
+
+export interface ProductVariant {
+  variantId: string;
+  /** The option selections this variant answers to: optionName -> choiceName. */
+  choices: Record<string, string>;
+  price: string;
+  compareAtPrice: string | null;
+  inStock: boolean;
+}
+
+/** A product as the detail page needs it. */
+export interface ProductDetail extends ProductSummary {
+  /** Product description as an HTML string — render with innerHTML, not as text. */
+  descriptionHtml: string;
+  /** Every gallery image as a resolved https URL, main image first, de-duplicated. */
+  gallery: string[];
+  options: ProductOption[];
+  modifiers: ProductModifier[];
+  variants: ProductVariant[];
+}
+
+export interface Category {
+  id: string;
+  slug: string;
+  name: string;
+}
+
+export interface CartLine {
+  /** The cart line id — what update/remove take (NOT the product id). */
+  lineItemId: string;
+  productName: string;
+  quantity: number;
+  /** Per-unit price, formatted. */
+  unitPrice: string;
+  /** Line total, formatted. */
+  linePrice: string;
+  /** Resolved https URL ("" when none). */
+  imageUrl: string;
+  /** Human-readable option/modifier labels, e.g. ["Color: Ink", "Size: M"]. */
+  descriptionLines: string[];
+  /** Not IN_STOCK → the line can't be checked out as-is. */
+  status: string;
+}
+
+export interface Cart {
+  lines: CartLine[];
+  /** Sum of line quantities. */
+  itemCount: number;
+  /** Formatted subtotal (after discounts) — from the cart estimate, not hand-summed. */
+  subtotal: string;
+  currency: string;
+}

package/skills/wix-headless-fast/references/storefront/app-astro/layouts/SiteLayout.astro

@@ -0,0 +1,46 @@
+---
+// The site chrome for every storefront page — THIS file (header/footer/nav) plus the @theme
+// token block in src/styles/global.css are what you brand. Keep:
+//   - the <slot name="seo-tags" /> in <head> (the product page's owner-editable SEO lands there)
+//   - the global.css import (Tailwind + the design tokens every shipped component reads)
+//   - one <CartButton> in the header and one <CartDrawer> per page (both client:only —
+//     they read browser cart state and must not server-render)
+import CartButton from "../components/storefront/CartButton";
+import CartDrawer from "../components/storefront/CartDrawer";
+import "../styles/global.css";
+
+interface Props {
+  title: string;
+  description?: string;
+}
+const { title, description } = Astro.props;
+---
+
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{title}</title>
+    {description && <meta name="description" content={description} />}
+    <slot name="seo-tags" />
+  </head>
+  <body>
+    <header class="sticky top-0 z-40 border-b border-border bg-background/80 backdrop-blur">
+      <div class="mx-auto flex h-16 max-w-6xl items-center justify-between px-6">
+        <a href="/" class="text-base font-bold tracking-tight text-foreground no-underline">Brand Name</a>
+        <nav class="flex items-center gap-6 text-sm">
+          <a href="/shop" class="text-foreground no-underline transition-colors hover:text-muted-foreground">Shop</a>
+          <CartButton client:only="react" />
+        </nav>
+      </div>
+    </header>
+    <main class="mx-auto max-w-6xl px-6 pb-24 pt-10">
+      <slot />
+    </main>
+    <footer class="border-t border-border px-6 py-10 text-center text-sm text-muted-foreground">
+      © Brand Name
+    </footer>
+    <CartDrawer client:only="react" />
+  </body>
+</html>

package/skills/wix-headless-fast/references/storefront/app-astro/pages/products/[slug].astro

@@ -0,0 +1,56 @@
+---
+// Product detail page — wire as-is; theme via SiteLayout's tokens.
+//
+// This is a Wix ITEM PAGE: the wixMetadata export + <SEO.Tags> below are what let the site
+// owner edit this page's title/description/OG in the dashboard, and register the route in
+// the sitemap. Keep all three SEO pieces when editing this file.
+import SiteLayout from "../../layouts/SiteLayout.astro";
+import ProductDetailView from "../../components/storefront/ProductDetailView";
+import { fetchProductBySlug } from "../../wix/storefront/catalog";
+import { WIX_APPS } from "@wix/essentials";
+import { SEO } from "@wix/seo/components";
+import { loadSEOTagsServiceConfig } from "@wix/seo/services";
+import { seoTags } from "@wix/seo";
+
+export const wixMetadata = {
+  appDefId: WIX_APPS.checkoutAndOrders.id,
+  pageIdentifier: WIX_APPS.checkoutAndOrders.productPageMetadata.pageIdentifier,
+  identifiers: {
+    slug: WIX_APPS.checkoutAndOrders.productPageMetadata.identifiers.handle,
+  },
+};
+
+const slug = Astro.params.slug!;
+
+// Behind Wix's proxy the request URL is the internal one — the real public page URL
+// arrives on x-wix-forwarded-url. The SEO service needs the public URL.
+const forwardedUrl = Astro.request.headers.get("x-wix-forwarded-url");
+const pageUrl =
+  forwardedUrl && URL.canParse(forwardedUrl) && /^https?:$/.test(new URL(forwardedUrl).protocol)
+    ? forwardedUrl
+    : Astro.url.href;
+
+let product = null;
+let seoTagsServiceConfig = null;
+try {
+  [product, seoTagsServiceConfig] = await Promise.all([
+    fetchProductBySlug(slug),
+    loadSEOTagsServiceConfig({
+      pageUrl,
+      itemType: seoTags.ItemType.STORES_PRODUCT,
+      itemData: { slug },
+    }),
+  ]);
+} catch {
+  // Guarded: an unhandled SSR throw truncates the response mid-stream.
+}
+
+if (!product) {
+  return new Response(null, { status: 404 });
+}
+---
+
+<SiteLayout title={product.name}>
+  <SEO.Tags seoTagsServiceConfig={seoTagsServiceConfig} slot="seo-tags" />
+  <ProductDetailView client:load initial={product} />
+</SiteLayout>

package/skills/wix-headless-fast/references/storefront/app-astro/pages/shop.astro

@@ -0,0 +1,23 @@
+---
+// Shop listing — products and categories are fetched SERVER-SIDE (SEO) and handed to the
+// island as serialized DTO props; category switches then filter live on the client.
+// Wire as-is; theme via SiteLayout's tokens.
+import SiteLayout from "../layouts/SiteLayout.astro";
+import ShopView from "../components/storefront/ShopView";
+import { fetchProducts, fetchCategories } from "../wix/storefront/catalog";
+import type { Category, ProductSummary } from "../wix/storefront/types";
+
+let products: ProductSummary[] = [];
+let categories: Category[] = [];
+try {
+  [products, categories] = await Promise.all([fetchProducts(), fetchCategories()]);
+} catch {
+  // An unguarded SSR throw truncates the response mid-stream; the island renders the
+  // shipped empty state instead.
+}
+---
+
+<SiteLayout title="Shop">
+  <h1 class="mb-8 text-2xl font-semibold tracking-tight">Shop</h1>
+  <ShopView client:load initialProducts={products} initialCategories={categories} />
+</SiteLayout>