@wix/auto-patterns 1.33.0 → 1.35.0

package/mcp-docs/error_handling.md

@@ -0,0 +1,470 @@
+# 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.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.withErrorHandler with:**
+
+- **External API calls** using `fetch()`, `axios.get()`, or other HTTP libraries
+- **Custom HTTP clients** (e.g., any non-Wix HTTP request library)
+- **Third-party API calls** using non-Wix HTTP methods
+
+**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:
+
+- **Unhandled Promise Rejections**: HTTP failures can crash your application
+- **Poor User Experience**: Users don't get meaningful error messages
+- **Inconsistent Error Management**: Different parts of your app handle errors differently
+- **Debugging Difficulties**: Hard to trace and diagnose API failures
+
+## Using @wix/essentials errorHandler
+
+The recommended approach is to use the `errorHandler` from `@wix/essentials` package, which provides consistent error handling patterns across Wix applications.
+
+### Installation
+
+First, ensure `@wix/essentials` is installed in your project:
+
+```bash
+npm install @wix/essentials
+```
+
+### Basic Error Handling Pattern
+
+**⚠️ MANDATORY**: Wrap Wix HTTP requests in your custom data source actions with `errorHandler.withErrorHandler`:
+
+```typescript
+import { errorHandler } from '@wix/essentials';
+
+// In your custom data source actions
+actions: {
+  get: async (entityId: string) => {
+    return errorHandler.withErrorHandler(
+      async () => {
+        const response = await httpClient.request(
+          getDummyEntity({ dummyEntityId: entityId })
+        );
+        return response.data.dummyEntity;
+      },
+      {}
+    );
+  },
+}
+```
+
+### ⚠️ 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:**
+
+```typescript
+return errorHandler.withErrorHandler(async () => {
+  const response = await httpClient.request(
+    getDummyEntity({ dummyEntityId: entityId })
+  );
+  return response.data.dummyEntity;
+}, {});
+```
+
+**Wix APIs (wix/data, wix/stores):**
+
+```typescript
+return errorHandler.withErrorHandler(async () => {
+  return await items.get(collectionId, entityId);
+}, {});
+```
+
+**httpClient.fetchWithAuth() calls:**
+
+```typescript
+return errorHandler.withErrorHandler(async () => {
+  const response = await httpClient.fetchWithAuth("/api/data");
+  return await response.json();
+}, {});
+```
+
+### Examples of HTTP Requests That Do NOT Need Error Handling
+
+**External API calls (using fetch, axios, etc.):**
+
+```typescript
+// ✅ CORRECT - No error handling needed for external APIs
+const response = await fetch("https://api.example.com/data");
+return await response.json();
+
+// ✅ CORRECT - No error handling needed for axios
+const response = await axios.get("https://api.example.com/data");
+return response.data;
+```
+
+**Third-party HTTP libraries:**
+
+```typescript
+// ✅ CORRECT - No error handling needed for third-party HTTP clients
+const response = await someThirdPartyHttpClient.get("/data");
+return response.data;
+```
+
+## Integration with AutoPatterns Error Handling
+
+The error handling in your custom data source integrates seamlessly with AutoPatterns' built-in error handling:
+
+1. **User-Friendly Messages**: Errors are displayed to users in a consistent format
+2. **Retry Mechanisms**: Users can retry failed operations
+3. **Loading States**: Proper loading states during HTTP requests
+4. **Error Boundaries**: Errors are caught and handled gracefully
+
+## ⚠️ 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
+
+### 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;
+        },
+        {}
+      );
+    },
+  };
+};
+```
+
+**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.33.0",
+  "version": "1.35.0",
   "license": "UNLICENSED",
   "author": {
     "name": "Matvey Oklander",
@@ -18,13 +18,14 @@
     "!dist/**/__tests__",
     "types",
     "react",
-    "form"
+    "form",
+    "docs",
+    "mcp-docs"
   ],
   "scripts": {
+    "build": "npm run generate-guide && yoshi-library build",
+    "start": "npm run generate-guide && yoshi-library start",
     "generate-guide": "node scripts/generate-guide.js",
-    "build": "yoshi-library build && npm run generate-guide",
-    "prestart": "npm run generate-guide",
-    "start": "yoshi-library start",
     "test": "yoshi-library test",
     "test:watch": "yoshi-library test --watch",
     "lint": "yoshi-library lint",
@@ -35,9 +36,8 @@
   },
   "dependencies": {
     "@babel/runtime": "^7.28.4",
-    "@wix/data": "^1.0.286",
+    "@wix/data": "^1.0.290",
     "@wix/wix-ui-icons-common": "^3.87.3",
-    "ejs": "^3.1.10",
     "lodash": "^4.17.21"
   },
   "publishConfig": {
@@ -46,22 +46,21 @@
   },
   "devDependencies": {
     "@testing-library/react": "^11.2.7",
-    "@types/ejs": "^3.1.5",
     "@types/jest": "^27.5.2",
     "@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.1008",
+    "@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.276.0",
-    "@wix/sdk": "^1.15.27",
-    "@wix/sdk-testkit": ">=0.1.7",
-    "@wix/wix-data-items-common": "^1.0.234",
-    "@wix/wix-data-items-sdk": "^1.0.427",
+    "@wix/patterns": "^1.279.0",
+    "@wix/sdk": "^1.16.0",
+    "@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",
     "@wix/yoshi-style-dependencies": "^6.158.0",
     "chance": "^1.1.13",
@@ -126,5 +125,5 @@
   "wallaby": {
     "autoDetect": true
   },
-  "falconPackageHash": "e334cdcca9d1178fdb528c8285b392ab2856be464988610a88518d39"
+  "falconPackageHash": "da47af708036d7d07cc5947543173eddfa769691a73169ff7e5a65b2"
 }

package/dist/docs/error_handling.md

@@ -1,135 +0,0 @@
-# Error Handling for HTTP Requests
-
-**⚠️ 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`:
-
-- **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:**
-
-- **External API calls** using `fetch()`, `axios.get()`, or other HTTP libraries
-- **Custom HTTP clients** (e.g., any non-Wix HTTP request library)
-- **Third-party API calls** using non-Wix HTTP methods
-
-**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.
-
-## Why Error Handling is Required
-
-Custom data sources often make HTTP requests to Wix APIs and services. Without proper error handling:
-
-- **Unhandled Promise Rejections**: HTTP failures can crash your application
-- **Poor User Experience**: Users don't get meaningful error messages
-- **Inconsistent Error Management**: Different parts of your app handle errors differently
-- **Debugging Difficulties**: Hard to trace and diagnose API failures
-
-## Using @wix/essentials errorHandler
-
-The recommended approach is to use the `errorHandler` from `@wix/essentials` package, which provides consistent error handling patterns across Wix applications.
-
-### Installation
-
-First, ensure `@wix/essentials` is installed in your project:
-
-```bash
-npm install @wix/essentials
-```
-
-### Basic Error Handling Pattern
-
-Wrap Wix HTTP requests in your custom data source actions with `errorHandler.withErrorHandler`:
-
-```typescript
-import { errorHandler } from '@wix/essentials';
-
-// In your custom data source actions
-actions: {
-  get: async (entityId: string) => {
-    return errorHandler.withErrorHandler(
-      async () => {
-        const response = await httpClient.request(
-          getDummyEntity({ dummyEntityId: entityId })
-        );
-        return response.data.dummyEntity;
-      },
-      {}
-    );
-  },
-}
-```
-
-### Examples of HTTP Requests That Need Error Handling
-
-**httpClient from @wix/essentials:**
-
-```typescript
-return errorHandler.withErrorHandler(async () => {
-  const response = await httpClient.request(
-    getDummyEntity({ dummyEntityId: entityId })
-  );
-  return response.data.dummyEntity;
-}, {});
-```
-
-**Wix APIs (wix/data, wix/stores):**
-
-```typescript
-return errorHandler.withErrorHandler(async () => {
-  return await items.get(collectionId, entityId);
-}, {});
-```
-
-**httpClient.fetchWithAuth() calls:**
-
-```typescript
-return errorHandler.withErrorHandler(async () => {
-  const response = await httpClient.fetchWithAuth("/api/data");
-  return await response.json();
-}, {});
-```
-
-### Examples of HTTP Requests That Do NOT Need Error Handling
-
-**External API calls (using fetch, axios, etc.):**
-
-```typescript
-// ✅ CORRECT - No error handling needed for external APIs
-const response = await fetch("https://api.example.com/data");
-return await response.json();
-
-// ✅ CORRECT - No error handling needed for axios
-const response = await axios.get("https://api.example.com/data");
-return response.data;
-```
-
-**Third-party HTTP libraries:**
-
-```typescript
-// ✅ CORRECT - No error handling needed for third-party HTTP clients
-const response = await someThirdPartyHttpClient.get("/data");
-return response.data;
-```
-
-## Integration with AutoPatterns Error Handling
-
-The error handling in your custom data source integrates seamlessly with AutoPatterns' built-in error handling:
-
-1. **User-Friendly Messages**: Errors are displayed to users in a consistent format
-2. **Retry Mechanisms**: Users can retry failed operations
-3. **Loading States**: Proper loading states during HTTP requests
-4. **Error Boundaries**: Errors are caught and handled gracefully
-
-## Validation Checklist
-
-Before deploying your custom data source, ensure:
-
-✅ **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