@wix/auto-patterns 1.34.0 → 1.35.0

package/mcp-docs/auto-patterns-guide.md

@@ -870,7 +870,7 @@ Custom collection page actions execute JavaScript code that you define for colle
              },
              successToast: 'Collection exported successfully',
              errorToast: (err, {retry}) => ({
-               message: 'Export failed',
+               text: 'Export failed',
                action: { text: 'Retry', onClick: retry }
              })
            }
@@ -880,6 +880,60 @@ Custom collection page actions execute JavaScript code that you define for colle
    };
    ```
 
+   **⚠️ CRITICAL: Error Handling for HTTP Requests**
+
+   The example above uses SDK methods which don't require error handling. However, if your custom collection action makes HTTP requests, you MUST follow the error handling patterns:
+
+   **For Wix HTTP requests (httpClient, wix/data, wix/stores):**
+   ```typescript
+   import { errorHandler } from '@wix/essentials';
+
+   export const myCollectionAction: CustomActionCollectionPageActionResolver = (params) => {
+     const { actionParams, sdk } = params;
+     const { collectionId } = actionParams;
+
+     return {
+       label: 'My Collection Action',
+       icon: <MyIcon />,
+       onClick: () => {
+         // ✅ CORRECT: Wix API call wrapped with errorHandler
+         errorHandler.withErrorHandler(
+           async () => {
+             const response = await httpClient.request(
+               myWixApiCall({ collectionId })
+             );
+             return response.data;
+           },
+           {}
+         );
+       },
+       biName: 'my-collection-action'
+     };
+   };
+   ```
+
+   **For External API requests (fetch, axios, third-party):**
+   ```typescript
+   export const myCollectionAction: CustomActionCollectionPageActionResolver = (params) => {
+     const { actionParams, sdk } = params;
+     const { collectionId } = actionParams;
+
+     return {
+       label: 'My Collection Action',
+       icon: <MyIcon />,
+       onClick: () => {
+         // ✅ CORRECT: External API call - NO errorHandler needed
+         fetch(`https://api.external-service.com/endpoint/${collectionId}`)
+           .then(response => response.json())
+           .then(data => console.log('External API response:', data));
+       },
+       biName: 'my-collection-action'
+     };
+   };
+   ```
+
+   **Read the "Error Handling for HTTP Requests" section for complete guidance.**
+
 3. Export your action in `actions/index.tsx`:
    ```typescript
    import { exportCollection } from './exportCollection';
@@ -1096,7 +1150,7 @@ export const quickToggle: CustomActionCollectionPageActionOnRowClickResolver = (
         },
         successToast: `${item.name} toggled successfully`,
         errorToast: (err, {retry}) => ({
-          message: 'Toggle failed',
+          text: 'Toggle failed',
           action: { text: 'Retry', onClick: retry }
         })
       });
@@ -1492,6 +1546,7 @@ Both properties are optional, but at least one should be provided for the Action
      - Browser interactions (alerts, downloads)
      - Complex operations
    - ⚠️ Requires implementation: Must register action in overrides
+   - ⚠️ **CRITICAL: Error Handling Required** - When implementing custom actions that make HTTP requests, you MUST read the "Error Handling for HTTP Requests" section and apply the correct error handling patterns. Wix HTTP requests require `errorHandler.withErrorHandler`, while external API calls should NOT use errorHandler.
 
 ### Action Appearance: The `skin` Property
 
@@ -1591,7 +1646,7 @@ Custom actions execute JavaScript code that you define. These actions receive pa
            },
            successToast: 'Pet details downloaded',
            errorToast: (err, {retry}) => ({
-             message: 'Download failed',
+             text: 'Download failed',
              action: { text: 'Retry', onClick: retry }
            })
          });
@@ -1601,6 +1656,53 @@ Custom actions execute JavaScript code that you define. These actions receive pa
    };
    ```
 
+   **⚠️ CRITICAL: Error Handling for HTTP Requests**
+
+   The example above uses SDK methods which don't require error handling. However, if your custom action makes HTTP requests, you MUST follow the error handling patterns:
+
+   **For Wix HTTP requests (httpClient, wix/data, wix/stores):**
+   ```typescript
+   import { errorHandler } from '@wix/essentials';
+
+   export const myAction: CustomActionCellSecondaryActionResolver = (params) => {
+     return {
+       label: 'My Action',
+       icon: <MyIcon />,
+       onClick: () => {
+         // ✅ CORRECT: Wix API call wrapped with errorHandler
+         errorHandler.withErrorHandler(
+           async () => {
+             const response = await httpClient.request(
+               myWixApiCall({ data: params.actionParams.item })
+             );
+             return response.data;
+           },
+           {}
+         );
+       },
+     };
+   };
+   ```
+
+   **For External API requests (fetch, axios, third-party):**
+   ```typescript
+   export const myAction: CustomActionCellSecondaryActionResolver = (params) => {
+     return {
+       label: 'My Action',
+       icon: <MyIcon />,
+       onClick: () => {
+         // ✅ CORRECT: External API call - NO errorHandler needed
+         fetch('https://api.external-service.com/endpoint', {
+           method: 'POST',
+           body: JSON.stringify(params.actionParams.item)
+         });
+       },
+     };
+   };
+   ```
+
+   **Read the "Error Handling for HTTP Requests" section for complete guidance.**
+
 3. Export your action in `actions/index.tsx`:
    ```typescript
    import { downloadPetDetails } from './downloadPetDetails';
@@ -1661,7 +1763,7 @@ Custom actions execute JavaScript code that you define. These actions receive pa
    - Enable analytics tracking for user interactions
 
 2. The implementation must return a `ResolvedAction` object with:
-   - `label`: Text displayed for the action 
+   - `label`: Text displayed for the action
    - `icon`: An Icon component from "@wix/wix-ui-icons-common"
    - `onClick`: Handler function for the action
    - `biName`: Business intelligence name for analytics tracking. Must match the `biName` in your action configuration (required)
@@ -1790,7 +1892,12 @@ Custom bulk actions execute JavaScript code that you define for bulk operations.
    ```
 
 2. Create your bulk action handler in `bulkExportPets.tsx`:
+
+   **⚠️ CRITICAL: Before implementing, read the "Error Handling for HTTP Requests" section to understand when to use `errorHandler.withErrorHandler`.**
+
+   **Example 1: Bulk action with Wix API call (REQUIRES errorHandler)**
    ```typescript
+   import { errorHandler } from '@wix/essentials';
    import { CustomBulkActionsActionResolver } from '@wix/auto-patterns';
    import { Download } from '@wix/wix-ui-icons-common';
    import React from 'react';
@@ -1804,43 +1911,92 @@ Custom bulk actions execute JavaScript code that you define for bulk operations.
        label: 'Export Selected',
        icon: <Download />,
        onClick: () => {
-         // sdk is provided to custom action resolvers (see SDK Utilities section)
+         // ✅ CORRECT: Wix API call wrapped with errorHandler
+         errorHandler.withErrorHandler(
+           async () => {
+             const response = await httpClient.request(
+               bulkExportPetsData({
+                 petIds: selectedValues.map(pet => pet.id),
+                 totalCount: total
+               })
+             );
+             return response.data;
+           },
+           {}
+         );
+       },
+       biName: 'bulk-export-pets-action'  // MANDATORY: For analytics tracking
+     };
+   };
+   ```
+
+   **Example 2: Bulk action with External API call (NO errorHandler needed)**
+   ```typescript
+   import { CustomBulkActionsActionResolver } from '@wix/auto-patterns';
+   import { Download } from '@wix/wix-ui-icons-common';
+   import React from 'react';
+
+   export const bulkExportPets: CustomBulkActionsActionResolver = (params) => {
+     const { actionParams, sdk } = params;
+     const { selectedValues, total } = actionParams;
+
+     return {
+       label: 'Export Selected',
+       icon: <Download />,
+       onClick: () => {
+         // ✅ CORRECT: External API call - NO errorHandler needed
+         const exportData = selectedValues.map(pet => ({
+           name: pet.name,
+           age: pet.age,
+           owner: pet.owner
+         }));
+
+         // Create and download CSV
+         const csv = exportData.map(row => Object.values(row).join(',')).join('\n');
+         const blob = new Blob([csv], { type: 'text/csv' });
+         const url = URL.createObjectURL(blob);
+         const a = document.createElement('a');
+         a.href = url;
+         a.download = 'pets-export.csv';
+         a.click();
+       },
+       biName: 'bulk-export-pets-action'  // MANDATORY: For analytics tracking
+     };
+   };
+   ```
+
+   **Example 3: Bulk action using SDK methods (NO errorHandler needed)**
+   ```typescript
+   import { CustomBulkActionsActionResolver } from '@wix/auto-patterns';
+   import { Download } from '@wix/wix-ui-icons-common';
+   import React from 'react';
+
+   export const bulkExportPets: CustomBulkActionsActionResolver = (params) => {
+     const { actionParams, sdk } = params;
+     const { selectedValues, total } = actionParams;
+
+     return {
+       label: 'Export Selected',
+       icon: <Download />,
+       onClick: () => {
+         // ✅ CORRECT: SDK methods - NO errorHandler needed
          const optimisticActions = sdk.getOptimisticActions(sdk.collectionId);
          const schema = sdk.getSchema(sdk.collectionId);
 
-         // Example: Mark pets as exported
          const updatedItems = selectedValues.map(item => ({
            ...item,
            lastExported: new Date()
          }));
          optimisticActions.updateMany(updatedItems, {
            submit: async (items) => {
-             // Your export logic here + update server
-             const exportData = items.map(pet => ({
-               name: pet.name,
-               age: pet.age,
-               owner: pet.owner
-             }));
-
-             // Create and download CSV
-             const csv = exportData.map(row => Object.values(row).join(',')).join('\n');
-             const blob = new Blob([csv], { type: 'text/csv' });
-             const url = URL.createObjectURL(blob);
-             const a = document.createElement('a');
-             a.href = url;
-             a.download = 'pets-export.csv';
-             a.click();
-
-             // Update server with export timestamp
-             // Handle potential undefined schema
              if (schema) {
                return await schema.actions.update(items);
              }
-             return items; // fallback when schema is unavailable
+             return items;
            },
            successToast: `${selectedValues.length} pets exported`,
            errorToast: (err, {retry}) => ({
-             message: 'Export failed',
+             text: 'Export failed',
              action: { text: 'Retry', onClick: retry }
            })
          });
@@ -1850,6 +2006,8 @@ Custom bulk actions execute JavaScript code that you define for bulk operations.
    };
    ```
 
+   **Read the "Error Handling for HTTP Requests" section for complete guidance.**
+
 3. Export your action in `actions/index.tsx`:
    ```typescript
    import { bulkExportPets } from './bulkExportPets';
@@ -2524,6 +2682,64 @@ The `CustomEntityPageActionResolver` type is used to implement custom actions fo
 
 #### Function Signature
 
+**⚠️ CRITICAL: Before implementing, read the "Error Handling for HTTP Requests" section to understand when to use `errorHandler.withErrorHandler`.**
+
+**Example 1: EntityPage action with Wix API call (REQUIRES errorHandler)**
+```typescript
+import { errorHandler } from '@wix/essentials';
+import { CustomEntityPageActionResolver } from '@wix/auto-patterns/types';
+
+export const sendEmail: CustomEntityPageActionResolver = (params) => {
+  const { actionParams: { entity, form } , sdk } = params;
+
+  return {
+    label: 'Send Email',
+    icon: <EmailIcon />, // required
+    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;
+        },
+        {}
+      );
+    },
+    biName: 'send-email-action'  // MANDATORY: For analytics tracking
+  };
+};
+```
+
+**Example 2: EntityPage action with External API call (NO errorHandler needed)**
+```typescript
+import { CustomEntityPageActionResolver } from '@wix/auto-patterns/types';
+
+export const exportData: CustomEntityPageActionResolver = (params) => {
+  const { actionParams: { entity, form } , sdk } = params;
+
+  return {
+    label: 'Export Data',
+    icon: <ExportIcon />, // required
+    onClick: () => {
+      // ✅ CORRECT: External API call - NO errorHandler needed
+      fetch(`https://api.external-service.com/export/${entity.id}`)
+        .then(response => response.blob())
+        .then(blob => {
+          const url = URL.createObjectURL(blob);
+          const a = document.createElement('a');
+          a.href = url;
+          a.download = `entity-${entity.id}.pdf`;
+          a.click();
+        });
+    },
+    biName: 'export-data-action'  // MANDATORY: For analytics tracking
+  };
+};
+```
+
+**Example 3: EntityPage action using SDK methods (NO errorHandler needed)**
 ```typescript
 import { CustomEntityPageActionResolver } from '@wix/auto-patterns/types';
 
@@ -2534,13 +2750,32 @@ export const myMoreAction: CustomEntityPageActionResolver = (params) => {
     label: 'My More Action',
     icon: <MyIcon />, // required
     onClick: () => {
-      // Your custom logic here
+      // ✅ CORRECT: SDK methods - NO errorHandler needed
+      const optimisticActions = sdk.getOptimisticActions(sdk.collectionId);
+      const schema = sdk.getSchema(sdk.collectionId);
+
+      const updatedEntity = { ...entity, lastAction: new Date() };
+      optimisticActions.updateOne(updatedEntity, {
+        submit: async (items) => {
+          if (schema) {
+            return await schema.actions.update(items[0]);
+          }
+          return items[0];
+        },
+        successToast: 'Action completed successfully',
+        errorToast: (err, {retry}) => ({
+          text: 'Action failed',
+          action: { text: 'Retry', onClick: retry }
+        })
+      });
     },
     biName: 'my-more-action'  // MANDATORY: For analytics tracking
   };
 };
 ```
 
+**Read the "Error Handling for HTTP Requests" section for complete guidance.**
+
 - **entity**: The current entity data (all field values). In actionParams.
 - **form**: The react-hook-form instance for the entity page. In actionParams.
 - **sdk**: The AutoPatterns SDK (see SDK Utilities section).
@@ -2580,6 +2815,8 @@ The `CustomEntityPageActionResolver` enables you to add custom, contextual actio
 
 View mode supports the complete collection-style actions API, providing maximum flexibility for entity operations.
 
+**⚠️ CRITICAL: Error Handling for Custom Actions** - When implementing custom actions (type: "custom") in view mode, you MUST read the "Error Handling for HTTP Requests" section and apply the correct error handling patterns. Wix HTTP requests require `errorHandler.withErrorHandler`, while external API calls should NOT use errorHandler.
+
 ## Supported Action Types
 
 ### Primary Actions
@@ -3027,6 +3264,7 @@ export const DataUpdateModal: React.FC = () => {
 
 - **Custom overrides are restricted to the defined areas only** - attempting to override or modify any other aspect of `AutoPatternsApp` is prohibited and can cause unexpected behavior
 - **Always verify override implementation** - when implementing custom overrides, you MUST ensure they are correctly imported and passed to the `AutoPatternsOverridesProvider`
+- **⚠️ CRITICAL: READ ERROR HANDLING DOCUMENTATION FIRST** - Before implementing ANY custom action (ActionCell, BulkActions, CollectionPage actions, EntityPage actions, or Custom Data Sources), you MUST read the "Error Handling for HTTP Requests" section and apply the correct error handling patterns. This is mandatory for all AI agents.
 - **CRITICAL: Error handling for custom actions** - Custom actions that make external API calls (using `fetch()`, `axios`, etc.) should NOT use `errorHandler.withErrorHandler`. Only Wix HTTP requests (httpClient from @wix/essentials, Wix APIs like wix/data and wix/stores, and httpClient.fetchWithAuth()) require errorHandler wrapping. See the "Error Handling for HTTP Requests" section for details.
 
 The `AutoPatternsOverridesProvider` allows you to inject custom code to override default behaviors or add additional functionality. Below are the areas where overrides can be applied:
@@ -4184,17 +4422,26 @@ Slots provide a powerful way to enhance collection pages with custom functionali
 
 # 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)
@@ -4202,6 +4449,20 @@ Slots provide a powerful way to enhance collection pages with custom functionali
 
 **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:
@@ -4225,7 +4486,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';
@@ -4246,6 +4507,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:**
@@ -4307,13 +4624,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:**
+
+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
 
-Before deploying your custom data source, ensure:
+### ActionCell Custom Actions
 
-✅ **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 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;
+        },
+        {}
+      );
+    },
+  };
+};
+```
+
+**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 }
+        })
+      });
+    },
+  };
+};
+```