@wix/agent-skills 1.20.1 → 1.22.0

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

@@ -1,106 +0,0 @@
-// 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

@@ -1,64 +0,0 @@
-// 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,27 +0,0 @@
-// 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);
-
-/** 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) => 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, imgSrc) : null;
-}

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

@@ -1,43 +0,0 @@
-// 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,22 +0,0 @@
-// 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. 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";
-
-export type { PurchaseOptions };
-
-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, 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/app/wix/pricing-plans/types.ts

@@ -1,30 +0,0 @@
-// Pricing Plans DTOs — the serializable shapes every hook, component, and page consumes.
-// Plain JSON: safe as Astro island props or across server/client boundaries. Images are
-// resolved https URLs; every displayable price is a ready formatted string.
-
-/** A plan as a pricing-grid card needs it. */
-export interface PlanSummary {
-  id: string;
-  slug: string;
-  name: string;
-  description: string;
-  /** Formatted price (e.g. "$29.00"); "Free" when the plan costs nothing. */
-  price: string;
-  free: boolean;
-  /** Display-ready cadence: "per month", "every 3 months", "one-time"; "" for free plans. */
-  billing: string;
-  /** Free-trial length in days (null when the plan has none). */
-  freeTrialDays: number | null;
-  /** Display-only feature bullets, in order. */
-  perks: string[];
-  /** False → a PUBLIC but merchant-assigned plan: show it without a subscribe CTA. */
-  buyable: boolean;
-  /** Resolved https URL ("" when the plan has no image). */
-  imageUrl: string;
-}
-
-/** A plan as the detail page needs it. */
-export interface PlanDetail extends PlanSummary {
-  /** Terms & conditions as plain text ("" when not set) — render as-is (pre-wrap). */
-  termsAndConditions: string;
-}

package/skills/wix-headless-fast/references/pricing-plans/app-astro/layouts/SiteLayout.astro

@@ -1,41 +0,0 @@
----
-// 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-fast/references/pricing-plans/app-astro/pages/plans/[slug].astro

@@ -1,40 +0,0 @@
----
-// 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 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">
-    {plan.imageUrl && (
-      <div class="mb-6 aspect-[16/9] overflow-hidden rounded-xl bg-secondary">
-        <img src={plan.imageUrl} 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-fast/references/pricing-plans/app-astro/pages/plans.astro

@@ -1,21 +0,0 @@
----
-// 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>