@wix/agent-skills 1.15.0 → 1.16.0

package/skills/wix-vibe-headless/references/pricing-plans/app/hooks/usePlans.js

@@ -0,0 +1,30 @@
+// usePlans — Plans-listing logic, no markup: load the first page of PUBLIC plans, page through with
+// the cursor, and start a members-only hosted checkout. The destructure of queryPlans() (returns
+// { plans, nextCursor }, NOT a bare array) and the checkout-then-redirect are load-bearing — keep
+// them. The Plans page only renders what this returns.
+import { useState, useEffect } from "react";
+import { queryPlans, checkout } from "@/rest/wix-pricing-plans";
+
+export function usePlans() {
+  const [plans, setPlans] = useState([]);
+  const [cursor, setCursor] = useState(null);
+  const [loaded, setLoaded] = useState(false);
+
+  useEffect(() => {
+    // NB: destructure — queryPlans returns { plans, nextCursor }, NOT a bare array.
+    queryPlans().then(({ plans, nextCursor }) => { setPlans(plans); setCursor(nextCursor); setLoaded(true); });
+  }, []);
+
+  const loadMore = () =>
+    queryPlans({ cursor }).then(({ plans: more, nextCursor }) => {
+      setPlans((p) => [...p, ...more]);
+      setCursor(nextCursor);
+    });
+
+  // members-only, Wix-hosted checkout; on success Wix returns to thankYouPageUrl with ?planOrderId=<GUID>
+  async function subscribe(plan) {
+    window.location.href = await checkout(plan.id, { thankYouPageUrl: `${window.location.origin}/my-plans` });
+  }
+
+  return { plans, cursor, loaded, loadMore, subscribe };
+}

package/skills/wix-vibe-headless/references/pricing-plans/app/pages/MyPlans.jsx

@@ -0,0 +1,30 @@
+// My plans page — thin view over useMyPlans (all logic lives in the hook). Shows the logged-in
+// member's active memberships and doubles as the post-checkout confirmation (re-syncs on
+// visibilitychange). getMyPlanOrders() resolves to [] for anonymous visitors, so the empty branch
+// covers both "not a member → log in" and "member with no active plans". Styled with base44 design
+// tokens (shadcn Tailwind classes).
+import { useMyPlans } from "@/hooks/useMyPlans";
+import OrderCard from "@/components/OrderCard";
+
+export default function MyPlans() {
+  const { orders, loaded } = useMyPlans({ orderStatuses: ["ACTIVE"] });
+
+  return (
+    <main className="max-w-[720px] mx-auto py-8 px-4">
+      <h1 className="font-display mb-4">My plans</h1>
+      {!loaded ? (
+        <p className="text-muted-foreground">Loading…</p>
+      ) : orders.length === 0 ? (
+        // [] = anonymous visitor OR a member with no active plans. Wire log-in via the members
+        // vertical (references/members/) so a member can sign in on your own UI, then re-check.
+        <p className="text-muted-foreground">
+          No active plans. Log in to see your plans, or choose one from the pricing page.
+        </p>
+      ) : (
+        <ul className="m-0 p-0 flex flex-col gap-4">
+          {orders.map((order) => <OrderCard key={order.id} order={order} />)}
+        </ul>
+      )}
+    </main>
+  );
+}

package/skills/wix-vibe-headless/references/pricing-plans/app/pages/PlanDetail.jsx

@@ -0,0 +1,53 @@
+// Plan detail page — thin view over usePlanDetail (all logic lives in the hook). Shows the full
+// price/billing summary, perks, terms & conditions if present, and a Subscribe button (only when
+// plan.buyable). Not-found state on a bad slug — never invent a plan. Styled with base44 design
+// tokens (shadcn Tailwind classes). termsAndConditions is plain text; render as-is.
+import { useParams } from "react-router-dom";
+import { usePlanDetail } from "@/hooks/usePlanDetail";
+import PlanPrice from "@/components/PlanPrice";
+
+export default function PlanDetail() {
+  const { slug } = useParams();
+  const { plan, notFound, subscribe } = usePlanDetail(slug);
+
+  if (notFound) return <Centered>Plan not found.</Centered>;
+  if (!plan) return <Centered>Loading…</Centered>;
+
+  return (
+    <main className="max-w-[720px] mx-auto py-8 px-4">
+      <h1 className="font-display m-0 mb-2">{plan.name}</h1>
+      {plan.description && (
+        <p className="text-muted-foreground leading-[1.6] m-0 mb-4">{plan.description}</p>
+      )}
+
+      <div className="my-4"><PlanPrice plan={plan} /></div>
+
+      {(plan.perks || []).length > 0 && (
+        <ul className="my-4 p-0 list-none flex flex-col gap-2.5">
+          {plan.perks.map((perk) => (
+            <li key={perk.id} className="flex gap-2 leading-[1.4]">
+              <span className="text-primary" aria-hidden>✓</span>
+              <span>{perk.description}</span>
+            </li>
+          ))}
+        </ul>
+      )}
+
+      {plan.buyable && (
+        <button onClick={subscribe}
+          className="py-3 px-8 cursor-pointer bg-primary text-primary-foreground rounded-sm text-[15px] font-semibold">Subscribe</button>
+      )}
+
+      {plan.termsAndConditions && (
+        <div className="mt-8 pt-4 border-t border-border">
+          <h2 className="font-display text-base">Terms &amp; conditions</h2>
+          <p className="text-muted-foreground leading-[1.6] whitespace-pre-wrap">{plan.termsAndConditions}</p>
+        </div>
+      )}
+    </main>
+  );
+}
+
+function Centered({ children }) {
+  return <div className="p-12 text-center text-muted-foreground">{children}</div>;
+}

package/skills/wix-vibe-headless/references/pricing-plans/app/pages/Plans.jsx

@@ -0,0 +1,28 @@
+// Plans / pricing page — thin view over usePlans (all logic lives in the hook). Lists PUBLIC plans
+// with an empty state, pages through with the cursor, and subscribes via the members-only hosted
+// checkout. Styled with base44 design tokens (shadcn Tailwind classes).
+import { usePlans } from "@/hooks/usePlans";
+import PlanGrid from "@/components/PlanGrid";
+
+export default function Plans() {
+  const { plans, cursor, loaded, loadMore, subscribe } = usePlans();
+
+  return (
+    <main className="max-w-[1200px] mx-auto p-4">
+      <h1 className="font-display mb-4">Plans &amp; Pricing</h1>
+      {!loaded
+        ? <p className="text-muted-foreground">Loading…</p>
+        : <PlanGrid
+            plans={plans}
+            onSubscribe={subscribe}
+            empty="No plans yet — create plans from your Wix dashboard."
+          />}
+      {cursor && (
+        <div className="text-center mt-6">
+          <button onClick={loadMore}
+            className="py-2.5 px-6 cursor-pointer bg-card text-foreground border border-border rounded-sm font-semibold">Load more</button>
+        </div>
+      )}
+    </main>
+  );
+}

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

@@ -0,0 +1,86 @@
+# Pricing Plans — seeding
+
+Seed Wix Pricing Plans (Plans V3) by **calling `seed-pricing-plans.js`** — don't hand-write the
+REST calls. It's a build-time module (run via `exec_tool`, not shipped in the app) that abstracts
+every Pricing Plans + Benefit Programs seed operation. `require` it and call the functions with
+plain data.
+
+> **NOT yet live-verified — transcribed from `setup-pricing-plans.md`.**
+
+```js
+// build-time exec_tool
+const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix"); // Base44 (generic: use $TOKEN)
+const fs = require("fs");
+// exec_tool's require can return EMPTY exports for these build-time modules — load the file itself:
+const seed = (() => { const m = { exports: {} };
+  new Function("module", "exports", "require", fs.readFileSync("/app/.agents/skills/wix-vibe-headless/references/pricing-plans/seed/seed-pricing-plans.js", "utf8"))(m, m.exports, require);
+  return m.exports; })();
+const ctx = { token: accessToken, siteId: WIX_METASITE_ID };
+
+// setupPricingPlans installs the Wix Pricing Plans app first (idempotent) — base44 sites may not have it.
+
+// DEFAULT: one call. Creates the plan(s), keeps their ids in memory, and (per plan) wires bookings
+// coverage when provided — createPlans then attachBookingsCoverage (2a→2b→2c), in order.
+const { plans, coverageAttached, benefitsCreated } = await seed.setupPricingPlans(ctx, {
+  plans: [
+    { name: "Studio Membership", description: "Unlimited group classes.", price: "20.00",
+      type: "recurring", billingCycle: { period: "MONTH", count: 1 },
+      perks: ["Unlimited group classes", "10% off workshops"],
+      coveredServiceIds: bookingsServiceIds },  // optional — only when this plan covers bookings services
+    // …just the plan data. price = decimal STRING; currency is site-derived (don't send it).
+    // limited pack instead of unlimited: bookingsCoverage: { serviceIds, creditAmount: 8 }
+  ],
+});
+// A plans-only run (no bookings) just omits coveredServiceIds — STEP 2 is skipped automatically.
+```
+
+**Seeding is additive — never delete or overwrite existing content.** Don't clean up, don't remove
+"sample" data, don't reset. Just add.
+
+## Escape hatch — individual functions
+Reach for the functions below only when the one-call `setupPricingPlans` doesn't fit (custom coverage,
+step-by-step control). `setupPricingPlans` is built from them, in this order:
+
+```js
+const plans = await seed.createPlans(ctx, [
+  { name: "Studio Membership", price: "20.00", perks: ["Unlimited group classes"],
+    coveredServiceIds: bookingsServiceIds },
+]);
+// STEP 2 — only when bookings is in the run AND the plan covers services (skip otherwise):
+await seed.attachBookingsCoverage(ctx, plans[0].id, plans[0].coveredServiceIds);
+// limited pack instead of unlimited: attachBookingsCoverage(ctx, id, ids, { creditAmount: 8 })
+```
+
+## Functions
+| fn | does |
+|---|---|
+| `setupPricingPlans(ctx, {plans})` | **DEFAULT** one call: createPlans → per-plan attachBookingsCoverage → `{plans,coverageAttached,benefitsCreated}` |
+| `createPlans(ctx, plans)` | one create call per plan (V3 has no bulk) → `[{id,name,coveredServiceIds}]` |
+| `attachBookingsCoverage(ctx, planId, serviceIds, {creditAmount?})` | STEP 2: 2a→2b→2c in order → `{itemSetId,serviceIds}` |
+| `getProgramDefinition(ctx, planId)` | 2a: READ the auto-created program definition (retry-once on 404) → `programDefinitionId` |
+| `createPoolDefinition(ctx, programDefinitionId, {creditAmount?})` | 2b: one pool + one Bookings benefit → `itemSetId` |
+| `createBenefitItems(ctx, itemSetId, serviceIds)` | 2c: bulk-create one benefit item per covered service |
+
+Plan `type`: `"recurring"` (default; `billingCycle` defaults to `{MONTH,1}`), `"one-time"`
+(bills once then ends; pass `billingCycle: null` for the unlimited one-time), or `"free"`
+(amount forced to `"0"` + a per-member-lifetime purchase limit). Amounts are decimal **strings**;
+`perks` are display-only bullets; plans default to `visibility: "PUBLIC"` + `buyable: true`.
+
+## Bookings-first dependency
+STEP 2 attaches **bookings service ids** to a plan through the Benefit Programs API (the coverage
+is NOT a plan field or a perk). Those ids come from the **bookings seed**
+(`seeded.bookings.serviceIds[]`), so **seed bookings before pricing-plans** and pass the ids in as
+`coveredServiceIds`. A plans-only run (no bookings) stops after `createPlans` — skip STEP 2 entirely.
+
+## Reference
+If a call returns a shape you didn't expect, or you need an operation this module doesn't cover,
+use the **`wix-docs`** skill to search + read the live Wix API reference — never guess. The
+authoritative source recipe is `wix-headless/references/inline-recipes/setup-pricing-plans.md`.
+
+Read a method's page before writing its call: it carries the exact body shape, the required
+permission scope, and the response envelope.
+- Install a Wix app onto the site: https://dev.wix.com/docs/api-reference/business-management/app-installation/app-installation/install-app.md
+- Create Plan: https://dev.wix.com/docs/api-reference/business-solutions/pricing-plans/plans-v3/create-plan.md
+- Create Pool Definition (benefits): https://dev.wix.com/docs/api-reference/business-solutions/benefit-programs/pool-definitions/create-pool-definition.md
+- Bulk Create Items (benefits): https://dev.wix.com/docs/api-reference/business-solutions/benefit-programs/items/bulk-create-items.md
+- Get Program Definition By External Id And Namespace: https://dev.wix.com/docs/api-reference/business-solutions/benefit-programs/program-definitions/get-program-definition-by-external-id-and-namespace.md

package/skills/wix-vibe-headless/references/pricing-plans/seed/seed-pricing-plans.js

@@ -0,0 +1,251 @@
+// Pricing-Plans seed helpers — run at BUILD TIME via exec_tool (NOT shipped in the app).
+// The agent requires this and calls the functions with plain data; all Wix Pricing Plans (V3)
+// + Benefit Programs request/response mechanics (the client-supplied GUID rule, the string-amount
+// rule, the three ordered coverage sub-steps, the @wix/pricing-plans namespace) live here, once.
+//
+// **NOT yet live-verified — transcribed from setup-pricing-plans.md.**
+//
+// Usage (build-time exec_tool):
+//   const { accessToken } = await base44.asServiceRole.connectors.getConnection("wix");  // Base44
+//   const seed = require("/app/.agents/skills/wix-vibe-headless/references/pricing-plans/seed/seed-pricing-plans.js");
+//   const ctx = { token: accessToken, siteId: WIX_METASITE_ID };
+//
+//   // Bookings is seeded FIRST — its service ids feed a plan's coverage (see SEED.md).
+//   const plans = await seed.createPlans(ctx, [
+//     { name: "Studio Membership", description: "Unlimited group classes.", price: "20.00",
+//       type: "recurring", billingCycle: { period: "MONTH", count: 1 },
+//       perks: ["Unlimited group classes", "10% off workshops"],
+//       coveredServiceIds: bookingsServiceIds },   // optional — only when this plan covers bookings
+//   ]);
+//   // Then, per plan that covers bookings services (STEP 2; skip entirely with no bookings):
+//   await seed.attachBookingsCoverage(ctx, plans[0].id, plans[0].coveredServiceIds);
+//
+// If any call fails with a shape the caller didn't expect, fall back to the wix-docs skill
+// (search + read the live Wix API reference) — never guess. Source recipe (authoritative):
+// wix-headless/references/inline-recipes/setup-pricing-plans.md.
+
+const { randomUUID } = require("crypto");
+
+const API = "https://www.wixapis.com";
+const BOOKINGS_APP_ID = "13d21c63-b5ec-5912-8397-c3a5ddb27a97"; // per recipe: providerAppId for coverage
+const PRICING_PLANS_APP_ID = "1522827f-c56c-a5c9-2ac9-00f9e6ae12d3"; // installPricingPlansApp installs this before seeding
+const PP_NAMESPACE = "@wix/pricing-plans"; // per recipe: literal, with @ and slash, in every 2a–2c call
+
+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));
+
+// [ "text" | { description } ] -> Wix perks[]; each gets a fresh client-supplied GUID (required).
+function buildPerks(perks = []) {
+  return perks.map((p) => ({
+    id: randomUUID(),
+    description: typeof p === "string" ? p : p.description,
+  }));
+}
+
+// billingTerms selects the plan type (recurring | one-time | free). Amounts are decimal STRINGS.
+// recurring: billingCycle {period,count} (default MONTH/1) + startType ON_PURCHASE + endType UNTIL_CANCELLED.
+// one-time:  endType CYCLES_COMPLETED + cyclesCompletedDetails {billingCycleCount:1} (bill once, then ends);
+//            an unlimited one-time instead sets billingCycle:null + endType UNTIL_CANCELLED.
+function buildBillingTerms(plan) {
+  const type = plan.type || "recurring";
+  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 (also the shape a free plan rides on)
+  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").
+function buildPricingVariant(plan) {
+  const free = (plan.type || "recurring") === "free";
+  const amount = free ? "0" : String(plan.price);
+  return {
+    id: randomUUID(), // required, client-supplied GUID — never model-typed
+    name: plan.variantName || "Standard",
+    billingTerms: buildBillingTerms(plan),
+    pricingStrategies: [{ flatRate: { amount } }],
+  };
+}
+
+// ---- exported operations ----
+
+/**
+ * Create the plan(s). Plans V3 has NO bulk-create — one create call per plan.
+ * @param plans [{ name, description?, price,           // price = decimal string ("20.00"); ignored for free
+ *   type?: "recurring"|"one-time"|"free",              // default "recurring"
+ *   billingCycle?: { period: "DAY"|"WEEK"|"MONTH"|"YEAR", count } | null,  // default { MONTH, 1 }
+ *   perks?: ["..."] | [{ description }],               // display-only bullets (no functional effect)
+ *   visibility?, buyable?,                             // default "PUBLIC" / true (public + orderable)
+ *   coveredServiceIds? }]                              // metadata for attachBookingsCoverage; not sent here
+ * @returns [{ id, name, coveredServiceIds }]  (id = plan.id — orders by it AND is the coverage externalId)
+ */
+async function createPlans(ctx, plans) {
+  const out = [];
+  for (const plan of plans) {
+    const free = (plan.type || "recurring") === "free";
+    const body = {
+      plan: {
+        name: plan.name,
+        description: plan.description,
+        status: "ACTIVE", // REQUIRED — omitting returns 400 "status value is required"
+        visibility: plan.visibility || "PUBLIC",
+        buyable: plan.buyable ?? true,
+        buyerCanCancel: plan.buyerCanCancel ?? true,
+        pricingVariants: [buildPricingVariant(plan)],
+        perks: buildPerks(plan.perks),
+        // free: cap lifetime reuse (older maxPurchasesPerBuyer is deprecated — prefer purchaseLimits)
+        ...(free ? { purchaseLimits: { type: "PER_MEMBER_LIFETIME", count: 1 } } : {}),
+      },
+    };
+    const r = await req(ctx, "/pricing-plans/v3/plans", { body });
+    out.push({ id: r.plan?.id, name: plan.name, coveredServiceIds: plan.coveredServiceIds });
+  }
+  return out;
+}
+
+// ---- STEP 2: bookings coverage via Benefit Programs API (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 on 404/empty, don't loop.
+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 (SIBLING of benefits[], NOT inside a benefit).
+async function createPoolDefinition(ctx, programDefinitionId, { creditAmount } = {}) {
+  const limited = creditAmount != null;
+  const details = {
+    ...(limited ? { creditConfiguration: { amount: String(creditAmount) } } : {}),
+    benefits: [
+      {
+        benefitKey: randomUUID(), // freshly generated random UUID you supply
+        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 items per call; category is an empty string; namespace/providerAppId repeat 2b's values.
+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 (STEP 2, per plan). Runs 2a -> 2b -> 2c in order.
+ * @param planId          plan.id from createPlans
+ * @param serviceIds      bookings service ids (seeded.bookings.serviceIds[]) the plan should cover
+ * @param creditAmount?   session-count for a limited pack; omit for the default unlimited ("0") case
+ * @returns { itemSetId, serviceIds }  — keep as seed-time linkage (bookingsCoverage[planId])
+ */
+async function attachBookingsCoverage(ctx, planId, serviceIds, { creditAmount } = {}) {
+  const programDefinitionId = await getProgramDefinition(ctx, planId);
+  const itemSetId = await createPoolDefinition(ctx, programDefinitionId, { creditAmount });
+  await createBenefitItems(ctx, itemSetId, serviceIds);
+  return { itemSetId, serviceIds };
+}
+
+/**
+ * DEFAULT one-call path — create plan(s) and, per plan, wire bookings coverage when provided.
+ * One call; created plan ids stay in memory so coverage never needs hand-threading of plan.id.
+ * Order: createPlans (all plans) -> per covering plan attachBookingsCoverage (2a->2b->2c, in order).
+ * The program definition is provisioned asynchronously ~1s after the plan; the retry-once-after-
+ * backoff on its 404 lives in getProgramDefinition and is preserved via attachBookingsCoverage.
+ * @param plan { plans: [{ ...createPlans fields (name, description?, price, type?, billingCycle?,
+ *   perks?, visibility?, buyable?),
+ *   coveredServiceIds?,                                    // bookings service ids this plan covers
+ *   bookingsCoverage?: { serviceIds?, creditAmount? } }] } // richer coverage; creditAmount = limited pack
+ * @returns { plans: [{id,name,coveredServiceIds}], coverageAttached: [{planId,itemSetId,serviceIds}], benefitsCreated }
+ */
+// Install the Wix Pricing Plans app before seeding — base44 sites aren't guaranteed to have it (no
+// separate Setup step here, unlike the wix-headless recipe). Idempotent: re-installing returns 200.
+async function installPricingPlansApp(ctx) {
+  return req(ctx, "/apps-installer-service/v1/app-instance/install", { body: {
+    tenant: { tenantType: "SITE", id: ctx.siteId },
+    appInstance: { appDefId: PRICING_PLANS_APP_ID, enabled: true },
+  } });
+}
+
+async function setupPricingPlans(ctx, { plans = [] } = {}) {
+  await installPricingPlansApp(ctx);
+  const created = await createPlans(ctx, plans); // ids kept in memory
+  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 — skip STEP 2
+    const r = await attachBookingsCoverage(ctx, created[i].id, serviceIds, { creditAmount: cov.creditAmount });
+    coverageAttached.push({ planId: created[i].id, ...r });
+  }
+  const benefitsCreated = coverageAttached.reduce((n, c) => n + c.serviceIds.length, 0);
+  return { plans: created, coverageAttached, benefitsCreated };
+}
+
+module.exports = {
+  setupPricingPlans, installPricingPlansApp,
+  createPlans,
+  attachBookingsCoverage,
+  getProgramDefinition, createPoolDefinition, createBenefitItems,
+};