@wix/agent-skills 1.15.1 → 1.16.1

package/skills/wix-app/references/editor-react-component/SITE-CONTEXT-HOOKS.md

@@ -0,0 +1,187 @@
+# Site Context Hooks
+
+Rules and patterns for reading **runtime site context** in Editor React
+components — the site's page tree, the current URL, the language direction, and
+editor mode. None of these can be carried by a prop.
+
+All of them come from hooks in `@wix/react-component-utils`, already a base
+dependency. No additional install is needed, but the hooks require
+`@wix/react-component-utils` ≥ 1.12.0.
+
+---
+
+## When this applies
+
+Apply only when the component genuinely needs live site context:
+
+- **The component reflects where the visitor is in the site** — breadcrumbs,
+  "you are here" indicators. Not navigation menus: the site owner authors those,
+  and their items need not necessarily be site pages, so they take a
+  `MenuItems` prop
+- **The component needs the page's own URL** — share buttons, copy-link,
+  canonical links, QR codes
+- **Language direction drives JavaScript** — keyboard navigation, transform or
+  animation math, conditional rendering
+- **Behavior must differ inside the editor** — suppressing autoplay, network
+  calls, or timers while the site owner is designing
+
+The test is whether the site owner **authors** the data. A hook reports state the
+owner cannot write — which page is being rendered, what the site's URL is. Data
+the owner chooses belongs in props, even when it happens to point at site
+pages — see [`PROPS-VS-CSS.md`](PROPS-VS-CSS.md) and
+[`COMPONENT-API.md`](COMPONENT-API.md). Purely visual RTL needs no hook
+either — use logical CSS properties, see
+[`DIRECTIONALITY.md`](DIRECTIONALITY.md).
+
+---
+
+## Rules
+
+### The Available Hooks
+
+| Hook | Returns | Use for |
+| --- | --- | --- |
+| `usePages()` | `Readonly<Record<string, PageConfig>>` | Every page on the site, keyed by page id |
+| `useCurrentPageId()` | `string` | Id of the page being rendered |
+| `useMainPageId()` | `string` | Id of the site's homepage |
+| `useSiteUrl()` | `string` | The site's public base URL |
+| `useCurrentUrl()` | `string` | Full URL of the page being rendered |
+| `useLanguageDirection()` | `'ltr' \| 'rtl'` | The site's language direction |
+| `useIsEditMode()` | `boolean` | `true` in editor design mode — see [`COMPONENT-PREVIEW.md`](COMPONENT-PREVIEW.md) |
+| `useReducedMotion()` | `boolean` | `true` when the OS requests reduced motion — see [`ANIMATED-COMPONENTS.md`](ANIMATED-COMPONENTS.md) |
+
+All import from the same place:
+
+```typescript
+import { usePages, useCurrentPageId, useSiteUrl } from '@wix/react-component-utils';
+```
+
+Each returns a plain value, so there is nothing to unwrap or guard. They are
+React hooks — call them at the top of the component or hook body, never at module
+scope, inside a callback, or conditionally.
+
+### Read Values During Render
+
+Hook values are read on the server too, so their results are part of the server
+markup — see [`SSR.md`](SSR.md). Use the value directly.
+
+**✅ Correct:**
+
+```tsx
+const siteUrl = useSiteUrl();
+```
+
+**❌ Wrong — empty on the server, then a hydration mismatch:**
+
+```tsx
+const resolvedUrl = useSiteUrl();
+const [siteUrl, setSiteUrl] = useState('');
+useEffect(() => setSiteUrl(resolvedUrl), []);
+```
+
+---
+
+## Patterns
+
+### Walking the Page Tree
+
+`usePages()` returns a map keyed by page id. Three things to get right:
+
+- **The map key is the page id** — the values carry no `id` field.
+- **`parentPageId` is absent for top-level pages** — treat those as children of
+  `useMainPageId()` when walking upward.
+- **`popup: true` pages are lightboxes**, not navigable pages. Filter them out of
+  breadcrumbs, menus, and page pickers.
+
+```tsx
+import { usePages, useCurrentPageId, useMainPageId } from '@wix/react-component-utils';
+
+export const useBreadcrumbTrail = (): Array<{ id: string; label: string }> => {
+  const pages = usePages();
+  const currentPageId = useCurrentPageId();
+  const mainPageId = useMainPageId();
+
+  const trail: Array<{ id: string; label: string }> = [];
+  const visited = new Set<string>();
+  let pageId: string | undefined = currentPageId;
+
+  while (pageId && !visited.has(pageId) && pages[pageId]) {
+    visited.add(pageId);
+    const page = pages[pageId]!;
+    if (!page.popup) {
+      trail.push({ id: pageId, label: page.title });
+    }
+    // Pages without parentPageId are top-level children of the homepage.
+    pageId = pageId === mainPageId ? undefined : (page.parentPageId ?? mainPageId);
+  }
+
+  return trail.reverse();
+};
+```
+
+The `visited` set is not optional — a misconfigured site can produce a parent
+cycle, and an unguarded walk hangs the render.
+
+### Building a Link to a Page
+
+Join a page's `path` onto `useSiteUrl()`. The base URL may or may not carry a
+trailing slash, so normalize before joining:
+
+```typescript
+const buildPageUrl = (path: string, siteUrl: string): string => {
+  const base = siteUrl.replace(/\/$/, '');
+  return path ? `${base}/${path}` : base;
+};
+```
+
+### Direction-Dependent Logic
+
+Resolve the component's own `direction` prop first, then fall back to the site:
+
+```typescript
+import type { Direction } from '@wix/editor-react-types';
+import { useLanguageDirection } from '@wix/react-component-utils';
+
+export const useResolvedDirection = (direction?: Direction): Direction => {
+  // Call unconditionally — `direction ?? useLanguageDirection()` would
+  // short-circuit and skip the hook whenever the prop is set.
+  const siteDirection = useLanguageDirection() as Direction;
+  return direction ?? siteDirection;
+};
+```
+
+Use the resolved value for **logic only** — arrow-key handling, transform sign,
+scroll direction:
+
+```tsx
+const isRTL = useResolvedDirection(direction) === 'rtl';
+
+const onKeyDown = (event: React.KeyboardEvent) => {
+  const forward = isRTL ? 'ArrowLeft' : 'ArrowRight';
+  if (event.key === forward) {
+    focusNext();
+  }
+};
+```
+
+---
+
+## Common Mistake: Direction Logic Instead of Logical CSS
+
+Calling `useLanguageDirection()` to pick between physical CSS properties.
+
+**❌ Wrong:**
+
+```tsx
+const isRTL = useLanguageDirection() === 'rtl';
+
+<div style={{ paddingLeft: isRTL ? 0 : 8, paddingRight: isRTL ? 8 : 0 }} />
+```
+
+**✅ Correct:**
+
+```scss
+.element {
+  padding-inline-start: 8px; // Auto RTL/LTR, no hook needed
+}
+```

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

@@ -31,27 +31,31 @@ This example sorts staff members to balance workload by prioritizing those with
 ```typescript
 import { staffSorting } from "@wix/bookings/service-plugins";
 import { auth } from "@wix/essentials";
-import { bookings } from "@wix/bookings";
+import { extendedBookings } 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();
+    const sevenDaysAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();
+    const elevatedQuery = auth.elevate(extendedBookings.query);
+    const result = await elevatedQuery({
+      filter: {
+        "bookedEntity.item.slot.resource.id": { "$in": availableResourceIds },
+        "startDate": { "$gte": sevenDaysAgo },
+      },
+      cursorPaging: { limit: 100 },
+    });
+    const recentBookings = result.extendedBookings ?? [];
 
     // 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;
+    for (const booking of recentBookings) {
+      const resourceId = booking.booking?.bookedEntity?.slot?.resource?._id;
       if (resourceId && bookingCounts.has(resourceId)) {
         bookingCounts.set(resourceId, (bookingCounts.get(resourceId) ?? 0) + 1);
       }

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

@@ -69,6 +69,10 @@ customTriggers.provideHandlers({
 });
 ```
 
+## Singular Constraint
+
+`ECOM_DISCOUNTS_TRIGGER` is **singular** — only one component of this type is allowed per app. Do not scaffold or include two Discount Triggers service plugins in the same app.
+
 ## Key Implementation Notes
 
 1. **Trigger IDs must match** - The `customTriggerId` in `getEligibleTriggers` must match an `_id` from `listTriggers`

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

@@ -67,6 +67,10 @@ giftVouchersProvider.provideHandlers({
 });
 ```
 
+## 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.
+
 ## Key Implementation Notes
 
 1. **All three handlers required** - You must implement `redeem`, `getBalance`, and `_void`

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

@@ -26,7 +26,7 @@ paymentSettings.provideHandlers({
   getPaymentSettings: async ({ request, metadata }) => {
     try {
       // Get the order total
-      const orderTotal = request.order?.totals?.total || 0;
+      const orderTotal = Number(request.order?.priceSummary?.total?.amount) || 0;
 
       // Determine if 3DS is required based on order value
       const require3DS = orderTotal >= HIGH_VALUE_THRESHOLD;
@@ -45,6 +45,7 @@ paymentSettings.provideHandlers({
       };
     }
   },
+  getPaymentSettingsForCheckout: async () => ({ blockedPaymentOptions: [] }),
 });
 ```
 
@@ -83,6 +84,7 @@ paymentSettings.provideHandlers({
       };
     }
   },
+  getPaymentSettingsForCheckout: async () => ({ blockedPaymentOptions: [] }),
 });
 ```
 

package/skills/wix-app/references/service-plugin/SHIPPING-RATES.md

@@ -53,6 +53,10 @@ shippingRates.provideHandlers({
 });
 ```
 
+## Singular Constraint
+
+`ECOM_SHIPPING_RATES` is **singular** — only one component of this type is allowed per app. Do not scaffold or include two Shipping Rates service plugins in the same app.
+
 ## Key Implementation Notes
 
 1. **Price as string** - All price values must be strings, not numbers

package/skills/wix-app/references/service-plugin/TOOLS_PROVIDER.md

@@ -0,0 +1,54 @@
+# Tools Provider Service Plugin Reference
+
+## Overview
+
+The Tools Provider SPI lets your app handle tool invocations from the Wix AI assistant. Implement the `runTool` handler — it receives the tool's `methodName` and a JSON `payload`, runs your business logic, and returns a response the AI assistant uses to answer the user.
+
+This is the execution side of the App Tools feature. The declaration side lives in the `APP_TOOLS` extension. See [APP_TOOLS.md](../APP_TOOLS.md) for the full picture.
+
+## Request and Response Schema
+
+Before implementing, call `ReadFullDocsMethodSchema` on the docs URL to get the full request/response types.
+
+| Handler | Docs URL |
+| --- | --- |
+| `runTool` | https://dev.wix.com/docs/api-reference/app-management/app-tools/tools-provider-v1/run-tool?apiView=SDK |
+
+## Example: Routing Tool Calls by methodName
+
+```typescript
+import { toolsProvider } from '@wix/app-tools/service-plugins';
+
+toolsProvider.provideHandlers({
+  runTool: async ({ request, metadata }) => {
+    const { methodName, payload } = request;
+
+    switch (methodName) {
+      case 'get-order-status': {
+        const orderId = payload?.['orderId'];
+        if (typeof orderId !== 'string' || !orderId) {
+          throw new Error('orderId is required');
+        }
+        // fetch order status...
+        return {
+          response: {
+            status: 'shipped',
+            trackingNumber: 'TRACK123'
+          }
+        };
+      }
+
+      default:
+        throw new Error(`Unknown tool: ${methodName}`);
+    }
+  }
+});
+```
+
+## Key Implementation Notes
+
+1. **Route on `methodName`** — use a `switch` or map to dispatch to the right handler logic
+2. **Validate inputs defensively** — `requestSchema` is advisory for the AI assistant; Wix does not validate the payload before calling your handler
+3. **Handle all activated tools** — cover every `methodName` with `activated: true` in your `APP_TOOLS` declaration; unhandled names should throw a clear error
+4. **Respond quickly** — the AI assistant is waiting; slow responses degrade the user experience
+5. **Elevate permissions for Wix API calls** — wrap SDK methods with `auth.elevate` from `@wix/essentials`

package/skills/wix-app/references/stores/QUERY.md

@@ -60,6 +60,38 @@ export async function listProductsPage(
 
 ---
 
+## Search products by name
+
+V3 `queryProducts` filters only on `_id`, `slug`, `options.id` and `handle` — `name` is a
+compile error. Use `productsV3.searchProducts()`, a direct call rather than a builder. V1 has
+no search method; its builder accepts `name` via `startsWith` (prefix match only, no `fuzzy`).
+
+Imports come from the first example in this file.
+
+```typescript
+// `v` comes from getVersion() — see STORES_VERSIONING.md.
+export async function searchByName(
+  term: string,
+  limit: number,
+  v: 'V1_CATALOG' | 'V3_CATALOG' | 'STORES_NOT_INSTALLED',
+) {
+  if (v === 'V3_CATALOG') {
+    const res = await productsV3.searchProducts({
+      cursorPaging: { limit },
+      // `fields` is required for free-text search. Searchable: 'name', 'description',
+      // 'variantsInfo.variants.sku', 'minVariantPriceInfo.sku'.
+      search: { expression: term, fields: ['name'], fuzzy: true },
+    });
+    // Note `products` (not `items`) and `pagingMetadata.hasNext` (a property, not a method).
+    return res.products ?? [];
+  }
+  const res = await products.queryProducts().startsWith('name', term).limit(limit).find();
+  return res.items;
+}
+```
+
+---
+
 ## Display price/stock without fetching variants
 
 V3 `queryProducts` does not return variants. Read product-level rollup fields instead: