@wix/agent-skills 1.0.0

package/skills/wix-app/references/editor-react-component/REACT-PATTERNS.md

@@ -0,0 +1,137 @@
+# React Component Patterns
+
+Code patterns and common mistakes for Editor React components.
+
+# Part 1: Implementation Patterns
+
+## 1.1 SSR-Safe Implementation
+
+Avoid browser-only APIs at module scope or during render; use them inside `useEffect` with `typeof window !== 'undefined'`.
+
+**❌ Wrong:**
+
+```typescript
+const userAgent = window.navigator.userAgent;
+```
+
+**✅ Correct:**
+
+```typescript
+useEffect(() => {
+  if (typeof window !== "undefined") {
+    const userAgent = window.navigator.userAgent;
+  }
+}, []);
+```
+
+## 1.2 Element Visibility (Platform-Managed)
+
+See [`PROPS-VS-CSS.md`](PROPS-VS-CSS.md) — element visibility is platform-managed; always render all elements, no conditional rendering.
+
+---
+
+# Part 2: CSS/SCSS Rules
+
+Authoritative SCSS rules: `REACT-GUIDELINES.md` Part 2. For RTL/logical CSS patterns, see [`DIRECTIONALITY.md`](DIRECTIONALITY.md).
+
+## 2.1 What NOT to Include
+
+```scss
+// ❌ NEVER include:
+
+// State CSS
+&:hover { ... }              // ❌
+&:focus { ... }              // ❌
+&:disabled { ... }           // ❌
+&[data-state='open'] { ... } // ❌
+
+// Transitions/Animations
+transition: all 0.3s;        // ❌
+animation: fadeIn 0.5s;      // ❌
+```
+
+---
+
+# Part 3: Common Mistakes
+
+## 3.1 Adding interaction-state CSS to parts
+
+The resting visual (background, color, border-radius, padding, font)
+belongs in the component's CSS — see `CSS-GUIDELINES.md` §"Keep all
+styling in CSS". What does NOT belong is **interaction-state CSS**
+(`:hover`, `:focus`, `:focus-visible`, `:active`, `:disabled`,
+`[data-state]`, `[aria-selected]`) — the platform owns those.
+Selection / mode variants (`selected`, `active`, `open`) are
+different — they go through a JS-toggled modifier class; see
+`CSS-GUIDELINES.md` §"Express selection / mode variants".
+
+**❌ Wrong — pseudo-class rules must be removed:**
+
+```scss
+.button {
+  background-color: #ffffff;
+  color: #0f172a;
+  border-radius: 8px;
+  padding-block: 8px;
+  padding-inline: 16px;
+}
+
+.button:hover { /* ❌ Interaction state — platform owns this */
+  background-color: #f0f0f0;
+}
+
+.button:disabled { /* ❌ Interaction state — platform owns this */
+  opacity: 0.5;
+}
+```
+
+**✅ Correct — keep the resting visual; drop the pseudo-class rules:**
+
+```scss
+.button {
+  display: flex;
+  align-items: center;
+  background-color: #ffffff;
+  color: #0f172a;
+  border-radius: 8px;
+  padding-block: 8px;
+  padding-inline: 16px;
+  box-sizing: border-box;
+}
+```
+
+## 3.2 Browser APIs at module scope
+
+**❌ Wrong:**
+
+```typescript
+const isMobile = window.innerWidth < 768; // ❌ SSR breaks
+```
+
+**✅ Correct:**
+
+```typescript
+useEffect(() => {
+  if (typeof window !== "undefined") {
+    setIsMobile(window.innerWidth < 768);
+  }
+}, []);
+```
+
+## 3.3 Use semantic HTML for collection-style UI
+
+For lists, breadcrumbs, tabs, menus, and similar collection-style UI, render the underlying semantic HTML directly (`<ol>`/`<ul>` + `<li>`, `<nav>`, `<button role="tab">`, etc.) and own the keyboard / ARIA wiring in your own React code.
+
+```tsx
+<ol className="breadcrumbs">
+  <li>
+    <a href="/">Home</a>
+  </li>
+  <li>
+    <span aria-hidden="true">/</span>
+    <a href="/products">Products</a>
+  </li>
+</ol>
+```
+
+Handle separators with CSS pseudo-elements or inside each item.

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

@@ -0,0 +1,112 @@
+# Additional Fees Service Plugin Reference
+
+## Overview
+
+The Additional Fees SPI allows you to add custom fees to orders during checkout, such as handling fees, rush delivery charges, or global order fees.
+
+## Import
+
+```typescript
+import { additionalFees } from '@wix/ecom/service-plugins';
+```
+
+## Handler
+
+| Handler | Description |
+| --- | --- |
+| `calculateAdditionalFees` | Calculate and return additional fees to apply to the order |
+
+## Request and Response Schema
+
+Before implementing, call `ReadFullDocsMethodSchema` with the docs URL below to get the full request/response types.
+
+**MCP Tools to use:**
+- `ReadFullDocsMethodSchema` - Full request/response schema with field names, types, and descriptions
+- `ReadFullDocsArticle` - Full documentation with code examples (use if schema needs more context)
+
+| Handler | Docs URL |
+| --- | --- |
+| `calculateAdditionalFees` | https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/extensions/additional-fees/additional-fees-service-plugin/calculate-additional-fees?apiView=SDK |
+
+## Example: Global Additional Fee from Database Configuration
+
+This example queries a CMS collection to retrieve a configurable global fee that applies to all orders.
+
+```typescript
+import { additionalFees } from '@wix/ecom/service-plugins';
+import { auth } from '@wix/essentials';
+import { items } from '@wix/data';
+
+interface GlobalFeeConfig {
+  _id: string;
+  feeAmount: number;
+  isEnabled: boolean;
+}
+
+additionalFees.provideHandlers({
+  calculateAdditionalFees: async ({ request, metadata }) => {
+    try {
+      // Query the global additional fee configuration (elevated permissions required)
+      const elevatedQuery = auth.elevate(items.query);
+      const configResult = await elevatedQuery('global-additional-fee-config')
+        .limit(1)
+        .find();
+
+      // If no configuration found or fee is disabled, return empty fees
+      if (!configResult.items.length) {
+        return {
+          additionalFees: [],
+          currency: metadata.currency || 'USD'
+        };
+      }
+
+      const config = configResult.items[0] as GlobalFeeConfig;
+
+      // Check if the fee is enabled and has a valid amount
+      if (!config.isEnabled || !config.feeAmount || config.feeAmount <= 0) {
+        return {
+          additionalFees: [],
+          currency: metadata.currency || 'USD'
+        };
+      }
+
+      // Ensure currency matches site currency
+      const responseCurrency = metadata.currency || 'USD';
+
+      // Convert fee amount to string as required by Wix API
+      const feeAmountString = config.feeAmount.toString();
+
+      // Create the global additional fee
+      const globalFee = {
+        code: 'global-additional-fee',
+        name: 'Global Additional Fee',
+        translatedName: 'Global Additional Fee',
+        price: feeAmountString,
+        taxDetails: {
+          taxable: true
+        }
+        // No lineItemIds specified - applies to entire cart
+      };
+
+      return {
+        additionalFees: [globalFee],
+        currency: responseCurrency
+      };
+
+    } catch (error) {
+      return {
+        additionalFees: [],
+        currency: metadata.currency || 'USD'
+      };
+    }
+  },
+});
+```
+
+## Key Implementation Notes
+
+1. **Elevate permissions for API calls** - Use `auth.elevate` from `@wix/essentials` when calling Wix APIs from service plugins
+2. **Return empty array when no fees apply** - Always return `{ additionalFees: [], currency: "..." }` when conditions aren't met
+3. **Price must be a string** - Convert numeric amounts to strings
+4. **Handle errors gracefully** - Return empty fees on error rather than throwing
+5. **Omit lineItemIds for cart-wide fees** - Only specify when fee applies to specific items

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

@@ -0,0 +1,118 @@
+# Bookings Staff Sorting Provider Service Plugin Reference
+
+## Overview
+
+The Staff Sorting Provider SPI allows you to implement custom staff assignment algorithms for Wix Bookings. When a booking slot has multiple available staff members, Wix calls your plugin to determine the priority order for staff assignment.
+
+**FQDN**: `wix.interfaces.resources.sorting.v1.staff_sorting_provider`
+
+## Import
+
+```typescript
+import { staffSorting } from "@wix/bookings/service-plugins";
+```
+
+## Handler
+
+| Handler | Description |
+| --- | --- |
+| `sortStaffMembers` | Sort available staff members by priority for a given booking slot |
+
+## Request and Response Schema
+
+Before implementing, call `ReadFullDocsMethodSchema` with the docs URL below to get the full request/response types.
+
+**MCP Tools to use:**
+- `ReadFullDocsMethodSchema` - Full request/response schema with field names, types, and descriptions
+- `ReadFullDocsArticle` - Full documentation with code examples (use if schema needs more context)
+
+| Handler | Docs URL |
+| --- | --- |
+| `sortStaffMembers` | https://dev.wix.com/docs/api-reference/business-solutions/bookings/staff-members/staff-sorting-service-plugin/sort-staff-members?apiView=SDK |
+
+**Important constraints:**
+- You must return the **exact same IDs** from `availableResourceIds`, reordered by priority
+- Do not add or remove any IDs
+- If your response is invalid, Wix falls back to random assignment
+
+## Performance Requirements
+
+- **Hard limit**: Response must be returned within **5 seconds**
+- **Recommended**: Keep response time under **500ms** for optimal user experience
+
+## Example: Workload Balancing
+
+This example sorts staff members to balance workload by prioritizing those with fewer recent bookings.
+
+```typescript
+import { staffSorting } from "@wix/bookings/service-plugins";
+import { auth } from "@wix/essentials";
+import { bookings } from "@wix/bookings";
+
+staffSorting.provideHandlers({
+  sortStaffMembers: async (payload) => {
+    const { request } = payload;
+    const { availableResourceIds, slot } = request;
+
+    // Query recent bookings for each available staff member
+    const elevatedQuery = auth.elevate(bookings.queryBookings);
+    const recentBookings = await elevatedQuery()
+      .eq("resource.id", availableResourceIds)
+      .ge("start.timestamp", new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString())
+      .find();
+
+    // Count bookings per staff member
+    const bookingCounts = new Map<string, number>();
+    for (const id of availableResourceIds) {
+      bookingCounts.set(id, 0);
+    }
+    for (const booking of recentBookings.items) {
+      const resourceId = booking.resource?.id;
+      if (resourceId && bookingCounts.has(resourceId)) {
+        bookingCounts.set(resourceId, (bookingCounts.get(resourceId) ?? 0) + 1);
+      }
+    }
+
+    // Sort by fewest bookings first (balance workload)
+    const sorted = [...availableResourceIds].sort(
+      (a, b) => (bookingCounts.get(a) ?? 0) - (bookingCounts.get(b) ?? 0)
+    );
+
+    return {
+      staff: sorted.map((resourceId) => ({ resourceId })),
+    };
+  },
+});
+```
+
+## Extension Registration
+
+Register the staff sorting provider using the `bookingsStaffSortingProvider()` builder. This builder requires additional fields beyond the standard ones:
+
+```typescript
+import { extensions } from "@wix/astro/builders";
+
+export const staffSorting = extensions.bookingsStaffSortingProvider({
+  id: "{{GENERATE_UUID}}",
+  name: "Workload Balanced Staff Assignment",
+  source: "./backend/service-plugins/bookings-staff-sorting/workload-balancer/plugin.ts",
+  methodName: "Workload Balancer",
+  methodDescription: "Balances workload by prioritizing staff with fewer recent bookings",
+});
+```
+
+### Additional Builder Fields
+
+| Field | Type | Required | Max Length | Description |
+| --- | --- | --- | --- | --- |
+| `methodName` | string | Yes | - | Display name for the sorting method |
+| `methodDescription` | string | Yes | 100 chars | Description of the sorting algorithm (max 100 characters) |
+| `dashboardPluginId` | string | No | - | Optional dashboard plugin ID for configuration UI |
+
+## 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

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

@@ -0,0 +1,87 @@
+# Discount Triggers Service Plugin Reference
+
+## Overview
+
+The Custom Triggers SPI allows you to define custom conditions that can trigger discounts in the Wix eCommerce system. You can create time-based triggers, product-based triggers, or any custom logic.
+
+## Import
+
+```typescript
+import { customTriggers } from "@wix/ecom/service-plugins";
+```
+
+## Handlers
+
+| Handler | Description |
+| --- | --- |
+| `getEligibleTriggers` | Evaluate current conditions and return which triggers are active |
+| `listTriggers` | Return the list of all available custom triggers |
+
+## Request and Response Schema
+
+Before implementing, call `ReadFullDocsMethodSchema` with the docs URLs below to get the full request/response types.
+
+**MCP Tools to use:**
+- `ReadFullDocsMethodSchema` - Full request/response schema with field names, types, and descriptions
+- `ReadFullDocsArticle` - Full documentation with code examples (use if schema needs more context)
+
+| Handler | Docs URL |
+| --- | --- |
+| `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 |
+
+## 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.
+
+```typescript
+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",
+        },
+      ],
+    };
+  },
+  listTriggers: 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:
+      customTriggers: [
+        {
+          _id: "my-happy-hour-trigger",
+          name: "Happy Hour 16:00-18:00",
+        },
+        {
+          _id: "my-digital-sale-trigger",
+          name: "Digital products discount",
+        },
+      ],
+    };
+  },
+});
+```
+
+## Key Implementation Notes
+
+1. **Trigger IDs must match** - The `customTriggerId` in `getEligibleTriggers` must match an `_id` from `listTriggers`
+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

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

@@ -0,0 +1,86 @@
+# Gift Cards Service Plugin Reference
+
+## Overview
+
+The Gift Vouchers Provider SPI allows you to integrate external gift card or voucher systems with Wix eCommerce. This enables customers to redeem gift cards, check balances, and void transactions.
+
+## Import
+
+```typescript
+import { giftVouchersProvider } from '@wix/ecom/service-plugins';
+```
+
+## Handlers
+
+| Handler | Description |
+| --- | --- |
+| `redeem` | Process a gift card redemption during checkout |
+| `getBalance` | Check the current balance of a gift card |
+| `_void` | Cancel/void a previous redemption |
+
+## Request and Response Schema
+
+Before implementing, call `ReadFullDocsMethodSchema` with the docs URLs below to get the full request/response types.
+
+**MCP Tools to use:**
+- `ReadFullDocsMethodSchema` - Full request/response schema with field names, types, and descriptions
+- `ReadFullDocsArticle` - Full documentation with code examples (use if schema needs more context)
+
+| Handler | Docs URL |
+| --- | --- |
+| `redeem` | https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/gift-cards/gift-cards-service-plugin/redeem?apiView=SDK |
+| `getBalance` | https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/gift-cards/gift-cards-service-plugin/get-balance?apiView=SDK |
+| `_void` | https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/gift-cards/gift-cards-service-plugin/void?apiView=SDK |
+
+## Example: Gift Card Provider Implementation
+
+This example shows a basic gift card provider with all three required handlers.
+
+```typescript
+import { giftVouchersProvider } from '@wix/ecom/service-plugins';
+
+giftVouchersProvider.provideHandlers({
+  redeem: 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:
+      remainingBalance: 80.00,
+      currencyCode: metadata.currency || "ILS",
+      transactionId: "00000000-0000-0000-0000-000000000001",
+    };
+  },
+  _void: 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:
+      remainingBalance: 100.00,
+      currencyCode: metadata.currency || "ILS",
+    };
+  },
+  getBalance: 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:
+      balance: 100.00,
+      currencyCode: metadata.currency || "ILS",
+    };
+  },
+});
+```
+
+## Key Implementation Notes
+
+1. **All three handlers required** - You must implement `redeem`, `getBalance`, and `_void`
+2. **Transaction tracking** - The `redeem` handler must return a unique `transactionId` for tracking
+3. **Balance as number** - Unlike other SPIs, balance values are numbers, not strings
+4. **Void restores balance** - The `_void` handler should restore the redeemed amount back to the card
+5. **Currency handling** - Use `metadata.currency` to get the site's currency setting

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

@@ -0,0 +1,135 @@
+# Payment Settings Service Plugin Reference
+
+## Overview
+
+The Payment Settings SPI allows you to integrate custom payment settings with the Wix eCommerce payment process. This is called during payment processing (e.g., when a customer enters credit card details) and returns payment settings that Wix passes to the payment provider.
+
+A common use case is to enforce 3D Secure (3DS) payments for certain transactions based on custom business logic.
+
+## Import
+
+```typescript
+import { paymentSettings } from '@wix/ecom/service-plugins';
+```
+
+## Handler
+
+| Handler | Description |
+| --- | --- |
+| `getPaymentSettings` | Return payment settings to apply during the payment process |
+
+## Request and Response Schema
+
+Before implementing, call `ReadFullDocsMethodSchema` with the docs URL below to get the full request/response types.
+
+**MCP Tools to use:**
+- `ReadFullDocsMethodSchema` - Full request/response schema with field names, types, and descriptions
+- `ReadFullDocsArticle` - Full documentation with code examples (use if schema needs more context)
+
+| Handler | Docs URL |
+| --- | --- |
+| `getPaymentSettings` | https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/payment-settings/payment-settings-integration-service-plugin/get-payment-settings?apiView=SDK |
+
+## Example: Require 3DS for High-Value Transactions
+
+This example enforces 3D Secure authentication for orders above a certain threshold.
+
+```typescript
+import { paymentSettings } from '@wix/ecom/service-plugins';
+
+// Configuration
+const HIGH_VALUE_THRESHOLD = 1000;
+
+paymentSettings.provideHandlers({
+  getPaymentSettings: async ({ request, metadata }) => {
+    try {
+      // Get the order total
+      const orderTotal = request.order?.totals?.total || 0;
+
+      // Determine if 3DS is required based on order value
+      const require3DS = orderTotal >= HIGH_VALUE_THRESHOLD;
+
+      return {
+        paymentSettings: {
+          requires3dSecure: require3DS
+        }
+      };
+    } catch (error) {
+      // Default to not requiring 3DS on error
+      return {
+        paymentSettings: {
+          requires3dSecure: false
+        }
+      };
+    }
+  },
+});
+```
+
+## Example: Region-Based 3DS Requirements
+
+This example requires 3D Secure for specific countries or regions.
+
+```typescript
+import { paymentSettings } from '@wix/ecom/service-plugins';
+
+// Countries that require 3DS
+const REQUIRE_3DS_COUNTRIES = ['GB', 'FR', 'DE', 'IT', 'ES'];
+
+paymentSettings.provideHandlers({
+  getPaymentSettings: async ({ request, metadata }) => {
+    try {
+      // Get billing country from order
+      const billingCountry = request.order?.billingInfo?.address?.country;
+
+      // Check if country requires 3DS
+      const require3DS = billingCountry
+        ? REQUIRE_3DS_COUNTRIES.includes(billingCountry)
+        : false;
+
+      return {
+        paymentSettings: {
+          requires3dSecure: require3DS
+        }
+      };
+    } catch (error) {
+      // Default to not requiring 3DS on error
+      return {
+        paymentSettings: {
+          requires3dSecure: false
+        }
+      };
+    }
+  },
+});
+```
+
+## Key Implementation Notes
+
+1. **Payment provider required** - Site must have a payment provider connected to collect payments
+2. **Provider support required** - The payment provider must support the settings (e.g., not all providers support 3DS)
+3. **Called during checkout** - This handler is invoked when the customer enters payment details during checkout
+4. **Settings passed to provider** - The returned settings are passed to the payment provider for enforcement
+5. **Fallback configuration** - Use the `fallbackValueForRequires3dSecure` builder field to set a default value if the SPI call fails (defaults to `false`)
+6. **Handle errors gracefully** - Return sensible defaults on error rather than throwing
+
+## Extension Registration
+
+Register the payment settings provider using the `ecomPaymentSettings()` builder. This builder accepts a special `fallbackValueForRequires3dSecure` field:
+
+```typescript
+import { extensions } from "@wix/astro/builders";
+
+export const paymentSettings = extensions.ecomPaymentSettings({
+  id: "{{GENERATE_UUID}}",
+  name: "Custom Payment Settings",
+  source: "./backend/service-plugins/ecom-payment-settings/my-payment-settings/plugin.ts",
+  fallbackValueForRequires3dSecure: false, // Default if SPI call fails
+});
+```
+
+### Additional Builder Fields
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `fallbackValueForRequires3dSecure` | boolean | No | Default value for `requires3dSecure` if the SPI call fails (defaults to `false`) |