@wix/agent-skills 1.16.3 → 1.18.0

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

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

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

@@ -0,0 +1,39 @@
+// Plans listing. SSR-friendly: pass server-fetched data as `initialPlans` (Astro frontmatter
+// / server component) and no client fetch happens; a SPA passes nothing.
+import { useEffect, useState } from "react";
+import { fetchPlans } from "../../wix/pricing-plans/plans";
+import type { PlanSummary } from "../../wix/pricing-plans/types";
+
+export interface UsePlansOptions {
+  initialPlans?: PlanSummary[];
+}
+
+export interface UsePlans {
+  /** null while the first load is in flight — render skeletons, not an empty state. */
+  plans: PlanSummary[] | null;
+  error: string | null;
+}
+
+export function usePlans({ initialPlans }: UsePlansOptions = {}): UsePlans {
+  const [plans, setPlans] = useState<PlanSummary[] | null>(initialPlans ?? null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let alive = true;
+    if (!initialPlans) {
+      fetchPlans()
+        .then((p) => alive && setPlans(p))
+        .catch((e) => {
+          if (!alive) return;
+          setPlans([]);
+          setError(e instanceof Error ? e.message : String(e));
+        });
+    }
+    return () => {
+      alive = false;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  return { plans, error };
+}

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

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

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

@@ -0,0 +1,45 @@
+// The purchase flow: one call that turns a plan id into a Wix-hosted checkout URL.
+// Purchasing a plan is a MEMBER action, but the hosted flow handles member login/signup,
+// the order form, and payment itself — so this works from an anonymous visitor session.
+// Never create the order yourself (orders.createOnlineOrder needs a logged-in member and
+// still leaves payment unhandled); never hand-build a checkout URL. Copy as-is.
+// 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";
+
+const redirects = wixModule(redirectsModule);
+
+type Raw = Record<string, any>;
+
+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;
+}
+
+/** Start the hosted purchase for a plan; resolves to the URL to send the browser to. */
+export async function purchasePlan(
+  planId: string,
+  { thankYouPageUrl, postFlowUrl }: PurchaseOptions = {},
+): Promise<string> {
+  if (!planId) throw new Error("A plan id is required to start checkout.");
+  const href = typeof window !== "undefined" ? window.location.href : "";
+  const session: Raw = await redirects.createRedirectSession({
+    paidPlansCheckout: { planId },
+    callbacks: {
+      postFlowUrl: postFlowUrl ?? (href || undefined),
+      ...(thankYouPageUrl ? { thankYouPageUrl } : {}),
+    },
+  });
+  const url = session?.redirectSession?.fullUrl;
+  if (!url) throw new Error("Checkout couldn't start — please try again.");
+  return url;
+}

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

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

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

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

@@ -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>