@wix/auto-patterns 1.33.0 → 1.35.0

package/{dist/docs → mcp-docs}/bulk_actions.md

@@ -64,7 +64,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';
@@ -78,43 +83,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 }
            })
          });
@@ -124,6 +178,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';

package/{dist/docs → mcp-docs}/collection_page_actions.md

@@ -95,7 +95,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 }
              })
            }
@@ -105,6 +105,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';
@@ -321,7 +375,7 @@ export const quickToggle: CustomActionCollectionPageActionOnRowClickResolver = (
         },
         successToast: `${item.name} toggled successfully`,
         errorToast: (err, {retry}) => ({
-          message: 'Toggle failed',
+          text: 'Toggle failed',
           action: { text: 'Retry', onClick: retry }
         })
       });

package/{dist/docs → mcp-docs}/custom_overrides.md

@@ -4,6 +4,7 @@
 
 - **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:

package/{dist/docs → mcp-docs}/entity_page_actions.md

@@ -50,6 +50,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';
 
@@ -60,13 +118,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).

package/{dist/docs → mcp-docs}/entity_page_view_actions.md

@@ -2,6 +2,8 @@
 
 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