@wix/auto-patterns 1.34.0 → 1.35.0

package/mcp-docs/error_handling.md

@@ -1,16 +1,25 @@
 # Error Handling for HTTP Requests
 
+**⚠️ CRITICAL FOR AI AGENTS**: When creating or updating ANY custom actions (ActionCell, BulkActions, CollectionPage actions, EntityPage actions, or Custom Data Sources), you **MUST ALWAYS** read this error handling documentation first and apply the correct error handling patterns.
+
+**⚠️ MANDATORY WORKFLOW FOR AI AGENTS:**
+1. **BEFORE** implementing any custom action, read this entire error handling documentation
+2. **IDENTIFY** what type of HTTP requests (if any) your action will make
+3. **APPLY** the correct error handling pattern based on the request type
+4. **VERIFY** your implementation follows the validation checklist below
+5. **NEVER** skip this process - it's critical for proper error handling
+
 **⚠️ 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.
 
 ## What Requires Error Handling
 
-**ONLY the following HTTP requests** in your custom data source actions must be wrapped with `errorHandler`:
+**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()`)
 - **httpClient.fetchWithAuth()** calls
 
-**DO NOT use errorHandler with:**
+**DO NOT use errorHandler.withErrorHandler with:**
 
 - **External API calls** using `fetch()`, `axios.get()`, or other HTTP libraries
 - **Custom HTTP clients** (e.g., any non-Wix HTTP request library)
@@ -18,6 +27,20 @@
 
 **EXCEPTION**: SDK actions that you get from the AutoPatterns SDK (e.g., `sdk.getOptimisticActions()`, `sdk.getSchema()`) do NOT need error handling as they are already handled internally.
 
+## ⚠️ CRITICAL: When to Apply Error Handling
+
+**ALWAYS apply error handling when:**
+
+1. **Creating Custom Data Sources** - All HTTP requests in data source actions must be wrapped
+2. **Implementing FQDN-based Custom Data Sources** - All Wix API calls must be wrapped
+3. **Making any Wix HTTP requests** in custom actions (ActionCell, BulkActions, etc.)
+
+**NEVER apply error handling when:**
+
+1. **Using external APIs** (fetch, axios, third-party libraries)
+2. **Using AutoPatterns SDK methods** (sdk.getOptimisticActions, sdk.getSchema, etc.)
+3. **Making non-HTTP operations** (local computations, form validations, etc.)
+
 ## Why Error Handling is Required
 
 Custom data sources often make HTTP requests to Wix APIs and services. Without proper error handling:
@@ -41,7 +64,7 @@ npm install @wix/essentials
 
 ### Basic Error Handling Pattern
 
-Wrap Wix HTTP requests in your custom data source actions with `errorHandler.withErrorHandler`:
+**⚠️ MANDATORY**: Wrap Wix HTTP requests in your custom data source actions with `errorHandler.withErrorHandler`:
 
 ```typescript
 import { errorHandler } from '@wix/essentials';
@@ -62,6 +85,62 @@ actions: {
 }
 ```
 
+### ⚠️ CRITICAL: Error Handling in Custom Actions
+
+**When implementing ANY custom action (ActionCell, BulkActions, CollectionPage actions, EntityPage actions), you MUST:**
+
+1. **Check if your action makes Wix HTTP requests**
+2. **If YES**: Wrap the HTTP request with `errorHandler.withErrorHandler`
+3. **If NO**: Do not use errorHandler (e.g., for external APIs, SDK methods, local operations)
+
+**Example: Custom ActionCell with Wix API call**
+```typescript
+import { errorHandler } from '@wix/essentials';
+
+export const myCustomAction: CustomActionCellActionResolver = (params) => {
+  const { actionParams, sdk } = params;
+  const { item } = actionParams;
+
+  return {
+    label: 'Update Status',
+    icon: <UpdateIcon />,
+    onClick: () => {
+      // ✅ CORRECT: Wix API call wrapped with errorHandler
+      errorHandler.withErrorHandler(
+        async () => {
+          const response = await httpClient.request(
+            updateEntityStatus({ entityId: item.id, status: 'active' })
+          );
+          return response.data;
+        },
+        {}
+      );
+    },
+  };
+};
+```
+
+**Example: Custom ActionCell with External API call**
+```typescript
+export const myCustomAction: CustomActionCellActionResolver = (params) => {
+  const { actionParams, sdk } = params;
+  const { item } = actionParams;
+
+  return {
+    label: 'Send to External Service',
+    icon: <SendIcon />,
+    onClick: () => {
+      // ✅ CORRECT: External API call - NO errorHandler needed
+      fetch('https://api.external-service.com/send', {
+        method: 'POST',
+        body: JSON.stringify({ data: item }),
+        headers: { 'Content-Type': 'application/json' }
+      });
+    },
+  };
+};
+```
+
 ### Examples of HTTP Requests That Need Error Handling
 
 **httpClient from @wix/essentials:**
@@ -123,13 +202,269 @@ The error handling in your custom data source integrates seamlessly with AutoPat
 3. **Loading States**: Proper loading states during HTTP requests
 4. **Error Boundaries**: Errors are caught and handled gracefully
 
-## Validation Checklist
+## ⚠️ AI AGENT VALIDATION CHECKLIST
+
+**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
+
+### ✅ 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
+
+### ✅ 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
+
+## Quick Decision Tree for AI Agents
+
+**When implementing custom actions, ask:**
 
-Before deploying your custom data source, ensure:
+1. **Does this action make HTTP requests?**
+   - **NO** → No error handling needed
+   - **YES** → Go to step 2
+
+2. **What type of HTTP request?**
+   - **Wix APIs** (httpClient, wix/data, wix/stores) → **WRAP with errorHandler.withErrorHandler**
+   - **External APIs** (fetch, axios, third-party) → **NO errorHandler needed**
+   - **SDK methods** (sdk.getOptimisticActions, sdk.getSchema) → **NO errorHandler needed**
+
+3. **Verify implementation:**
+   - **Wix requests** are wrapped with `errorHandler.withErrorHandler`
+   - **External requests** are NOT wrapped
+   - **SDK methods** are used directly
+
+## Complete Examples for All Custom Action Types
+
+### ActionCell Custom Actions
+
+**Example 1: ActionCell with Wix API call (REQUIRES errorHandler)**
+```typescript
+import { errorHandler } from '@wix/essentials';
+import { CustomActionCellActionResolver } from '@wix/auto-patterns';
+
+export const updateEntityStatus: CustomActionCellActionResolver = (params) => {
+  const { actionParams, sdk } = params;
+  const { item } = actionParams;
+
+  return {
+    label: 'Update Status',
+    icon: <UpdateIcon />,
+    onClick: () => {
+      // ✅ CORRECT: Wix API call wrapped with errorHandler
+      errorHandler.withErrorHandler(
+        async () => {
+          const response = await httpClient.request(
+            updateEntityStatus({ entityId: item.id, status: 'active' })
+          );
+          return response.data;
+        },
+        {}
+      );
+    },
+  };
+};
+```
 
-✅ **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
+**Example 2: ActionCell with External API call (NO errorHandler needed)**
+```typescript
+import { CustomActionCellActionResolver } from '@wix/auto-patterns';
+
+export const sendToExternalService: CustomActionCellActionResolver = (params) => {
+  const { actionParams, sdk } = params;
+  const { item } = actionParams;
+
+  return {
+    label: 'Send to External Service',
+    icon: <SendIcon />,
+    onClick: () => {
+      // ✅ CORRECT: External API call - NO errorHandler needed
+      fetch('https://api.external-service.com/send', {
+        method: 'POST',
+        body: JSON.stringify({ data: item }),
+        headers: { 'Content-Type': 'application/json' }
+      });
+    },
+  };
+};
+```
+
+### BulkActions Custom Actions
+
+**Example 3: BulkAction with Wix API call (REQUIRES errorHandler)**
+```typescript
+import { errorHandler } from '@wix/essentials';
+import { CustomBulkActionsActionResolver } from '@wix/auto-patterns';
+
+export const bulkUpdateStatus: CustomBulkActionsActionResolver = (params) => {
+  const { actionParams, sdk } = params;
+  const { selectedValues } = actionParams;
+
+  return {
+    label: 'Bulk Update Status',
+    icon: <BulkUpdateIcon />,
+    onClick: () => {
+      // ✅ CORRECT: Wix API call wrapped with errorHandler
+      errorHandler.withErrorHandler(
+        async () => {
+          const response = await httpClient.request(
+            bulkUpdateEntityStatus({
+              entityIds: selectedValues.map(item => item.id),
+              status: 'active'
+            })
+          );
+          return response.data;
+        },
+        {}
+      );
+    },
+  };
+};
+```
+
+### CollectionPage Custom Actions
+
+**Example 4: CollectionPage action with Wix API call (REQUIRES errorHandler)**
+```typescript
+import { errorHandler } from '@wix/essentials';
+import { CustomActionCollectionPageActionResolver } from '@wix/auto-patterns';
+
+export const exportCollection: CustomActionCollectionPageActionResolver = (params) => {
+  const { actionParams, sdk } = params;
+  const { collectionId } = actionParams;
+
+  return {
+    label: 'Export Collection',
+    icon: <ExportIcon />,
+    onClick: () => {
+      // ✅ CORRECT: Wix API call wrapped with errorHandler
+      errorHandler.withErrorHandler(
+        async () => {
+          const response = await httpClient.request(
+            exportCollectionData({ collectionId })
+          );
+          return response.data;
+        },
+        {}
+      );
+    },
+  };
+};
+```
+
+### EntityPage Custom Actions
+
+**Example 5: EntityPage action with Wix API call (REQUIRES errorHandler)**
+```typescript
+import { errorHandler } from '@wix/essentials';
+import { CustomEntityPageMoreActionsActionResolver } from '@wix/auto-patterns';
+
+export const sendEmail: CustomEntityPageMoreActionsActionResolver = (params) => {
+  const { actionParams, sdk } = params;
+  const { entity } = actionParams;
+
+  return {
+    label: 'Send Email',
+    icon: <EmailIcon />,
+    onClick: () => {
+      // ✅ CORRECT: Wix API call wrapped with errorHandler
+      errorHandler.withErrorHandler(
+        async () => {
+          const response = await httpClient.request(
+            sendEmailToEntity({ entityId: entity.id, email: entity.email })
+          );
+          return response.data;
+        },
+        {}
+      );
+    },
+  };
+};
+```
+
+### Custom Data Sources
+
+**Example 6: Custom Data Source with Wix API calls (REQUIRES errorHandler)**
+```typescript
+import { errorHandler } from '@wix/essentials';
+
+export const myCustomDataSource = async (collectionId: string, context: any) => {
+  return {
+    id: 'myCustomCollection',
+    fields: {
+      // ... field definitions
+    },
+    idField: 'id',
+    actions: {
+      get: async (entityId: string) => {
+        // ✅ CORRECT: Wix API call wrapped with errorHandler
+        return errorHandler.withErrorHandler(
+          async () => {
+            const response = await httpClient.request(
+              getDummyEntity({ dummyEntityId: entityId })
+            );
+            return response.data.dummyEntity;
+          },
+          {}
+        );
+      },
+      create: async (newEntity: any) => {
+        // ✅ CORRECT: Wix API call wrapped with errorHandler
+        return errorHandler.withErrorHandler(
+          async () => {
+            const response = await httpClient.request(
+              createDummyEntity({ dummyEntity: newEntity })
+            );
+            return response.data.dummyEntity;
+          },
+          {}
+        );
+      },
+      // ... other actions
+    },
+  };
+};
+```
+
+### Actions Using SDK Methods (NO errorHandler needed)
+
+**Example 7: Action using SDK methods (NO errorHandler needed)**
+```typescript
+import { CustomActionCellActionResolver } from '@wix/auto-patterns';
+
+export const quickUpdate: CustomActionCellActionResolver = (params) => {
+  const { actionParams, sdk } = params;
+  const { item } = actionParams;
+
+  return {
+    label: 'Quick Update',
+    icon: <QuickUpdateIcon />,
+    onClick: () => {
+      // ✅ CORRECT: SDK methods - NO errorHandler needed
+      const optimisticActions = sdk.getOptimisticActions(sdk.collectionId);
+      const schema = sdk.getSchema(sdk.collectionId);
+
+      const updatedItem = { ...item, lastUpdated: new Date() };
+      optimisticActions.updateOne(updatedItem, {
+        submit: async (items) => schema.actions.update(items[0]),
+        successToast: 'Item updated successfully',
+        errorToast: (err, {retry}) => ({
+          text: 'Update failed',
+          action: { text: 'Retry', onClick: retry }
+        })
+      });
+    },
+  };
+};
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/auto-patterns",
-  "version": "1.34.0",
+  "version": "1.35.0",
   "license": "UNLICENSED",
   "author": {
     "name": "Matvey Oklander",
@@ -36,7 +36,7 @@
   },
   "dependencies": {
     "@babel/runtime": "^7.28.4",
-    "@wix/data": "^1.0.289",
+    "@wix/data": "^1.0.290",
     "@wix/wix-ui-icons-common": "^3.87.3",
     "lodash": "^4.17.21"
   },
@@ -51,14 +51,14 @@
     "@types/node": "^16.18.126",
     "@types/node-fetch": "^2.6.13",
     "@types/react": "^16.14.66",
-    "@wix/crm": "^1.0.1021",
+    "@wix/crm": "^1.0.1022",
     "@wix/design-system": "^1.214.3",
     "@wix/eslint-config-yoshi": "^6.158.0",
     "@wix/fe-essentials-standalone": "^1.1380.0",
     "@wix/jest-yoshi-preset": "^6.158.0",
-    "@wix/patterns": "^1.277.0",
+    "@wix/patterns": "^1.279.0",
     "@wix/sdk": "^1.16.0",
-    "@wix/sdk-testkit": ">=0.1.7",
+    "@wix/sdk-testkit": ">=0.1.8",
     "@wix/wix-data-items-common": "^1.0.235",
     "@wix/wix-data-items-sdk": "^1.0.428",
     "@wix/yoshi-flow-library": "^6.158.0",
@@ -125,5 +125,5 @@
   "wallaby": {
     "autoDetect": true
   },
-  "falconPackageHash": "3b95f950e8cf046662d2a6326593abe425912fede0ff9c0711897c1f"
+  "falconPackageHash": "da47af708036d7d07cc5947543173eddfa769691a73169ff7e5a65b2"
 }