@wix/agent-skills 1.20.1 → 1.22.0

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

@@ -1,31 +0,0 @@
-// Plan reads over REST — the twin of app/wix/pricing-plans/plans.ts. Same exports, same DTOs; the
-// rules and mappers come from plans-core (the SAME file the SDK transport uses, deployed flat next
-// to this one by deploy.mjs --stack static), so this file is only the transport: one fetch with a
-// literal body per function. Every call here is safe from a browser with a visitor token.
-// Porting: keep the path, keep the body, port the core once.
-// docs: https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/plans-v3/query-plans.md
-import { wixRequest } from "./client.js";
-import { imgSrc } from "./media.js";
-import { plansQuery, toDetail, toSummary, type Raw } from "./plans-core.js";
-import type { PlanDetail, PlanSummary } from "./types.js";
-
-const QUERY = "/pricing-plans/v3/plans/query";
-
-/**
- * The public plans for the pricing grid, as card-ready DTOs.
- * POST /pricing-plans/v3/plans/query  { query: { filter: { visibility: "PUBLIC" }, cursorPaging: { limit } } }
- */
-export async function fetchPlans({ limit = 100 } = {}): Promise<PlanSummary[]> {
-  const res = await wixRequest<Raw>(QUERY, { body: { query: plansQuery({ limit }) } });
-  return ((res?.plans ?? []) as Raw[]).map((p) => toSummary(p, imgSrc));
-}
-
-/**
- * One public plan by its URL slug; null when the slug doesn't resolve (an empty `plans`, not a 404).
- * POST /pricing-plans/v3/plans/query  { query: { filter: { visibility: "PUBLIC", slug }, cursorPaging: { limit: 1 } } }
- */
-export async function fetchPlanBySlug(slug: string): Promise<PlanDetail | null> {
-  const res = await wixRequest<Raw>(QUERY, { body: { query: plansQuery({ limit: 1, slug }) } });
-  const raw: Raw | undefined = res?.plans?.[0];
-  return raw ? toDetail(raw, imgSrc) : null;
-}

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

@@ -1,20 +0,0 @@
-// The purchase flow over REST — the twin of app/wix/pricing-plans/purchase.ts. Same export, same
-// signature; the body and the result reading come from purchase-core (the SAME file the SDK
-// transport uses). Purchasing is a MEMBER action, but the hosted flow handles login/signup, the
-// order form, and payment itself, so a visitor token starts it. Never create the order yourself,
-// never hand-build a checkout URL.
-// docs: https://dev.wix.com/docs/api-reference/business-management/headless/redirects/create-redirect-session.md
-import { wixRequest } from "./client.js";
-import { purchaseBody, redirectUrl, type PurchaseOptions } from "./purchase-core.js";
-import type { Raw } from "./plans-core.js";
-
-export type { PurchaseOptions };
-
-/**
- * Start the hosted purchase for a plan; resolves to the URL to navigate the FULL document to.
- * POST /headless/v1/redirect-session  { paidPlansCheckout: { planId }, callbacks: { postFlowUrl, thankYouPageUrl? } }
- */
-export async function purchasePlan(planId: string, options: PurchaseOptions = {}): Promise<string> {
-  const session = await wixRequest<Raw>("/headless/v1/redirect-session", { body: purchaseBody(planId, options) });
-  return redirectUrl(session);
-}

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

@@ -1,79 +0,0 @@
-# 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>/references/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 / yearly), each with 3–4 perks; together they
-exercise every price shape the UI handles. 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 },
-      "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 },
-      "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.
-- `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 `references/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 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; the
-authoritative source recipe is `wix-headless/references/inline-recipes/setup-pricing-plans.md`.

package/skills/wix-headless-fast/references/pricing-plans/seed/seed-pricing-plans.mjs

@@ -1,279 +0,0 @@
-// 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>/references/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,
-//                 "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; authoritative source recipe:
-// wix-headless/references/inline-recipes/setup-pricing-plans.md.
-import { execFileSync } from "node:child_process";
-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() } = {}) {
-  const config = JSON.parse(readFileSync(`${cwd}/wix.config.json`, "utf8"));
-  const siteId = config.siteId ?? config.projectId;
-  if (!siteId) throw new Error("wix.config.json has no siteId — is this a Wix CLI project?");
-  const token = execFileSync("npx", ["@wix/cli@latest", "token", "--site", siteId], {
-    encoding: "utf8",
-    cwd,
-  }).trim();
-  if (!token) throw new Error("The Wix CLI returned no token — run `npx @wix/cli@latest login` first.");
-  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" };
-}
-
-// 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.
-function buildPricingVariant(plan) {
-  const free = (plan.type || "recurring") === "free";
-  const amount = free ? "0" : String(plan.price);
-  return {
-    id: randomUUID(),
-    name: plan.variantName || "Standard",
-    billingTerms: buildBillingTerms(plan),
-    pricingStrategies: [{ flatRate: { amount } }],
-  };
-}
-
-// 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 = [] } = {}) {
-  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);
-    });
-}