@wix/agent-skills 1.25.0 → 1.27.0

package/skills/wix-headless-templates/pricing-plans/app/components/pricing-plans/PlanDetailView.tsx

@@ -0,0 +1,54 @@
+// REFERENCE detail surface: price/billing/duration block + fees + perks + terms + the shipped SubscribeButton, on
+// the @theme tokens. Correct and complete; per the skill's model you design and build your own
+// (the plan itself arrives as an SSR-fetched DTO prop; the purchase control is SubscribeButton).
+import SubscribeButton from "./SubscribeButton";
+import type { PlanDetail } from "../../wix/pricing-plans/types";
+
+export default function PlanDetailView({ plan }: { plan: PlanDetail }) {
+  return (
+    <div>
+      <p>
+        <span className="text-4xl font-bold tracking-tight text-foreground">{plan.price}</span>
+        {plan.billing && <span className="ml-2 text-muted-foreground">{plan.billing}</span>}
+        {plan.duration && <span className="text-muted-foreground"> · valid {plan.duration}</span>}
+      </p>
+      {/* Fees are part of the price — under it, before the CTA, never hidden. */}
+      {plan.fees.map((fee) => (
+        <p key={fee.name + fee.amount} className="mt-1 text-sm text-muted-foreground">
+          + {fee.amount} {fee.name}
+        </p>
+      ))}
+      {plan.freeTrialDays !== null && (
+        <p className="mt-1 text-sm text-muted-foreground">{plan.freeTrialDays}-day free trial</p>
+      )}
+
+      {plan.perks.length > 0 && (
+        <ul className="mt-6 space-y-2.5">
+          {plan.perks.map((perk) => (
+            <li key={perk} className="flex gap-2 text-sm text-foreground">
+              <span className="text-muted-foreground" aria-hidden="true">
+                ✓
+              </span>
+              <span>{perk}</span>
+            </li>
+          ))}
+        </ul>
+      )}
+
+      <div className="mt-6">
+        <SubscribeButton plan={plan} className="rounded-control bg-primary px-8 py-3 text-sm font-semibold text-primary-foreground transition-opacity hover:opacity-90 disabled:opacity-50">
+          {plan.free ? "Get this plan" : `Subscribe · ${plan.price}`}
+        </SubscribeButton>
+      </div>
+
+      {plan.termsAndConditions && (
+        <div className="mt-10 border-t border-border pt-5">
+          <p className="eyebrow">Terms &amp; conditions</p>
+          <p className="mt-2 whitespace-pre-wrap text-sm leading-relaxed text-muted-foreground">
+            {plan.termsAndConditions}
+          </p>
+        </div>
+      )}
+    </div>
+  );
+}

package/skills/wix-headless-templates/pricing-plans/app/components/pricing-plans/PlansView.tsx

@@ -0,0 +1,108 @@
+// REFERENCE pricing surface: plan cards in a grid on the @theme tokens. Correct and
+// complete; per the skill's model you design and build your own on usePlans, with the shipped
+// SubscribeButton as each card's purchase control.
+import type { ComponentType, ReactNode } from "react";
+import { usePlans } from "../../hooks/pricing-plans/usePlans";
+import SubscribeButton from "./SubscribeButton";
+import type { PlanSummary } from "../../wix/pricing-plans/types";
+
+export interface LinkLikeProps {
+  href: string;
+  className?: string;
+  children?: ReactNode;
+}
+
+const PlainLink = ({ href, className, children }: LinkLikeProps) => (
+  <a href={href} className={className}>
+    {children}
+  </a>
+);
+
+export interface PlanCardProps {
+  plan: PlanSummary;
+  planHref?: (slug: string) => string;
+  LinkComponent?: ComponentType<LinkLikeProps>;
+}
+
+export function PlanCard({ plan, planHref = (slug) => `/plans/${slug}`, LinkComponent = PlainLink }: PlanCardProps) {
+  return (
+    <div className="flex h-full flex-col rounded-lg border border-border bg-background p-6">
+      <p className="text-base font-semibold text-foreground">{plan.name}</p>
+      {plan.description && <p className="mt-1 text-sm text-muted-foreground">{plan.description}</p>}
+      <p className="mt-4">
+        <span className="text-3xl font-bold tracking-tight text-foreground">{plan.price}</span>
+        {plan.billing && <span className="ml-1.5 text-sm text-muted-foreground">{plan.billing}</span>}
+        {plan.duration && <span className="text-sm text-muted-foreground"> · valid {plan.duration}</span>}
+      </p>
+      {/* Fees are part of the price — under it, before the CTA, never hidden. */}
+      {plan.fees.map((fee) => (
+        <p key={fee.name + fee.amount} className="mt-1 text-sm text-muted-foreground">
+          + {fee.amount} {fee.name}
+        </p>
+      ))}
+      {plan.freeTrialDays !== null && (
+        <p className="mt-1 text-xs font-medium text-muted-foreground">{plan.freeTrialDays}-day free trial</p>
+      )}
+      {plan.perks.length > 0 && (
+        <ul className="mt-4 space-y-2">
+          {plan.perks.map((perk) => (
+            <li key={perk} className="flex gap-2 text-sm text-foreground">
+              <span className="text-muted-foreground" aria-hidden="true">
+                ✓
+              </span>
+              <span>{perk}</span>
+            </li>
+          ))}
+        </ul>
+      )}
+      <div className="mt-auto grid gap-2 pt-6">
+        <SubscribeButton plan={plan} assignedText={null} />
+        <LinkComponent
+          href={planHref(plan.slug)}
+          className="rounded-control border border-border px-6 py-2.5 text-center text-sm font-semibold text-foreground no-underline transition-colors hover:bg-secondary"
+        >
+          View details
+        </LinkComponent>
+      </div>
+    </div>
+  );
+}
+
+export interface PlansViewProps {
+  initialPlans?: PlanSummary[];
+  emptyMessage?: string;
+  planHref?: PlanCardProps["planHref"];
+  LinkComponent?: ComponentType<LinkLikeProps>;
+  CardComponent?: ComponentType<PlanCardProps>;
+}
+
+export default function PlansView({
+  initialPlans,
+  emptyMessage = "No plans yet — check back soon.",
+  planHref,
+  LinkComponent,
+  CardComponent = PlanCard,
+}: PlansViewProps) {
+  const { plans, error } = usePlans({ initialPlans });
+
+  return (
+    <div>
+      {error && <p className="mb-4 text-sm text-destructive">{error}</p>}
+      {plans === null ? (
+        <div className="grid grid-cols-1 gap-6 sm:grid-cols-2 lg:grid-cols-3" aria-busy="true">
+          {Array.from({ length: 3 }, (_, i) => (
+            <div key={i} className="h-80 animate-pulse rounded-lg bg-secondary" />
+          ))}
+        </div>
+      ) : plans.length === 0 ? (
+        <p className="py-16 text-center text-muted-foreground">{emptyMessage}</p>
+      ) : (
+        <div className="grid grid-cols-1 gap-6 sm:grid-cols-2 lg:grid-cols-3">
+          {plans.map((p) => (
+            <CardComponent key={p.id} plan={p} planHref={planHref} LinkComponent={LinkComponent} />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

package/skills/wix-headless-templates/pricing-plans/app/components/pricing-plans/RequirePlan.tsx

@@ -0,0 +1,87 @@
+// The gate for plan-holders-only content — wire as-is around anything a plan unlocks. It owns the
+// rules a paywall gets wrong when rewritten: nothing gated renders while the session or the orders
+// read is unsettled; a visitor gets the way in (log in, with a return to this page); a member
+// without an active order for one of the plans gets the way to the plans; a failed read keeps the
+// content closed and shows the message. Access itself is usePlanAccess → hasActiveOrderFor: an
+// ACTIVE order for one of `planIds`, nothing here decides that.
+//
+// The session comes from the `members` vertical (its useMember()) — pass it in; this vertical does
+// not ship it. Routing-free: plain <a> links, both hrefs overridable. Client-side only (the
+// session is a browser cookie) — mount it client:only="react" on Astro, like members' RequireAuth.
+import type { ReactNode } from "react";
+import { usePlanAccess, type PlanAccessSession, type UsePlanAccessOptions } from "../../hooks/pricing-plans/usePlanAccess";
+
+export interface RequirePlanProps extends UsePlanAccessOptions {
+  /** The plans that unlock the content (any one of them). */
+  planIds: string[];
+  /** The members session: `useMember()` from the members vertical. */
+  session: PlanAccessSession;
+  children: ReactNode;
+  /** Where a visitor logs in; `{returnTo}` is replaced with the current path. */
+  loginHref?: string;
+  /** Where a member without a plan goes to get one. */
+  plansHref?: string;
+  /** Rendered for a member without an active plan instead of the default prompt. */
+  fallback?: ReactNode;
+}
+
+export default function RequirePlan({
+  planIds,
+  session,
+  children,
+  loginHref = "/login?returnTo={returnTo}",
+  plansHref = "/plans",
+  fallback,
+  ...options
+}: RequirePlanProps) {
+  const { hasAccess, loading, error } = usePlanAccess(planIds, session, options);
+
+  if (loading) {
+    return (
+      <div className="py-16 text-center text-muted-foreground" aria-busy="true">
+        Loading…
+      </div>
+    );
+  }
+
+  if (hasAccess) return <>{children}</>;
+
+  if (error) {
+    return (
+      <p className="py-8 text-center text-sm text-destructive" role="alert">
+        {error}
+      </p>
+    );
+  }
+
+  if (!session.loggedIn) {
+    const returnTo = typeof window !== "undefined" ? window.location.pathname : "/";
+    return (
+      <div className="mx-auto max-w-md rounded-lg border border-border p-8 text-center">
+        <p className="text-sm text-muted-foreground">This content is for plan members. Log in to continue.</p>
+        <a
+          href={loginHref.replace("{returnTo}", encodeURIComponent(returnTo))}
+          className="mt-4 inline-block rounded-control bg-primary px-5 py-2 text-sm font-medium text-primary-foreground no-underline transition-opacity hover:opacity-90"
+        >
+          Log in / Sign up
+        </a>
+      </div>
+    );
+  }
+
+  return (
+    <>
+      {fallback ?? (
+        <div className="mx-auto max-w-md rounded-lg border border-border p-8 text-center">
+          <p className="text-sm text-muted-foreground">This content is included with a plan you don't have yet.</p>
+          <a
+            href={plansHref}
+            className="mt-4 inline-block rounded-control bg-primary px-5 py-2 text-sm font-medium text-primary-foreground no-underline transition-opacity hover:opacity-90"
+          >
+            See plans
+          </a>
+        </div>
+      )}
+    </>
+  );
+}

package/skills/wix-headless-templates/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-control 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-destructive" role="alert">{error}</p>}
+    </div>
+  );
+}

package/skills/wix-headless-templates/pricing-plans/app/hooks/pricing-plans/usePlanAccess.ts

@@ -0,0 +1,31 @@
+// React binding of the plan-access store (wix/pricing-plans/plan-access-store.ts) — the paywall
+// logic lives there, framework-free; this hook subscribes to one instance per gated surface and
+// feeds it the members session. The session is the `members` vertical's `useMember()` result
+// (`{ loggedIn, loading }`) — this vertical does not ship it, so the caller passes it:
+//   const session = useMember(); const { hasAccess, loading } = usePlanAccess(planIds, session);
+// SSR-friendly: `initialAccess` resolved in frontmatter renders at once. Astro islands and React
+// SPAs use this; a static page, Vue, or Svelte uses the store directly.
+import { useEffect, useRef, useSyncExternalStore } from "react";
+import {
+  createPlanAccessStore,
+  type PlanAccessSession,
+  type PlanAccessState,
+  type PlanAccessStore,
+  type PlanAccessStoreOptions,
+} from "../../wix/pricing-plans/plan-access-store";
+
+export type { PlanAccessSession };
+export type UsePlanAccessOptions = Omit<PlanAccessStoreOptions, "planIds">;
+export type UsePlanAccess = PlanAccessState;
+
+/** `planIds` are read once, on mount — a surface gated by other plans is another mount. */
+export function usePlanAccess(planIds: string[], session: PlanAccessSession, options: UsePlanAccessOptions = {}): UsePlanAccess {
+  const ref = useRef<PlanAccessStore | null>(null);
+  if (!ref.current) ref.current = createPlanAccessStore({ planIds, ...options });
+  const store = ref.current;
+  useEffect(() => {
+    store.check(session);
+    return () => store.stop();
+  }, [store, session.loggedIn, session.loading]);
+  return useSyncExternalStore(store.subscribe, store.getState, store.getState);
+}

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

@@ -0,0 +1,16 @@
+// 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 type UsePlanPurchase = PlanPurchaseState & Pick<PlanPurchaseStore, "purchase">;
+
+export function usePlanPurchase(): UsePlanPurchase {
+  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-templates/pricing-plans/app/hooks/pricing-plans/usePlans.ts

@@ -0,0 +1,22 @@
+// 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 type UsePlansOptions = PlansStoreOptions;
+
+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(() => {
+    store.start();
+    return () => store.stop();
+  }, [store]);
+  return useSyncExternalStore(store.subscribe, store.getState, store.getState);
+}

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