@wix/agent-skills 1.8.0 → 1.9.0

package/skills/wix-manage/references/stores/create-product-from-image.md

@@ -183,6 +183,30 @@ Examine the images for visible product attributes that should become variant opt
 - If multiple images show the **same product from different angles**, treat them as additional product media — NOT as separate variants.
 - If only one image is provided and a distinctive color is visible, suggest that single color as a choice and ask the user if the product comes in other colors.
 
+### 4h. Subscription Eligibility Detection (silent — no user interaction)
+
+Based on the product name, description, and image analysis, determine whether this product is **subscription-eligible**. A product qualifies if it is a consumable that gets depleted at a predictable rate — something customers buy repeatedly on a regular schedule.
+
+**Eligible categories (examples):**
+- Food & beverage: coffee beans/pods, tea, protein powder, meal kits
+- Supplements & health: vitamins, probiotics, protein supplements
+- Pet: pet food, flea/tick treatments, cat litter
+- Personal care: skincare routine products, razor blades/cartridges, deodorant, shampoo/conditioner
+- Household: cleaning supplies, paper towels, toilet paper, laundry detergent
+- Baby: diapers, formula, wipes
+- Media: print/digital newspapers, magazines
+- Candles (daily-use scented candles with high burn frequency)
+
+**NOT eligible (do not suggest):**
+- Furniture, art, décor (one-time purchase)
+- Electronics, tools, appliances
+- Standard clothing, apparel, shoes (not subscription-typical)
+- Jewelry, watches
+- Books (single title), games, toys
+- Any unique or collectible item
+
+Store the result internally as `subscription_eligible: true/false`. If `true`, also note a brief reason (e.g., `"coffee beans — daily consumable"`). No user interaction at this step.
+
 ---
 
 ## V3 STEP 4: Present Review Card to User (INTERACTIVE)
@@ -207,6 +231,7 @@ Present a structured review card using the markdown format below. This provides
 | Images | [count] uploaded |
 | SEO | [first 60 chars of meta description]… |
 | Tone | [Matched from existing site products / Neutral e-commerce] |
+| Subscription | [e.g. Monthly · 10% off] or [Not applicable] |
 
 **Info Sections**
 - **[Title 1]:** [one-line summary]
@@ -221,7 +246,7 @@ After the card, present the action options:
 
 > 1. **Refine** — tell me what to change (e.g., "make the description shorter", "the price should be lower")
 > 2. **Regenerate** — I'll start the analysis over, optionally with additional context from you
-> 3. **Approve** — proceed to options and product creation
+> 3. **Approve** — lock in these details and continue to the next steps
 
 If the user provided a text note that **contradicts** what's visible in the image (e.g., image shows blue but note says "available in red"), ask the user to clarify before proceeding.
 
@@ -229,6 +254,68 @@ If the user provided a text note that **contradicts** what's visible in the imag
 
 ---
 
+## V3 STEP 4.5: Suggest Subscription (INTERACTIVE, conditional)
+
+> **Run this step ONLY if `subscription_eligible: true` was set in V3 STEP 3 section 4h.** Otherwise skip directly to V3 STEP 5.
+
+Present a short, non-pushy suggestion card:
+
+---
+
+**This product looks like a great candidate for a subscription plan.**
+Customers who subscribe to *[product name]* get auto-refills on a schedule they choose — boosting repeat revenue for you.
+
+Would you like to add a subscription option?
+- **Yes** — set it up now (takes ~30 seconds)
+- **No** — create as a one-time purchase only
+
+---
+
+If the user says **No**, proceed directly to V3 STEP 5.
+
+If the user says **Yes**, ask the following 4 questions (can be presented together as a single form):
+
+**Q1 — Billing frequency**
+> "How often should subscribers be charged and receive this product?"
+
+| Choice | `frequency` | `interval` |
+|--------|------------|-----------|
+| Every week | `WEEK` | `1` |
+| Every 2 weeks | `WEEK` | `2` |
+| Every month *(Recommended)* | `MONTH` | `1` |
+| Every 2 months | `MONTH` | `2` |
+| Every 3 months | `MONTH` | `3` |
+| Every 6 months | `MONTH` | `6` |
+| Every year | `YEAR` | `1` |
+
+**Q2 — Duration**
+> "How long should the subscription run?"
+
+- **Ongoing** — renews automatically until the customer cancels (omit `billingCycles`)
+- **Fixed** — ends after N cycles (ask: "How many cycles?") → set `billingCycles: N`
+
+**Q3 — Subscriber discount (optional incentive)**
+> "Would you like to offer a discount to customers who subscribe?"
+
+- No discount (omit `discount` block)
+- **10% off** *(Recommended)* → `type: "PERCENTAGE", amount: 10`
+- Custom percentage → ask for value → `type: "PERCENTAGE", amount: [value]`
+- Fixed amount off → ask for value → `type: "AMOUNT", amount: [value]`
+
+**Q4 — Allow one-time purchase alongside subscription**
+> "Can customers also buy this product as a one-time purchase (without subscribing)?"
+
+- **Yes — sell both ways** *(Recommended)* → `allowOneTimePurchases: true`
+- No — subscription only → `allowOneTimePurchases: false`
+
+After collecting the user's answers, show a brief confirmation line before moving on:
+
+> Subscription plan configured: [e.g. Monthly · Ongoing · 10% off · One-time purchases also allowed]
+
+Store the collected subscription data for use in V3 STEP 6.
+
+---
+
 ## V3 STEP 5: Suggest Options and Ask User (INTERACTIVE)
 
 **Present the detected options from V3 STEP 4g and ask the user if they want to add product options.**
@@ -255,10 +342,74 @@ If no options were detected:
 
 ## V3 STEP 6: Create the Product
 
+Before making the API call, ask the user one final time:
+
+> Everything is ready. Shall I create the product now?
+> - **Yes, create it** — I'll submit the product to your store now.
+> - **No, go back** — return to a previous step to make changes.
+
+**Wait for confirmation.** Only proceed with the API call if the user says Yes.
+
+---
+
 **API Endpoint:** `POST https://www.wixapis.com/stores/v3/products`
 
 Build the request body with all confirmed fields. The write must be **atomic** — either all fields save or none do.
 
+**If a subscription was configured in V3 STEP 4.5**, include a `subscriptionDetails` block in the product body (see rules below). Otherwise omit it entirely.
+
+**`subscriptionDetails` rules:**
+- `title`: auto-generate from frequency (e.g. `"Monthly Subscription"`, `"Weekly Subscription"`, `"Quarterly Subscription"`)
+- `description`: if a discount was set, write a short sentence referencing it (e.g. `"Subscribe and save 10% on every order."`). Omit if no discount.
+- `visible`: always `true`
+- `frequency` + `interval`: from user's Q1 answer
+- `billingCycles`: include only for fixed-duration subscriptions (from Q2). Omit for ongoing.
+- `discount`: include only if a discount was chosen (from Q3). Omit the entire block if no discount.
+- `allowOneTimePurchases`: from user's Q4 answer
+
+**Example `subscriptionDetails` block (monthly, ongoing, 10% off, one-time also allowed):**
+
+```json
+"subscriptionDetails": {
+    "subscriptions": [
+        {
+            "title": "Monthly Subscription",
+            "description": "Subscribe and save 10% on every order.",
+            "visible": true,
+            "frequency": "MONTH",
+            "interval": 1,
+            "discount": {
+                "type": "PERCENTAGE",
+                "amount": 10
+            }
+        }
+    ],
+    "allowOneTimePurchases": true
+}
+```
+
+**Example with fixed duration and flat amount discount (every 2 months, 6 cycles, $5 off, subscription only):**
+
+```json
+"subscriptionDetails": {
+    "subscriptions": [
+        {
+            "title": "Bi-Monthly Subscription",
+            "description": "Subscribe and save $5 on every order.",
+            "visible": true,
+            "frequency": "MONTH",
+            "interval": 2,
+            "billingCycles": 6,
+            "discount": {
+                "type": "AMOUNT",
+                "amount": 5
+            }
+        }
+    ],
+    "allowOneTimePurchases": false
+}
+```
+
 ---
 
 ### Path A: Simple Product (No Options)
@@ -650,8 +801,9 @@ Before reporting success to the user, verify ALL of the following:
 - [ ] V3 STEP 2 completed: User provided 1-3 images, all uploaded to Media Manager with wixstatic.com URLs.
 - [ ] V3 STEP 3 completed: Images analyzed from user's message, all product fields generated based on what's visible in the image(s).
 - [ ] V3 STEP 4 completed: User reviewed and approved the generated details.
+- [ ] V3 STEP 4.5 completed (if applicable): Subscription eligibility was evaluated. If eligible, user was asked and their choice (Yes/No) was applied before proceeding to STEP 5.
 - [ ] V3 STEP 5 completed: User confirmed, modified, or skipped product options.
-- [ ] V3 STEP 6 completed: Product was created via API and you received a product ID.
+- [ ] V3 STEP 6 completed: User confirmed "create now", product was created via API and you received a product ID.
 
 ---
 

package/skills/wix-headless/references/astro/templates/bookings/ManageBooking.tsx

@@ -1,84 +0,0 @@
-import { useState } from "react";
-import { createClient, OAuthStrategy } from "@wix/sdk";
-import { bookings } from "@wix/bookings";
-import { WIX_CLIENT_ID } from "astro:env/client";
-
-// ManageBooking.tsx — client:only="react" island for /manage-booking.
-// The server (manage-booking.astro) already minted an anonymous action token
-// (app-elevated) and passed it in. The cancel call is a NO-AUTH anonymous method,
-// so the visitor client runs it directly with the token. Reschedule-in-place
-// needs a verified class V2Slot shape, so we offer cancel-and-rebook instead.
-
-interface Props {
-  token: string | null;
-  revision: string;
-  serviceName: string;
-  startDate: string | null;
-  status: string | null;
-  canCancel: boolean;
-  showSummary?: boolean; // false when embedded under a page that already shows the service/date
-}
-
-const wixClient = createClient({
-  modules: { bookings },
-  auth: OAuthStrategy({ clientId: WIX_CLIENT_ID }),
-});
-
-const fmt = (iso: string | null) => {
-  if (!iso) return null;
-  const d = new Date(iso);
-  return Number.isNaN(d.getTime())
-    ? null
-    : d.toLocaleString([], { weekday: "long", month: "long", day: "numeric", hour: "2-digit", minute: "2-digit" });
-};
-
-export default function ManageBooking({ token, revision, serviceName, startDate, status, canCancel, showSummary }: Props) {
-  const [state, setState] = useState<"idle" | "canceling" | "canceled" | "error">(
-    status === "CANCELED" ? "canceled" : "idle",
-  );
-  const when = fmt(startDate);
-
-  const handleCancel = async () => {
-    if (!token) return;
-    setState("canceling");
-    try {
-      await wixClient.bookings.bookingsCancelBookingAnonymously(token, revision);
-      setState("canceled");
-    } catch (err) {
-      console.error("[manage-booking] cancel failed:", err);
-      setState("error");
-    }
-  };
-
-  if (state === "canceled") {
-    return (
-      <div className="manage-booking">
-        <p className="manage-booking-status">
-          Your booking for <strong>{serviceName}</strong>{when ? <> on <strong>{when}</strong></> : null} is canceled.
-        </p>
-        <a href="/services" className="booking-submit" style={{ display: "inline-block" }}>Book another service</a>
-      </div>
-    );
-  }
-
-  return (
-    <div className="manage-booking">
-      {showSummary !== false && (
-        <p className="manage-booking-summary">
-          <strong>{serviceName}</strong>{when ? <> · {when}</> : null}
-        </p>
-      )}
-      {state === "error" && <p className="booking-error">Something went wrong canceling your booking. Please try again.</p>}
-      {canCancel ? (
-        <button type="button" className="booking-submit" onClick={handleCancel} disabled={state === "canceling"}>
-          {state === "canceling" ? "Canceling…" : "Cancel this booking"}
-        </button>
-      ) : (
-        <p className="manage-booking-note">This booking can no longer be canceled online.</p>
-      )}
-      <p className="manage-booking-note">
-        Need a different time? Cancel above, then <a href="/services" className="manage-booking-link">book another time</a>.
-      </p>
-    </div>
-  );
-}

package/skills/wix-headless/references/astro/templates/bookings/api/confirm-booking.ts

@@ -1,34 +0,0 @@
-import type { APIRoute } from "astro";
-import { auth } from "@wix/essentials";
-import { bookings } from "@wix/bookings";
-
-// POST /api/confirm-booking { bookingId, revision }
-//
-// createBooking() leaves the booking CREATED — which does NOT occupy a seat, so
-// the class/appointment stays bookable and OVERBOOKS (remainingCapacity never
-// drops). confirmBooking() promotes it to CONFIRMED (holds the seat); with
-// flowControlSettings.checkAvailabilityValidation it REJECTS the confirm if the
-// session filled up since the slot was picked — the real overbooking guard.
-// confirmBooking requires Manage Bookings, so elevate (app identity) here;
-// confirmBooking is a real SDK method, so auth.elevate(...) works directly.
-
-const json = (ok: boolean, status: number, extra: Record<string, unknown> = {}) =>
-  new Response(JSON.stringify({ ok, ...extra }), { status, headers: { "Content-Type": "application/json" } });
-
-export const POST: APIRoute = async ({ request }) => {
-  let body: any;
-  try { body = await request.json(); } catch { return json(false, 400, { error: "Invalid request body." }); }
-  const { bookingId, revision } = body ?? {};
-  if (!bookingId || !revision) return json(false, 400, { error: "Missing bookingId or revision." });
-
-  try {
-    const res = await auth.elevate(bookings.confirmBooking)(bookingId, String(revision), {
-      paymentStatus: "NOT_PAID", // pay-on-site reservation
-      flowControlSettings: { checkAvailabilityValidation: true },
-    });
-    return json(true, 200, { status: res.booking?.status });
-  } catch (err) {
-    console.error("[api/confirm-booking] failed:", err);
-    return json(false, 409, { error: "unavailable" }); // most likely: session just filled up
-  }
-};

package/skills/wix-headless/references/astro/templates/bookings/api/waitlist.ts

@@ -1,74 +0,0 @@
-import type { APIRoute } from "astro";
-import { auth, httpClient } from "@wix/essentials";
-
-// POST /api/waitlist { sessionId, totalParticipants, contactDetails:{firstName,lastName,email,phone} }
-//
-// Native Wix Bookings waitlist. There is NO v2/v3 waitlist API — createBooking
-// can't waitlist; the only join is the legacy v1 Register To Waitlist
-// (POST /bookings/v1/waitlist/register), which needs Manage Bookings + a Wix
-// contactId. So this runs server-side, elevated to app identity. CLASS only.
-//
-// `sessionId` is the v1-encoded session id (the `waitingResource`); the browser
-// gets it from the SESSION_CAPACITY_EXCEEDED error createBooking returns for a
-// full session ("…on session <id>").
-//
-// IMPORTANT: auth.elevate() only grants permissions for a real SDK function. The
-// waitlist + Contacts calls are raw REST (no SDK wrapper), so elevate the
-// authenticated fetch ITSELF — NOT a closure that calls it (a closure runs
-// un-elevated/visitor and 403s).
-
-const json = (ok: boolean, status: number, extra: Record<string, unknown> = {}) =>
-  new Response(JSON.stringify({ ok, ...extra }), { status, headers: { "Content-Type": "application/json" } });
-
-export const POST: APIRoute = async ({ request }) => {
-  let body: any;
-  try { body = await request.json(); } catch { return json(false, 400, { error: "Invalid request body." }); }
-  const { sessionId, totalParticipants = 1, contactDetails } = body ?? {};
-  const email: string | undefined = contactDetails?.email;
-  if (!sessionId || !email) return json(false, 400, { error: "Missing sessionId or email." });
-
-  const ef = auth.elevate(httpClient.fetchWithAuth as typeof fetch) as typeof fetch;
-  const api = (url: string, payload: unknown) =>
-    ef(url, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(payload) });
-
-  try {
-    // 1. Resolve a contactId (reuse by email; create if absent).
-    let contactId: string | undefined;
-    const q = await api("https://www.wixapis.com/contacts/v4/contacts/query", {
-      query: { filter: { "info.emails.email": email } },
-    });
-    contactId = ((await q.json().catch(() => ({}))) as any).contacts?.[0]?.id;
-    if (!contactId) {
-      const c = await api("https://www.wixapis.com/contacts/v4/contacts", {
-        info: {
-          name: { first: contactDetails.firstName, last: contactDetails.lastName || undefined },
-          emails: { items: [{ email, primary: true }] },
-          ...(contactDetails.phone ? { phones: { items: [{ phone: contactDetails.phone, primary: true }] } } : {}),
-        },
-      });
-      contactId = ((await c.json().catch(() => ({}))) as any).contact?.id;
-    }
-    if (!contactId) throw new Error("could not resolve contactId");
-
-    // 2. Register on the native waitlist.
-    const reg = await api("https://www.wixapis.com/bookings/v1/waitlist/register", {
-      waitingResource: sessionId,
-      formInfo: {
-        paymentSelection: [{ rateLabel: "general", numberOfParticipants: totalParticipants }],
-        contactDetails: {
-          contactId,
-          firstName: contactDetails.firstName,
-          lastName: contactDetails.lastName || undefined,
-          email,
-          phone: contactDetails.phone || undefined,
-        },
-      },
-    });
-    const rj: any = await reg.json().catch(() => ({}));
-    if (!reg.ok || !rj.registrationId) throw new Error(`register ${reg.status}: ${JSON.stringify(rj).slice(0, 200)}`);
-    return json(true, 200, { registrationId: rj.registrationId });
-  } catch (err) {
-    console.error("[api/waitlist] failed:", err);
-    return json(false, 502, { error: "Waitlist registration failed." });
-  }
-};

package/skills/wix-headless/references/astro/templates/bookings/manage-booking.astro

@@ -1,76 +0,0 @@
----
-// src/pages/manage-booking.astro — per-booking manage page (view + cancel).
-// Reached from the confirmation page or a shared manage link:
-//   /manage-booking?bookingId=<id>&service=<name>
-//
-// A visitor token can't list/cancel bookings (queryExtendedBookings/cancelBooking
-// are APP/MEMBER identity). The supported visitor path is the ANONYMOUS ACTION
-// TOKEN: the server elevates (app identity) to mint a per-booking token, then the
-// no-auth bookingsGet/CancelBookingAnonymously methods act on it. Minting MUST be
-// server-side; the token is then safe to hand to the browser island.
-import Layout from "../layouts/Layout.astro";
-import ManageBooking from "../components/ManageBooking";
-import { auth } from "@wix/essentials";
-import { bookings } from "@wix/bookings";
-
-const bookingId = Astro.url.searchParams.get("bookingId");
-
-let token: string | null = null;
-let booking: any = null;
-let allowed = { cancel: false, reschedule: false };
-let error: string | null = null;
-
-if (!bookingId) {
-  error = "No booking was specified.";
-} else {
-  try {
-    const tokenRes = await auth.elevate(bookings.getAnonymousActionToken)(bookingId); // APP identity → elevate
-    token = tokenRes.token ?? null;
-    if (token) {
-      const res = await bookings.bookingsGetBookingAnonymously(token); // no auth
-      booking = res.booking ?? null;
-      allowed = {
-        cancel: !!res.allowedAnonymousActions?.cancel,
-        reschedule: !!res.allowedAnonymousActions?.reschedule,
-      };
-    }
-  } catch (err) {
-    console.error("[manage-booking] load failed:", err);
-    error = "We couldn't load this booking — the link may have expired.";
-  }
-}
-
-const serviceName =
-  booking?.bookedEntity?.title ?? Astro.url.searchParams.get("service") ?? "your booking";
-const startDate =
-  (booking?.startDate as string | undefined) ??
-  booking?.bookedEntity?.slot?.startDate ??
-  Astro.url.searchParams.get("startDate") ??
-  null;
-const status = (booking?.status as string | undefined) ?? null;
-const revision = (booking?.revision as string | undefined) ?? "";
----
-
-<Layout title="Manage your booking">
-  <section class="container-reading px-lg py-4xl">
-    <a href="/services" class="inline-block text-sm text-mute hover:text-ink mb-xl">← All services</a>
-    <hr class="editorial-rule w-16 ml-0" />
-    <h1 class="font-display text-4xl md:text-5xl leading-tight mb-xl">Manage your booking</h1>
-
-    {
-      error ? (
-        <p class="booking-error">{error}</p>
-      ) : (
-        <ManageBooking
-          token={token}
-          revision={revision}
-          serviceName={serviceName}
-          startDate={startDate}
-          status={status}
-          canCancel={allowed.cancel}
-          client:only="react"
-        />
-      )
-    }
-  </section>
-</Layout>