@wix/agent-skills 1.26.0 → 1.28.0

package/skills/wix-headless-templates/pricing-plans/seed/SEED.md

@@ -0,0 +1,93 @@
+# Pricing Plans — seeding
+
+Seed by **running `seed-pricing-plans.mjs` with a plan file** — don't hand-write the REST
+calls. The script mints its own site token via the Wix CLI (logged-in session +
+`wix.config.json` required), installs the Pricing Plans app if needed, and creates everything
+in the right order.
+
+```bash
+# from the project root (where wix.config.json lives):
+node <SKILL_ROOT>/templates/pricing-plans/seed/seed-pricing-plans.mjs plan.json
+```
+
+`plan.json` is plain data — write it from the brief. **Default to 3 plans** — a tier ladder
+the grid can render (e.g. free / monthly with a trial / yearly with a setup fee), each with 3–4
+perks; together they exercise every price shape the UI handles (free, cadence, trial badge, fee
+line). Plans have no seedable images (the owner adds one per plan in the dashboard).
+
+```json
+{
+  "plans": [
+    { "name": "Community", "type": "free",
+      "description": "Get a taste — member perks, zero commitment.",
+      "perks": ["Member-only newsletter", "Community events access"] },
+    { "name": "Studio Membership", "price": "29.00",
+      "type": "recurring", "billingCycle": { "period": "MONTH", "count": 1 },
+      "freeTrialDays": 14,
+      "description": "The full experience, month to month.",
+      "perks": ["Unlimited group classes", "10% off workshops", "Priority booking"] },
+    { "name": "Annual Pass", "price": "290.00",
+      "type": "recurring", "billingCycle": { "period": "YEAR", "count": 1 },
+      "setupFee": { "name": "Registration fee", "amount": "25.00" },
+      "description": "Two months free, billed yearly.",
+      "perks": ["Everything in Studio Membership", "2 guest passes", "Annual member gift"] }
+  ]
+}
+```
+
+- `type` — `"recurring"` (default; `billingCycle` defaults to `{ "period": "MONTH", "count": 1 }`),
+  `"one-time"` (bills once, then ends; `billingCycle: null` makes it never expire), or
+  `"free"` (amount forced to `"0"` + a per-member-lifetime purchase limit).
+- `price` — a decimal string (`"29.00"`; a number is stringified). Currency is site-derived —
+  never sent per plan.
+- `currency` — 3-letter ISO code at the top of the plan, set **only when the brief names one**: a
+  sentence about currency, or a price written with its unit ("9 dollars", "$9", "€20"). Do **not**
+  infer it from a language, a country, or an address. The seed sets the site to it before creating
+  anything, because prices are stored in the site currency at create time; a new site starts in the
+  currency of the account that created it, not the business's.
+- `freeTrialDays` — days before the first charge (a number, up to 999), on a paid plan; the card
+  shows "14-day free trial". Omit for none.
+- `setupFee` — `{ "name", "amount" }`: one additional fee charged with the first payment, shown
+  with the price ("+ €25.00 Registration fee"). `fees` is the array form (up to 5). Amounts are
+  decimal strings in the site currency, like `price`. Only when the brief names a fee — never invent one.
+- `perks` — display-only bullets on the plan card; they grant nothing by themselves.
+- `termsAndConditions` (plain text), `visibility` (`"PUBLIC"`), `buyable` (`true`) — optional
+  overrides. A `buyable: false` plan renders without a subscribe CTA (merchant-assigned).
+
+## Covering bookings services (only when bookings is also seeded)
+
+A plan can COVER bookings services — members then book them with the membership. The link
+goes through the Benefit Programs API, not the plan object, keyed by the **bookings seed's
+service ids** — so seed bookings FIRST, then pass the ids:
+
+```json
+{ "name": "Studio Membership", "price": "29.00",
+  "perks": ["Unlimited group classes"],
+  "coveredServiceIds": ["<bookings service id>", "…"] }
+```
+
+Unlimited coverage is the default; a limited pack (e.g. 8 sessions) instead uses
+`"bookingsCoverage": { "serviceIds": [...], "creditAmount": 8 }`. A plans-only run just
+omits both — coverage is skipped automatically.
+
+**Seeding is additive — never delete or overwrite existing content**; ask first if a cleanup
+seems needed.
+
+## Supplied content
+
+The general rules are in `templates/shared/SUPPLIED-CONTENT.md`. For pricing plans, each plan the
+user lists is one entry. Its name becomes `name`; a price with a billing period becomes `price`
+with `type: "recurring"` and the matching `billingCycle`; a price paid once becomes
+`type: "one-time"`; no price means `type: "free"`; a list of features or benefits becomes `perks`;
+the description becomes `description`; a trial ("first two weeks free") becomes `freeTrialDays`; a
+one-off joining/registration/setup charge becomes `setupFee`. A price with no period is a question
+for the user.
+
+## Escape hatch — individual functions
+`setupPricingPlans` composes exported steps — `installPricingPlansApp`, `createPlans`,
+`attachBookingsCoverage` (and its `getProgramDefinition`, `createPoolDefinition`,
+`createBenefitItems` sub-steps), plus `makeCtx()` — import them only for a partial re-seed.
+
+## Reference
+Unexpected shape or an uncovered operation → read the live Wix API reference; every call the script
+makes carries a `docs:` line with its reference page.

package/skills/wix-headless-templates/pricing-plans/seed/read-site.mjs

@@ -0,0 +1,22 @@
+// What the site sells as plans: public pricing plans.
+//   node <SKILL_ROOT>/templates/pricing-plans/seed/read-site.mjs [--site <siteId>] [--limit <n>]
+import { runReader } from "../../shared/seed/read-site.mjs";
+
+const PRICING_PLANS_APP_ID = "1522827f-c56c-a5c9-2ac9-00f9e6ae12d3";
+const D = "https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans";
+
+await runReader({
+  vertical: "pricing-plans",
+  appId: PRICING_PLANS_APP_ID,
+  async read(api, { limit }) {
+    const r = await api.call({ path: "/pricing-plans/v3/plans/query", body: { query: { filter: { visibility: "PUBLIC" }, cursorPaging: { limit } } }, docs: `${D}/plans-v3/query-plans` });
+    return {
+      planCount: r.pagingMetadata?.total ?? (r.plans ?? []).length,
+      plans: (r.plans ?? []).map((p) => {
+        const v = p.pricingVariants?.[0]; const s = v?.pricingStrategies?.[0];
+        // perks is an ARRAY of { id, description } (not { values }); fees[].fixedAmountOptions.amount is the setup-fee surface.
+        return { name: p.name, slug: p.slug ?? null, visibility: p.visibility, price: s?.flatRate?.amount ?? null, currency: p.currency ?? null, billing: v?.billingTerms?.billingCycle ? `${v.billingTerms.billingCycle.count} ${v.billingTerms.billingCycle.period}` : (v?.billingTerms?.startType ?? null), freeTrialDays: v?.freeTrialDays || null, fees: (v?.fees ?? []).map((f) => ({ name: f.name, amount: f.fixedAmountOptions?.amount ?? null })), perks: (p.perks ?? []).length };
+      }),
+    };
+  },
+});

package/skills/wix-headless-templates/pricing-plans/seed/seed-pricing-plans.mjs

@@ -0,0 +1,301 @@
+// Pricing Plans seed — a BUILD-TIME script, never shipped in the app. Run from the project
+// root (where wix.config.json lives) with a plan file:
+//
+//   node <SKILL_ROOT>/templates/pricing-plans/seed/seed-pricing-plans.mjs plan.json
+//
+// It mints its own site token via the Wix CLI, installs the Wix Pricing Plans app if needed,
+// creates the plans (Plans V3 — one create call per plan; there is no bulk-create), and —
+// only when a plan carries bookings service ids — wires the plan to COVER those services
+// through the Benefit Programs API. Prints a JSON result to stdout.
+//
+// Plan shape (see SEED.md):
+//   { "plans": [{ "name", "description"?, "price"? (decimal string; a number is stringified),
+//                 "type"?: "recurring"|"one-time"|"free",
+//                 "billingCycle"?: { "period": "DAY"|"WEEK"|"MONTH"|"YEAR", "count" } | null,
+//                 "freeTrialDays"?: 14, "setupFee"?: { "name", "amount" } | "fees"?: [{ "name", "amount" }],
+//                 "perks"?: ["..."], "termsAndConditions"?, "visibility"?, "buyable"?,
+//                 "coveredServiceIds"?: ["<bookings service id>"],
+//                 "bookingsCoverage"?: { "serviceIds"?, "creditAmount"? } }] }
+//
+// Seeding is ADDITIVE — never deletes or overwrites existing content. Unexpected shapes →
+// read the live API reference; every call below
+// carries a docs: line with its reference page.
+import { setSiteCurrency } from "../../shared/seed/site.mjs";
+import { seedSiteId } from "../../shared/seed/site-context.mjs";
+import { wixToken } from "../../shared/seed/wix-cli.mjs";
+import { readFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+
+const API = "https://www.wixapis.com";
+const PRICING_PLANS_APP_ID = "1522827f-c56c-a5c9-2ac9-00f9e6ae12d3";
+const BOOKINGS_APP_ID = "13d21c63-b5ec-5912-8397-c3a5ddb27a97"; // coverage providerAppId — NOT the Plans id
+const PP_NAMESPACE = "@wix/pricing-plans"; // literal, with the @ and the slash, in every coverage call
+
+export function makeCtx({ cwd = process.cwd() } = {}) {
+  // The content site: the config's site, or the parent on a migration preview (site-context.mjs stops
+  // a seed there unless --allow-parent is passed after the user confirmed).
+  const siteId = seedSiteId({ cwd, argv: process.argv });
+  const token = wixToken(siteId, cwd);
+  return { token, siteId };
+}
+
+async function req(ctx, path, { method = "POST", body } = {}) {
+  const res = await fetch(API + path, {
+    method,
+    headers: {
+      Authorization: `Bearer ${ctx.token}`,
+      "wix-site-id": ctx.siteId,
+      "Content-Type": "application/json",
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const json = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(`${method} ${path} -> ${res.status}: ${JSON.stringify(json).slice(0, 400)}`);
+  return json;
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// billingTerms selects the plan type (recurring | one-time | free). recurring: billingCycle
+// {period,count} (default MONTH/1) + ON_PURCHASE + UNTIL_CANCELLED. one-time: endType
+// CYCLES_COMPLETED + billingCycleCount 1 (bill once, then ends); an unlimited one-time
+// instead sets billingCycle:null + UNTIL_CANCELLED. free: MUST be the no-cycle unlimited
+// shape — a $0 variant with a billingCycle is rejected ("Free pricing variant cannot be
+// recurring").
+function buildBillingTerms(plan) {
+  const type = plan.type || "recurring";
+  if (type === "free") {
+    return { billingCycle: null, startType: "ON_PURCHASE", endType: "UNTIL_CANCELLED" };
+  }
+  if (type === "one-time") {
+    if (plan.billingCycle === null) {
+      return { billingCycle: null, startType: "ON_PURCHASE", endType: "UNTIL_CANCELLED" };
+    }
+    const cycle = plan.billingCycle || { period: "MONTH", count: 1 };
+    return {
+      billingCycle: cycle,
+      startType: "ON_PURCHASE",
+      endType: "CYCLES_COMPLETED",
+      cyclesCompletedDetails: { billingCycleCount: 1 },
+    };
+  }
+  // recurring
+  const cycle = plan.billingCycle || { period: "MONTH", count: 1 };
+  return { billingCycle: cycle, startType: "ON_PURCHASE", endType: "UNTIL_CANCELLED" };
+}
+
+// Additional fees on the variant (up to 5): each { name (1–40 chars), priceType FIXED_AMOUNT,
+// fixedAmountOptions: { amount } (decimal string, > 0), appliedAt FIRST_PAYMENT — the only value:
+// a fee is added to the first payment }. `setupFee` is the one-fee shorthand of `fees`. The
+// frontend reads them back as fees[].fixedAmountOptions.amount and shows them with the price.
+// The id is a client-supplied GUID like the variant's and the perks'.
+function buildFees(plan) {
+  const fees = [...(plan.setupFee ? [plan.setupFee] : []), ...(plan.fees ?? [])];
+  return fees.map((f) => ({
+    id: randomUUID(),
+    name: f.name || "Setup fee",
+    priceType: "FIXED_AMOUNT",
+    fixedAmountOptions: { amount: String(f.amount) },
+    appliedAt: "FIRST_PAYMENT",
+  }));
+}
+
+// One pricingVariant with one pricingStrategy (schema allows ≤20 but is "currently limited
+// to 1"). Amounts are decimal STRINGS ("20.00"); the variant id is a REQUIRED
+// client-supplied GUID — omitting it returns 400. freeTrialDays (a number, ≤ 999) is the trial
+// before the first charge — a paid plan's field (nothing to trial on a free plan); fees ride on
+// the variant too.
+function buildPricingVariant(plan) {
+  const free = (plan.type || "recurring") === "free";
+  const amount = free ? "0" : String(plan.price);
+  const fees = free ? [] : buildFees(plan);
+  return {
+    id: randomUUID(),
+    name: plan.variantName || "Standard",
+    billingTerms: buildBillingTerms(plan),
+    pricingStrategies: [{ flatRate: { amount } }],
+    ...(!free && plan.freeTrialDays ? { freeTrialDays: Number(plan.freeTrialDays) } : {}),
+    ...(fees.length ? { fees } : {}),
+  };
+}
+
+// plain plan -> Plans V3 create body. status:"ACTIVE" is REQUIRED (omitting → 400
+// "status value is required"); currency is NOT sent (read-only, site-derived); perks are
+// display-only bullets, each with a REQUIRED client-supplied GUID.
+function buildPlan(plan) {
+  const free = (plan.type || "recurring") === "free";
+  return {
+    name: plan.name,
+    description: plan.description,
+    status: "ACTIVE",
+    visibility: plan.visibility || "PUBLIC",
+    buyable: plan.buyable ?? true,
+    buyerCanCancel: plan.buyerCanCancel ?? true,
+    ...(plan.termsAndConditions ? { termsAndConditions: plan.termsAndConditions } : {}),
+    pricingVariants: [buildPricingVariant(plan)],
+    perks: (plan.perks ?? []).map((p) => ({
+      id: randomUUID(),
+      description: typeof p === "string" ? p : p.description,
+    })),
+    // free: cap lifetime reuse. Array + maxCount per the SDK schema (PurchaseLimit[]); the
+    // recipe's older `{ type, count }` object form predates it.
+    ...(free ? { purchaseLimits: [{ type: "PER_MEMBER_LIFETIME", maxCount: 1 }] } : {}),
+  };
+}
+
+// ---- operations ----------------------------------------------------------------------------------
+
+// docs: https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/platform/about-apps-created-by-wix.md
+export async function installPricingPlansApp(ctx) {
+  try {
+    await req(ctx, "/apps-installer-service/v1/app-instance/install", { body: {
+      tenant: { tenantType: "SITE", id: ctx.siteId },
+      appInstance: { appDefId: PRICING_PLANS_APP_ID, enabled: true },
+    } });
+  } catch {
+    /* already installed is fine */
+  }
+}
+
+// Create the plan(s) — Plans V3 has NO bulk-create: one POST per plan. Keep plan.id: the
+// frontend orders by it AND it is the coverage externalId.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/plans-v3/create-plan.md
+export async function createPlans(ctx, plans) {
+  const out = [];
+  for (const plan of plans) {
+    const r = await req(ctx, "/pricing-plans/v3/plans", { body: { plan: buildPlan(plan) } });
+    out.push({
+      id: r.plan?.id,
+      slug: r.plan?.slug,
+      name: plan.name,
+      coveredServiceIds: plan.coveredServiceIds,
+    });
+  }
+  return out;
+}
+
+// ---- bookings coverage via Benefit Programs (SKIP when no bookings in the run) -------------------
+// Strictly ordered: plan.id -> programDefinition.id -> itemSetId -> items. Do NOT parallelize.
+
+// 2a: READ the auto-created program definition (the Plans app creates it; you never create
+// it). Provisioning is ~immediate but async — retry ONCE after a short backoff, don't loop.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/benefit-programs/program-definitions/introduction.md
+export async function getProgramDefinition(ctx, planId) {
+  const path = `/benefit-programs/v1/program-definitions/by-namespace-and-external-id?externalId=${planId}&namespace=${encodeURIComponent(PP_NAMESPACE)}`;
+  try {
+    const r = await req(ctx, path, { method: "GET" });
+    if (r.programDefinition?.id) return r.programDefinition.id;
+  } catch {
+    /* fall through to the single insurance retry */
+  }
+  await sleep(1000);
+  const r = await req(ctx, path, { method: "GET" });
+  return r.programDefinition?.id;
+}
+
+// 2b: create ONE pool definition with EXACTLY ONE benefit naming Bookings as the provider.
+// price "0" = unlimited (default; no creditConfiguration). Limited pack: pass creditAmount →
+// price "1" + details.creditConfiguration (a SIBLING of benefits[], NOT inside a benefit —
+// nesting it 400s with "Price should be 0 when credit pool is not set up").
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/benefit-programs/pool-definitions/create-pool-definition.md
+export async function createPoolDefinition(ctx, programDefinitionId, { creditAmount } = {}) {
+  const limited = creditAmount != null;
+  const details = {
+    ...(limited ? { creditConfiguration: { amount: String(creditAmount) } } : {}),
+    benefits: [
+      {
+        benefitKey: randomUUID(),
+        displayName: "Bookings sessions",
+        providerAppId: BOOKINGS_APP_ID,
+        price: limited ? "1" : "0",
+      },
+    ],
+  };
+  const r = await req(ctx, "/benefit-programs/v1/pool-definitions", {
+    body: {
+      poolDefinition: {
+        namespace: PP_NAMESPACE,
+        displayName: "Bookings benefit",
+        programDefinitionIds: [programDefinitionId],
+        details,
+      },
+      cascade: "IMMEDIATELY",
+    },
+  });
+  // itemSetId lives at poolDefinition.details.benefits[i].itemSetId — one benefit here, so [0].
+  return r.poolDefinition?.details?.benefits?.[0]?.itemSetId;
+}
+
+// 2c: bulk-create the benefit items — ONE item per covered service (externalId = bookings
+// service id). Up to 100 per call; category is an empty string; namespace/providerAppId
+// repeat 2b's values.
+// docs: https://dev.wix.com/docs/api-reference/business-solutions/benefit-programs/items/bulk-create-items.md
+export async function createBenefitItems(ctx, itemSetId, serviceIds) {
+  return req(ctx, "/benefit-programs/v1/bulk/items/create", {
+    body: {
+      items: serviceIds.map((externalId) => ({
+        namespace: PP_NAMESPACE,
+        category: "",
+        providerAppId: BOOKINGS_APP_ID,
+        itemSetId,
+        externalId,
+      })),
+      returnEntity: true,
+    },
+  });
+}
+
+/**
+ * Wire a plan to COVER bookings services (per plan). Runs 2a → 2b → 2c in order.
+ * serviceIds come from the BOOKINGS seed — seed bookings first.
+ */
+export async function attachBookingsCoverage(ctx, planId, serviceIds, { creditAmount } = {}) {
+  const programDefinitionId = await getProgramDefinition(ctx, planId);
+  if (!programDefinitionId) throw new Error(`No program definition for plan ${planId} — is the Pricing Plans app installed?`);
+  const itemSetId = await createPoolDefinition(ctx, programDefinitionId, { creditAmount });
+  await createBenefitItems(ctx, itemSetId, serviceIds);
+  return { itemSetId, serviceIds };
+}
+
+/**
+ * ONE-CALL seed: install → create plans (ids kept in memory) → per covering plan, wire
+ * bookings coverage (2a → 2b → 2c, strictly ordered). The default path.
+ */
+export async function setupPricingPlans(ctx, { plans = [], currency } = {}) {
+  // Before any plan exists: a plan's price is stored in the site currency.
+  if (currency) await setSiteCurrency(ctx, currency);
+  await installPricingPlansApp(ctx);
+  const created = await createPlans(ctx, plans);
+  const coverageAttached = [];
+  for (let i = 0; i < created.length; i++) {
+    const cov = plans[i].bookingsCoverage || {};
+    const serviceIds = cov.serviceIds || created[i].coveredServiceIds;
+    if (!serviceIds?.length) continue; // plans-only plan — coverage skipped
+    const r = await attachBookingsCoverage(ctx, created[i].id, serviceIds, { creditAmount: cov.creditAmount });
+    coverageAttached.push({ planId: created[i].id, ...r });
+  }
+  return {
+    plans: created,
+    coverageAttached,
+    benefitsCreated: coverageAttached.reduce((n, c) => n + c.serviceIds.length, 0),
+  };
+}
+
+// ---- CLI entry ----------------------------------------------------------------------------------
+
+const invokedDirectly = process.argv[1] && import.meta.url.endsWith(process.argv[1].split("/").pop());
+if (invokedDirectly) {
+  const planPath = process.argv[2];
+  if (!planPath) {
+    console.error("usage: node seed-pricing-plans.mjs <plan.json>   (run from the project root)");
+    process.exit(1);
+  }
+  const plan = JSON.parse(readFileSync(planPath, "utf8"));
+  const ctx = makeCtx();
+  setupPricingPlans(ctx, plan)
+    .then((result) => console.log(JSON.stringify(result, null, 2)))
+    .catch((e) => {
+      console.error(e.message);
+      process.exit(1);
+    });
+}