@wix/agent-skills 1.17.0 → 1.18.1

package/skills/wix-vibe-headless/platforms/base44.md

@@ -8,45 +8,35 @@ only), safe in the frontend; use it directly for the Wix client setup.
 
 > **The Wix skills installed below are the complete build and seed path for this app — the Wix connector supplies the token for admin API calls.** **Do NOT use the Base44 commerce kit (or any Base44 solution kit).**
 
-Follow STEPs 1–5 below exactly (run STEP 4 in parallel with STEP 3).
+Follow STEPs 1–5 below exactly (run STEP 4 in parallel with STEP 3 — **except `forms`**, see STEP 3).
 
 ## STEP 1 — Install the Wix skills locally
 
-Install three skills — they land under `.agents/skills/`:
-- **`wix-vibe-headless`** — the client build **and** seed guide (STEPs 3–4): your main source of
-  truth. Seeding lives here too, per-vertical under `references/<vertical>/seed/`.
-- **`wix-manage`** — REST recipes for managing and configuring the site (install apps, seed
-  catalogs, business setup).
-- **`wix-base44-connector`** — building on Wix from the Base44 sandbox: site context, API
-  contracts, and the docs **fallback** — find + read the Wix API docs for anything
-  `wix-vibe-headless` doesn't cover.
+Install three skills under `.agents/skills/`: **`wix-vibe-headless`** (the client build + seed guide — your main source of truth), **`wix-manage`** (REST recipes to manage/configure the site), and **`wix-base44-connector`** (site context + API-doc discovery, the fallback for anything the others don't cover).
 
 Run this through exec_tool, exactly as written — installs all three skills, deploys REST scaffolds + UI into `src/`, writes `wix-config.js`, and pins the AGENTS.md note.
 
-**Set `VERTICALS`** to what the prompt asks for (too vague to tell? do STEP 2 first, then set it):
+**Set `VERTICALS`** to what the prompt asks for — **list every vertical the app uses**, since several often join the main one (too vague to tell? do STEP 2 first, then set it). Adding one later: re-run with the extra name.
 
 | vertical | pick it when the app needs to |
 |---|---|
 | `storefront` | sell products |
 | `bookings` | take appointments or service bookings |
+| `rentals` | rent out an item for a length the customer picks (by the hour or by the day) |
 | `blog` | publish articles |
 | `events` | publish events with RSVPs or ticket sales |
 | `portfolio` | showcase creative work |
-| `pricing-plans` | sell memberships or subscriptions |
+| `pricing-plans` | sell memberships or subscriptions, incl. paid enrollment/access to an online course or program — but an "online store selling courses" is still `storefront` |
 | `restaurants` | show a menu, take orders, book tables |
 | `members` | let visitors sign in — this is **auth** |
-| `cms` | keep its own structured content — user submissions, galleries, listings, anything the rows above don't already cover |
-
-**List every vertical the app uses.** `cms` for app-stored content, `members` for visitor sign-in — these often join the main vertical. Adding one later: re-run with the extra name.
+| `forms` | any visitor-fillable form: contact, signup, waitlist, application, survey, quote request (an event RSVP is `events`; a per-service booking form is `bookings`) |
+| `cms` | structured content the app reads back — galleries, listings, "my submissions" (a visitor-fillable form is `forms`) |
 
 ```js
 const { execSync } = require('child_process');
 const { existsSync, readdirSync } = require('fs');
-const VERTICALS = ['storefront'];        // ← set from the prompt; list every vertical the app uses
-// const VERTICALS = ['members', 'cms']; // ← e.g. visitors sign in AND the app stores what they submit
-// COPY these two straight from the prompt — deploy writes them into src/rest/wix-config.js, so never
-// retype either one into a file by hand afterwards.
-const WIX_CLIENT_ID = '<client id from the prompt>';
+const VERTICALS = ['storefront'];         // ← set from the prompt; list every vertical the app uses (e.g. ['members','cms'])
+const WIX_CLIENT_ID = '<client id from the prompt>';   // copy both from the prompt — deploy writes them into src/rest/wix-config.js
 const WIX_METASITE_ID = '<site id from the prompt>';
 const results = {};
 for (const skill of ['wix-vibe-headless', 'wix-manage', 'wix-base44-connector']) {
@@ -93,63 +83,39 @@ truth for how the client is built.
 
 **REST scaffolds + `wix-config.js` are already in `src/rest/`** (STEP 1 wrote them). Some verticals also ship a ready UI client in `src/` — theme + wire it per `INSTRUCTIONS.md`, don't rebuild. **Don't `read_file` deployed files** — every field shape is in `INSTRUCTIONS.md`; read one only on a real error or gap.
 
+**⚠️ `forms` is the ONE vertical that does NOT run in parallel with STEP 4** — its UI is gated on a
+file the seed writes. Read its `INSTRUCTIONS.md` **Prerequisites** before building any form UI; seed
+it first (STEP 4) and build the rest of the app meanwhile.
+
 **`src/App.jsx`: edit surgically, never rewrite.** It carries required platform auth scaffolding
 (`AuthProvider`/`useAuth` from `@/lib/AuthContext`); a full rewrite drops them → the validator
 rejects the write. Wire routes/imports in with `find_replace`, leave the rest as-is.
 
 ## STEP 4 — Manage and seed the business
 
-**Never delete or clean up anything on the user's site — seeding is additive only.** It's a live
-user-owned business, so never delete or overwrite existing content, even apparent sample data. If a
-cleanup truly seems needed, ask the user first.
-
 Seed by calling your vertical's ready-made seed module — read
-`.agents/skills/wix-vibe-headless/references/<vertical>/seed/SEED.md` and load its `seed-*.js` via
-its loader snippet (build-time exec_tool); call its functions with your data. Gaps or an unexpected
-shape → the **`wix-base44-connector`** skill's doc discovery.
-
-**Auth for these admin calls is the already-configured Wix connector — nothing else.** Get its
-access token and send it as a bearer token:
+`.agents/skills/wix-vibe-headless/references/<vertical>/seed/SEED.md` and follow it (the loader
+snippet, admin connector token, entity images with the final `media.base44.com` url, and every field
+shape are there). Gaps or an unexpected shape → the **`wix-base44-connector`** skill's doc discovery.
+Seeding is **admin-only** — not part of the client, which is built solely per the `wix-vibe-headless` skill.
 
-```js
-const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix");
-// then: fetch(url, { headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json" }, ... })
-```
-
-Inline via exec_tool, `base44` is already declared — use it directly; do **not** import
-`@base44/sdk`, re-declare it, or call `createClient()` (that's for standalone `.js` files only;
-inline it throws *"Identifier 'base44' has already been declared."*).
-
-**Entity images.** For image-bearing entities (store products, blog covers, bookings services,
-restaurant items, portfolio projects, event heroes, CMS items), generate with **Base44's built-in
-image generation**, then attach via the vertical seed module's image-attach step —
-`wix-base44-connector` doc discovery if the module doesn't cover that entity.
-
-**Seed images with the FINAL url, in one call.** Seeding writes to Wix, so use the real
-`https://media.base44.com/...` url from the **completed** `generate_image` result and pass it straight
-into your single `setupStore`/seed call (images included). A still-generating `/__generating__/<id>.png`
-placeholder is not a real url — Wix can't fetch it. `generate_image` runs in the background while you
-build the client, so the urls are ready by the time you seed.
-
-The connector + seeding are **admin-only** (STEP 4) — **not** part of the client, which is built
-solely per the `wix-vibe-headless` skill.
+- **Additive only:** never delete or overwrite the user's content, even apparent sample data; ask first if a cleanup truly seems needed.
+- Inline in exec_tool, `base44` is already declared — use it directly; do **not** `import @base44/sdk`, re-declare it, or call `createClient()` (throws *"Identifier 'base44' has already been declared."*).
 
 ## STEP 5 — Wrap up
 
-Once the site is built and seeded:
-
-1. **Mount the preview-only manage banner** (required; links the app to its Wix back office; shipped,
-   self-gates to the preview, never on the published site): render the `<WixManageBanner/>` component
-   in your Layout's fixed top region, above the header, per your vertical's INSTRUCTIONS STEP 4.
-2. **Ask the user to open** `https://manage.wix.com/dashboard/{metaSiteId}` (substitute your
-   metasite id) to complete setup in Wix (required), and mention that the preview shows a dismissible
-   top banner linking to this same dashboard.
+1. **Mount `<WixManageBanner/>`** (required) in your Layout's fixed top region, above the header, per your vertical's INSTRUCTIONS — it links the app to its Wix back office, self-gates to the preview, and never shows on the published site.
+2. **Ask the user to open** `https://manage.wix.com/dashboard/{metaSiteId}` (your metasite id) to complete setup in Wix.
 
-**Preview briefly, don't chase images.** Broken images are expected — `generate_image` returns a `/__generating__/…` placeholder that the platform swaps for the final url automatically at turn end (failures get a stock fallback). **Do NOT edit, re-seed, or debug image urls.** Leave them and finish.
+**Don't chase images.** A `/__generating__/…` placeholder is swapped for the final url automatically at turn end — do **not** edit, re-seed, or debug image urls.
 
 ## Later admin requests
 
 For any later admin/management request, work as in STEP 4: your vertical's seed module first, else
 `wix-base44-connector` doc discovery — all over the connector.
 
-version: v1338
+**A change to what the business data COLLECTS is one of these, however UI it sounds** — a new form
+field, product option or service setting. Change it on Wix first per the vertical's `seed/SEED.md`,
+then edit the client against the verified result.
+
+version: v1341

package/skills/wix-vibe-headless/platforms/generic.md

@@ -27,7 +27,7 @@ Everything is under `.agents/skills/wix-vibe-headless/references/`.
 - `INSTRUCTIONS.md` — the vertical's build guide + field-shape snippets; `seed/SEED.md` — how the seed
   module is run.
 
-**The nine verticals — data layer (`app/rest/`) + seed module (`seed/`):**
+**The verticals — data layer (`app/rest/`) + seed module (`seed/`):**
 
 | vertical | `app/rest/` data layer | seed module |
 |---|---|---|
@@ -37,7 +37,8 @@ Everything is under `.agents/skills/wix-vibe-headless/references/`.
 | events | `wix-events-browse.js`, `wix-events-registration.js` — events & categories; RSVP / ticketing + checkout | `seed-events.js` |
 | portfolio | `wix-portfolio.js` — collections, projects, galleries | `seed-portfolio.js` |
 | restaurants | `wix-restaurants-menu.js`, `-ordering.js`, `-reservations.js` — menu; online ordering; table reservations | `seed-restaurants.js` |
-| cms | `wix-cms.js` — Wix Data collections: list / detail / filter + form CRUD | `seed-cms.js` |
+| forms | `wix-forms.js`, `wix-forms-submissions.js` — any visitor-fillable form: read the schema; upload attachments, create a submission (schema accessors ship alongside in `lib/wix-form-schema-utils.js`) | *(none — REST shapes in `seed/SEED.md`)* |
+| cms | `wix-cms.js` — Wix Data collections: list / detail / filter | `seed-cms.js` |
 | pricing-plans | `wix-pricing-plans.js` — plans list + subscribe/checkout | `seed-pricing-plans.js` |
 | members | `wix-members-auth.js` — custom login/signup (email+password, social, SSO), session, account | *(none — members sign up at runtime; nothing to seed)* |
 
@@ -49,7 +50,9 @@ the token set) is **universal — follow it as-is**.
 
 ## The flow — install → build client → seed → done
 
-Run **build the client** (step 2) and **seed** (step 3) in parallel; parallelize independent work within each.
+Run **build the client** (step 2) and **seed** (step 3) in parallel; parallelize independent work
+within each. **One exception — `forms` must be seeded before its UI is built; read that gate in
+`references/forms/INSTRUCTIONS.md` (Prerequisites) first.** Everything else still parallelizes.
 
 ### 1 · Install the skills
 

package/skills/wix-vibe-headless/references/bookings/INSTRUCTIONS.md

@@ -225,6 +225,49 @@ the areas they sit in:
 - eCommerce checkout (paid bookings): https://dev.wix.com/docs/api-reference/business-solutions/e-commerce.md
 - Headless redirect session (hosted checkout): https://dev.wix.com/docs/api-reference/business-management/headless/redirects.md
 
+## Rentals — the same client, one extra step
+
+**Wix Rentals has no APIs of its own.** A rental is a Bookings *service* with rentals-specific
+field values, so this whole client works on it: the catalog read, the booking form, and the
+`createBooking → cart → checkout` chain are all unchanged. `rest/wix-bookings-rentals.js` and
+`hooks/useRentalDuration.js` carry the only differences.
+
+**What tells a rental apart — the DATA, never the brief.** A service carries either a fixed
+session length or a duration RANGE the customer picks within; the two are mutually exclusive:
+
+```js
+import { isRental, rentalDuration, rentalRateLabel } from "@/rest/wix-bookings-rentals";
+isRental(service)   // true only when schedule.availabilityConstraints.durationRange is present
+```
+
+A 60-minute yoga class and a 60-minute massage are **not** rentals even though a massage is
+`type: "APPOINTMENT"` exactly like a rental is. Never branch on the service's name, its
+category, or what the brief called it.
+
+**The extra step.** An ordinary service is one choice (a slot). A rental is two: pick a START,
+then pick HOW LONG — and the price follows the length.
+
+```jsx
+const detail = useServiceDetail(serviceId);                        // service + start times
+const rental = useRentalDuration(detail.service, detail.selectedSlot, detail.timeZone);
+
+<SlotPicker … />                                                   {/* pick a start, as ever */}
+{rental.isRental && <RentalDurationPicker rental={rental} />}      {/* then pick a length */}
+```
+
+Book with `rental.endDate` as the slot's `localEndDate`; everything else in the booking call is
+identical.
+
+**Hard rules on top of the ones below:**
+
+- **Filter every catalog read by `appId`.** `queryRentals()` does it. On a site with both apps
+  an unfiltered `queryServices` returns haircuts next to meeting rooms.
+- **Never compute the total yourself.** A rental is charged as a rate, hourly at per-minute
+  granularity — 90 minutes of a $10/hour room is $15. `useRentalDuration` prices the chosen
+  length on the server; multiplying the displayed rate disagrees with checkout.
+- **Show the total before the customer commits.** A rate alone is not a price.
+- **One unit type per service.** A room rented by the hour *and* by the day is two services.
+
 ## Hard rules
 - Style via base44 design tokens (`index.css` / shadcn Tailwind classes), never by rewriting the shipped components or adding a parallel theme file.
 - Header/footer live in a `Layout` around `<Outlet/>` (STEP 3) — never edit the shipped

package/skills/wix-vibe-headless/references/bookings/app/components/RentalDurationPicker.jsx

@@ -0,0 +1,67 @@
+// Rental length picker — pure UI. The options, the selection handler and the priced total all
+// come from useRentalDuration; no data wiring lives here.
+//
+// Renders the step an ordinary service doesn't have: the customer has already picked a START
+// (SlotPicker), and now picks HOW LONG. The running total sits beside the choices because a
+// rental's cost depends on the length — showing only a rate per hour leaves the customer
+// discovering the real number at checkout.
+//
+// Show this only when `rental.isRental` — an appointment or class has no length to choose.
+// Styled with base44 design tokens (shadcn Tailwind classes).
+const optionCls = "py-2.5 px-3 cursor-pointer text-sm font-body border rounded-sm transition-colors";
+const idle = "border-border bg-card text-foreground hover:border-foreground/40";
+const active = "border-primary bg-primary text-primary-foreground";
+
+/**
+ * @param {{
+ *   rental: object,        // the whole return of useRentalDuration
+ *   startLabel?: string,   // e.g. "Fri 4 Sep, 10:00" — what the customer already picked
+ * }} props
+ */
+export default function RentalDurationPicker({ rental, startLabel }) {
+  const { isRental, duration, options, selected, select, price, loading, error } = rental;
+  if (!isRental) return null;
+
+  const unitWord = duration?.unit === "DAY" ? "days" : "hours";
+
+  return (
+    <div className="mb-6">
+      <div className="mb-2 flex items-baseline justify-between gap-3">
+        <p className="text-xs font-semibold uppercase tracking-wider text-muted-foreground">
+          How long{startLabel ? ` from ${startLabel}` : ""}
+        </p>
+        {price?.total ? (
+          <p className="text-sm font-semibold text-foreground">{price.total}</p>
+        ) : selected ? (
+          <p className="text-sm text-muted-foreground">Pricing…</p>
+        ) : null}
+      </div>
+
+      {loading ? (
+        <p className="text-sm text-muted-foreground">Loading available {unitWord}…</p>
+      ) : error ? (
+        <p className="text-sm text-destructive">{error}</p>
+      ) : !options.length ? (
+        // An empty list is a real answer: this start has no bookable length. Say so, and leave
+        // the start picker in place so the customer can choose another one.
+        <p className="text-sm text-muted-foreground">
+          Nothing available from that start — pick another time.
+        </p>
+      ) : (
+        <div className="grid grid-cols-3 gap-2 sm:grid-cols-4">
+          {options.map((option) => (
+            <button
+              key={option.localEndDate}
+              type="button"
+              aria-pressed={selected?.localEndDate === option.localEndDate}
+              className={`${optionCls} ${selected?.localEndDate === option.localEndDate ? active : idle}`}
+              onClick={() => select(option)}
+            >
+              {option.label}
+            </button>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

package/skills/wix-vibe-headless/references/bookings/app/hooks/useRentalDuration.js

@@ -0,0 +1,128 @@
+// useRentalDuration — the extra step a rental has and an ordinary service doesn't: once the
+// customer has picked a START, they pick how LONG, and the price follows the length.
+//
+// Compose it with useServiceDetail rather than replacing it. That hook already loads the
+// service, lists start times, holds the contact fields and runs bookAndCheckout — all of which
+// a rental uses unchanged. This adds only the second choice and its price:
+//
+//   const detail = useServiceDetail(serviceId);                       // service + start slots
+//   const rental = useRentalDuration(detail.service, detail.selectedSlot, detail.timeZone);
+//   // render detail.slots → customer picks a start → render rental.options → picks a length
+//   // book with rental.endDate as the slot's localEndDate
+//
+// Returns empty options for a non-rental service, so a page that renders both kinds needs no
+// branch of its own — `isRental(service)` decides whether to show the length step at all.
+import { useCallback, useEffect, useState } from "react";
+import {
+  dailyEndOptions,
+  isRental,
+  listEndOptions,
+  previewRentalPrice,
+  rentalDuration,
+} from "@/rest/wix-bookings-rentals";
+
+/** "1 hr 30 min" / "2 days" — the label for one length option. */
+function lengthLabel(startLocal, endLocal, unit) {
+  if (unit === "DAY") {
+    const days = Math.round((new Date(`${endLocal}Z`) - new Date(`${startLocal}Z`)) / 86400000);
+    return days === 1 ? "1 day" : `${days} days`;
+  }
+  const minutes = Math.round((new Date(`${endLocal}Z`) - new Date(`${startLocal}Z`)) / 60000);
+  const h = Math.floor(minutes / 60);
+  const m = minutes % 60;
+  return [h ? `${h} hr` : "", m ? `${m} min` : ""].filter(Boolean).join(" ") || "0 min";
+}
+
+/**
+ * @param {object|null} service   The service from useServiceDetail — may be null while loading.
+ * @param {object|null} startSlot The slot the customer picked (its localStartDate is the start).
+ * @param {string|null} timeZone  The zone the slot list came back in.
+ * @returns {{
+ *   isRental: boolean,
+ *   duration: { unit: "HOUR"|"DAY", min: number, max: number, step: number }|null,
+ *   options: { localEndDate: string, label: string }[],
+ *   selected: object|null,
+ *   select: (option: object) => void,
+ *   endDate: string|null,   // pass as the booking's localEndDate
+ *   price: { total: string, currency: string|null }|null,
+ *   loading: boolean,
+ *   error: string|null,
+ * }}
+ */
+export function useRentalDuration(service, startSlot, timeZone) {
+  const [options, setOptions] = useState([]);
+  const [selected, setSelected] = useState(null);
+  const [price, setPrice] = useState(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState(null);
+
+  const rental = isRental(service);
+  const duration = rentalDuration(service);
+  const start = startSlot?.localStartDate ?? null;
+  // Forward the chosen slot's own location to end-options.
+  const location = startSlot?.location ?? null;
+  const serviceId = service?._id || service?.id || null;
+
+  // A new start invalidates the lengths that were valid for the previous one.
+  useEffect(() => {
+    setSelected(null);
+    setPrice(null);
+    if (!rental || !start || !serviceId) {
+      setOptions([]);
+      return;
+    }
+    let alive = true;
+    setLoading(true);
+    setError(null);
+    const load = duration.unit === "DAY"
+      ? dailyEndOptions(service, { localStartDate: start, timeZone })
+          .then((list) => list.map((o) => ({ localEndDate: o.localEndDate, label: lengthLabel(start, o.localEndDate, "DAY") })))
+      : listEndOptions(serviceId, { localStartDate: start, location, timeZone })
+          .then(({ endOptions }) =>
+            endOptions.map((o) => ({ localEndDate: o.localEndDate, label: lengthLabel(start, o.localEndDate, "HOUR") })),
+          );
+    load
+      .then((list) => {
+        if (!alive) return;
+        setOptions(list);
+        setLoading(false);
+      })
+      .catch((e) => {
+        if (!alive) return;
+        // Fail loudly — an empty length list and a failed call look identical on screen
+        // otherwise, and the second one is a bug the visitor should not absorb silently.
+        setError(e?.message || "Could not load available lengths.");
+        setOptions([]);
+        setLoading(false);
+      });
+    return () => {
+      alive = false;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [rental, serviceId, start, timeZone, duration?.unit]);
+
+  // The price comes from the server for the chosen length — never multiply the rate locally.
+  const select = useCallback(
+    (option) => {
+      setSelected(option);
+      setPrice(null);
+      if (!option || !serviceId || !start || !timeZone) return;
+      previewRentalPrice(serviceId, { localStartDate: start, localEndDate: option.localEndDate, timeZone })
+        .then((p) => setPrice({ total: p.total, currency: p.currency }))
+        .catch((e) => setError(e?.message || "Could not price that length."));
+    },
+    [serviceId, start, timeZone],
+  );
+
+  return {
+    isRental: rental,
+    duration,
+    options,
+    selected,
+    select,
+    endDate: selected?.localEndDate ?? null,
+    price,
+    loading,
+    error,
+  };
+}

package/skills/wix-vibe-headless/references/bookings/app/hooks/useServiceDetail.js

@@ -31,8 +31,9 @@ export function useServiceDetail(serviceId) {
   const [error, setError] = useState(null);
 
   useEffect(() => {
-    // getService returns null on a miss — show not-found, never invent a service.
-    getService(serviceId).then((s) => (s ? setService(s) : setNotFound(true)));
+    // getService returns null on a miss — show not-found, never invent a service. A rejected
+    // request (network, 4xx) must also resolve the page to not-found, never leave it loading forever.
+    getService(serviceId).then((s) => (s ? setService(s) : setNotFound(true))).catch(() => setNotFound(true));
   }, [serviceId]);
 
   useEffect(() => {
@@ -41,7 +42,8 @@ export function useServiceDetail(serviceId) {
     // returns { slots, nextCursor }. The LIST call takes fromLocalDate / toLocalDate — a different
     // arg naming than the single-slot re-validate call (getAvailableSlot: localStartDate/localEndDate).
     listSlotsForService(service, { fromLocalDate: localMidnight(0), toLocalDate: localMidnight(14) })
-      .then(({ slots, nextCursor, timeZone }) => { setSlots(slots); setCursor(nextCursor); setTimeZone(timeZone); });
+      .then(({ slots, nextCursor, timeZone }) => { setSlots(slots); setCursor(nextCursor); setTimeZone(timeZone); })
+      .catch(() => setSlots([]));
   }, [service]);
 
   const loadMoreSlots = useCallback(() => {