@wix/agent-skills 1.19.2 → 1.20.1

package/skills/wix-headless-fast/references/pricing-plans/app/components/pricing-plans/SubscribeButton.tsx

@@ -0,0 +1,41 @@
+// The purchase control for one plan — wire as-is on every card, detail page, and home strip.
+// It owns the rules a CTA gets wrong when rewritten: rendered only for a `buyable` plan (a PUBLIC
+// plan can be merchant-assigned — `assignedText` shows instead, or nothing when null), the label
+// from the DTO ("Get this plan" for a free plan, "Subscribe" otherwise, your children override it),
+// "Redirecting…" while the hosted checkout is starting, the failure inline. The redirect itself is
+// usePlanPurchase → purchasePlan; nothing here builds a URL or marks anything paid.
+import type { ReactNode } from "react";
+import { usePlanPurchase } from "../../hooks/pricing-plans/usePlanPurchase";
+import type { PurchaseOptions } from "../../wix/pricing-plans/purchase";
+import type { PlanSummary } from "../../wix/pricing-plans/types";
+
+export interface SubscribeButtonProps {
+  plan: PlanSummary;
+  /** thankYouPageUrl / postFlowUrl for the hosted flow — see purchase.ts; omit for the defaults. */
+  options?: PurchaseOptions;
+  /** Replaces the default label ("Get this plan" / "Subscribe"). */
+  children?: ReactNode;
+  className?: string;
+  /** Shown for a plan that isn't buyable; null renders nothing (a grid card). */
+  assignedText?: string | null;
+}
+
+export default function SubscribeButton({
+  plan,
+  options,
+  children,
+  className = "rounded-full bg-primary px-6 py-2.5 text-sm font-semibold text-primary-foreground transition-opacity hover:opacity-90 disabled:opacity-50",
+  assignedText = "This plan is assigned by the site owner.",
+}: SubscribeButtonProps) {
+  const { purchase, purchasingId, error } = usePlanPurchase();
+  if (!plan.buyable) return assignedText ? <p className="text-sm text-muted-foreground">{assignedText}</p> : null;
+  const purchasing = purchasingId === plan.id;
+  return (
+    <div className="grid gap-2">
+      <button type="button" disabled={purchasing} onClick={() => void purchase(plan.id, options).catch(() => {})} className={className}>
+        {purchasing ? "Redirecting…" : children ?? (plan.free ? "Get this plan" : "Subscribe")}
+      </button>
+      {error && <p className="text-sm text-red-600" role="alert">{error}</p>}
+    </div>
+  );
+}

package/skills/wix-headless-fast/references/pricing-plans/app/hooks/pricing-plans/usePlanPurchase.ts

@@ -1,37 +1,16 @@
-// The purchase action for any surface (grid card, detail CTA, home strip). All correctness
-// (the hosted redirect session, member login/signup, payment) lives in the data layer —
-// this hook tracks in-flight state; you own how it looks.
-import { useState } from "react";
-import { purchasePlan } from "../../wix/pricing-plans/purchase";
-import type { PurchaseOptions } from "../../wix/pricing-plans/purchase";
+// React binding of the purchase store (wix/pricing-plans/plan-purchase-store.ts) — the purchase
+// action for any surface (grid card, detail CTA, home strip). All correctness (the hosted redirect
+// session, member login/signup, payment) lives in the data layer; the store tracks in-flight state;
+// you own how it looks.
+import { useRef, useSyncExternalStore } from "react";
+import { createPlanPurchaseStore, type PlanPurchaseState, type PlanPurchaseStore } from "../../wix/pricing-plans/plan-purchase-store";
 
-export interface UsePlanPurchase {
-  /**
-   * Starts the hosted checkout — when it resolves the browser is already navigating away.
-   * Rejects with a visitor-facing message otherwise — surface it, don't swallow it.
-   */
-  purchase: (planId: string, options?: PurchaseOptions) => Promise<void>;
-  /** The plan id a purchase is in flight for (null when idle) — key CTA spinners off it. */
-  purchasingId: string | null;
-  error: string | null;
-}
+export type UsePlanPurchase = PlanPurchaseState & Pick<PlanPurchaseStore, "purchase">;
 
 export function usePlanPurchase(): UsePlanPurchase {
-  const [purchasingId, setPurchasingId] = useState<string | null>(null);
-  const [error, setError] = useState<string | null>(null);
-
-  async function purchase(planId: string, options?: PurchaseOptions): Promise<void> {
-    setPurchasingId(planId);
-    setError(null);
-    try {
-      window.location.href = await purchasePlan(planId, options);
-      // stays "purchasing" — the browser is leaving for the hosted checkout
-    } catch (e) {
-      setPurchasingId(null);
-      setError(e instanceof Error ? e.message : String(e));
-      throw e;
-    }
-  }
-
-  return { purchase, purchasingId, error };
+  const ref = useRef<PlanPurchaseStore | null>(null);
+  if (!ref.current) ref.current = createPlanPurchaseStore();
+  const store = ref.current;
+  const state = useSyncExternalStore(store.subscribe, store.getState, store.getState);
+  return { ...state, purchase: store.purchase };
 }

package/skills/wix-headless-fast/references/pricing-plans/app/hooks/pricing-plans/usePlans.ts

@@ -1,39 +1,22 @@
-// Plans listing. SSR-friendly: pass server-fetched data as `initialPlans` (Astro frontmatter
-// / server component) and no client fetch happens; a SPA passes nothing.
-import { useEffect, useState } from "react";
-import { fetchPlans } from "../../wix/pricing-plans/plans";
-import type { PlanSummary } from "../../wix/pricing-plans/types";
+// React binding of the plans store (wix/pricing-plans/plans-store.ts) — the listing logic lives
+// there, framework-free; this hook subscribes to one instance per mounted listing. SSR-friendly:
+// pass server-fetched data as `initialPlans` (Astro frontmatter / server component) and no client
+// fetch happens; a SPA passes nothing. Astro islands and React SPAs use this; a static page, Vue,
+// or Svelte uses the store directly.
+import { useEffect, useRef, useSyncExternalStore } from "react";
+import { createPlansStore, type PlansState, type PlansStore, type PlansStoreOptions } from "../../wix/pricing-plans/plans-store";
 
-export interface UsePlansOptions {
-  initialPlans?: PlanSummary[];
-}
-
-export interface UsePlans {
-  /** null while the first load is in flight — render skeletons, not an empty state. */
-  plans: PlanSummary[] | null;
-  error: string | null;
-}
+export type UsePlansOptions = PlansStoreOptions;
 
-export function usePlans({ initialPlans }: UsePlansOptions = {}): UsePlans {
-  const [plans, setPlans] = useState<PlanSummary[] | null>(initialPlans ?? null);
-  const [error, setError] = useState<string | null>(null);
+export type UsePlans = PlansState;
 
+export function usePlans(options: UsePlansOptions = {}): UsePlans {
+  const ref = useRef<PlansStore | null>(null);
+  if (!ref.current) ref.current = createPlansStore(options);
+  const store = ref.current;
   useEffect(() => {
-    let alive = true;
-    if (!initialPlans) {
-      fetchPlans()
-        .then((p) => alive && setPlans(p))
-        .catch((e) => {
-          if (!alive) return;
-          setPlans([]);
-          setError(e instanceof Error ? e.message : String(e));
-        });
-    }
-    return () => {
-      alive = false;
-    };
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, []);
-
-  return { plans, error };
+    store.start();
+    return () => store.stop();
+  }, [store]);
+  return useSyncExternalStore(store.subscribe, store.getState, store.getState);
 }

package/skills/wix-headless-fast/references/pricing-plans/app/wix/pricing-plans/plan-purchase-store.ts

@@ -0,0 +1,54 @@
+// The purchase action as a framework-free store — the logic behind usePlanPurchase, usable from
+// React (usePlanPurchase wraps it), from a static page's card or detail CTA, from Vue/Svelte, or
+// as the specification for a port. All correctness (the hosted redirect session, member
+// login/signup, payment) lives in the data layer; this store tracks the in-flight plan and the
+// last failure, and navigates the FULL document to the hosted checkout.
+//
+// One store per purchase surface (a grid and a detail CTA each key their own spinner):
+// createPlanPurchaseStore(), not a singleton. No async work on mount, so no start/stop.
+import { purchasePlan, type PurchaseOptions } from "./purchase";
+
+export interface PlanPurchaseState {
+  /** The plan id a purchase is in flight for (null when idle) — key CTA spinners off it. */
+  purchasingId: string | null;
+  /** The last failed purchase's visitor-facing message; a new purchase clears it. */
+  error: string | null;
+}
+
+export interface PlanPurchaseStore {
+  getState(): PlanPurchaseState;
+  subscribe(listener: () => void): () => void;
+  /**
+   * Starts the hosted checkout — when it resolves the browser is already navigating away, and
+   * `purchasingId` stays set. Rejects (and records `error`) otherwise — surface it, don't swallow it.
+   */
+  purchase(planId: string, options?: PurchaseOptions): Promise<void>;
+}
+
+export function createPlanPurchaseStore(): PlanPurchaseStore {
+  let state: PlanPurchaseState = { purchasingId: null, error: null };
+  const listeners = new Set<() => void>();
+
+  function setState(patch: Partial<PlanPurchaseState>): void {
+    state = { ...state, ...patch };
+    for (const fn of listeners) fn();
+  }
+
+  return {
+    getState: () => state,
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+    async purchase(planId, options) {
+      setState({ purchasingId: planId, error: null });
+      try {
+        window.location.href = await purchasePlan(planId, options);
+        // stays "purchasing" — the browser is leaving for the hosted checkout
+      } catch (e) {
+        setState({ purchasingId: null, error: e instanceof Error ? e.message : String(e) });
+        throw e;
+      }
+    },
+  };
+}

package/skills/wix-headless-fast/references/pricing-plans/app/wix/pricing-plans/plans-core.ts

@@ -0,0 +1,106 @@
+// Plan rules and DTO mapping — transport-agnostic, imported by BOTH transports: ./plans.ts (the
+// SDK, managed Astro and React) and the REST twin in references/pricing-plans/rest/plans.ts
+// (fetch, a static site or a port to another language). Every rule about prices, billing labels,
+// perks, buyability, images lives HERE, once. A raw plan may come from the SDK (`_id`, image as a
+// `wix:image://` string) or from REST (`id`, image as { id, url }); the mappers accept both.
+// Imports are type-only so a strip to JS emits no imports.
+import type { PlanDetail, PlanSummary } from "./types";
+
+/** A raw Plans V3 entity as either transport returns it. */
+export type Raw = Record<string, any>;
+/** Media value + size → https URL. Injected: the SDK transport scales through @wix/sdk, REST through the URL form. */
+export type ImgSrc = (value: any, width: number, height: number) => string;
+
+const id = (raw: Raw | undefined): string => raw?._id ?? raw?.id ?? "";
+
+// ---- query ----------------------------------------------------------------------------------------
+
+export interface PlansQueryOptions {
+  /** 1–100, default 100 (the grid shows every public plan). */
+  limit?: number;
+  /** One plan by URL slug (the detail page). */
+  slug?: string;
+}
+
+/**
+ * The Query Plans body both transports send: only PUBLIC plans (a HIDDEN plan is merchant-assigned
+ * and never listed), cursor paging, and the slug when one plan is wanted. The SDK builder spells the
+ * same filter as `.eq("visibility", "PUBLIC")`.
+ */
+export function plansQuery({ limit = 100, slug }: PlansQueryOptions = {}): Raw {
+  if (!Number.isInteger(limit) || limit < 1 || limit > 100) throw new Error("limit must be between 1 and 100.");
+  const filter: Raw = { visibility: "PUBLIC" };
+  if (slug) filter.slug = slug;
+  return { filter, cursorPaging: { limit } };
+}
+
+// ---- price rules ----------------------------------------------------------------------------------
+
+/** "€29.00" in the visitor's locale for the plan's currency; "Free" for no or zero amount. Never assume USD. */
+export function formatPrice(value: string | undefined, currency: string | undefined): string {
+  if (value == null || value === "" || Number(value) === 0) return "Free";
+  try {
+    return new Intl.NumberFormat(undefined, { style: "currency", currency: currency || "USD" }).format(Number(value));
+  } catch {
+    return `${value} ${currency ?? ""}`.trim();
+  }
+}
+
+/**
+ * billingTerms → a display label. billingCycle.count is a STRING on both transports ("1") — Number()
+ * it. No billingCycle → a one-time payment; endType CYCLES_COMPLETED with billingCycleCount 1 also
+ * bills once; more cycles read "per month × 6".
+ */
+export function billingLabel(terms: Raw | undefined): string {
+  const cycle = terms?.billingCycle;
+  if (!cycle) return "one-time";
+  const cyclesTotal = Number(terms?.cyclesCompletedDetails?.billingCycleCount ?? 0);
+  if (terms?.endType === "CYCLES_COMPLETED" && cyclesTotal === 1) return "one-time";
+  const count = Number(cycle.count ?? 1) || 1;
+  const period = String(cycle.period ?? "MONTH").toLowerCase();
+  const base = count === 1 ? `per ${period}` : `every ${count} ${period}s`;
+  return terms?.endType === "CYCLES_COMPLETED" && cyclesTotal > 1 ? `${base} × ${cyclesTotal}` : base;
+}
+
+/**
+ * The plan's image as a value imgSrc resolves: the SDK hands a `wix:image://…` string; REST hands
+ * an Image object { id, url } — its url when present, else the media id in the wix:image form the
+ * URL builder scales. "" when the plan has no image.
+ */
+export function planImage(raw: Raw): string {
+  const img = raw.image;
+  if (!img) return "";
+  if (typeof img === "string") return img;
+  if (img.url) return String(img.url);
+  return img.id ? `wix:image://v1/${img.id}/${img.id}` : "";
+}
+
+// ---- DTO mappers -----------------------------------------------------------------------------------
+
+/**
+ * The price is DISPLAY-ONLY: a decimal string at pricingVariants[0].pricingStrategies[0]
+ * .flatRate.amount ("0" = free), paired with plan.currency (site-derived). Wix settles the actual
+ * charge, tax, and schedule at the hosted checkout.
+ */
+export function toSummary(raw: Raw, imgSrc: ImgSrc): PlanSummary {
+  const variant: Raw = raw.pricingVariants?.[0] ?? {};
+  const amount: string | undefined = variant.pricingStrategies?.[0]?.flatRate?.amount;
+  const free = amount == null || Number(amount) === 0;
+  return {
+    id: id(raw),
+    slug: raw.slug ?? "",
+    name: raw.name ?? "",
+    description: raw.description ?? "",
+    price: free ? "Free" : formatPrice(amount, raw.currency),
+    free,
+    billing: free ? "" : billingLabel(variant.billingTerms),
+    freeTrialDays: variant.freeTrialDays || null,
+    perks: ((raw.perks ?? []) as Raw[]).map((p) => p.description ?? "").filter((d: string) => d),
+    buyable: raw.buyable === true, // a PUBLIC plan can still be merchant-assigned — no CTA then
+    imageUrl: imgSrc(planImage(raw), 800, 800),
+  };
+}
+
+export function toDetail(raw: Raw, imgSrc: ImgSrc): PlanDetail {
+  return { ...toSummary(raw, imgSrc), termsAndConditions: raw.termsAndConditions ?? "" };
+}

package/skills/wix-headless-fast/references/pricing-plans/app/wix/pricing-plans/plans-store.ts

@@ -0,0 +1,64 @@
+// The plans listing as a framework-free store — the logic behind usePlans, usable from React
+// (usePlans wraps it with useSyncExternalStore), from a static page or Vue/Svelte (subscribe and
+// render), or as the specification for a port. State, subscribe/getState, start/stop, emit after
+// every change.
+//
+// SSR-friendly: seed with `initialPlans` and they render at once with no client fetch; without a
+// seed `start()` fetches the public plans. A failed load leaves `plans: []` with the message in
+// `error`, so the surface renders its empty state and the message, never a skeleton forever.
+//
+// One store per mounted listing (a pricing page and a home-page strip can coexist): createPlansStore(),
+// not a singleton. It imports the data layer by names the REST twin exports identically, so the
+// same file runs over the SDK in Astro and over REST on a static page.
+import { fetchPlans } from "./plans";
+import type { PlanSummary } from "./types";
+
+export interface PlansStoreOptions {
+  initialPlans?: PlanSummary[];
+}
+
+/** Everything a pricing grid renders from. Read it with getState() or through a subscription. */
+export interface PlansState {
+  /** null while the first load is in flight — render skeletons, not an empty state. */
+  plans: PlanSummary[] | null;
+  error: string | null;
+}
+
+export interface PlansStore {
+  getState(): PlansState;
+  subscribe(listener: () => void): () => void;
+  /** Fetch the plans when no `initialPlans` were given. Call once when mounted (a browser). */
+  start(): void;
+  /** Stop reacting; drop a late response. */
+  stop(): void;
+}
+
+export function createPlansStore({ initialPlans }: PlansStoreOptions = {}): PlansStore {
+  let state: PlansState = { plans: initialPlans ?? null, error: null };
+  let started = false;
+  const listeners = new Set<() => void>();
+
+  function setState(patch: Partial<PlansState>): void {
+    state = { ...state, ...patch };
+    for (const fn of listeners) fn();
+  }
+
+  return {
+    getState: () => state,
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+    start() {
+      if (started) return;
+      started = true;
+      if (initialPlans) return;
+      fetchPlans()
+        .then((plans) => { if (started) setState({ plans }); })
+        .catch((e) => { if (started) setState({ plans: [], error: e instanceof Error ? e.message : String(e) }); });
+    },
+    stop() {
+      started = false;
+    },
+  };
+}

package/skills/wix-headless-fast/references/pricing-plans/app/wix/pricing-plans/plans.ts

@@ -1,75 +1,27 @@
-// Plan reads (Wix Pricing Plans, Plans V3) — the only file that touches raw plan entities.
-// Everything it returns is a plain DTO from ./types. Copy as-is; extend by adding functions,
-// not by editing these.
+// Plan reads (Wix Pricing Plans, Plans V3) over the SDK — the only file that touches raw plan
+// entities on this transport. Everything it returns is a plain DTO from ./types. The rules and
+// mappers live in ./plans-core (shared with the REST twin in references/pricing-plans/rest/);
+// this file is the transport only. Copy as-is; extend by adding functions, not by editing these.
 //
 // The read module is plansV3 — NOT `plans` (that's the V2 namespace; it has no queryPlans).
 // docs: https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/plans-v3/query-plans.md
 import { plansV3 } from "@wix/pricing-plans";
 import { wixModule } from "../sdk";
 import { imgSrc } from "../media";
+import { toDetail, toSummary, type Raw } from "./plans-core";
 import type { PlanDetail, PlanSummary } from "./types";
 
 const plans = wixModule(plansV3);
 
-type Raw = Record<string, any>;
-
-function formatPrice(value: string | undefined, currency: string | undefined): string {
-  if (value == null || value === "" || Number(value) === 0) return "Free";
-  try {
-    return new Intl.NumberFormat(undefined, { style: "currency", currency: currency || "USD" }).format(Number(value));
-  } catch {
-    return `${value} ${currency ?? ""}`.trim();
-  }
-}
-
-// billingTerms → a display label. billingCycle.count comes back as a STRING in SDK reads
-// ("1") — Number() it. endType CYCLES_COMPLETED with billingCycleCount 1 bills once.
-function billingLabel(terms: Raw | undefined): string {
-  const cycle = terms?.billingCycle;
-  if (!cycle) return "one-time";
-  const cyclesTotal = Number(terms?.cyclesCompletedDetails?.billingCycleCount ?? 0);
-  if (terms?.endType === "CYCLES_COMPLETED" && cyclesTotal === 1) return "one-time";
-  const count = Number(cycle.count ?? 1) || 1;
-  const period = String(cycle.period ?? "MONTH").toLowerCase();
-  const base = count === 1 ? `per ${period}` : `every ${count} ${period}s`;
-  return terms?.endType === "CYCLES_COMPLETED" && cyclesTotal > 1 ? `${base} × ${cyclesTotal}` : base;
-}
-
-// The price is DISPLAY-ONLY: a decimal string at pricingVariants[0].pricingStrategies[0]
-// .flatRate.amount ("0" = free), paired with plan.currency (site-derived — never assume
-// USD). Wix settles the actual charge, tax, and schedule at the hosted checkout.
-function toSummary(raw: Raw): PlanSummary {
-  const variant: Raw = raw.pricingVariants?.[0] ?? {};
-  const amount: string | undefined = variant.pricingStrategies?.[0]?.flatRate?.amount;
-  const free = amount == null || Number(amount) === 0;
-  return {
-    id: raw._id ?? "", // SDK entity id is _id, never id (that's the REST view)
-    slug: raw.slug ?? "",
-    name: raw.name ?? "",
-    description: raw.description ?? "",
-    price: free ? "Free" : formatPrice(amount, raw.currency),
-    free,
-    billing: free ? "" : billingLabel(variant.billingTerms),
-    freeTrialDays: variant.freeTrialDays || null,
-    perks: (raw.perks ?? []).map((p: Raw) => p.description ?? "").filter((d: string) => d),
-    buyable: raw.buyable === true,
-    imageUrl: imgSrc(raw.image, 800, 800),
-  };
-}
-
-function toDetail(raw: Raw): PlanDetail {
-  return { ...toSummary(raw), termsAndConditions: raw.termsAndConditions ?? "" };
-}
-
 /** List the public plans for the pricing grid, as card-ready DTOs. */
 export async function fetchPlans({ limit = 100 } = {}): Promise<PlanSummary[]> {
   const res = await plans.queryPlans().eq("visibility", "PUBLIC").limit(limit).find();
-  return (res.items ?? []).map((p: Raw) => toSummary(p));
+  return (res.items ?? []).map((p) => toSummary(p as Raw, imgSrc));
 }
 
 /** Fetch one public plan by its URL slug. Null when not found. */
 export async function fetchPlanBySlug(slug: string): Promise<PlanDetail | null> {
   const res = await plans.queryPlans().eq("visibility", "PUBLIC").eq("slug", slug).limit(1).find();
   const raw = res.items?.[0];
-  return raw ? toDetail(raw as Raw) : null;
+  return raw ? toDetail(raw as Raw, imgSrc) : null;
 }

package/skills/wix-headless-fast/references/pricing-plans/app/wix/pricing-plans/purchase-core.ts

@@ -0,0 +1,43 @@
+// Purchase rules — transport-agnostic, imported by both ./purchase.ts (SDK) and the REST twin in
+// references/pricing-plans/rest/purchase.ts (fetch). The redirect-session body for a plan and the
+// reading of its result live HERE, once. Type-only imports: a strip to JS emits none.
+import type { Raw } from "./plans-core";
+
+export interface PurchaseOptions {
+  /**
+   * Success-only return URL — Wix appends `?planOrderId=<GUID>` to it. Omit → Wix shows its
+   * hosted thank-you page, then returns to postFlowUrl. Point it at a page of yours only if
+   * that page reads the param and renders a real confirmation.
+   */
+  thankYouPageUrl?: string;
+  /**
+   * Where a completed, abandoned, or interrupted flow returns (default: the current page).
+   * Landing here is NOT a success signal — only thankYouPageUrl carries one.
+   */
+  postFlowUrl?: string;
+}
+
+/**
+ * The Create Redirect Session body for a plan: `paidPlansCheckout: { planId }` plus the callbacks.
+ * postFlowUrl defaults to the current page (browser); a server caller passes it explicitly.
+ * The return origin must be the site's real https origin as registered on the OAuth app's allowed
+ * domains — an unlisted or http origin 403s on return.
+ */
+export function purchaseBody(planId: string, { thankYouPageUrl, postFlowUrl }: PurchaseOptions = {}): Raw {
+  if (!planId) throw new Error("A plan id is required to start checkout.");
+  const href = typeof window !== "undefined" ? window.location.href : "";
+  return {
+    paidPlansCheckout: { planId },
+    callbacks: {
+      postFlowUrl: postFlowUrl ?? (href || undefined),
+      ...(thankYouPageUrl ? { thankYouPageUrl } : {}),
+    },
+  };
+}
+
+/** The hosted checkout URL out of a redirect-session response; throws when there is none. */
+export function redirectUrl(session: Raw | null | undefined): string {
+  const url = session?.redirectSession?.fullUrl;
+  if (!url) throw new Error("Checkout couldn't start — please try again.");
+  return url;
+}

package/skills/wix-headless-fast/references/pricing-plans/app/wix/pricing-plans/purchase.ts

@@ -1,45 +1,22 @@
-// The purchase flow: one call that turns a plan id into a Wix-hosted checkout URL.
+// The purchase flow over the SDK: one call that turns a plan id into a Wix-hosted checkout URL.
 // Purchasing a plan is a MEMBER action, but the hosted flow handles member login/signup,
 // the order form, and payment itself — so this works from an anonymous visitor session.
 // Never create the order yourself (orders.createOnlineOrder needs a logged-in member and
-// still leaves payment unhandled); never hand-build a checkout URL. Copy as-is.
+// still leaves payment unhandled); never hand-build a checkout URL. The body and the result
+// reading live in ./purchase-core (shared with the REST twin); this file is the transport only.
+// Copy as-is.
 // docs: https://dev.wix.com/docs/api-reference/business-management/headless/redirects/create-redirect-session.md
 import { redirects as redirectsModule } from "@wix/redirects";
 import { wixModule } from "../sdk";
+import { purchaseBody, redirectUrl, type PurchaseOptions } from "./purchase-core";
+import type { Raw } from "./plans-core";
 
-const redirects = wixModule(redirectsModule);
-
-type Raw = Record<string, any>;
+export type { PurchaseOptions };
 
-export interface PurchaseOptions {
-  /**
-   * Success-only return URL — Wix appends `?planOrderId=<GUID>` to it. Omit → Wix shows its
-   * hosted thank-you page, then returns to postFlowUrl. Point it at a page of yours only if
-   * that page reads the param and renders a real confirmation.
-   */
-  thankYouPageUrl?: string;
-  /**
-   * Where a completed, abandoned, or interrupted flow returns (default: the current page).
-   * Landing here is NOT a success signal — only thankYouPageUrl carries one.
-   */
-  postFlowUrl?: string;
-}
+const redirects = wixModule(redirectsModule);
 
 /** Start the hosted purchase for a plan; resolves to the URL to send the browser to. */
-export async function purchasePlan(
-  planId: string,
-  { thankYouPageUrl, postFlowUrl }: PurchaseOptions = {},
-): Promise<string> {
-  if (!planId) throw new Error("A plan id is required to start checkout.");
-  const href = typeof window !== "undefined" ? window.location.href : "";
-  const session: Raw = await redirects.createRedirectSession({
-    paidPlansCheckout: { planId },
-    callbacks: {
-      postFlowUrl: postFlowUrl ?? (href || undefined),
-      ...(thankYouPageUrl ? { thankYouPageUrl } : {}),
-    },
-  });
-  const url = session?.redirectSession?.fullUrl;
-  if (!url) throw new Error("Checkout couldn't start — please try again.");
-  return url;
+export async function purchasePlan(planId: string, options: PurchaseOptions = {}): Promise<string> {
+  const session: Raw = await redirects.createRedirectSession(purchaseBody(planId, options) as any);
+  return redirectUrl(session);
 }

package/skills/wix-headless-fast/references/pricing-plans/rest/plans.ts

@@ -0,0 +1,31 @@
+// Plan reads over REST — the twin of app/wix/pricing-plans/plans.ts. Same exports, same DTOs; the
+// rules and mappers come from plans-core (the SAME file the SDK transport uses, deployed flat next
+// to this one by deploy.mjs --stack static), so this file is only the transport: one fetch with a
+// literal body per function. Every call here is safe from a browser with a visitor token.
+// Porting: keep the path, keep the body, port the core once.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/plans-v3/query-plans.md
+import { wixRequest } from "./client.js";
+import { imgSrc } from "./media.js";
+import { plansQuery, toDetail, toSummary, type Raw } from "./plans-core.js";
+import type { PlanDetail, PlanSummary } from "./types.js";
+
+const QUERY = "/pricing-plans/v3/plans/query";
+
+/**
+ * The public plans for the pricing grid, as card-ready DTOs.
+ * POST /pricing-plans/v3/plans/query  { query: { filter: { visibility: "PUBLIC" }, cursorPaging: { limit } } }
+ */
+export async function fetchPlans({ limit = 100 } = {}): Promise<PlanSummary[]> {
+  const res = await wixRequest<Raw>(QUERY, { body: { query: plansQuery({ limit }) } });
+  return ((res?.plans ?? []) as Raw[]).map((p) => toSummary(p, imgSrc));
+}
+
+/**
+ * One public plan by its URL slug; null when the slug doesn't resolve (an empty `plans`, not a 404).
+ * POST /pricing-plans/v3/plans/query  { query: { filter: { visibility: "PUBLIC", slug }, cursorPaging: { limit: 1 } } }
+ */
+export async function fetchPlanBySlug(slug: string): Promise<PlanDetail | null> {
+  const res = await wixRequest<Raw>(QUERY, { body: { query: plansQuery({ limit: 1, slug }) } });
+  const raw: Raw | undefined = res?.plans?.[0];
+  return raw ? toDetail(raw, imgSrc) : null;
+}

package/skills/wix-headless-fast/references/pricing-plans/rest/purchase.ts

@@ -0,0 +1,20 @@
+// The purchase flow over REST — the twin of app/wix/pricing-plans/purchase.ts. Same export, same
+// signature; the body and the result reading come from purchase-core (the SAME file the SDK
+// transport uses). Purchasing is a MEMBER action, but the hosted flow handles login/signup, the
+// order form, and payment itself, so a visitor token starts it. Never create the order yourself,
+// never hand-build a checkout URL.
+// docs: https://dev.wix.com/docs/api-reference/business-management/headless/redirects/create-redirect-session.md
+import { wixRequest } from "./client.js";
+import { purchaseBody, redirectUrl, type PurchaseOptions } from "./purchase-core.js";
+import type { Raw } from "./plans-core.js";
+
+export type { PurchaseOptions };
+
+/**
+ * Start the hosted purchase for a plan; resolves to the URL to navigate the FULL document to.
+ * POST /headless/v1/redirect-session  { paidPlansCheckout: { planId }, callbacks: { postFlowUrl, thankYouPageUrl? } }
+ */
+export async function purchasePlan(planId: string, options: PurchaseOptions = {}): Promise<string> {
+  const session = await wixRequest<Raw>("/headless/v1/redirect-session", { body: purchaseBody(planId, options) });
+  return redirectUrl(session);
+}

package/skills/wix-headless-fast/references/pricing-plans/seed/SEED.md

@@ -61,6 +61,14 @@ omits both — coverage is skipped automatically.
 **Seeding is additive — never delete or overwrite existing content**; ask first if a cleanup
 seems needed.
 
+## Supplied content
+
+The general rules are in `references/shared/SUPPLIED-CONTENT.md`. For pricing plans, each plan the
+user lists is one entry. Its name becomes `name`; a price with a billing period becomes `price`
+with `type: "recurring"` and the matching `billingCycle`; a price paid once becomes
+`type: "one-time"`; no price means `type: "free"`; a list of features or benefits becomes `perks`;
+the description becomes `description`. A price with no period is a question for the user.
+
 ## Escape hatch — individual functions
 `setupPricingPlans` composes exported steps — `installPricingPlansApp`, `createPlans`,
 `attachBookingsCoverage` (and its `getProgramDefinition`, `createPoolDefinition`,