@wix/auto-patterns 1.39.0 → 1.41.0

package/mcp-docs/error_handling.md

@@ -11,12 +11,53 @@
 
 **⚠️ CRITICAL**: When implementing custom data sources that make HTTP requests, you **MUST** wrap specific HTTP calls with proper error handling. This ensures consistent error management, prevents unhandled promise rejections, and provides better user experience.
 
+## 🚨 GOLDEN RULE: If it's a Wix Library, Wrap it with errorHandler!
+
+**Simple Rule for AI Agents:**
+- **ANY Wix SDK call** from libraries with `@wix/` prefix → **ALWAYS wrap with `errorHandler.withErrorHandler`**
+- This includes: `@wix/data`, `@wix/stores`, `@wix/events`, `@wix/bookings`, `@wix/crm`, and ALL other `@wix/*` packages
+- **NO exceptions** - all Wix SDK calls must use error handling
+
+### ❌ DON'T DO THIS (Common Mistake)
+
+```typescript
+import { items } from '@wix/data';
+
+// ❌ WRONG - No errorHandler wrapping
+async function getAllPets() {
+  try {
+    const result = await items.query('WixPets').find();
+    return result.items;
+  } catch (error) {
+    console.error(error);
+    throw error;
+  }
+}
+```
+
+### ✅ DO THIS (Correct Pattern)
+
+```typescript
+import { items } from '@wix/data';
+import { errorHandler } from '@wix/essentials';
+
+// ✅ CORRECT - Wix SDK call wrapped with errorHandler
+async function getAllPets() {
+  return errorHandler.withErrorHandler(
+    async () => {
+      const result = await items.query('WixPets').find();
+      return result.items;
+    },
+    {}
+  );
+}
+```
 ## What Requires Error Handling
 
 **ONLY the following HTTP requests** in your custom data source actions must be wrapped with `errorHandler.withErrorHandler`:
 
 - **httpClient from @wix/essentials** (e.g., `httpClient.request(getDummyEntity(...))`)
-- **Wix APIs** (e.g., `wix/data`, `wix/stores`, `items.get()`, `items.insert()`, `collections.getDataCollection()`)
+- **Wix API calls from libraries with `wix/` prefix** (e.g., `@wix/data`, `@wix/stores`, `@wix/events`, `@wix/bookings`, `collections.getDataCollection()`, etc.)
 - **httpClient.fetchWithAuth()** calls
 
 **DO NOT use errorHandler.withErrorHandler with:**
@@ -154,12 +195,68 @@ return errorHandler.withErrorHandler(async () => {
 }, {});
 ```
 
-**Wix APIs (wix/data, wix/stores):**
+**Wix APIs (@wix/data, @wix/stores, @wix/crm, etc.):**
 
 ```typescript
+import { items } from '@wix/data';
+import { errorHandler } from '@wix/essentials';
+
+// ✅ CORRECT: Wix Data API calls wrapped with errorHandler
 return errorHandler.withErrorHandler(async () => {
   return await items.get(collectionId, entityId);
 }, {});
+
+// ✅ CORRECT: Query operations wrapped with errorHandler
+return errorHandler.withErrorHandler(async () => {
+  return await items.query('WixPets').find();
+}, {});
+
+// ✅ CORRECT: Insert operations wrapped with errorHandler
+return errorHandler.withErrorHandler(async () => {
+  return await items.insert(collectionId, dataItem);
+}, {});
+
+// ✅ CORRECT: Update operations wrapped with errorHandler
+return errorHandler.withErrorHandler(async () => {
+  return await items.update(collectionId, dataItem);
+}, {});
+
+// ✅ CORRECT: Delete operations wrapped with errorHandler
+return errorHandler.withErrorHandler(async () => {
+  return await items.remove(collectionId, itemId);
+}, {});
+
+// ✅ CORRECT: Bulk delete operations wrapped with errorHandler
+return errorHandler.withErrorHandler(async () => {
+  return await items.bulkRemove(collectionId, itemIds);
+}, {});
+```
+
+**All Other Wix API calls from libraries with `@wix/` prefix:**
+
+```typescript
+import { stores } from '@wix/stores';
+import { events } from '@wix/events';
+import { bookings } from '@wix/bookings';
+import { contacts } from '@wix/crm';
+import { errorHandler } from '@wix/essentials';
+
+// ✅ CORRECT: All Wix API calls from @wix/* libraries must be wrapped
+return errorHandler.withErrorHandler(async () => {
+  return await stores.queryProducts().find();
+}, {});
+
+return errorHandler.withErrorHandler(async () => {
+  return await events.queryEvents().find();
+}, {});
+
+return errorHandler.withErrorHandler(async () => {
+  return await bookings.queryBookings().find();
+}, {});
+
+return errorHandler.withErrorHandler(async () => {
+  return await contacts.queryContacts().find();
+}, {});
 ```
 
 **httpClient.fetchWithAuth() calls:**
@@ -207,25 +304,120 @@ The error handling in your custom data source integrates seamlessly with AutoPat
 **BEFORE implementing ANY custom action or data source, AI agents MUST verify:**
 
 ### ✅ Error Handling Requirements
-- **httpClient from @wix/essentials** is wrapped with `errorHandler.withErrorHandler`
-- **Wix APIs (wix/data, wix/stores, etc)** are wrapped with `errorHandler.withErrorHandler`
-- **httpClient.fetchWithAuth()** calls are wrapped with `errorHandler.withErrorHandler`
-- **External API calls are NOT wrapped** with errorHandler (e.g., fetch(), axios, third-party HTTP clients)
-- **SDK actions are used directly** without error handling (e.g., `sdk.getOptimisticActions()`, `sdk.getSchema()`)
-- **@wix/essentials** is installed as a dependency
+- ✅ **ALL Wix API calls from `@wix/*` libraries** are wrapped with `errorHandler.withErrorHandler`
+  - Including: `@wix/data`, `@wix/stores`, `@wix/events`, `@wix/bookings`, `@wix/crm`, and ALL other `@wix/*` packages
+- ✅ **httpClient from @wix/essentials** is wrapped with `errorHandler.withErrorHandler`
+- ✅ **httpClient.fetchWithAuth()** calls are wrapped with `errorHandler.withErrorHandler`
+- ✅ **External API calls are NOT wrapped** with errorHandler (e.g., fetch(), axios, third-party HTTP clients)
+- ✅ **SDK actions are used directly** without error handling (e.g., `sdk.getOptimisticActions()`, `sdk.getSchema()`)
+- ✅ **@wix/essentials** is installed as a dependency
+
+### ✅ Correct API Signature Verification
+- ✅ **Check TypeScript/linter errors FIRST** - they tell you when the API is used incorrectly
+- ✅ **Verify imports are correct** - `import { items } from '@wix/data'` (not default imports)
+- ✅ **Use correct method signatures** - refer to the API reference section
+- ✅ **Pass correct parameters** - verify collectionId, itemId, and data structure
+- ✅ **Handle return values correctly** - `.find()` returns `{ items, ... }`, not just items array
 
 ### ✅ Implementation Checklist
-- **Read this error handling documentation** before implementing any custom action
-- **Identify the type of HTTP request** being made (Wix vs External)
-- **Apply the correct error handling pattern** based on the request type
-- **Test error scenarios** to ensure proper error handling
-- **Verify error messages** are user-friendly and actionable
+- ✅ **Read this error handling documentation** before implementing any custom action
+- ✅ **Identify the type of HTTP request** being made (Wix vs External)
+- ✅ **Apply the correct error handling pattern** based on the request type
+- ✅ **Test error scenarios** to ensure proper error handling
+- ✅ **Verify error messages** are user-friendly and actionable
+- ✅ **Run linter after implementation** to catch any API usage errors
 
 ### ✅ Common Mistakes to Avoid
 - ❌ **NEVER** wrap external API calls (fetch, axios) with errorHandler
 - ❌ **NEVER** wrap SDK methods (sdk.getOptimisticActions) with errorHandler
 - ❌ **NEVER** forget to wrap Wix HTTP requests with errorHandler
 - ❌ **NEVER** implement custom actions without reading this documentation first
+- ❌ **NEVER** use incorrect API signatures (e.g., `items.queryDataItems()` instead of `items.query()`)
+- ❌ **NEVER** ignore TypeScript/linter errors - they indicate incorrect API usage
+- ❌ **NEVER** use try-catch blocks instead of errorHandler for Wix SDK calls
+
+## 🎯 Common Wix SDK API Reference
+
+### @wix/data - Data Items API
+
+**ALWAYS use with errorHandler.withErrorHandler:**
+
+```typescript
+import { items } from '@wix/data';
+import { errorHandler } from '@wix/essentials';
+
+// Query all items
+errorHandler.withErrorHandler(async () => {
+  const result = await items.query('WixPets').find();
+  return result.items;
+}, {});
+
+// Query with filters
+errorHandler.withErrorHandler(async () => {
+  const result = await items.query('WixPets')
+    .contains('name', 'fluffy')
+    .eq('age', 5)
+    .find();
+  return result.items;
+}, {});
+
+// Get single item by ID
+errorHandler.withErrorHandler(async () => {
+  const item = await items.get('WixPets', itemId);
+  return item;
+}, {});
+
+// Insert new item
+errorHandler.withErrorHandler(async () => {
+  const newItem = await items.insert('WixPets', { name: 'Fluffy', age: 5 });
+  return newItem;
+}, {});
+
+// Update existing item
+errorHandler.withErrorHandler(async () => {
+  const updatedItem = await items.update('WixPets', { _id: itemId, name: 'Updated Name' });
+  return updatedItem;
+}, {});
+
+// Delete single item
+errorHandler.withErrorHandler(async () => {
+  await items.remove('WixPets', itemId);
+}, {});
+
+// Bulk delete items
+errorHandler.withErrorHandler(async () => {
+  await items.bulkRemove('WixPets', [itemId1, itemId2, itemId3]);
+}, {});
+```
+
+### @wix/essentials - Error Handler
+
+```typescript
+import { errorHandler } from '@wix/essentials';
+
+// Basic pattern (recommended)
+errorHandler.withErrorHandler(
+  async () => {
+    // Your Wix SDK call here
+    return await items.query('WixPets').find();
+  },
+  {
+    // Optional: Custom error handling
+    handleError: (error) => {
+      console.error('Custom error handling:', error);
+      throw error; // Re-throw to show error to user
+    },
+  }
+);
+
+// Simple pattern (empty options object)
+errorHandler.withErrorHandler(
+  async () => {
+    return await items.query('WixPets').find();
+  },
+  {}
+);
+```
 
 ## Quick Decision Tree for AI Agents
 
@@ -236,7 +428,7 @@ The error handling in your custom data source integrates seamlessly with AutoPat
    - **YES** → Go to step 2
 
 2. **What type of HTTP request?**
-   - **Wix APIs** (httpClient, wix/data, wix/stores) → **WRAP with errorHandler.withErrorHandler**
+   - **Wix API libraries with `@wix/` prefix** (@wix/data, @wix/stores, @wix/events, @wix/bookings, @wix/crm) → **WRAP with errorHandler.withErrorHandler**
    - **External APIs** (fetch, axios, third-party) → **NO errorHandler needed**
    - **SDK methods** (sdk.getOptimisticActions, sdk.getSchema) → **NO errorHandler needed**
 
@@ -245,6 +437,15 @@ The error handling in your custom data source integrates seamlessly with AutoPat
    - **External requests** are NOT wrapped
    - **SDK methods** are used directly
 
+## 🚨 TypeScript Error Detection
+
+**CRITICAL**: If you see TypeScript/linter errors when using Wix SDK methods:
+
+1. ✅ **Check the import** - Make sure you're importing from the correct package
+2. ✅ **Check the method signature** - Verify you're using the correct API signature (refer to the API reference above)
+3. ✅ **Check errorHandler wrapping** - Ensure the call is wrapped with `errorHandler.withErrorHandler`
+4. ✅ **Run linter** - Read the linter error message carefully; it tells you what's wrong
+
 ## Complete Examples for All Custom Action Types
 
 ### ActionCell Custom Actions
@@ -437,9 +638,44 @@ export const myCustomDataSource = async (collectionId: string, context: any) =>
 };
 ```
 
+### Actions Using Wix API Libraries (REQUIRES errorHandler)
+
+**Example 7: Action using Wix API libraries with `wix/` prefix (REQUIRES errorHandler)**
+```typescript
+import { errorHandler } from '@wix/essentials';
+import { data } from '@wix/data';
+import { stores } from '@wix/stores';
+import { CustomActionCellActionResolver } from '@wix/auto-patterns';
+
+export const syncWithWixData: CustomActionCellActionResolver = (params) => {
+  const { actionParams, sdk } = params;
+  const { item } = actionParams;
+
+  return {
+    label: 'Sync with Wix Data',
+    icon: <SyncIcon />,
+    onClick: () => {
+      // ✅ CORRECT: Wix API library calls wrapped with errorHandler
+      errorHandler.withErrorHandler(
+        async () => {
+          // Using @wix/data library
+          const dataResult = await data.query('MyCollection').eq('id', item.id).find();
+
+          // Using @wix/stores library
+          const productResult = await stores.queryProducts().eq('sku', item.sku).find();
+
+          return { dataResult, productResult };
+        },
+        {}
+      );
+    },
+  };
+};
+```
+
 ### Actions Using SDK Methods (NO errorHandler needed)
 
-**Example 7: Action using SDK methods (NO errorHandler needed)**
+**Example 8: Action using SDK methods (NO errorHandler needed)**
 ```typescript
 import { CustomActionCellActionResolver } from '@wix/auto-patterns';
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/auto-patterns",
-  "version": "1.39.0",
+  "version": "1.41.0",
   "license": "UNLICENSED",
   "author": {
     "name": "Matvey Oklander",
@@ -10,6 +10,33 @@
   "module": "dist/esm/index.js",
   "sideEffects": false,
   "types": "dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "require": "./dist/cjs/index.js",
+      "import": "./dist/esm/index.js",
+      "types": "./dist/types/index.d.ts"
+    },
+    "./testkit/enzyme": {
+      "require": "./dist/cjs/exports/testkit/enzyme.js",
+      "import": "./dist/esm/exports/testkit/enzyme.js",
+      "types": "./dist/types/exports/testkit/enzyme.d.ts"
+    },
+    "./testkit/jsdom": {
+      "require": "./dist/cjs/exports/testkit/jsdom.js",
+      "import": "./dist/esm/exports/testkit/jsdom.js",
+      "types": "./dist/types/exports/testkit/jsdom.d.ts"
+    },
+    "./testkit/playwright": {
+      "require": "./dist/cjs/exports/testkit/playwright.js",
+      "import": "./dist/esm/exports/testkit/playwright.js",
+      "types": "./dist/types/exports/testkit/playwright.d.ts"
+    },
+    "./testkit/puppeteer": {
+      "require": "./dist/cjs/exports/testkit/puppeteer.js",
+      "import": "./dist/esm/exports/testkit/puppeteer.js",
+      "types": "./dist/types/exports/testkit/puppeteer.d.ts"
+    }
+  },
   "files": [
     "dist/cjs",
     "dist/esm",
@@ -36,8 +63,9 @@
   },
   "dependencies": {
     "@babel/runtime": "^7.28.4",
-    "@wix/data": "^1.0.302",
-    "@wix/wix-ui-icons-common": "^3.87.3",
+    "@wix/data": "^1.0.316",
+    "@wix/wix-ui-icons-common": "^3.100.0",
+    "@wix/wix-ui-test-utils": "^1.3.3",
     "lodash": "^4.17.21"
   },
   "publishConfig": {
@@ -50,23 +78,23 @@
     "@types/lodash": "^4.17.20",
     "@types/node": "^16.18.126",
     "@types/node-fetch": "^2.6.13",
-    "@types/react": "^16.14.66",
-    "@wix/crm": "^1.0.1049",
-    "@wix/design-system": "^1.214.3",
-    "@wix/eslint-config-yoshi": "^6.160.0",
+    "@types/react": "^16.14.67",
+    "@wix/crm": "^1.0.1117",
+    "@wix/design-system": "^1.223.0",
+    "@wix/eslint-config-yoshi": "^6.161.0",
     "@wix/fe-essentials-standalone": "^1.1380.0",
-    "@wix/jest-yoshi-preset": "^6.160.0",
-    "@wix/patterns": "^1.281.0",
+    "@wix/jest-yoshi-preset": "^6.161.0",
+    "@wix/patterns": "^1.294.0",
     "@wix/sdk": "^1.17.1",
     "@wix/sdk-testkit": ">=0.1.9",
-    "@wix/wix-data-items-common": "^1.0.246",
-    "@wix/wix-data-items-sdk": "^1.0.441",
-    "@wix/yoshi-flow-library": "^6.160.0",
-    "@wix/yoshi-style-dependencies": "^6.160.0",
+    "@wix/wix-data-items-common": "^1.0.255",
+    "@wix/wix-data-items-sdk": "^1.0.450",
+    "@wix/yoshi-flow-library": "^6.161.0",
+    "@wix/yoshi-style-dependencies": "^6.161.0",
     "chance": "^1.1.13",
     "date-fns": "^2.30.0",
     "express": "^4.21.2",
-    "fetch-mock": "^12.5.4",
+    "fetch-mock": "^12.5.5",
     "jest": "^27.5.1",
     "node-fetch": "^2.7.0",
     "react": "16.14.0",
@@ -125,5 +153,5 @@
   "wallaby": {
     "autoDetect": true
   },
-  "falconPackageHash": "cd2cfeb335288a9e22923c993cb70aae4addb1583cd40923c1e6e192"
+  "falconPackageHash": "22d551f0337bd0d5e5de5a5cb32af3a84c6f8c8e1139cb9d4dbcd3f1"
 }