@wix/agent-skills 1.0.0

package/skills/wix-headless/templates/gift-cards/components-gift-cards.css

@@ -0,0 +1,219 @@
+/* Gift Cards pack — scoped CSS.
+ *
+ * Imported by Layout.astro alongside other components-*.css files. Covers:
+ *   1. Buy form (`.gift-card-form` + fields)
+ *   2. /gift-cards landing page sections
+ *   3. Home teaser block
+ *
+ * Reuses tokens declared by the designer foundation: --color-cream,
+ * --color-cream-deep, --color-ink, --color-ink-soft, --color-muted,
+ * --color-rule, --color-paper, --color-bark/espresso/gold-deep,
+ * --spacing-{sm,md,lg,xl,2xl,3xl,4xl}, --radius-sm, --font-body,
+ * --font-display. If a token isn't in your design system, fall back to a
+ * sibling token; do NOT invent new ones.
+ */
+
+/* -------------------------------------------------------------------------- */
+/* Buy form                                                                    */
+/* -------------------------------------------------------------------------- */
+
+.gift-card-form {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-lg);
+  margin-top: var(--spacing-lg);
+}
+
+.gift-card-fieldset {
+  border: none;
+  padding: 0;
+  margin: 0;
+}
+
+.gift-card-amounts {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--spacing-sm);
+  margin-top: var(--spacing-sm);
+}
+
+.gift-card-grid {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: var(--spacing-md);
+}
+
+.gift-card-field {
+  display: flex;
+  flex-direction: column;
+  gap: 0.4rem;
+  position: relative;
+}
+
+.gift-card-field-wide {
+  grid-column: 1 / -1;
+}
+
+.gift-card-field input,
+.gift-card-field textarea {
+  font-family: var(--font-body);
+  font-size: 0.9375rem;
+  line-height: 1.5;
+  color: var(--color-ink);
+  background: var(--color-cream);
+  border: 1px solid var(--color-rule);
+  border-radius: var(--radius-sm);
+  padding: 0.65rem 0.8rem;
+  transition: border-color 0.2s ease;
+}
+
+.gift-card-field input:focus,
+.gift-card-field textarea:focus {
+  outline: none;
+  border-color: var(--color-ink);
+}
+
+.gift-card-field textarea {
+  resize: vertical;
+  min-height: 5rem;
+}
+
+.gift-card-counter {
+  position: absolute;
+  right: 0;
+  bottom: -1.2rem;
+  font-family: var(--font-body);
+  font-size: 0.6875rem;
+  color: var(--color-muted);
+}
+
+.gift-card-error {
+  font-family: var(--font-body);
+  font-size: 0.875rem;
+  color: var(--color-gold-deep, #a04a3c);
+  margin: 0;
+}
+
+/* -------------------------------------------------------------------------- */
+/* /gift-cards landing page                                                    */
+/* -------------------------------------------------------------------------- */
+
+.gift-card-page {
+  max-width: 80rem;
+  margin: 0 auto;
+  padding: var(--spacing-3xl) var(--spacing-lg) var(--spacing-4xl);
+}
+
+.gift-card-grid-wrap {
+  display: grid;
+  grid-template-columns: 1fr;
+  gap: var(--spacing-2xl);
+  align-items: start;
+}
+
+@media (min-width: 768px) {
+  .gift-card-grid-wrap {
+    grid-template-columns: 1fr 1fr;
+    gap: var(--spacing-4xl);
+  }
+}
+
+.gift-card-hero-image {
+  background: var(--color-cream-deep, var(--color-paper, var(--color-cream)));
+  border-radius: var(--radius-sm);
+  overflow: hidden;
+  aspect-ratio: 1 / 1;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.gift-card-hero-image img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+.gift-card-body {
+  max-width: 36rem;
+}
+
+.gift-card-body h1 {
+  margin: var(--spacing-md) 0 var(--spacing-md);
+}
+
+.gift-card-lede {
+  font-family: var(--font-body);
+  font-size: 1.0625rem;
+  line-height: 1.7;
+  color: var(--color-ink-soft);
+  max-width: 48ch;
+  margin: 0 0 var(--spacing-xl);
+}
+
+.gift-card-fineprint {
+  margin-top: var(--spacing-lg);
+  font-family: var(--font-body);
+  font-size: 0.8125rem;
+  line-height: 1.6;
+  color: var(--color-muted);
+  max-width: 44ch;
+}
+
+/* -------------------------------------------------------------------------- */
+/* Home teaser                                                                 */
+/* -------------------------------------------------------------------------- */
+
+.gift-card-teaser {
+  padding: var(--spacing-4xl) var(--spacing-lg);
+  background: var(--color-cream-deep, var(--color-paper, var(--color-cream)));
+}
+
+.gift-card-teaser-link {
+  display: grid;
+  grid-template-columns: 1fr;
+  gap: var(--spacing-2xl);
+  max-width: 80rem;
+  margin: 0 auto;
+  align-items: center;
+  text-decoration: none;
+  color: var(--color-ink);
+}
+
+@media (min-width: 768px) {
+  .gift-card-teaser-link {
+    grid-template-columns: 1fr 1fr;
+    gap: var(--spacing-4xl);
+  }
+}
+
+.gift-card-teaser-image {
+  aspect-ratio: 4 / 3;
+  overflow: hidden;
+  border-radius: var(--radius-sm);
+  background: var(--color-cream);
+}
+
+.gift-card-teaser-image img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  transition: transform 0.6s ease;
+}
+
+.gift-card-teaser-link:hover .gift-card-teaser-image img {
+  transform: scale(1.02);
+}
+
+.gift-card-teaser-body h2 {
+  margin: var(--spacing-md) 0 var(--spacing-md);
+}
+
+.gift-card-teaser-lede {
+  font-family: var(--font-body);
+  font-size: 1.0625rem;
+  line-height: 1.7;
+  color: var(--color-ink-soft);
+  max-width: 44ch;
+  margin: 0 0 var(--spacing-lg);
+}

package/skills/wix-headless/templates/gift-cards/gift-cards.astro

@@ -0,0 +1,51 @@
+---
+import Layout from "../layouts/Layout.astro";
+import GiftCardPurchase from "../components/GiftCardPurchase.tsx";
+import { getGiftCardProduct } from "../utils/gift-cards";
+import { resolveWixImageUrl } from "../utils/wix-image";
+
+// The probe returns null if the Wix Gift Card app is uninstalled, revoked,
+// or the dashboard's eGift Card template hasn't been configured. Redirect
+// rather than rendering an empty page — keeps stale links from showing a
+// broken UI.
+const product = await getGiftCardProduct();
+if (!product) return Astro.redirect("/", 302);
+
+const heroImage = resolveWixImageUrl(product.image, 800, 800);
+---
+
+<Layout
+  title={product.name}
+  description={product.description}
+>
+  <section class="py-3xl md:py-4xl">
+    <div class="max-w-wide mx-auto px-xl grid grid-cols-1 md:grid-cols-2 gap-2xl md:gap-4xl items-center">
+      <div class="aspect-square bg-cream rounded-sm overflow-hidden">
+        {heroImage && (
+          <img
+            src={heroImage}
+            alt={product.image?.altText || product.name}
+            loading="lazy"
+            decoding="async"
+            width={product.image?.width ?? 800}
+            height={product.image?.height ?? 800}
+            class="w-full h-full object-cover"
+          />
+        )}
+      </div>
+
+      <div class="flex flex-col gap-lg">
+        <p class="eyebrow">A gift, considered</p>
+        <h1 class="font-display text-5xl leading-tight">{product.name}</h1>
+        <p class="text-ink-soft leading-relaxed">{product.description}</p>
+
+        <GiftCardPurchase product={product} client:load />
+
+        <p class="text-mute text-sm leading-relaxed">
+          Sent by email to your recipient with a redeemable code. Redeemed at
+          checkout against any product on the site.
+        </p>
+      </div>
+    </div>
+  </section>
+</Layout>

package/skills/wix-headless/templates/gift-cards/gift-cards.ts

@@ -0,0 +1,75 @@
+// Wix Gift Card app — eGift Card template fetch.
+//
+// The dashboard's Catalog → Gift Cards screen configures a single eGift Card
+// "product" with preset denominations. That product is queryable via a public
+// REST endpoint (POST /gift-cards/v1/gift-card-products/query). The JS SDK
+// auto-package @wix/auto_sdk_ecom_gift-vouchers only exposes redemption
+// methods (getGiftCard / redeemGiftCard / voidTransaction), so we hit REST
+// directly using @wix/essentials httpClient.fetchWithAuth.
+//
+// The buy flow uses the standard cart: currentCart.addToCurrentCart with a
+// catalogReference whose appId is WIX_GIFT_CARDS_APP_ID below. After payment,
+// Wix's gift-card backend automatically issues a redeemable gift card with
+// source: "ORDER" and emails the recipient — no follow-up API call needed.
+//
+// The appId is observable on installed sites and stable across sites. If Wix
+// ever rotates it, update this constant; both the runtime probe and the buy
+// flow will fail together (and the page hides gracefully — same as "app
+// uninstalled").
+
+import { httpClient } from "@wix/essentials";
+
+export const WIX_GIFT_CARDS_APP_ID = "d80111c5-a0f4-47a8-b63a-65b54d774a27";
+
+export interface GiftCardImage {
+  id?: string;
+  url?: string;
+  height?: number;
+  width?: number;
+  altText?: string;
+}
+
+export interface GiftCardPresetVariant {
+  id: string;
+  price: { amount: string; formattedAmount: string; convertedAmount?: string; formattedConvertedAmount?: string };
+  value: { amount: string; formattedAmount: string; convertedAmount?: string; formattedConvertedAmount?: string };
+}
+
+export interface GiftCardProduct {
+  id: string;
+  revision?: string;
+  name: string;
+  description: string;
+  image?: GiftCardImage;
+  expirationType?: string;
+  presetVariants: GiftCardPresetVariant[];
+}
+
+const ENDPOINT = "https://www.wixapis.com/gift-cards/v1/gift-card-products/query";
+
+// Module-level memoization. Navigation, the home teaser, and /gift-cards all
+// call getGiftCardProduct() in the same request — coalesce them into one
+// fetch by holding the in-flight promise at module scope.
+let cached: Promise<GiftCardProduct | null> | null = null;
+
+export async function getGiftCardProduct(): Promise<GiftCardProduct | null> {
+  if (cached) return cached;
+  cached = (async () => {
+    try {
+      const res = await httpClient.fetchWithAuth(ENDPOINT, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ query: { paging: { limit: 1 } } }),
+      });
+      if (!res.ok) return null;
+      const data = await res.json();
+      const products = data?.giftCardProducts;
+      if (!Array.isArray(products) || products.length === 0) return null;
+      return products[0] as GiftCardProduct;
+    } catch (err) {
+      console.error("[gift-cards] queryGiftCardProducts failed:", err);
+      return null;
+    }
+  })();
+  return cached;
+}

package/skills/wix-headless/templates/stores/AddToCartButton.tsx

@@ -0,0 +1,77 @@
+import { useState } from "react";
+import { currentCart } from "@wix/ecom";
+import { trackEvent } from "../utils/analytics";
+
+const WIX_STORES_APP_ID = "215238eb-22a5-4c36-9e7b-e7c08025e04e";
+
+interface AddToCartButtonProps {
+  productId: string;
+  productName: string;
+  price?: number;
+  currency?: string;
+  variantId?: string;
+  variantName?: string;
+  quantity?: number;
+  disabled?: boolean;
+  // Modifier selections, already flattened by ProductPurchase. Shapes:
+  //   modifierChoices:  { [modifier.key]: choice.key }
+  //   customTextFields: { [modifier.freeTextSettings.key]: "<user input>" }
+  modifierChoices?: Record<string, string>;
+  customTextFields?: Record<string, string>;
+}
+
+export default function AddToCartButton({
+  productId, productName, price, currency,
+  variantId, variantName, quantity = 1, disabled,
+  modifierChoices, customTextFields,
+}: AddToCartButtonProps) {
+  const [status, setStatus] = useState<"idle" | "added">("idle");
+
+  const handleAddToCart = async () => {
+    // Optimistic: show success immediately, fire API in background
+    setStatus("added");
+    setTimeout(() => setStatus("idle"), 2000);
+    window.dispatchEvent(new CustomEvent("cart-updated", { detail: { delta: quantity } }));
+
+    try {
+      // Build catalogReference.options per Wix Stores Catalog V3 contract:
+      //   { variantId, options: { [modifier.key]: choice.key }, customTextFields: { … } }
+      const catalogOptions: Record<string, unknown> = {};
+      if (variantId) catalogOptions.variantId = variantId;
+      if (modifierChoices && Object.keys(modifierChoices).length > 0) {
+        catalogOptions.options = modifierChoices;
+      }
+      if (customTextFields && Object.keys(customTextFields).length > 0) {
+        catalogOptions.customTextFields = customTextFields;
+      }
+      const { cart } = await currentCart.addToCurrentCart({
+        lineItems: [{
+          catalogReference: {
+            appId: WIX_STORES_APP_ID,
+            catalogItemId: productId,
+            options: Object.keys(catalogOptions).length > 0 ? catalogOptions : undefined,
+          },
+          quantity,
+        }],
+      });
+      window.dispatchEvent(new CustomEvent("cart-updated", { detail: { cart } }));
+      trackEvent("AddToCart", {
+        id: productId, name: productName, price, currency,
+        quantity, variant: variantName, origin: "Product Page",
+      });
+    } catch {
+      setStatus("idle");
+      window.dispatchEvent(new CustomEvent("cart-updated", { detail: {} }));
+    }
+  };
+
+  return (
+    <button
+      onClick={handleAddToCart}
+      disabled={disabled || status === "added"}
+      className="add-to-cart-btn"
+    >
+      {disabled ? "Select Options" : status === "added" ? "Added \u2713" : "Add to Cart"}
+    </button>
+  );
+}

package/skills/wix-headless/templates/stores/BackInStockForm.tsx

@@ -0,0 +1,176 @@
+import { useState } from "react";
+import { backInStockNotifications } from "@wix/ecom";
+import { WIX_STORES_BACK_IN_STOCK_APP_ID } from "../utils/back-in-stock";
+
+interface BackInStockFormProps {
+  productId: string;
+  variantId?: string;
+  productName: string;
+  // Numeric price (number or numeric string). The Wix backend validates
+  // `itemDetails.price >= 0` against the parsed decimal, so currency-
+  // formatted strings ("$695") are stripped here before submission.
+  productPrice: number | string;
+  variantLabel?: string;
+}
+
+type Status =
+  | { kind: "idle" }
+  | { kind: "submitting" }
+  | { kind: "success"; alreadySubscribed?: boolean }
+  | { kind: "error"; message: string };
+
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+function normalizePrice(raw: number | string): string {
+  const s =
+    typeof raw === "number" ? String(raw) : String(raw).replace(/[^0-9.]/g, "");
+  const n = Number(s);
+  return Number.isFinite(n) && n >= 0 ? s : "0";
+}
+
+function readErrorCode(err: unknown): string | undefined {
+  if (!err || typeof err !== "object") return undefined;
+  // Wix SDK errors expose details.applicationError.code; some shapes also
+  // surface a top-level details.code or http status. Try the common ones.
+  const e = err as Record<string, any>;
+  return (
+    e?.details?.applicationError?.code ??
+    e?.details?.code ??
+    e?.applicationError?.code ??
+    undefined
+  );
+}
+
+export default function BackInStockForm({
+  productId,
+  variantId,
+  productName,
+  productPrice,
+  variantLabel,
+}: BackInStockFormProps) {
+  const [email, setEmail] = useState("");
+  const [status, setStatus] = useState<Status>({ kind: "idle" });
+
+  const submitting = status.kind === "submitting";
+  const success = status.kind === "success";
+
+  async function handleSubmit(e: React.FormEvent<HTMLFormElement>) {
+    e.preventDefault();
+    if (submitting) return;
+    if (!EMAIL_RE.test(email)) {
+      setStatus({ kind: "error", message: "Enter a valid email." });
+      return;
+    }
+    setStatus({ kind: "submitting" });
+
+    // Bare-fields rule: the SDK throws an opaque
+    // "TypeError: Failed to construct 'URL': Invalid URL" when the optional
+    // request.itemUrl or itemDetails.image fields are present, even with
+    // browser-valid URLs. Send only the four required fields:
+    // catalogReference, email, name, price. The dashboard's Back-in-Stock
+    // Requests view + the customer notification email both work without
+    // them; the email just won't have a thumbnail and the dashboard uses
+    // its default item URL.
+    const request = {
+      catalogReference: {
+        appId: WIX_STORES_BACK_IN_STOCK_APP_ID,
+        catalogItemId: productId,
+        ...(variantId ? { options: { variantId } } : {}),
+      },
+      email,
+    };
+    const itemDetails = {
+      name: productName,
+      price: normalizePrice(productPrice),
+    };
+
+    try {
+      await backInStockNotifications.createBackInStockNotificationRequest(
+        request,
+        itemDetails,
+      );
+      setStatus({ kind: "success" });
+    } catch (err) {
+      const code = readErrorCode(err);
+      if (code === "BACK_IN_STOCK_NOTIFICATION_REQUEST_ALREADY_EXISTS") {
+        setStatus({ kind: "success", alreadySubscribed: true });
+        return;
+      }
+      if (code === "REQUEST_COLLECTION_DISABLED") {
+        setStatus({
+          kind: "error",
+          message: "Notifications aren't being collected right now.",
+        });
+        return;
+      }
+      console.error("[back-in-stock] subscribe failed:", err);
+      setStatus({
+        kind: "error",
+        message: "Something went wrong. Please try again.",
+      });
+    }
+  }
+
+  if (success) {
+    return (
+      <div className="back-in-stock-success" role="status" aria-live="polite">
+        <p className="back-in-stock-success-headline">
+          {status.alreadySubscribed
+            ? "You're already on the list."
+            : "We'll let you know."}
+        </p>
+        <p className="back-in-stock-success-detail">
+          {status.alreadySubscribed
+            ? `We had your note for ${productName}${variantLabel ? ` (${variantLabel})` : ""}. We'll email ${email} the moment it's back.`
+            : `We'll email ${email} the moment ${productName}${variantLabel ? ` (${variantLabel})` : ""} is back in stock.`}
+        </p>
+      </div>
+    );
+  }
+
+  return (
+    <form className="back-in-stock-form" onSubmit={handleSubmit} noValidate>
+      <div className="back-in-stock-headline">
+        <span className="back-in-stock-eyebrow">Currently sold out</span>
+        <p className="back-in-stock-lede">
+          Leave your email and we'll notify you the moment
+          {variantLabel ? ` ${variantLabel.toLowerCase()}` : ""} is back in
+          stock.
+        </p>
+      </div>
+      <label className="back-in-stock-label" htmlFor="back-in-stock-email">
+        Email
+      </label>
+      <div className="back-in-stock-row">
+        <input
+          id="back-in-stock-email"
+          type="email"
+          inputMode="email"
+          autoComplete="email"
+          required
+          placeholder="you@example.com"
+          value={email}
+          onChange={(e) => {
+            setEmail(e.target.value);
+            if (status.kind === "error") setStatus({ kind: "idle" });
+          }}
+          className="back-in-stock-input"
+          aria-invalid={status.kind === "error"}
+          disabled={submitting}
+        />
+        <button
+          type="submit"
+          className="back-in-stock-submit"
+          disabled={submitting || email.trim().length === 0}
+        >
+          {submitting ? "Sending…" : "Notify me"}
+        </button>
+      </div>
+      {status.kind === "error" && (
+        <p className="back-in-stock-error" role="alert">
+          {status.message}
+        </p>
+      )}
+    </form>
+  );
+}

package/skills/wix-headless/templates/stores/CategoryRail.astro

@@ -0,0 +1,69 @@
+---
+// Shared category-rail + Prev/Next pagination for /products and
+// /category/[slug]. Persists across <ClientRouter /> swaps so pill clicks
+// feel like an in-place filter, not a navigation. The active pill is
+// recomputed from the URL by an astro:after-swap hook in Layout.astro.
+//
+// Owned by the stores pack. Ecom/blog/etc. do NOT write to this file.
+import type { StoreCategory } from "../utils/categories";
+
+interface Props {
+  categories: StoreCategory[];
+  // null = "All" view; otherwise the slug of the active category.
+  activeSlug: string | null;
+  prevHref: string | null;
+  nextHref: string | null;
+}
+
+const { categories, activeSlug, prevHref, nextHref } = Astro.props;
+---
+
+{categories.length > 0 && (
+  <nav
+    class="category-rail"
+    aria-label="Browse by category"
+    data-category-rail
+    transition:persist="category-rail"
+    transition:name="category-rail"
+  >
+    <div class="container-page category-rail-inner">
+      <a
+        href="/products"
+        class="category-pill"
+        data-category-slug=""
+        data-astro-prefetch="hover"
+        aria-current={activeSlug ? undefined : "page"}
+      >All</a>
+      {categories.map((cat) => (
+        <a
+          href={`/category/${cat.slug}`}
+          class="category-pill"
+          data-category-slug={cat.slug}
+          data-astro-prefetch="hover"
+          aria-current={activeSlug === cat.slug ? "page" : undefined}
+        >{cat.name}</a>
+      ))}
+    </div>
+  </nav>
+)}
+
+{(prevHref || nextHref) && (
+  <nav class="pagination" aria-label="Listing pagination">
+    <div class="container-page pagination-inner">
+      {prevHref ? (
+        <a href={prevHref} class="pagination-link" data-astro-prefetch="hover" rel="prev">
+          &larr; Previous
+        </a>
+      ) : (
+        <span class="pagination-link is-disabled" aria-disabled="true">&larr; Previous</span>
+      )}
+      {nextHref ? (
+        <a href={nextHref} class="pagination-link" data-astro-prefetch="hover" rel="next">
+          Next &rarr;
+        </a>
+      ) : (
+        <span class="pagination-link is-disabled" aria-disabled="true">Next &rarr;</span>
+      )}
+    </div>
+  </nav>
+)}