@wix/agent-skills 1.26.0 → 1.28.0

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;
+      }
+    },
+  };
+}

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

@@ -0,0 +1,212 @@
+// Plan rules and DTO mapping — transport-agnostic, imported by BOTH transports: ./plans.ts (the
+// SDK, managed Astro and React) and the REST twin in templates/pricing-plans/rest/plans.ts
+// (fetch, a static site or a port to another language). Every rule about prices, fees, billing
+// labels, duration, 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, PlanFee, 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;
+  /** Specific plans by id (a featured strip, the plans a paywall requires). */
+  ids?: string[];
+}
+
+/**
+ * The Query Plans body both transports send: only PUBLIC plans (a HIDDEN plan is merchant-assigned
+ * and never listed), cursor paging, the slug when one plan is wanted, `id: { $in }` for a set of
+ * plans. REST filters on `id`; the SDK builder spells the same filters as `.eq("visibility",
+ * "PUBLIC")`, `.eq("slug", slug)`, `.in("_id", ids)`.
+ */
+export function plansQuery({ limit = 100, slug, ids }: 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;
+  if (ids) {
+    if (!ids.length) throw new Error("At least one plan id is required.");
+    filter.id = { $in: ids };
+  }
+  return { filter, cursorPaging: { limit } };
+}
+
+// ---- price rules ----------------------------------------------------------------------------------
+
+export interface FormatOptions {
+  /**
+   * BCP 47 locale for the money strings. Default undefined = the runtime's locale — in a browser the
+   * visitor's, on Astro SSR the SERVER's (baked into the DTO for every visitor). A brief with a known
+   * market pins it ("de-DE").
+   */
+  locale?: string;
+}
+
+/**
+ * A decimal-string amount → "€25.00" in the plan's currency; "" when the value isn't a finite
+ * number (an absent fee amount). Never assumes USD: the currency is the plan's, site-derived.
+ */
+export function formatAmount(value: string | number | undefined, currency: string | undefined, locale?: string): string {
+  if (value == null || value === "") return "";
+  const n = Number(value);
+  if (!Number.isFinite(n)) return "";
+  // No currency → a bare number, never an assumed "$": the plan's currency is site-derived and always sent.
+  if (!currency) return new Intl.NumberFormat(locale).format(n);
+  try {
+    return new Intl.NumberFormat(locale, { style: "currency", currency }).format(n);
+  } catch {
+    return `${value} ${currency}`;
+  }
+}
+
+/** "€29.00" for the plan's currency; "Free" for a zero amount. Callers pass a valid amount — see `planAmount`. */
+export function formatPrice(value: string | number, currency: string | undefined, locale?: string): string {
+  return Number(value) === 0 ? "Free" : formatAmount(value, currency, locale);
+}
+
+/**
+ * The plan's amount — `pricingVariants[0].pricingStrategies[0].flatRate.amount`, a decimal string
+ * ("0" = free) — or undefined for a MALFORMED plan: no pricing variant, or an amount that isn't a
+ * number. A malformed plan is dropped by the mappers (never rendered "Free" with a live CTA): the
+ * hosted checkout would charge something the card didn't show.
+ */
+export function planAmount(raw: Raw): string | undefined {
+  const variant: Raw | undefined = raw.pricingVariants?.[0];
+  const amount = variant?.pricingStrategies?.[0]?.flatRate?.amount;
+  if (variant == null || amount == null || amount === "" || !Number.isFinite(Number(amount))) return undefined;
+  return String(amount);
+}
+
+/**
+ * Additional fees — `pricingVariants[0].fees[]`, each `{ name, fixedAmountOptions: { amount } }`,
+ * charged with the first payment (appliedAt FIRST_PAYMENT is the only value). Formatted in the
+ * plan's currency; a fee without a numeric amount is skipped.
+ */
+export function planFees(variant: Raw | undefined, currency: string | undefined, locale?: string): PlanFee[] {
+  return ((variant?.fees ?? []) as Raw[])
+    .map((f) => ({ name: String(f.name ?? ""), amount: formatAmount(f.fixedAmountOptions?.amount, currency, locale) }))
+    .filter((f) => f.amount);
+}
+
+// ---- billing rules --------------------------------------------------------------------------------
+
+/**
+ * Recurring vs one-time, from billingTerms: endType UNTIL_CANCELLED with a billingCycle recurs;
+ * CYCLES_COMPLETED recurs unless billingCycleCount is 1 (bill once, then end); no cycle never recurs.
+ * billingCycleCount is a STRING on both transports ("1") — compare as a string.
+ */
+export function isRecurring(terms: Raw | undefined): boolean {
+  if (!terms?.billingCycle) return false;
+  if (terms.endType === "UNTIL_CANCELLED") return true;
+  if (terms.endType === "CYCLES_COMPLETED") return String(terms.cyclesCompletedDetails?.billingCycleCount) !== "1";
+  return false;
+}
+
+const periodLabel = (cycle: Raw, total: number): string => {
+  const period = String(cycle.period ?? "MONTH").toLowerCase();
+  return `${total} ${period}${total === 1 ? "" : "s"}`;
+};
+
+/**
+ * billingTerms → the CADENCE only: "per month", "every 3 months", "one-time". How long the plan
+ * lasts is `durationLabel`, a separate value — "per month × 6" folded both into one string and read
+ * wrong for a one-time plan with a cycle. billingCycle.count is a STRING ("1") — Number() it.
+ */
+export function billingLabel(terms: Raw | undefined): string {
+  if (!isRecurring(terms)) return "one-time";
+  const cycle: Raw = terms!.billingCycle;
+  const count = Number(cycle.count ?? 1) || 1;
+  const period = String(cycle.period ?? "MONTH").toLowerCase();
+  return count === 1 ? `per ${period}` : `every ${count} ${period}s`;
+}
+
+/**
+ * billingTerms → how long the plan stays valid, or null when it runs until canceled (endType
+ * UNTIL_CANCELLED, or no terms/cycle at all). Recurring for N cycles → count × N ("6 months" for a
+ * monthly plan over 6 cycles); one-time with a cycle → that cycle ("1 month").
+ */
+export function durationLabel(terms: Raw | undefined): string | null {
+  const cycle: Raw | undefined = terms?.billingCycle;
+  if (!terms || !cycle || terms.endType === "UNTIL_CANCELLED") return null;
+  const count = Number(cycle.count ?? 1) || 1;
+  const cycles = isRecurring(terms) ? Number(terms.cyclesCompletedDetails?.billingCycleCount ?? 1) || 1 : 1;
+  return periodLabel(cycle, count * cycles);
+}
+
+// ---- image ----------------------------------------------------------------------------------------
+
+/** The size every plan image resolves at — landscape, matching the 16:9 band the detail page shows. */
+export const PLAN_IMAGE_WIDTH = 1200;
+export const PLAN_IMAGE_HEIGHT = 675;
+/** height / width — pass to imgAttrs(plan.imageUrl, sizes, PLAN_IMAGE_RATIO) so srcset candidates keep the aspect. */
+export const PLAN_IMAGE_RATIO = PLAN_IMAGE_HEIGHT / PLAN_IMAGE_WIDTH;
+
+/**
+ * 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); fees likewise. Wix
+ * settles the actual charge, tax, and schedule at the hosted checkout. Null for a malformed plan
+ * (see `planAmount`) — callers drop it (`toSummaries`) or treat it as not found.
+ */
+export function toSummary(raw: Raw, imgSrc: ImgSrc, { locale }: FormatOptions = {}): PlanSummary | null {
+  const amount = planAmount(raw);
+  if (amount === undefined) return null;
+  const variant: Raw = raw.pricingVariants[0];
+  const free = Number(amount) === 0;
+  return {
+    id: id(raw),
+    slug: raw.slug ?? "",
+    name: raw.name ?? "",
+    description: raw.description ?? "",
+    pricingVariantId: id(variant),
+    price: formatPrice(amount, raw.currency, locale),
+    free,
+    billing: free ? "" : billingLabel(variant.billingTerms),
+    duration: durationLabel(variant.billingTerms),
+    fees: planFees(variant, raw.currency, locale),
+    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), PLAN_IMAGE_WIDTH, PLAN_IMAGE_HEIGHT),
+  };
+}
+
+/** A list of raw plans → cards, with every malformed plan dropped (one console.warn each, so the grid still renders). */
+export function toSummaries(raws: Raw[], imgSrc: ImgSrc, options: FormatOptions = {}): PlanSummary[] {
+  const out: PlanSummary[] = [];
+  for (const raw of raws) {
+    const summary = toSummary(raw, imgSrc, options);
+    if (summary) out.push(summary);
+    else console.warn(`Pricing plan "${raw?.name ?? id(raw)}" has no numeric price — not shown.`);
+  }
+  return out;
+}
+
+export function toDetail(raw: Raw, imgSrc: ImgSrc, options: FormatOptions = {}): PlanDetail | null {
+  const summary = toSummary(raw, imgSrc, options);
+  return summary ? { ...summary, termsAndConditions: raw.termsAndConditions ?? "" } : null;
+}

package/skills/wix-headless-templates/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-templates/pricing-plans/app/wix/pricing-plans/plans.ts

@@ -0,0 +1,54 @@
+// 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 templates/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).
+// Each function builds the shared query body (plansQuery — the limit rule, the filters) and spells
+// it with the SDK builder. A plan without a numeric price is malformed and never returned
+// (plans-core `planAmount`).
+// 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 { plansQuery, toDetail, toSummaries, type FormatOptions, type Raw } from "./plans-core";
+import type { PlanDetail, PlanSummary } from "./types";
+
+export type { FormatOptions };
+
+const plans = wixModule(plansV3);
+
+export interface FetchPlansOptions extends FormatOptions {
+  /** 1–100, default 100. */
+  limit?: number;
+}
+
+/** List the public plans for the pricing grid, as card-ready DTOs. */
+export async function fetchPlans({ limit = 100, locale }: FetchPlansOptions = {}): Promise<PlanSummary[]> {
+  const q = plansQuery({ limit });
+  const res = await plans.queryPlans().eq("visibility", "PUBLIC").limit(q.cursorPaging.limit).find();
+  return toSummaries((res.items ?? []) as Raw[], imgSrc, { locale });
+}
+
+/** Specific public plans by id (a featured strip, the plans a paywall requires), in the API's order. Unknown ids are simply absent. */
+export async function fetchPlansByIds(ids: string[], { locale }: FormatOptions = {}): Promise<PlanSummary[]> {
+  const q = plansQuery({ ids, limit: Math.min(Math.max(ids.length, 1), 100) });
+  const res = await plans.queryPlans().eq("visibility", "PUBLIC").in("_id", ids).limit(q.cursorPaging.limit).find();
+  return toSummaries((res.items ?? []) as Raw[], imgSrc, { locale });
+}
+
+/** Fetch one public plan by its URL slug. Null when not found (or malformed). */
+export async function fetchPlanBySlug(slug: string, { locale }: FormatOptions = {}): Promise<PlanDetail | null> {
+  const q = plansQuery({ limit: 1, slug });
+  const res = await plans.queryPlans().eq("visibility", "PUBLIC").eq("slug", slug).limit(q.cursorPaging.limit).find();
+  const raw = res.items?.[0];
+  return raw ? toDetail(raw as Raw, imgSrc, { locale }) : null;
+}
+
+/** Fetch one public plan by id. Null when not found (or malformed). */
+export async function fetchPlanById(planId: string, { locale }: FormatOptions = {}): Promise<PlanDetail | null> {
+  const q = plansQuery({ limit: 1, ids: [planId] });
+  const res = await plans.queryPlans().eq("visibility", "PUBLIC").eq("_id", planId).limit(q.cursorPaging.limit).find();
+  const raw = res.items?.[0];
+  return raw ? toDetail(raw as Raw, imgSrc, { locale }) : null;
+}