@wix/agent-skills 1.25.0 → 1.27.0

package/skills/wix-headless-templates/pricing-plans/project/src/layouts/SiteLayout.astro

@@ -0,0 +1,41 @@
+---
+// The site chrome for every pricing-plans 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> and the global.css import. (Deploy is fill-only: if
+// another vertical is already deployed, its SiteLayout won — merge a Plans nav link there
+// instead.)
+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="/plans" class="text-foreground no-underline transition-colors hover:text-muted-foreground">Plans</a>
+        </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>
+  </body>
+</html>

package/skills/wix-headless-templates/pricing-plans/project/src/pages/index.astro

@@ -0,0 +1,8 @@
+---
+import Hero from '../components/Hero.astro';
+import Layout from '../layouts/Layout.astro';
+---
+
+<Layout>
+	<Hero />
+</Layout>

package/skills/wix-headless-templates/pricing-plans/project/src/pages/plans/[slug].astro

@@ -0,0 +1,43 @@
+---
+// Plan detail page.
+//
+// Pricing Plans has no documented owner-editable SEO item type (unlike bookings services /
+// store products), so this page carries plain <title>/<meta> from the DTO — no wixMetadata,
+// no <SEO.Tags>. The island is client:load: the plan arrives as an SSR-fetched prop; only
+// the purchase action runs client-side.
+import SiteLayout from "../../layouts/SiteLayout.astro";
+import PlanDetailView from "../../components/pricing-plans/PlanDetailView";
+import { fetchPlanBySlug } from "../../wix/pricing-plans/plans";
+import { PLAN_IMAGE_RATIO } from "../../wix/pricing-plans/plans-core";
+import { imgAttrs } from "../../wix/media";
+import type { PlanDetail } from "../../wix/pricing-plans/types";
+
+const slug = Astro.params.slug!;
+
+let plan: PlanDetail | null = null;
+try {
+  plan = await fetchPlanBySlug(slug);
+} catch {
+  // Guarded: an unhandled SSR throw truncates the response mid-stream.
+}
+
+if (!plan) {
+  return new Response(null, { status: 404 });
+}
+---
+
+<SiteLayout title={plan.name} description={plan.description || undefined}>
+  <div class="mx-auto max-w-2xl">
+    <!-- The DTO image is 16:9 (plans-core PLAN_IMAGE_RATIO); the band matches it, so nothing is cropped. -->
+    {plan.imageUrl && (
+      <div class="mb-6 aspect-[16/9] max-h-[40vh] overflow-hidden rounded-xl bg-secondary">
+        <img {...imgAttrs(plan.imageUrl, "(min-width: 768px) 672px, 100vw", PLAN_IMAGE_RATIO)} alt={plan.name} class="h-full w-full object-cover" />
+      </div>
+    )}
+    <h1 class="text-2xl font-semibold tracking-tight">{plan.name}</h1>
+    {plan.description && <p class="mt-2 text-muted-foreground">{plan.description}</p>}
+    <div class="mt-6">
+      <PlanDetailView client:load plan={plan} />
+    </div>
+  </div>
+</SiteLayout>

package/skills/wix-headless-templates/pricing-plans/project/src/pages/plans.astro

@@ -0,0 +1,21 @@
+---
+// Plans & Pricing — data fetched SERVER-SIDE (SEO) and handed to the island as DTO props.
+// Keep this frontmatter; swap the island import to YOUR pricing component.
+import SiteLayout from "../layouts/SiteLayout.astro";
+import PlansView from "../components/pricing-plans/PlansView";
+import { fetchPlans } from "../wix/pricing-plans/plans";
+import type { PlanSummary } from "../wix/pricing-plans/types";
+
+let plans: PlanSummary[] = [];
+try {
+  plans = await fetchPlans();
+} catch {
+  // An unguarded SSR throw truncates the response mid-stream; the island renders the
+  // empty state instead.
+}
+---
+
+<SiteLayout title="Plans & Pricing">
+  <h1 class="mb-8 text-2xl font-semibold tracking-tight">Plans &amp; Pricing</h1>
+  <PlansView client:load initialPlans={plans} />
+</SiteLayout>

package/skills/wix-headless-templates/pricing-plans/project/src/styles/global.css

@@ -0,0 +1,57 @@
+@import url('https://fonts.googleapis.com/css2?family=Wix+Madefor+Text:wght@400;500;600;700;800&display=swap');
+@import 'tailwindcss';
+
+/* ─── THE design system ─────────────────────────────────────────────────────────────────
+   Theme the entire store by editing THIS @theme block (same token family as the official
+   Wix headless templates). Every shipped component styles itself from these via Tailwind
+   utilities (bg-primary, text-muted-foreground, text-destructive, rounded-lg, …) — change a token, everything
+   follows. A dark theme is just flipped values (dark background/foreground, adjusted
+   secondary/border). Don't restyle shipped component markup; restyle the tokens.
+
+   Choosing values: argue polarity from the business — light is not "cheap" (wellness/food
+   usually read better light); never dark-by-default for "premium". Palette: one dominant +
+   accents from ADJACENT hues (~30° arc), 2-4 colors total. Every background/foreground pair
+   you set must hit WCAG 4.5:1 (3:1 for text ≥24px); body copy never below 16px/1.5. Derive
+   from THIS brand — a look repeated across projects is a failure, not a shortcut. The user's
+   explicit direction beats all of this except the contrast floor. */
+@theme {
+  --color-background: hsl(0 0% 100%);
+  --color-foreground: hsl(230 24% 14%);
+  --color-primary: hsl(230 24% 14%);
+  --color-primary-foreground: hsl(0 0% 100%);
+  --color-secondary: hsl(228 24% 96%);
+  --color-secondary-foreground: hsl(230 24% 14%);
+  --color-muted-foreground: hsl(228 8% 46%);
+  --color-border: hsl(220 14% 90%);
+  --color-destructive: hsl(0 72% 51%);
+
+  --radius-lg: 12px;
+  --radius-md: 8px;
+  --radius-sm: 6px;
+  /* Buttons, chips, labels, steppers and the progress bar. Follows --radius-md unless the brand
+     wants otherwise: 9999px is the pill, 0 is square. Genuine circles (swatches, avatars, dots)
+     stay rounded-full and do not read this. */
+  --radius-control: var(--radius-md);
+
+  --font-sans: 'Wix Madefor Text', system-ui, sans-serif;
+}
+
+@layer base {
+  body {
+    background-color: var(--color-background);
+    color: var(--color-foreground);
+    font-family: var(--font-sans);
+    -webkit-font-smoothing: antialiased;
+    font-feature-settings: 'cv02', 'cv03', 'cv04', 'cv11';
+  }
+}
+
+@layer utilities {
+  .eyebrow {
+    font-size: 0.8125rem;
+    font-weight: 600;
+    letter-spacing: 0.1em;
+    text-transform: uppercase;
+    color: var(--color-muted-foreground);
+  }
+}

package/skills/wix-headless-templates/pricing-plans/project/src/wix/config.ts

@@ -0,0 +1,16 @@
+// Wix connection config — written by the skill's deploy step (install/deploy.mjs).
+//
+// WIX_CLIENT_ID = null  → ambient auth (a Wix-managed Astro project: `@wix/astro` authenticates
+//                         every SDK call automatically; there is no client and nothing to set).
+// WIX_CLIENT_ID = "..." → manual visitor client (any other React setup): the public OAuth client id.
+//                         It is NOT a secret — it only mints anonymous visitor tokens — so
+//                         hardcoding and committing it is fine. deploy.mjs copies it from `.env.local`
+//                         (`WIX_CLIENT_ID`, what `wix env pull` writes): the CONTENT site's app — on a
+//                         migration preview the site being migrated, while wix.config.json names
+//                         only the deploy target.
+export const WIX_CLIENT_ID: string | null = null;
+
+// Kept for projects deployed before the Members vertical moved onto the shared seam; the shipped
+// members code no longer reads it (ambient Astro uses the built-in /api/auth routes, manual mode
+// uses the shared client above). deploy.mjs still fills it so older code keeps compiling.
+export const WIX_MEMBERS_CLIENT_ID: string | null = null;

package/skills/wix-headless-templates/pricing-plans/project/src/wix/media.ts

@@ -0,0 +1,106 @@
+// Wix media resolution — define once, use on EVERY image render path. Copy as-is.
+//
+// SDK media fields come back either as an already-absolute https URL, or as a
+// `wix:image://v1/<hash>/<file>#originWidth=…` identifier that a browser cannot load
+// (ERR_UNKNOWN_URL_SCHEME). The wix:image:// form must go through the SDK media module;
+// never hand-build a static.wixstatic.com URL (wrong format → 403).
+// docs: https://dev.wix.com/docs/sdk/core-modules/sdk/media.md
+import { media } from "@wix/sdk";
+
+type MediaLike =
+  | string
+  | null
+  | undefined
+  | { image?: unknown; url?: string | null; id?: string | null };
+
+/** A bare Wix media file id (`e6a89e_06cf…~mv2.png`): what REST-shaped media objects carry as `url` and `id`. */
+const BARE_FILE_ID = /^[\w-]+~mv2\.[a-z0-9]+$/i;
+
+function rawOf(value: MediaLike): string {
+  if (!value) return "";
+  if (typeof value === "string") return value;
+  if (value.image != null && typeof value.image === "object") return rawOf(value.image as MediaLike); // { image: { id, url } }
+  return (typeof value.image === "string" ? value.image : null) ?? value.url ?? value.id ?? "";
+}
+
+/** Resolve any Wix media value to a browser-loadable URL ("" when absent). */
+export function imgSrc(value: MediaLike, width = 600, height = 600): string {
+  const v = rawOf(value);
+  if (!v) return "";
+  if (v.startsWith("wix:image://")) {
+    return media.getScaledToFillImageUrl(v, width, height, {});
+  }
+  // A bare file id (what REST-shaped media objects carry) or an absolute Wix media URL (bare, or
+  // already carrying a /v1/fill/ segment at some other size): re-issue it through the scaler at the
+  // requested size, so every image path lands on one shape.
+  const file = BARE_FILE_ID.test(v) ? v : v.match(/^https:\/\/static\.wixstatic\.com\/media\/([^/?#]+)/)?.[1];
+  if (file) return `https://static.wixstatic.com/media/${file}/v1/fill/w_${width},h_${height},al_c,q_90/${file}`;
+  return v;
+}
+
+/**
+ * Responsive candidates for `srcset`: the same image at several widths through Wix's scaler, so a
+ * card never downloads a hero-sized file. Pair with `sizes`:
+ *   <img src={imgSrc(m, 640, 640)} srcSet={imgSrcSet(m)} sizes="(min-width: 1024px) 25vw, 50vw"
+ *        width={640} height={640} loading="lazy" alt={…} />
+ * Accepts every form an image reaches you in: a raw `wix:image://` id, an ALREADY-RESOLVED Wix URL
+ * (what the DTOs carry — `imageUrl`, `gallery[]`; its `/v1/fill/w_…,h_…` segment is rewritten per
+ * width), or any other https URL (returned as the single candidate). `ratio` is height/width
+ * (1 = square). "" only when there is no image at all — still set `src` as well.
+ */
+export function imgSrcSet(value: MediaLike, widths: number[] = [320, 480, 640, 960], ratio = 1): string {
+  const raw = rawOf(value);
+  if (!raw) return "";
+  if (raw.startsWith("wix:image://") || BARE_FILE_ID.test(raw)) {
+    return widths.map((w) => `${imgSrc(value, w, Math.round(w * ratio))} ${w}w`).join(", ");
+  }
+  // A resolved Wix URL: …/v1/fill/w_800,h_800,al_c,… — swap the size for each width.
+  const FILL = /\/v1\/fill\/w_\d+,h_\d+/;
+  if (/static\.wixstatic\.com\//.test(raw) && FILL.test(raw)) {
+    return widths.map((w) => `${raw.replace(FILL, `/v1/fill/w_${w},h_${Math.round(w * ratio)}`)} ${w}w`).join(", ");
+  }
+  return raw; // one candidate, never an empty srcset for a real image
+}
+
+/**
+ * Everything an <img> needs for one Wix image, so a tile can never ship `srcSet` without `src`:
+ *   <img {...imgAttrs(p.imageUrl, "(min-width: 1024px) 25vw, 50vw")} alt={p.name} />
+ * `sizes` is the width the image renders at (a CSS length or media-query list); `ratio` is
+ * height/width. Returns an empty object when there is no image — render your placeholder then.
+ */
+export function imgAttrs(value: MediaLike, sizes: string, ratio = 1): { src: string; srcSet: string; sizes: string; loading: "lazy"; decoding: "async" } | Record<string, never> {
+  const src = imgSrc(value, 640, Math.round(640 * ratio));
+  if (!src) return {};
+  return { src, srcSet: imgSrcSet(value, undefined, ratio), sizes, loading: "lazy", decoding: "async" };
+}
+
+/**
+ * Height/width of a Wix image when the value carries its size: a raw
+ * `wix:image://…#originWidth=W&originHeight=H` id (the natural size) or a resolved `/v1/fill/w_W,h_H/`
+ * URL (the size it was scaled to). null when neither is present. Pass it as `ratio` to keep a
+ * srcset at the image's own aspect instead of the square default:
+ *   <img {...imgAttrs(item.photo, "33vw", imgRatio(item.photo) ?? 1)} alt={…} />
+ */
+export function imgRatio(value: MediaLike): number | null {
+  const v = rawOf(value);
+  if (typeof v !== "string" || !v) return null;
+  const size = v.startsWith("wix:image://")
+    ? [v.match(/[#&]originWidth=(\d+)/)?.[1], v.match(/[#&]originHeight=(\d+)/)?.[1]]
+    : (v.match(/\/v1\/fill\/w_(\d+),h_(\d+)/)?.slice(1) ?? []);
+  const w = Number(size[0]);
+  const h = Number(size[1]);
+  return w > 0 && h > 0 ? h / w : null;
+}
+
+/**
+ * The identity of a media value BEFORE scaling — de-duplicate galleries on this, never on a
+ * resolved URL (two scaled URLs of one photo differ in their size parameters).
+ */
+export function mediaKey(value: MediaLike): string {
+  const v = rawOf(value);
+  if (!v) return "";
+  // The file id, whichever form the value takes — a raw id and a resolved URL of one photo share it.
+  if (v.startsWith("wix:image://")) return v.slice("wix:image://v1/".length).split("/")[0].split("#")[0];
+  const m = v.match(/^https:\/\/static\.wixstatic\.com\/media\/([^/?#]+)/);
+  return m ? m[1] : v;
+}

package/skills/wix-headless-templates/pricing-plans/project/src/wix/money.ts

@@ -0,0 +1,24 @@
+// Money formatting for API amounts that carry no formatted string. Copy as-is.
+//
+// Catalog prices come with a ready `formattedAmount` — use that directly. But eCom Cart V2
+// amounts are ConvertedMoney `{ amount, convertedAmount }` with NO formatted string, and the
+// currency lives on the cart, not on the money object. Never hardcode "$" or assume USD.
+export interface ConvertedMoneyLike {
+  amount?: string | null;
+  convertedAmount?: string | null;
+}
+
+/** Format a ConvertedMoney in the given currency, using the visitor's locale. */
+export function formatMoney(
+  money: ConvertedMoneyLike | null | undefined,
+  currencyCode: string | null | undefined,
+): string {
+  const value = money?.convertedAmount ?? money?.amount;
+  if (value == null || value === "") return "";
+  const currency = currencyCode || "USD";
+  try {
+    return new Intl.NumberFormat(undefined, { style: "currency", currency }).format(Number(value));
+  } catch {
+    return `${value} ${currency}`;
+  }
+}

package/skills/wix-headless-templates/pricing-plans/project/src/wix/pricing-plans/plan-access-core.ts

@@ -0,0 +1,29 @@
+// Plan-access (paywall) rules — transport-agnostic, imported by BOTH transports: ./plan-access.ts
+// (the SDK) and the REST twin in templates/pricing-plans/rest/plan-access.ts (fetch). What "has
+// access" MEANS and what the member-orders read asks for live HERE, once. Type-only imports: a
+// strip to JS emits none.
+import type { Raw } from "./plans-core";
+
+/** The one order status that grants access: purchased, started, not paused/ended/canceled. */
+export const ACCESS_ORDER_STATUSES = ["ACTIVE"] as const;
+
+/** The Member List Orders filter both transports send. */
+export interface MemberOrdersQuery {
+  planIds: string[];
+  orderStatuses: readonly ("ACTIVE")[];
+}
+
+/** The filter for "the current member's ACTIVE orders for these plans"; throws on an empty plan list. */
+export function memberOrdersQuery(requiredPlanIds: string[]): MemberOrdersQuery {
+  if (!requiredPlanIds.length) throw new Error("At least one required plan id is needed to check access.");
+  return { planIds: requiredPlanIds, orderStatuses: ACCESS_ORDER_STATUSES };
+}
+
+/**
+ * Access = the member has at least one order with status ACTIVE whose planId is one of the required
+ * plans. Re-checked here even though the query already filtered (a caller may pass orders it read
+ * for another reason). Visitors never reach this: they have no orders to list.
+ */
+export function hasPlanAccess(orders: Raw[] | null | undefined, requiredPlanIds: string[]): boolean {
+  return (orders ?? []).some((o) => o?.status === "ACTIVE" && requiredPlanIds.includes(o?.planId));
+}

package/skills/wix-headless-templates/pricing-plans/project/src/wix/pricing-plans/plan-access-store.ts

@@ -0,0 +1,92 @@
+// Plan access (paywall) as a framework-free store — the logic behind usePlanAccess, usable from
+// React (usePlanAccess wraps it with useSyncExternalStore), from a static page or Vue/Svelte
+// (subscribe and render), or as the specification for a port. State, subscribe/getState,
+// check/stop, emit after every change.
+//
+// It does not know who is logged in — that is the `members` vertical's session (its store's
+// `{ loggedIn, loading }`), handed in through `check(session)`. The rules: while the session is
+// still loading, so is access; a visitor has no access and NO call is made (Member List Orders is
+// member-only — it would be refused); a member gets one read, re-run only when the session flips.
+// A failed read leaves `hasAccess: false` with the message in `error` — gated content stays closed.
+//
+// SSR-friendly: `initialAccess` (resolved in frontmatter with hasActiveOrderFor under a member
+// session) renders at once with no client call. One store per gated surface: createPlanAccessStore().
+// 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 { hasActiveOrderFor, type MemberOrdersCall } from "./plan-access";
+
+/** The slice of the members session this store reads — the members store's `{ loggedIn, loading }` fits as-is. */
+export interface PlanAccessSession {
+  loggedIn: boolean;
+  /** True until the session read settles — access stays `loading` too. */
+  loading: boolean;
+}
+
+export interface PlanAccessStoreOptions {
+  /** The plans that grant access (any one of them). Fixed for the store's life. */
+  planIds: string[];
+  /** Resolved server-side → no client call. */
+  initialAccess?: boolean;
+  /** A Member List Orders call bound to the member's client — needed on a manual-client stack (see plan-access.ts). */
+  call?: MemberOrdersCall;
+}
+
+/** Everything a gated surface renders from. */
+export interface PlanAccessState {
+  /** False until proven: a visitor, a member without an active order, a failed read, or still loading. */
+  hasAccess: boolean;
+  /** True while the session or the orders read is unsettled — render a neutral state, never the fallback. */
+  loading: boolean;
+  /** The failed read's message (null when none). */
+  error: string | null;
+}
+
+export interface PlanAccessStore {
+  getState(): PlanAccessState;
+  subscribe(listener: () => void): () => void;
+  /** Feed the current session; call again whenever it changes (the hook does, on every render that changes it). */
+  check(session: PlanAccessSession): void;
+  /** Stop reacting; drop a late response. */
+  stop(): void;
+}
+
+export function createPlanAccessStore({ planIds, initialAccess, call }: PlanAccessStoreOptions): PlanAccessStore {
+  let state: PlanAccessState = { hasAccess: initialAccess ?? false, loading: initialAccess === undefined, error: null };
+  let stopped = false;
+  /** The loggedIn value the last read ran for — a member is read once, not on every render. */
+  let readFor: boolean | null = initialAccess === undefined ? null : true;
+  const listeners = new Set<() => void>();
+
+  function setState(patch: Partial<PlanAccessState>): void {
+    state = { ...state, ...patch };
+    for (const fn of listeners) fn();
+  }
+
+  return {
+    getState: () => state,
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+    check(session) {
+      stopped = false;
+      if (session.loading) {
+        if (!state.loading) setState({ loading: true });
+        return;
+      }
+      if (readFor === session.loggedIn) return;
+      readFor = session.loggedIn;
+      if (!session.loggedIn) {
+        setState({ hasAccess: false, loading: false, error: null }); // a visitor: no orders, no call
+        return;
+      }
+      setState({ loading: true, error: null });
+      hasActiveOrderFor(planIds, call)
+        .then((hasAccess) => { if (!stopped) setState({ hasAccess, loading: false }); })
+        .catch((e) => { if (!stopped) setState({ hasAccess: false, loading: false, error: e instanceof Error ? e.message : String(e) }); });
+    },
+    stop() {
+      stopped = true;
+    },
+  };
+}

package/skills/wix-headless-templates/pricing-plans/project/src/wix/pricing-plans/plan-access.ts

@@ -0,0 +1,37 @@
+// Plan access (paywall) over the SDK — does the CURRENT MEMBER hold an active order for one of the
+// required plans? Member List Orders is a MEMBER call: it lists the caller's own orders and is
+// refused for a visitor, so callers check the session first (the store does) and never call for a
+// visitor. The rule lives in ./plan-access-core (shared with the REST twin); this file is the
+// transport only.
+//
+// The session it needs comes from the `members` vertical (custom login), which this vertical does
+// not ship — so the call path is injectable:
+//   default — the shared seam (../sdk `wixModule`). On managed Astro that is ambient auth, which
+//             runs as the member once the members vertical's login has written the wixSession
+//             cookie (its client.ts does), in islands and in frontmatter alike.
+//   manual client (React SPA, lib) — the shared seam holds a VISITOR token; pass a call bound to the
+//             member's client instead, e.g. from templates/members' client.ts strategy:
+//             `createClient({ auth: membersAuth, modules: { orders } }).orders.memberListOrders`.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/orders/member-list-orders.md
+import { orders as ordersModule } from "@wix/pricing-plans";
+import { wixModule } from "../sdk";
+import { hasPlanAccess, memberOrdersQuery, type MemberOrdersQuery } from "./plan-access-core";
+import type { Raw } from "./plans-core";
+
+export type { MemberOrdersQuery };
+
+/** An already-authenticated Member List Orders call: the query in, the raw `{ orders }` response out. */
+export type MemberOrdersCall = (query: MemberOrdersQuery) => Promise<Raw>;
+
+const orders = wixModule(ordersModule);
+const sharedSeam: MemberOrdersCall = (query) => orders.memberListOrders({ planIds: query.planIds, orderStatuses: [...query.orderStatuses] }) as Promise<Raw>;
+
+/**
+ * True when the current member has an ACTIVE order for one of `requiredPlanIds`. Member-only —
+ * throws when the call is refused (a visitor, an expired session); the store shields that.
+ * `call` defaults to the shared seam; pass one bound to the member's client on a manual-client stack.
+ */
+export async function hasActiveOrderFor(requiredPlanIds: string[], call: MemberOrdersCall = sharedSeam): Promise<boolean> {
+  const res = await call(memberOrdersQuery(requiredPlanIds));
+  return hasPlanAccess(res?.orders as Raw[] | undefined, requiredPlanIds);
+}

package/skills/wix-headless-templates/pricing-plans/project/src/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;
+      }
+    },
+  };
+}