@wix/agent-skills 1.26.0 → 1.28.0

package/skills/wix-headless-templates/restaurants/app/wix/restaurants/time-core.ts

@@ -0,0 +1,118 @@
+// Wall-clock arithmetic in a named IANA zone with nothing but Intl — no date-fns-tz. The one
+// place that knows how to turn "2026-10-03 19:00 in America/New_York" into an instant and back;
+// ordering-core (menu availability windows in the setting's zone) and reservations-core (slot
+// search and labels in the LOCATION's zone, never the visitor's) both import it. No imports of its
+// own, so a strip to JS emits none; deploy copies every *-core.ts next to the transports.
+
+export interface ZonedParts {
+  year: number;
+  /** 1-12 */
+  month: number;
+  day: number;
+  /** 0-23 */
+  hour: number;
+  minute: number;
+  second: number;
+  /** 0 = Sunday … 6 = Saturday */
+  weekday: number;
+}
+
+const WEEKDAYS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+const pad = (n: number) => String(n).padStart(2, "0");
+
+/** The wall-clock parts of an instant in `timeZone` ("" or an unknown zone → the runtime's zone). */
+export function zonedParts(date: Date, timeZone: string): ZonedParts {
+  try {
+    const parts = new Intl.DateTimeFormat("en-US", {
+      timeZone: timeZone || undefined,
+      hourCycle: "h23",
+      weekday: "short",
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+      hour: "2-digit",
+      minute: "2-digit",
+      second: "2-digit",
+    }).formatToParts(date);
+    const get = (type: string) => parts.find((p) => p.type === type)?.value ?? "";
+    const hour = Number(get("hour")) % 24; // some engines print "24" for midnight
+    return {
+      year: Number(get("year")),
+      month: Number(get("month")),
+      day: Number(get("day")),
+      hour,
+      minute: Number(get("minute")),
+      second: Number(get("second")),
+      weekday: Math.max(0, WEEKDAYS.indexOf(get("weekday"))),
+    };
+  } catch {
+    return {
+      year: date.getFullYear(),
+      month: date.getMonth() + 1,
+      day: date.getDate(),
+      hour: date.getHours(),
+      minute: date.getMinutes(),
+      second: date.getSeconds(),
+      weekday: date.getDay(),
+    };
+  }
+}
+
+/** "YYYY-MM-DD" of an instant in `timeZone`. */
+export function zonedDayKey(date: Date, timeZone: string): string {
+  const p = zonedParts(date, timeZone);
+  return `${p.year}-${pad(p.month)}-${pad(p.day)}`;
+}
+
+/** Minutes since midnight of an instant in `timeZone`. */
+export function zonedMinutes(date: Date, timeZone: string): number {
+  const p = zonedParts(date, timeZone);
+  return p.hour * 60 + p.minute;
+}
+
+/**
+ * The instant at which the wall clock in `timeZone` reads `dayKey` ("YYYY-MM-DD") `hhmm` ("HH:mm"),
+ * as an ISO string. Two offset iterations cover DST edges. Invalid input → "".
+ */
+export function zonedIso(dayKey: string, hhmm: string, timeZone: string): string {
+  const [y, m, d] = dayKey.split("-").map(Number);
+  const [h, mi] = hhmm.split(":").map(Number);
+  if (![y, m, d, h, mi].every(Number.isFinite)) return "";
+  const target = Date.UTC(y, m - 1, d, h, mi, 0);
+  let utc = target;
+  for (let i = 0; i < 2; i++) {
+    const p = zonedParts(new Date(utc), timeZone);
+    const wall = Date.UTC(p.year, p.month - 1, p.day, p.hour, p.minute, p.second);
+    utc = target - (wall - utc);
+  }
+  return new Date(utc).toISOString();
+}
+
+/** A short time label of an instant in `timeZone` in the visitor's language ("7:00 PM"); "" on failure. */
+export function zonedTimeLabel(date: Date, timeZone: string, locale?: string): string {
+  try {
+    return date.toLocaleTimeString(locale || undefined, { hour: "numeric", minute: "2-digit", timeZone: timeZone || undefined });
+  } catch {
+    try {
+      return date.toLocaleTimeString(undefined, { hour: "numeric", minute: "2-digit" });
+    } catch {
+      return "";
+    }
+  }
+}
+
+/** A short date + time label of an instant in `timeZone` ("Fri, Oct 3, 7:00 PM"); "" on failure. */
+export function zonedDateTimeLabel(date: Date, timeZone: string, locale?: string): string {
+  try {
+    return date.toLocaleString(locale || undefined, {
+      weekday: "short",
+      month: "short",
+      day: "numeric",
+      hour: "numeric",
+      minute: "2-digit",
+      timeZone: timeZone || undefined,
+    });
+  } catch {
+    return "";
+  }
+}

package/skills/wix-headless-templates/restaurants/app/wix/restaurants/types.ts

@@ -0,0 +1,337 @@
+// Restaurants DTOs — the serializable shapes every hook, component, and page consumes.
+// Plain JSON: safe as Astro island props or across server/client boundaries. Images are
+// resolved https URLs. EVERY money value is a formatted string in the site's currency and
+// locale (read once from the eCommerce settings' BUSINESS_INFO, the way Wix's own menus code
+// does) — "" when the currency could not be read; the raw decimal rides beside it in the
+// `*Amount` fields for arithmetic. Order-cart prices (eCom) are formatted from the cart's currency.
+
+/** The site's currency + locale, from the eCommerce settings. `currency` "" when unknown. */
+export interface SiteMoney {
+  /** ISO 4217, e.g. "USD"; "" when the settings could not be read (prices then format to ""). */
+  currency: string;
+  /** BCP 47, e.g. "en-US"; "" → the runtime's default locale. */
+  locale: string;
+}
+
+/** A dietary/style label on a menu item (e.g. "Vegan", "Spicy"). */
+export interface MenuItemLabel {
+  id: string;
+  name: string;
+  /** Resolved https URL ("" when the label has no icon). */
+  iconUrl: string;
+}
+
+/** One price variant of an item ("Glass" / "Bottle"). An item has price OR variants. */
+export interface MenuItemVariant {
+  variantId: string;
+  name: string;
+  /** Formatted price ("" when the currency is unknown). */
+  price: string;
+  /** Decimal amount, site currency, no symbol ("9.50"). */
+  priceAmount: string;
+}
+
+/** One choice inside a modifier group ("Extra cheese"). */
+export interface MenuModifier {
+  /** The modifier entity id — what the cart line carries. The same id may appear twice in one group. */
+  id: string;
+  /** Unique within the group: `${id}~${index}` — the selection key (duplicate ids stay distinct). */
+  key: string;
+  name: string;
+  preSelected: boolean;
+  /** Formatted up-charge ("" when free or the currency is unknown). */
+  additionalCharge: string;
+  /** Decimal up-charge amount ("0" = free), site currency, no symbol. */
+  additionalChargeAmount: string;
+  inStock: boolean;
+}
+
+/**
+ * The shape of a group's rule, derived from required/min/max the way Wix's ordering code does:
+ * NO_LIMIT (optional, any count) · CHOOSE_ONE (exactly or up to one) · CHOOSE_X (required, min = max)
+ * · AT_LEAST_ONE · AT_LEAST_X · UP_TO_X (optional, max > 1) · BETWEEN_X_AND_Y (required, min < max).
+ */
+export type ModifierRuleType =
+  | "NO_LIMIT"
+  | "CHOOSE_ONE"
+  | "CHOOSE_X"
+  | "CHOOSE_AT_LEAST_ONE"
+  | "CHOOSE_AT_LEAST_X"
+  | "CHOOSE_UP_TO_X"
+  | "CHOOSE_BETWEEN_X_AND_Y";
+
+/** A modifier group on an item ("Toppings", choose 0–3). Selections are sent on the cart line. */
+export interface MenuModifierGroup {
+  id: string;
+  name: string;
+  required: boolean;
+  minSelections: number;
+  maxSelections: number | null;
+  rule: ModifierRuleType;
+  /** required && min 1 && max 1 → render radios (one selection replaces the other); else checkboxes. */
+  singleSelect: boolean;
+  modifiers: MenuModifier[];
+}
+
+/** A dish/drink as the menu page needs it. */
+export interface MenuItem {
+  id: string;
+  name: string;
+  description: string;
+  /** Formatted price; null when the item is variant-priced or market-priced. */
+  price: string | null;
+  /** Decimal base price ("12.50"); null when variant-priced or market-priced. */
+  priceAmount: string | null;
+  /** True → show "Market price"; the item can't be ordered online (an ours-only display rule: owners use "no price" for market price). */
+  marketPrice: boolean;
+  /** Non-empty exactly when price is null and not marketPrice. The cheapest is the default selection. */
+  variants: MenuItemVariant[];
+  /** Resolved https URL ("" when the item has no image). */
+  imageUrl: string;
+  /** The main image followed by the additional images, resolved (may be empty). */
+  gallery: string[];
+  labels: MenuItemLabel[];
+  modifierGroups: MenuModifierGroup[];
+  /** The item's own stock flag (orderSettings.inStock). */
+  inStock: boolean;
+  /** !inStock, OR a required group can't be satisfied from in-stock modifiers → render "Sold out". */
+  soldOut: boolean;
+  /** Can be added online: not market-priced and not sold out. Menu- and operation-level gates are on the order cart. */
+  orderable: boolean;
+  /** The kitchen accepts a free-text note on this item (orderSettings.acceptSpecialRequests). */
+  acceptsSpecialRequests: boolean;
+  featured: boolean;
+}
+
+/** A section of a menu ("Appetizers"), items already in display order. */
+export interface MenuSection {
+  id: string;
+  name: string;
+  description: string;
+  /** Resolved https URL ("" when none). */
+  imageUrl: string;
+  items: MenuItem[];
+}
+
+/** A whole menu ("Dinner"), sections already in display order. */
+export interface MenuData {
+  id: string;
+  name: string;
+  description: string;
+  /** URL fragment (urlQueryParam), e.g. "dinner". */
+  slug: string;
+  sections: MenuSection[];
+  /** The currency + locale every price on this menu was formatted with — for live price math (`itemPrice`). */
+  money: SiteMoney;
+}
+
+/**
+ * What a visitor chose on a dish before adding it: the variant (variant-priced items only), the
+ * modifier KEYS per group (MenuModifier.key — never the id), and the special request.
+ * Start from `initialSelection(item)`; change with `toggleModifier`; check with `validateSelection`.
+ */
+export interface OrderSelection {
+  variantId: string | null;
+  /** groupId → selected MenuModifier.key list. */
+  modifiers: Record<string, string[]>;
+  specialRequest: string;
+}
+
+/** The result of validating a selection: one message per group that fails its rule. */
+export interface SelectionValidation {
+  ok: boolean;
+  /** groupId → message ("Choose at least 2", …). */
+  errors: Record<string, string>;
+}
+
+/** The live price of a selection: amount and the formatted string. */
+export interface SelectionPrice {
+  amount: number;
+  formatted: string;
+}
+
+/** The online-ordering operation's state, resolved once per session. */
+export interface OrderingStatus {
+  /** The operation to order through; null when the site has none. */
+  operationId: string | null;
+  /** ENABLED accepts orders. DISABLED and PAUSED_UNTIL refuse them; NONE = no operation. */
+  status: "ENABLED" | "DISABLED" | "PAUSED_UNTIL" | "NONE";
+  /** When status is PAUSED_UNTIL: the moment ordering resumes (ISO). */
+  pausedUntilIso: string | null;
+  /** The operation's location timezone (for rendering pausedUntilIso), "" when unknown. */
+  timeZone: string;
+  /** The fulfillment methods this operation offers (ids) — fetchFulfillmentMethods is limited to them. */
+  fulfillmentIds: string[];
+  defaultFulfillmentType: "PICKUP" | "DELIVERY" | null;
+}
+
+/** One weekly availability window, wall-clock in the setting's timezone. */
+export interface WeeklyWindow {
+  day: "MON" | "TUE" | "WED" | "THU" | "FRI" | "SAT" | "SUN";
+  /** "HH:mm" (24h). An end before the start wraps past midnight. */
+  start: string;
+  end: string;
+}
+
+/**
+ * A menu's ordering settings under the resolved operation (one entry per menu). A menu with no
+ * entry, or `enabled: false`, or outside its availability, isn't orderable — show no add control.
+ */
+export interface MenuOrderingInfo {
+  menuId: string;
+  enabled: boolean;
+  availability: {
+    /** ALWAYS_AVAILABLE · WEEKLY_SCHEDULE (see `weekly`) · TIMESTAMP_RANGES (see `ranges`). */
+    type: "ALWAYS_AVAILABLE" | "WEEKLY_SCHEDULE" | "TIMESTAMP_RANGES" | "UNSPECIFIED";
+    /** IANA zone the windows are expressed in ("" → the visitor's). */
+    timeZone: string;
+    weekly: WeeklyWindow[];
+    ranges: { startIso: string; endIso: string }[];
+  };
+}
+
+/** A pickup/delivery method the operation offers (the buyer picks one on the hosted checkout). */
+export interface FulfillmentMethodInfo {
+  id: string;
+  type: "PICKUP" | "DELIVERY";
+  name: string;
+  /** Formatted fee ("" when free or the currency is unknown). */
+  fee: string;
+  feeAmount: string;
+  /** Formatted minimum order ("" when none). */
+  minOrderPrice: string;
+  minOrderPriceAmount: string;
+}
+
+export interface OrderLine {
+  /** The cart line id — what update/remove take (NOT the menu item id). */
+  lineItemId: string;
+  itemName: string;
+  quantity: number;
+  /** Per-unit price, formatted. */
+  unitPrice: string;
+  /** Line total, formatted. */
+  linePrice: string;
+  /** Resolved https URL ("" when none). */
+  imageUrl: string;
+  /** Human-readable selection labels the platform attached (variant, modifiers, special request). */
+  descriptionLines: string[];
+  /** Not IN_STOCK → the line can't be checked out as-is. */
+  status: string;
+}
+
+export interface OrderCart {
+  lines: OrderLine[];
+  /** Sum of line quantities. */
+  itemCount: number;
+  /** Formatted subtotal (after discounts) — from the cart estimate, not hand-summed. */
+  subtotal: string;
+  currency: string;
+}
+
+/** A custom question the owner added to the reservation form. */
+export interface ReservationCustomField {
+  id: string;
+  name: string;
+  required: boolean;
+}
+
+/** A policy link or text the form must show ({ url } or { text }). */
+export interface ReservationPolicy {
+  url: string;
+  text: string;
+}
+
+/** The owner's reservation form configuration — render the form from it, validate against it. */
+export interface ReservationFormConfig {
+  /** firstName and phone are ALWAYS required; these two are per configuration. */
+  lastNameRequired: boolean;
+  emailRequired: boolean;
+  /** An email-marketing consent checkbox; null when the owner disabled it. */
+  marketingCheckbox: { checkedByDefault: boolean } | null;
+  customFields: ReservationCustomField[];
+  /** Terms and conditions to show when enabled; null otherwise. */
+  terms: ReservationPolicy | null;
+  /** Privacy policy to show when enabled; null otherwise. */
+  privacy: ReservationPolicy | null;
+  /** The owner's post-submit message ("" when none). */
+  submitMessage: string;
+}
+
+/** A reservation location as the booking form needs it. */
+export interface ReservationLocationInfo {
+  id: string;
+  name: string;
+  /** Formatted address ("" when none). */
+  address: string;
+  /** IANA zone — slot search and labels are computed in it, never in the visitor's. */
+  timeZone: string;
+  default: boolean;
+  /** Bound the party-size input to [partySizeMin, partySizeMax]. */
+  partySizeMin: number;
+  partySizeMax: number;
+  /** "AUTOMATIC" confirms instantly; "MANUAL" always asks the restaurant; "MANUAL_FOR_LARGE_PARTIES" from the threshold up. */
+  approvalMode: "AUTOMATIC" | "MANUAL" | "MANUAL_FOR_LARGE_PARTIES";
+  /** Parties of this size and up need approval (MANUAL_FOR_LARGE_PARTIES); null otherwise. */
+  manualApprovalPartySizeThreshold: number | null;
+  /** False (premium-gated toggle off) → slots/booking won't work; show an honest notice. */
+  onlineReservationsEnabled: boolean;
+  form: ReservationFormConfig;
+}
+
+/** One reservation time slot. */
+export interface ReservationSlot {
+  /** ISO datetime — pass to holdSlot as-is. */
+  startIso: string;
+  /** Display label in the location's timezone, e.g. "7:00 PM". */
+  label: string;
+  /** "YYYY-MM-DD" in the location's timezone — for grouping/labeling. */
+  dayKey: string;
+  durationMinutes: number;
+  /** This slot needs staff approval → the reservation is requested (no hold), ending REQUESTED. */
+  manualApproval: boolean;
+}
+
+/** A 10-minute hold on a slot; completeReservation needs BOTH ids. */
+export interface ReservationHold {
+  reservationId: string;
+  revision: string;
+  startIso: string;
+  partySize: number;
+  /** When the hold lapses (created + 10 minutes) — drive a countdown from it. */
+  expiresAtIso: string;
+}
+
+/** The visitor's details. firstName + phone are ALWAYS required; the rest per ReservationFormConfig. */
+export interface ReservationReservee {
+  firstName: string;
+  phone: string;
+  lastName?: string;
+  email?: string;
+  /** The marketing checkbox's value; only when the form shows one. */
+  marketingConsent?: boolean;
+  /** custom field id → the visitor's answer. */
+  customFields?: Record<string, string>;
+}
+
+/** Every status the Reservations API can return. */
+export type ReservationStatus =
+  | "HELD"
+  | "RESERVED"
+  | "REQUESTED"
+  | "PAYMENT_INFORMATION_PENDING"
+  | "CANCELED"
+  | "DECLINED"
+  | "FINISHED"
+  | "NO_SHOW"
+  | "SEATED"
+  | "UNKNOWN";
+
+/** The outcome of completing or requesting a reservation. */
+export interface ReservationConfirmation {
+  reservationId: string;
+  /** The API's status, unmapped. */
+  status: ReservationStatus;
+  /** confirmed = RESERVED; pending = REQUESTED or PAYMENT_INFORMATION_PENDING; anything else = other. */
+  outcome: "confirmed" | "pending" | "other";
+}

package/skills/wix-headless-templates/restaurants/app-astro/layouts/SiteLayout.astro

@@ -0,0 +1,47 @@
+---
+// The site chrome for every restaurant 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 global.css import, and one OrderCartButton in the header + one
+// OrderCartDrawer per page (both client:only — they read browser cart state and must not
+// server-render). (If another vertical is also deployed, its SiteLayout may have won; merge
+// the Menu/Reservations nav links and the order-cart mounts there instead.)
+import OrderCartButton from "../components/restaurants/OrderCartButton";
+import OrderCartDrawer from "../components/restaurants/OrderCartDrawer";
+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="/menu" class="text-foreground no-underline transition-colors hover:text-muted-foreground">Menu</a>
+          <a href="/reservations" class="text-foreground no-underline transition-colors hover:text-muted-foreground">Reservations</a>
+          <OrderCartButton 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>
+    <OrderCartDrawer client:only="react" />
+  </body>
+</html>

package/skills/wix-headless-templates/restaurants/app-astro/pages/menu.astro

@@ -0,0 +1,22 @@
+---
+// Menu page — the full menu tree fetched SERVER-SIDE (SEO: dish names in view-source) and
+// handed to the island as DTO props. Keep this frontmatter; swap the island import to YOUR
+// menu component. The island is client:load — add-to-order needs the browser.
+import SiteLayout from "../layouts/SiteLayout.astro";
+import MenuView from "../components/restaurants/MenuView";
+import { fetchMenus } from "../wix/restaurants/menu";
+import type { MenuData } from "../wix/restaurants/types";
+
+let menus: MenuData[] = [];
+try {
+  menus = await fetchMenus();
+} catch {
+  // An unguarded SSR throw truncates the response mid-stream; the island renders the
+  // empty state instead.
+}
+---
+
+<SiteLayout title="Menu">
+  <h1 class="mb-8 text-2xl font-semibold tracking-tight">Menu</h1>
+  <MenuView client:load initialMenus={menus} />
+</SiteLayout>

package/skills/wix-headless-templates/restaurants/app-astro/pages/reservations.astro

@@ -0,0 +1,12 @@
+---
+// Reservations page. The surface is client:only — availability is timezone- and
+// party-specific, so nothing useful can server-render. Swap the island import to YOUR
+// reservation component.
+import SiteLayout from "../layouts/SiteLayout.astro";
+import ReservationView from "../components/restaurants/ReservationView";
+---
+
+<SiteLayout title="Reservations" description="Reserve a table">
+  <h1 class="mb-8 text-2xl font-semibold tracking-tight">Reserve a table</h1>
+  <ReservationView client:only="react" />
+</SiteLayout>

package/skills/wix-headless-templates/restaurants/project/README.md

@@ -0,0 +1,15 @@
+# Wix Astro Blank Template
+
+**[Live demo](https://h6s-1a31f9730cd85b-headlessstack.wix-site-host.com)**
+
+Our Astro templates are still in development and subject to change.
+
+To use a template, follow the [Wix CLI for Headless Quick Start](https://dev.wix.com/docs/go-headless/get-started/quick-starts/wix-managed-headless/quick-start-with-the-wix-cli), and select the desired template during the setup process.
+
+## Need help?
+
+For documentation and support, check out:
+
+- [Wix Headless Documentation](https://dev.wix.com/docs/go-headless)
+- [Wix SDK Documentation](https://dev.wix.com/docs/sdk)
+- [Community on Discord](https://discord.gg/n6TBrSnYTp)

package/skills/wix-headless-templates/restaurants/project/astro.config.mjs

@@ -0,0 +1,22 @@
+import tailwindcss from "@tailwindcss/vite";
+// @ts-check
+import { defineConfig } from 'astro/config';
+import wix from "@wix/astro";
+import wixPages from "@wix/astro-pages";
+
+import react from "@astrojs/react";
+import wixHostingAdapter from "@wix/astro-wix-hosting-adapter";
+
+// https://astro.build/config
+export default defineConfig({
+  vite: { plugins: [tailwindcss()] },
+  integrations: [wix(), wixPages(), react()],
+  security: { checkOrigin: false },
+  adapter: wixHostingAdapter(),
+
+  image: {
+    domains: ["static.wixstatic.com"],
+  },
+
+  output: "server",
+});