@wix/agent-skills 1.19.2 → 1.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/agent-skills",
-  "version": "1.19.2",
+  "version": "1.20.0",
   "description": "Wix Skills for AI coding agents — versioned npm distribution of the wix/skills content.",
   "license": "MIT",
   "repository": {

package/skills/wix-app/references/SERVICE_PLUGIN.md

@@ -1,7 +1,7 @@
 
 # Wix Service Plugin (SPI) Builder
 
-Service plugins are a set of APIs defined by Wix that let you inject custom logic into the existing backend flows of Wix business solutions or introduce entirely new flows. When you implement a service plugin, Wix calls your custom functions during specific flows. Common use cases include eCommerce customization (shipping, fees, payment settings, validations) and Bookings customization (staff sorting).
+Service plugins are a set of APIs defined by Wix that let you inject custom logic into the existing backend flows of Wix business solutions or introduce entirely new flows. When you implement a service plugin, Wix calls your custom functions during specific flows. Common use cases include eCommerce customization (shipping, fees, payment settings, validations), Bookings customization (staff sorting, booking validation, policies, pricing, availability), Realtime channel permissions, and exposing tools to the Wix AI assistant.
 
 ## Scaffold
 
@@ -16,12 +16,19 @@ Use `wix generate --params` with `extensionType: SERVICE_PLUGIN`. `pluginType` i
 | `ECOM_PAYMENT_SETTINGS` | Payment Settings | No |
 | `GIFT_CARDS_PROVIDER` | Gift Cards Provider | **Yes** |
 | `STAFF_SORTING_PROVIDER` | Bookings Staff Sorting | No |
+| `BOOKINGS_VALIDATION_PROVIDER` | Bookings Validation | No |
+| `BOOKING_POLICY_PROVIDER` | Booking Policy | No |
+| `BOOKINGS_PRICING_PROVIDER` | Bookings Pricing Provider | No |
+| `AVAILABILITY_TIME_SLOTS_CONFIGURATION_PROVIDER` | Availability Time Slots Configuration | No |
 | `REALTIME_PERMISSIONS_PROVIDER` | Realtime Permissions Provider | No |
+| `TOOLS_PROVIDER_CONFIG` | Tools Provider | No |
 
 > **Singular types** — `ECOM_SHIPPING_RATES`, `ECOM_DISCOUNTS_TRIGGER`, and `GIFT_CARDS_PROVIDER` are **singular**: only one component of each type is allowed per app. Never scaffold or include two components of the same singular type in the same app payload.
 
 `name` must be lowercase alphanumeric + hyphens, max 19 characters. The CLI generates the folder, `plugin.ts`, the builder file, the UUID, and the `src/extensions.ts` registration with the appropriate builder method for the SPI type. Some SPI types (e.g., `ECOM_SHIPPING_RATES`) get a `description` placeholder field in the generated builder — replace it with your real copy.
 
+> **Missing dependency after scaffolding:** `wix generate` adds the SPI's SDK package (e.g. `@wix/bookings`, `@wix/realtime`) to `package.json`, but does not always install it into `node_modules`. If `tsc`/`wix build` reports the import as unresolved right after scaffolding, run `npm install <package>` for just that package (no need for a full reinstall) before debugging further.
+
 ## References
 
 **You MUST read the relevant reference document before implementing an SPI**, and **call `ReadFullDocsMethodSchema`** with the docs URL it points at to get the exact request/response types — **do NOT edit code until you have the schema**. If the schema alone isn't enough, follow up with `ReadFullDocsArticle` on the same URL for prose explanations and additional code examples. Each reference also contains the correct imports, handler signatures, response structures, and a worked example.
@@ -35,6 +42,12 @@ Use `wix generate --params` with `extensionType: SERVICE_PLUGIN`. `pluginType` i
 | Shipping Rates | [SHIPPING-RATES.md](service-plugin/SHIPPING-RATES.md) |
 | Validations | [VALIDATIONS.md](service-plugin/VALIDATIONS.md) |
 | Bookings Staff Sorting | [BOOKINGS-STAFF-SORTING.md](service-plugin/BOOKINGS-STAFF-SORTING.md) |
+| Bookings Validation | [BOOKINGS-VALIDATION.md](service-plugin/BOOKINGS-VALIDATION.md) |
+| Booking Policy | [BOOKING-POLICY.md](service-plugin/BOOKING-POLICY.md) |
+| Bookings Pricing Provider | [BOOKINGS-PRICING.md](service-plugin/BOOKINGS-PRICING.md) |
+| Availability Time Slots Configuration | [AVAILABILITY-TIME-SLOTS-CONFIGURATION.md](service-plugin/AVAILABILITY-TIME-SLOTS-CONFIGURATION.md) |
+| Realtime Permissions Provider | [REALTIME-PERMISSIONS.md](service-plugin/REALTIME-PERMISSIONS.md) |
+| Tools Provider | [TOOLS_PROVIDER.md](service-plugin/TOOLS_PROVIDER.md) |
 
 ## Implementation Pattern
 

package/skills/wix-app/references/editor-react-component/ANIMATED-COMPONENTS.md

@@ -140,7 +140,7 @@ clears `isStoppedByFocus`.
 
 ## 3. Add the Play/Pause Button
 
-Create play/pause icons that visually match the component's style. Use simple recognizable shapes — a triangle for play, two rectangles for pause — implemented as inline SVG so there is no external icon dependency. Size, stroke, and fill should feel native to the component's design.
+Create play/pause icons that visually match the component's style. Use simple recognizable shapes — a triangle for play, two rectangles for pause — implemented as inline SVG so there is no external icon dependency. Size and color of SVG should be controlled by CSS variables declared on the button level: --icon-size and --icon-color.
 
 Position the button absolutely so it overlays the content without pushing other elements out of place:
 
@@ -152,14 +152,14 @@ Position the button absolutely so it overlays the content without pushing other
 }
 
 .playButton {
+  --icon-size: 20px;
+  --icon-color: #ffffff;
   position: absolute;
   inset-inline-end: 5px;
   inset-block-start: 5px;
 }
 
-/* Design-state selectors: pair native pseudo-class with editor-injected modifier class.
-   The editor applies the modifier class (e.g. my-animation-play-button--hover) when
-   the site owner previews that state in the design panel, so both selectors must exist. */
+/* Design-state selectors: pair native pseudo-class with editor-injected modifier class. */
 .playButton:global(.my-animation-play-button--hover),
 .playButton:hover {
   /* e.g. background: rgba(255, 255, 255, 1); */
@@ -257,8 +257,7 @@ const ComponentNamePreview: FC<ComponentProps<typeof Component>> = (props) => {
 };
 ```
 
-In editor design mode (`isEditMode` is `true`) → `autoPlay` is forced to `false` and `pauseButtonVisibility` is forced to `'showAlways'` so the site owner can always see and interact with the button.
-In preview mode (`isEditMode` is `false`) → both use the user's configured values.
+Design mode stops autoplay and exposes the control; preview uses the user's values.
 
 ## Checklist
 
@@ -267,6 +266,8 @@ In preview mode (`isEditMode` is `false`) → both use the user's configured val
       present only when repeat behavior is supported.
 - [ ] Reduced motion starts paused and never restarts playback automatically.
 - [ ] The play/pause button is a fully wired named part with a stable accessible name.
+- [ ] Both icons inherit button-owned `--icon-size` for width and height and
+      `--icon-color` via `color` and `currentColor` for fill or stroke.
 - [ ] Hover has a paired editor design state; `:focus-visible` remains a
       standalone keyboard indicator.
 - [ ] Hover-only visibility changes behavior, not the button's editable styling surface.

package/skills/wix-app/references/service-plugin/ADDITIONAL-FEES.md

@@ -87,6 +87,10 @@ additionalFees.provideHandlers({
 });
 ```
 
+## Manual Setup Required
+
+None — confirmed live. Once the app is installed and released, Wix calls this plugin automatically on every cart/checkout calculation; no dashboard configuration or extra API call is needed to "turn it on."
+
 ## Key Implementation Notes
 
 1. **Elevate permissions for API calls** - Use `auth.elevate` from `@wix/essentials` when calling Wix APIs from service plugins

package/skills/wix-app/references/service-plugin/AVAILABILITY-TIME-SLOTS-CONFIGURATION.md

@@ -0,0 +1,118 @@
+# Availability Time Slots Configuration Service Plugin Reference
+
+## Overview
+
+The Availability Time Slots Configuration SPI lets you customize how Wix calculates available time slots for booking services: duration, split interval, buffer time, locations, and required/available resources. Wix calls your `listAvailabilityTimeSlotConfigurations` handler whenever a customer views available times or books a service. [Resources](https://dev.wix.com/docs/api-reference/business-solutions/bookings/resources/resources-v2/introduction) must already exist before time slot calculation runs.
+
+## ⚠️ `resourceTypeId` is not a placeholder you can invent
+
+`resourceTypes[].resourceTypeId` must be a real resource type ID or Wix rejects every availability query for the service — confirmed live: a made-up GUID here 500s `List Availability Time Slots` and fails booking creation with `FAILED_VALIDATING_AVAILABILITY`, for every service on the site, not just the one you're configuring. If the service is staffed (the common case), use the universal Wix Bookings staff-member resource type ID, which is the same across every site — it is not something you provision or look up per site:
+
+```typescript
+const STAFF_MEMBER_RESOURCE_TYPE_ID = '1cd44cf8-756f-41c3-bd90-3e2ffcaf1155';
+```
+
+For a non-staff resource (a room, piece of equipment, etc.), get the real ID from [Get Resource](https://dev.wix.com/docs/api-reference/business-solutions/bookings/resources/resources-v2/get-resource) (`resource.typeId`) — never fabricate one.
+
+## ⚠️ `resourceTypes[].resourceIds` — populate it, don't leave it implicit
+
+`resourceIds` ("IDs of resources available for booking within this resource type... may be a subset of all resources in the type") tells Wix *which* resources of that type are valid for this specific service. Omitting it (relying on `resourceTypeId` alone) was part of the same live 500 chain above — once `resourceTypeId` and `scheduleId` were both fixed, availability queries still failed until `resourceIds` was populated too. Get the service's actual assigned staff from [Get Service](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/get-service)'s `service.staffMemberIds`.
+
+## ⚠️ `scheduleId` is required — omitting it also 500s
+
+The response schema requires `scheduleId` (confirmed live: leaving it out 500s the same as a bad `resourceTypeId`), but it's easy to miss since it's not mentioned in the request/response summary above. Fetch it from the service itself — [Get Service](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/get-service)'s `service.schedule._id` (REST docs call this field `id`; the SDK's `Service.schedule` type names it `_id`):
+
+```typescript
+import { auth } from "@wix/essentials";
+import { services } from "@wix/bookings";
+
+const elevatedGetService = auth.elevate(services.getService);
+const service = await elevatedGetService(serviceId);
+const scheduleId = service.schedule?._id;
+```
+
+## ⚠️ `locations[]._id` is required when `locationType` is `BUSINESS`
+
+The schema notes `_id` is "returned only for business locations" — read that as *required whenever `locationType: BUSINESS`*, not optional. Omitting it was the third and last piece of the same live 500 chain. Get the service's actual configured locations from [Get Service](https://dev.wix.com/docs/api-reference/business-solutions/bookings/services/services-v2/get-service)'s `service.locations[]` (each has its own `_id`) rather than hardcoding a bare `{ locationType: "BUSINESS" }`.
+
+## Manual Setup Required
+
+None for activation — Wix calls this plugin automatically once installed and released. But get all three fields above right, or every availability query for every service on the site fails with a bare 500, not just a validation error on the one service you're configuring.
+
+## Request and Response Schema
+
+Before implementing, call `ReadFullDocsMethodSchema` on the docs URL to get the full request/response types.
+
+| Handler | Docs URL |
+| --- | --- |
+| `listAvailabilityTimeSlotConfigurations` | https://dev.wix.com/docs/api-reference/business-solutions/bookings/time-slots/availability-time-slots-configuration-service-plugin/list-availability-time-slot-configurations?apiView=SDK |
+
+The request's `services` array (up to 100 entries) lists each service to configure, with the customer's `customerChoices` (selected duration variant and/or add-ons) — the same service GUID can appear more than once with different choices. Your response's `configurations` array must contain exactly one configuration per requested entry, **in the same order**, with `resourceTypes`, `locations`, and `scheduleId` fully populated.
+
+For services with a bookable duration **range** (the customer picks how long to book), return `durationUnit` (`HOUR` or `DAY`) with `minDuration`/`maxDuration` instead of a fixed `duration`; for hourly ranges also return `duration.defaultInMinutes` as the minimum.
+
+## Example: Duration From Add-Ons, Single Resource Type
+
+```typescript
+import { availabilityTimeSlotsConfiguration } from "@wix/bookings/service-plugins";
+import { auth } from "@wix/essentials";
+import { services } from "@wix/bookings";
+
+// Universal Wix Bookings staff-member resource type ID — same on every site, not per-site data.
+const STAFF_MEMBER_RESOURCE_TYPE_ID = "1cd44cf8-756f-41c3-bd90-3e2ffcaf1155";
+
+availabilityTimeSlotsConfiguration.provideHandlers({
+  listAvailabilityTimeSlotConfigurations: async (payload) => {
+    const { request } = payload;
+    // services is optional on the request type — default it, or the .map()
+    // calls below fail `tsc` with "possibly undefined."
+    const { services: requestedServices = [] } = request;
+
+    // scheduleId is required in the response but isn't in the request — fetch it per service.
+    const elevatedGetService = auth.elevate(services.getService);
+    const serviceById = new Map(
+      await Promise.all(
+        requestedServices.map(async ({ serviceId }) =>
+          [serviceId, serviceId ? await elevatedGetService(serviceId) : undefined] as const
+        )
+      )
+    );
+
+    const configurations = requestedServices.map(({ serviceId, customerChoices }) => {
+      const baseDuration = 60;
+      const addOnMinutes = (customerChoices?.addOnIds ?? []).length * 15;
+      const service = serviceById.get(serviceId);
+
+      return {
+        serviceId,
+        resourceTypes: [
+          {
+            resourceTypeId: STAFF_MEMBER_RESOURCE_TYPE_ID,
+            resourceIds: service?.staffMemberIds ?? [],
+            numberOfResourcesRequired: 1,
+          },
+        ],
+        locations: (service?.locations ?? []).map((location) => ({
+          _id: location._id,
+          locationType: availabilityTimeSlotsConfiguration.LocationType.BUSINESS,
+        })),
+        splitIntervalInMinutes: baseDuration + addOnMinutes,
+        duration: { defaultInMinutes: baseDuration + addOnMinutes },
+        bufferTimeInMinutes: 10,
+        scheduleId: service?.schedule?._id,
+      };
+    });
+
+    return { configurations };
+  },
+});
+```
+
+## Key Implementation Notes
+
+1. **One configuration per requested entry, same order** — the response array must line up positionally with the request's `services`, even when the same service GUID repeats with different `customerChoices`.
+2. **Prefer `addOnIds` over `durationInMinutes`** in the request — when both are present they must agree, so let Wix Bookings compute total duration from add-ons rather than passing a duration you'd have to keep in sync.
+3. **`splitIntervalInMinutes` vs `duration`** — when the split interval matches the service duration, `splitIntervalInMinutes` is `duration.defaultInMinutes + bufferTimeInMinutes`.
+4. **Duration ranges** — use `durationUnit` for services where the customer picks the length of the booking; leave `duration` empty for `DAY`-unit ranges.
+5. **Called on the hot path** — this handler runs on every availability query, so keep it fast.
+6. **`services` is optional on the request type** — default it to `[]` when destructuring, or the `.map()` calls fail `tsc` with "possibly undefined."

package/skills/wix-app/references/service-plugin/BOOKING-POLICY.md

@@ -0,0 +1,65 @@
+# Booking Policy Service Plugin Reference
+
+## Overview
+
+The Booking Policy SPI lets you provide dynamic booking policies instead of a service's single static policy. Wix calls your `listBookingPolicies` handler whenever it needs to know how early/late a service can be booked or whether online booking is allowed — for example, when a customer loads the booking calendar or books a service. Your implementation can return a different policy for the same service based on your own criteria (e.g., customer type, time of year).
+
+## Request and Response Schema
+
+Before implementing, call `ReadFullDocsMethodSchema` on the docs URL to get the full request/response types.
+
+| Handler | Docs URL |
+| --- | --- |
+| `listBookingPolicies` | https://dev.wix.com/docs/api-reference/business-solutions/bookings/policies/booking-policy-service-plugin/list-booking-policies?apiView=SDK |
+
+The request's `serviceIds` array has 1–8 service GUIDs. Your response's `bookingPolicies` array must contain exactly one policy per requested service, **in the same order** — all fields are required unless the schema marks them optional.
+
+## Example: Different Early-Booking Windows by Service Category
+
+```typescript
+import { bookingPolicy } from "@wix/bookings/service-plugins";
+import { auth } from "@wix/essentials";
+import { services } from "@wix/bookings";
+
+bookingPolicy.provideHandlers({
+  listBookingPolicies: async (payload) => {
+    const { request } = payload;
+    const { serviceIds } = request;
+
+    // queryServices is a fluent query builder, not a request-object call — it returns { items }, not { services }.
+    const elevatedQueryServices = auth.elevate(services.queryServices);
+    const { items: matchedServices } = await elevatedQueryServices().in('_id', serviceIds).find();
+    const serviceById = new Map((matchedServices ?? []).map((s) => [s._id, s]));
+
+    const bookingPolicies = serviceIds.map((serviceId) => {
+      const isPremium = serviceById.get(serviceId)?.category?.name === "Premium";
+
+      return {
+        serviceId,
+        limitEarlyBooking: {
+          enabled: true,
+          earliestBookingInMinutes: isPremium ? 20160 : 10080, // 14 vs 7 days
+        },
+        limitLateBooking: {
+          enabled: true,
+          latestBookingInMinutes: 1440, // 1 day
+        },
+        onlineBooking: { enabled: true },
+      };
+    });
+
+    return { bookingPolicies };
+  },
+});
+```
+
+## Manual Setup Required
+
+None. Confirmed the overall availability/policy pipeline this plugin feeds into is live and enforcing real constraints (a dashboard booking attempt was correctly rejected for being outside staff working hours) — this SPI's own specific early/late-booking window differentiation wasn't isolated independently of that pipeline, but no dashboard configuration is needed beyond having the app installed and released.
+
+## Key Implementation Notes
+
+1. **One policy per service, same order** — the response array must line up positionally with the request's `serviceIds`; don't omit or reorder entries.
+2. **All fields required unless marked optional** — return `limitEarlyBooking`, `limitLateBooking`, and `onlineBooking` fully populated rather than partially.
+3. **Called on the hot path** — this handler runs whenever availability is queried or a booking is made, so keep it fast and avoid unnecessary external calls.
+4. **Elevate permissions** — use `auth.elevate` when querying Wix APIs (e.g., service details) from the handler.

package/skills/wix-app/references/service-plugin/BOOKINGS-PRICING.md

@@ -0,0 +1,71 @@
+# Bookings Pricing Provider Service Plugin Reference
+
+## ⚠️ Requires manual sign-up before it's live
+
+Unlike every other SPI in this skill, this integration isn't self-serve. Before Wix will ever call your handler on a real site, email `bookings-integration@wix.com` with subject "Bookings Pricing Integration" and include: your business type, a few words about your business/market, the URL of the site hosting your app, and your app ID. Wix reviews the request and replies by email. **Implement and build the plugin, but tell the user this sign-up step is required and still pending** — don't present the feature as live just because the code compiles and builds.
+
+## Overview
+
+The Bookings Pricing Provider lets your app calculate custom prices for bookings — regional tax, discounts for specific customer types, or any combination — instead of Wix's standard per-variant pricing. Once installed, your plugin becomes the **sole source of price** for the service: Wix does not hand you a pre-computed subtotal to adjust, so if you need a base price, derive or store it yourself (e.g. read it from the service via `@wix/bookings`, or from your own config).
+
+Wix calls your handler only *after* a booking already exists (`booking._id` is set) — this SPI cannot be used in advance to preview a price list. There is only one handler; there's no separate "preview" handler.
+
+**FQDN**: `wix.bookings.pricing.v1.pricing_provider`
+
+## Request and Response Schema
+
+Before implementing, call `ReadFullDocsMethodSchema` on the docs URL to get the full request/response types. Note: the public docs page for this SPI still describes an older REST/webhook-only integration and does not yet reflect the `provideHandlers` SDK wrapper below — trust what `wix generate` actually scaffolds and the installed `@wix/auto_sdk_bookings_pricing-provider` types over the doc's prose/code samples, but its **field descriptions** (e.g. `booking.contactDetails.fullAddress.subdivision`) and the sign-up requirement above are still accurate.
+
+| Handler | Docs URL |
+| --- | --- |
+| `calculatePrice` | https://dev.wix.com/docs/api-reference/business-solutions/bookings/pricing/pricing-integration-service-plugin/calculate-price |
+
+Your handler receives `{ request: { booking }, metadata }`, where `booking` is the full [booking object](https://dev.wix.com/docs/rest/business-solutions/bookings/bookings/bookings-writer-v2/booking-object) — pull whatever you need from it (e.g. `booking.contactDetails.fullAddress.subdivision` for regional tax, `booking.totalParticipants` / `booking.participantsChoices` for participant count). Return **either**:
+
+- `{ calculatedPrice: <number> }` — a numeric price. The site owner's dashboard can perform further calculations on top of it, but calling the Preview Price API on a booking priced this way fails.
+- `{ priceDescription: <string> }` — a textual price description — lets Preview Price succeed, but Wix cannot do further numeric calculations on it.
+
+Decide which shape to return before you write the handler; you can't mix both per request.
+
+## Example: Regional Tax From Contact Address
+
+```typescript
+import { pricingProvider } from "@wix/bookings/service-plugins";
+
+const TAX_RATE_BY_SUBDIVISION: Record<string, number> = {
+  CA: 0.0725,
+  NY: 0.08,
+};
+
+const BASE_PRICE_PER_PARTICIPANT = 100; // wire this to your real per-service price
+
+pricingProvider.provideHandlers({
+  calculatePrice: async (payload) => {
+    const { booking } = payload.request;
+    if (!booking) {
+      return { calculatedPrice: 0 };
+    }
+
+    const participants =
+      booking.totalParticipants ??
+      (booking.participantsChoices?.serviceChoices ?? []).reduce(
+        (sum, choice) => sum + (choice.numberOfParticipants ?? 0),
+        0
+      ) ??
+      1;
+
+    const subdivision = booking.contactDetails?.fullAddress?.subdivision;
+    const taxRate = subdivision ? TAX_RATE_BY_SUBDIVISION[subdivision] ?? 0 : 0;
+
+    return { calculatedPrice: BASE_PRICE_PER_PARTICIPANT * participants * (1 + taxRate) };
+  },
+});
+```
+
+## Key Implementation Notes
+
+1. **Sign-up is mandatory and manual** — see the warning above; there is no self-serve activation flow.
+2. **You own pricing entirely** — the request doesn't carry a merchant-configured base price; compute or look one up yourself.
+3. **Only called after booking creation** — you cannot use this SPI to display prices in advance of a booking existing.
+4. **Pick one response shape** — a numeric `calculatedPrice` (lets the dashboard add further calculations, but breaks Preview Price) or a `priceDescription` (the reverse). Decide once, per your app's use case.
+5. **Confirm with the user before promising this feature** — since activation depends on an out-of-band email approval, tell the user this step is required rather than assuming the integration is live once code is deployed.

package/skills/wix-app/references/service-plugin/BOOKINGS-STAFF-SORTING.md

@@ -36,10 +36,12 @@ import { extendedBookings } from "@wix/bookings";
 staffSorting.provideHandlers({
   sortStaffMembers: async (payload) => {
     const { request } = payload;
-    const { availableResourceIds, slot } = request;
+    // availableResourceIds is optional on the request type — default it, or
+    // spreading/iterating it below fails `tsc` with "possibly undefined."
+    const { availableResourceIds = [], slot } = request;
 
     const sevenDaysAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();
-    const elevatedQuery = auth.elevate(extendedBookings.query);
+    const elevatedQuery = auth.elevate(extendedBookings.queryExtendedBookings);
     const result = await elevatedQuery({
       filter: {
         "bookedEntity.item.slot.resource.id": { "$in": availableResourceIds },
@@ -73,10 +75,16 @@ staffSorting.provideHandlers({
 });
 ```
 
+## Manual Setup Required
+
+None. Confirmed live with a service that has 2 assigned staff — the dashboard's "Add booking" flow resolved a specific staff member from the plugin's sorted order, and the booking created successfully with no errors. No dashboard configuration is needed beyond having the app installed and released, and the service having 2+ staff assigned to genuinely exercise the sort.
+
 ## Key Implementation Notes
 
 1. **Return all IDs** - You must return every ID from `availableResourceIds`, just reordered
 2. **Performance matters** - Keep logic fast; the booking flow waits for your response
 3. **Elevate permissions** - Use `auth.elevate` when querying Wix APIs from the handler
 4. **Deterministic sorting** - Use a tiebreaker (e.g., resource ID) when priorities are equal
-5. **Graceful degradation** - If your external data source is unavailable, return the original order rather than failing
+5. **Use `queryExtendedBookings`, not `query`** — `extendedBookings.query` is deprecated. `queryExtendedBookings` takes the same `filter`/`cursorPaging` shape, so it's a drop-in replacement; confirmed live after switching.
+6. **`availableResourceIds` is optional on the request type** — default it to `[]` when destructuring, or spreading/iterating it fails `tsc` with "possibly undefined."
+7. **Graceful degradation** - If your external data source is unavailable, return the original order rather than failing

package/skills/wix-app/references/service-plugin/BOOKINGS-VALIDATION.md

@@ -0,0 +1,137 @@
+# Bookings Validation Service Plugin Reference
+
+## Overview
+
+The Bookings Validation SPI lets you implement custom validation logic for booking operations. When a customer creates, cancels, or reschedules a booking (single-service or multi-service), Wix calls the handler matching that operation before it executes. Return `valid: true` to allow the operation or `valid: false` to block it with a customer-facing message.
+
+`bookingsValidation.provideHandlers` requires all six handlers in the object literal — TypeScript rejects a partial object even though you may only care about one or two targets. For the ones you don't have real logic for, provide a no-op that returns an empty `results`/`singleServiceBookingResults` array (an empty array is a no-op: "Omitting an item's result treats it as valid," and an empty results array omits every item's result). Confirmed live: `wix generate` itself scaffolds all six handlers by default — that's not incidental boilerplate you can trim.
+
+## Handlers
+
+| Handler | Validation target | On error/timeout |
+| --- | --- | --- |
+| `validateBeforeCreate` | `CREATE` | Blocked (fail-closed) |
+| `validateBeforeCancel` | `CANCEL` | Blocked (fail-closed) |
+| `validateBeforeReschedule` | `RESCHEDULE` | Continues (fail-open) |
+| `validateBeforeCreateMultiService` | `CREATE_MULTI_SERVICE` | Blocked (fail-closed) |
+| `validateBeforeCancelMultiService` | `CANCEL_MULTI_SERVICE` | Blocked (fail-closed) |
+| `validateBeforeRescheduleMultiService` | `RESCHEDULE_MULTI_SERVICE` | Continues (fail-open) |
+
+## Request and Response Schema
+
+Before implementing, call `ReadFullDocsMethodSchema` on each docs URL to get the full request/response types.
+
+| Handler | Docs URL |
+| --- | --- |
+| `validateBeforeCreate` | https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-validation-service-plugin/validate-before-create?apiView=SDK |
+| `validateBeforeCancel` | https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-validation-service-plugin/validate-before-cancel?apiView=SDK |
+| `validateBeforeReschedule` | https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-validation-service-plugin/validate-before-reschedule?apiView=SDK |
+| `validateBeforeCreateMultiService` | https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-validation-service-plugin/validate-before-create-multi-service?apiView=SDK |
+| `validateBeforeCancelMultiService` | https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-validation-service-plugin/validate-before-cancel-multi-service?apiView=SDK |
+| `validateBeforeRescheduleMultiService` | https://dev.wix.com/docs/api-reference/business-solutions/bookings/bookings/bookings-validation-service-plugin/validate-before-reschedule-multi-service?apiView=SDK |
+
+**Correlation differs by handler — this is easy to get wrong, and doing so fails `tsc`, not just at runtime:**
+
+| Handler(s) | Item shape | Max items | Result correlates by |
+| --- | --- | --- | --- |
+| `validateBeforeCreate`, `validateBeforeCreateMultiService` | `{ itemIndex, booking }` | 40 | `itemIndex` |
+| `validateBeforeCancel`, `validateBeforeReschedule`, and their multi-service equivalents | `{ booking }` — **no `itemIndex` field at all** | 8 | `bookingId` (from `booking._id`) |
+
+Only the create family carries `itemIndex`; cancel and reschedule items don't have one, so their results key on the booking's own ID instead. The single-service response field is `results`; the multi-service response field is `singleServiceBookingResults` — same per-item shape either way. Omitting an item's result treats it as valid. `contactDetails` and resource `name`/`email` fields are redacted before reaching your handler.
+
+## Example: Membership Limit and Cancellation Fee
+
+This example enforces a pricing-plan booking limit on create, and blocks late cancellations.
+
+```typescript
+import { bookingsValidation } from "@wix/bookings/service-plugins";
+import { auth } from "@wix/essentials";
+import { orders } from "@wix/pricing-plans";
+
+bookingsValidation.provideHandlers({
+  validateBeforeCreate: async (payload) => {
+    const { request } = payload;
+
+    const results = await Promise.all(
+      (request.items ?? []).map(async (item) => {
+        const memberId = item.booking?.contactDetails?.contactId;
+        if (!memberId) {
+          return { itemIndex: item.itemIndex, result: { valid: true } };
+        }
+
+        // Not orders.listOrders — that method doesn't exist on @wix/pricing-plans.
+        // managementListOrders takes flat buyerIds/orderStatuses, not a nested filter.
+        const elevatedListOrders = auth.elevate(orders.managementListOrders);
+        const { orders: activeOrders } = await elevatedListOrders({
+          buyerIds: [memberId],
+          orderStatuses: ["ACTIVE"],
+        });
+
+        if ((activeOrders ?? []).length === 0) {
+          return {
+            itemIndex: item.itemIndex,
+            result: {
+              valid: false,
+              invalidReason: {
+                message: "An active membership is required to book this service.",
+                fieldViolations: [
+                  { field: "booking.contactDetails", description: "No active membership found.", code: "PLAN_EXPIRED" },
+                ],
+              },
+            },
+          };
+        }
+
+        return { itemIndex: item.itemIndex, result: { valid: true } };
+      })
+    );
+
+    return { results };
+  },
+
+  validateBeforeCancel: async (payload) => {
+    const { request } = payload;
+
+    // Cancel items carry no itemIndex — correlate results by the booking's own _id.
+    const results = (request.items ?? []).map((item) => {
+      const bookingId = item.booking?._id ?? undefined;
+      const startDate = item.booking?.bookedEntity?.slot?.startDate;
+      const hoursUntilStart = startDate
+        ? (new Date(startDate).getTime() - Date.now()) / (1000 * 60 * 60)
+        : Infinity;
+
+      if (hoursUntilStart < 24) {
+        return {
+          bookingId,
+          result: {
+            valid: false,
+            invalidReason: { message: "Cancellations within 24 hours of the appointment aren't allowed." },
+          },
+        };
+      }
+
+      return { bookingId, result: { valid: true } };
+    });
+
+    return { results };
+  },
+
+  // Unimplemented targets still need a handler — see the note above the example.
+  validateBeforeReschedule: async () => ({ results: [] }),
+  validateBeforeCreateMultiService: async () => ({ singleServiceBookingResults: [] }),
+  validateBeforeCancelMultiService: async () => ({ singleServiceBookingResults: [] }),
+  validateBeforeRescheduleMultiService: async () => ({ singleServiceBookingResults: [] }),
+});
+```
+
+## Manual Setup Required
+
+None — confirmed live via the real Cancel Booking API: a cancellation under 24h was correctly blocked with a structured `428 VALIDATION_FAILED`, and one over 24h correctly succeeded. Wix calls this plugin automatically on the relevant booking operations once the app is installed and released.
+
+## Key Implementation Notes
+
+1. **Bulk requests, per-item results** — return a result for every item you received (keyed by `itemIndex` on create, by `bookingId` on cancel/reschedule — see the correlation table above); a missing entry is treated as valid, not rejected.
+2. **Respond fast** — `validateBeforeCreate`, `validateBeforeCancel`, and their multi-service equivalents fail-closed (block the operation) on error or timeout; `validateBeforeReschedule` and its multi-service equivalent fail-open (allow it).
+3. **Multiple providers run concurrently** — if other apps also register validators for the same target, any single rejection blocks the operation.
+4. **Write customer-facing messages** — `invalidReason.message` and `fieldViolations[].description` are shown to the customer; keep them clear and free of internal jargon. `fieldViolations[].code` is for your own programmatic handling, not display.
+5. **Elevate permissions** — use `auth.elevate` when querying Wix APIs (e.g., pricing plan orders) from the handler.

package/skills/wix-app/references/service-plugin/DISCOUNT-TRIGGERS.md

@@ -20,6 +20,10 @@ Before implementing, call `ReadFullDocsMethodSchema` on each docs URL to get the
 | `getEligibleTriggers` | https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/extensions/discounts/custom-discount-triggers-integration-service-plugin/get-eligible-triggers?apiView=SDK |
 | `listTriggers` | https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/extensions/discounts/custom-discount-triggers-integration-service-plugin/list-triggers?apiView=SDK |
 
+## ⚠️ `identifier` must be echoed from the request, never invented
+
+`getEligibleTriggers` receives `request.triggers[]`, each with a `customTrigger._id` and an `identifier` Wix generated for that occurrence. Your response's `eligibleTriggers[i].identifier` **must be the exact same value** from the matching `request.triggers[i].identifier` — it's how Wix correlates your answer back to the discount rule that asked. A hardcoded or self-invented `identifier` never matches, so the discount silently never applies — confirmed live: the discount rule stays wired up and no error is raised, it just never fires.
+
 ## Example: Happy Hour and Digital Products Triggers
 
 This example defines two custom triggers: a time-based "Happy Hour" trigger and a product-type-based "Digital Sale" trigger.
@@ -30,22 +34,16 @@ import { customTriggers } from "@wix/ecom/service-plugins";
 customTriggers.provideHandlers({
   getEligibleTriggers: async (payload) => {
     const { request, metadata } = payload;
-    // Use the `request` and `metadata` received from Wix and
-    // apply custom logic.
-    return {
-      // Return your response exactly as documented to integrate with Wix.
-      // Return value example:
-      eligibleTriggers: [
-        {
-          customTriggerId: "my-happy-hour-trigger",
-          identifier: "123",
-        },
-        {
-          customTriggerId: "my-digital-sale-trigger",
-          identifier: "234",
-        },
-      ],
-    };
+    // request.triggers tells you which trigger occurrences Wix is asking about —
+    // filter to the ones you recognize and echo back their `identifier` exactly.
+    const eligibleTriggers = (request.triggers ?? [])
+      .filter((t) => t.customTrigger?._id === "my-happy-hour-trigger" /* + your eligibility check */)
+      .map((t) => ({
+        customTriggerId: "my-happy-hour-trigger",
+        identifier: t.identifier,
+      }));
+
+    return { eligibleTriggers };
   },
   listTriggers: async (payload) => {
     const { request, metadata } = payload;
@@ -79,3 +77,12 @@ customTriggers.provideHandlers({
 2. **Both handlers required** - You must implement both `getEligibleTriggers` and `listTriggers`
 3. **Dynamic eligibility** - `getEligibleTriggers` is called during checkout to determine which triggers are currently active
 4. **Static list** - `listTriggers` provides the master list of all possible triggers for configuration in the Wix dashboard
+5. **Manual step required, every time** — this plugin only supplies *eligibility*. It has no visible effect until the merchant creates an Automatic Discount that uses your trigger. Tell the user this step is required; don't imply the discount is live just because the plugin is installed. Confirmed live, click-by-click in the dashboard:
+   1. Go to **Catalog** (left sidebar) → **Discounts** → **Automatic Discounts**.
+   2. Click **Create Discount**.
+   3. Pick a discount type (e.g. **Standard discount**) and click **Continue**.
+   4. Under **Offer** → **"Are there any requirements?"**, check **Custom requirement**.
+   5. A dropdown appears next to it — click it and select your trigger by the `name` your `listTriggers` handler returned for it (e.g. "Happy Hour 16:00-18:00"). It only shows up here once your app is installed and `listTriggers` includes it — there's no dashboard flow to type in an arbitrary trigger ID.
+   6. Fill in the discount's offer/eligibility/dates as normal, then click **Save**.
+
+   Note: the dialog's own **"Create New"** button under that dropdown only offers Wix's *built-in* requirement templates (email domain, first purchase, order count, etc.) — it does not create a new app-linked custom trigger. Your trigger must already be coming back from `listTriggers` to appear in the dropdown at all.

package/skills/wix-app/references/service-plugin/GIFT-CARDS.md

@@ -67,6 +67,10 @@ giftVouchersProvider.provideHandlers({
 });
 ```
 
+## Manual Setup Required
+
+No dashboard configuration beyond installing the app. But there's nothing to `redeem`/`getBalance` against until a real gift card exists — a customer (or you, via the Wix Gift Cards app's own purchase/issuance flow) must actually buy or be issued a gift card first. You can't shortcut this by calling `redeem` with a made-up code; the code has to correspond to a gift card your provider recognizes as real. Test by issuing a real gift card through the site's own gift-card purchase flow, then redeeming it at checkout.
+
 ## Singular Constraint
 
 `GIFT_CARDS_PROVIDER` is **singular** — only one component of this type is allowed per app. Do not scaffold or include two Gift Cards service plugins in the same app.

package/skills/wix-app/references/service-plugin/PAYMENT-SETTINGS.md

@@ -45,7 +45,6 @@ paymentSettings.provideHandlers({
       };
     }
   },
-  getPaymentSettingsForCheckout: async () => ({ blockedPaymentOptions: [] }),
 });
 ```
 
@@ -84,10 +83,13 @@ paymentSettings.provideHandlers({
       };
     }
   },
-  getPaymentSettingsForCheckout: async () => ({ blockedPaymentOptions: [] }),
 });
 ```
 
+## Manual Setup Required
+
+No dashboard configuration beyond installing the app — Wix calls this SPI automatically once installed. The one real prerequisite: **a payment provider must already be connected** on the site (Wix Payments or another provider), or there's nothing for `requires3dSecure` to apply to. You can't exercise this handler with just a Cart `calculate`/`refresh` call — it only fires during actual payment submission (a customer entering card details), so verifying it end-to-end needs a real or sandbox payment attempt, not just an API-level cart inspection.
+
 ## Key Implementation Notes
 
 1. **Payment provider required** - Site must have a payment provider connected to collect payments