@wix/auto-patterns 1.37.0 → 1.38.0

package/mcp-docs/wix_fqdn_custom_data_source.md

@@ -3,6 +3,7 @@
 **🛑 CRITICAL PREREQUISITE**: This guide explains a specialized feature that exists within the broader auto-patterns framework. You **CANNOT** implement this guide without first having the complete content of the WixAutoPatternsGuide.
 
 **📋 MANDATORY FIRST STEP**: Before proceeding with this FQDN-specific implementation:
+
 1. **You MUST call the `WixAutoPatternsGuide` tool first** to get the foundational auto-patterns knowledge
 2. **This document is NOT standalone** - it's an advanced feature guide that builds upon the core auto-patterns concepts
 3. **Without the WixAutoPatternsGuide content**, you will not understand the basic concepts, component structure, or implementation patterns required for this FQDN implementation
@@ -16,12 +17,14 @@ When implementing a custom data source based on a Wix Business API FQDN, you'll
 ## Prerequisites: Required Tools and Knowledge
 
 **🛑 ABSOLUTE REQUIREMENT - WixAutoPatternsGuide Content**:
+
 - **You MUST have the complete WixAutoPatternsGuide content** before starting this implementation
 - **This FQDN guide is NOT self-contained** - it's a specialized extension of the main auto-patterns guide
 - **If you haven't called the `WixAutoPatternsGuide` tool yet**, stop now and call it first
 - **This guide will reference concepts, components, and patterns** that are only explained in the main guide
 
 **🛑 CRITICAL**: Before proceeding with this guide, you must have the following tools available:
+
 - `WixAutoPatternsGuide` tool for understanding auto-patterns fundamentals and implementation patterns (**MANDATORY FIRST STEP**)
 - `fqdn_schema` tool for extracting schema information from FQDNs
 - `client_lib` tool for determining the correct client library package
@@ -30,6 +33,7 @@ When implementing a custom data source based on a Wix Business API FQDN, you'll
 
 **Auto-Patterns Context Requirement:**
 If you haven't already used the `WixAutoPatternsGuide` tool in this conversation, you MUST call it first to understand:
+
 - How AutoPatternsApp works
 - AppConfig structure and requirements
 - Custom data source implementation patterns
@@ -42,6 +46,7 @@ If you haven't already used the `WixAutoPatternsGuide` tool in this conversation
 To add these tools, you need to install the **business-schema-mcp** server:
 
 **Installation Instructions:**
+
 1. Follow the setup instructions at: https://github.com/wix-private/mcp-servers/tree/master/packages/business-schema-mcp
 2. Configure the MCP server according to the documentation
 3. Restart your development environment to load the new tools
@@ -49,6 +54,7 @@ To add these tools, you need to install the **business-schema-mcp** server:
 
 **Tool Verification:**
 Before continuing, verify that you have access to:
+
 - `fqdn_schema` tool - for extracting entity schema from FQDNs
 - `client_lib` tool - for determining the correct SDK package to use
 
@@ -61,6 +67,7 @@ Use fqdn_schema tool with your FQDN (e.g., "wix.bookings.v1.sessions")
 ```
 
 This will provide you with:
+
 - Entity field definitions
 - Available actions/operations
 - Field types and constraints
@@ -81,6 +88,7 @@ This will tell you which library to import for your custom data source implement
 Transform the FQDN schema from Step 1 into a AutoPatterns-compatible SchemaConfig by mapping the FQDN field types to AutoPatterns field types. Identify appropriate fields for `displayField` and `idField` based on your FQDN schema.
 
 **🛑 MANDATORY - Query Operators Must Be Empty Array**: When implementing a custom data source, you **MUST** set `supportedQueryOperators: []` (empty array) for all fields. This is required because:
+
 - Custom data sources handle all query operations directly through your implementation
 - You don't need to specify individual operators for each field
 - The custom data source `find` action will receive all queries regardless of declared operators
@@ -94,12 +102,14 @@ Transform the FQDN schema from Step 1 into a AutoPatterns-compatible SchemaConfi
 - **In API calls**: Use the original snake_case field names (e.g., `primary_info.email`, `created_date`, `last_activity.activity_date`)
 
 **Field Path Conversion Examples:**
+
 - `primary_info.email` → `primaryInfo.email` (NOT `primaryEmail`)
 - `last_activity.activity_date` → `lastActivity.activityDate` (NOT `lastActivityDate`)
 - `job_title` → `jobTitle`
 - `created_date` → `createdDate`
 
 This conversion ensures:
+
 - **Consistent JavaScript naming conventions** in your AutoPatterns configuration
 - **Preserved field path structure** for nested object access
 - **Proper field mapping** between configuration and data source
@@ -123,10 +133,14 @@ Follow the complete custom data source implementation guide in the "Custom Overr
 Create your custom data source with the hook pattern:
 
 In `components/customDataSources/myCustomDataSource.ts`:
+
 ```typescript
-import { errorHandler } from '@wix/essentials';
+import { SchemaConfig } from '@wix/auto-patterns/types';
 
-export const myCustomDataSource = async (collectionId: string, context: any) => {
+export const myCustomDataSource = async (
+  collectionId: string,
+  context: any,
+): Promise<SchemaConfig> => {
   return {
     id: 'myCustomCollection',
     fields: {
@@ -145,7 +159,9 @@ export const myCustomDataSource = async (collectionId: string, context: any) =>
         //   {}
         // );
         // Remember to map the response fields from snake_case to camelCase
-        throw new Error('get action not implemented - user must implement this method');
+        throw new Error(
+          'get action not implemented - user must implement this method',
+        );
       },
       create: async (newEntity: any) => {
         // TODO: Implement using your FQDN client library
@@ -157,7 +173,9 @@ export const myCustomDataSource = async (collectionId: string, context: any) =>
         //   {}
         // );
         // Remember to map the request fields from camelCase to snake_case
-        throw new Error('create action not implemented - user must implement this method');
+        throw new Error(
+          'create action not implemented - user must implement this method',
+        );
       },
       update: async (updatedEntity: any) => {
         // TODO: Implement using your FQDN client library
@@ -169,7 +187,9 @@ export const myCustomDataSource = async (collectionId: string, context: any) =>
         //   {}
         // );
         // Remember to map the request fields from camelCase to snake_case
-        throw new Error('update action not implemented - user must implement this method');
+        throw new Error(
+          'update action not implemented - user must implement this method',
+        );
       },
       delete: async (entityId: string) => {
         // TODO: Implement using your FQDN client library
@@ -180,7 +200,9 @@ export const myCustomDataSource = async (collectionId: string, context: any) =>
         //   },
         //   {}
         // );
-        throw new Error('delete action not implemented - user must implement this method');
+        throw new Error(
+          'delete action not implemented - user must implement this method',
+        );
       },
       bulkDelete: async (entityIds: string[]) => {
         // TODO: Implement using your FQDN client library
@@ -191,7 +213,9 @@ export const myCustomDataSource = async (collectionId: string, context: any) =>
         //   },
         //   {}
         // );
-        throw new Error('bulkDelete action not implemented - user must implement this method');
+        throw new Error(
+          'bulkDelete action not implemented - user must implement this method',
+        );
       },
       find: async (query: Query, options?: any) => {
         // TODO: Implement using your FQDN client library
@@ -207,21 +231,47 @@ export const myCustomDataSource = async (collectionId: string, context: any) =>
         // Detect by presence of query.cursor (cursor mode) vs. query.offset/page (offset mode):
         // - Cursor mode: return { items, cursor, total? }
         // - Offset mode (default): return { items, hasNext, total? }
-        throw new Error('find action not implemented - user must implement this method');
-      }
-    }
+        throw new Error(
+          'find action not implemented - user must implement this method',
+        );
+      },
+      move: async (
+        id,
+        {
+          moveAfterId,
+        }: {
+          moveAfterId: string | null | undefined;
+        },
+      ) => {
+        // TODO: Implement using your FQDN client library if it supports ordering/moving entities
+        // Example:
+        // return errorHandler.withErrorHandler(
+        //   async () => {
+        //     return yourFQDNClient.mvoeEntity(id, {
+        //       moveAfterCategoryId: moveAfterId,
+        //       position: moveAfterId ? 'AFTER' : 'FIRST',
+        //     })
+        //   },
+        //   {}
+        // );
+        throw new Error(
+          'move action not implemented - user must implement this method',
+        );
+      },
+    },
   };
 };
 ```
 
 In `components/customDataSources/index.tsx`:
+
 ```typescript
 import { myCustomDataSource } from './myCustomDataSource';
 
 export const useCustomDataSources = () => {
   // You can access React context and other hooks here
   return {
-    myCustomDataSource
+    myCustomDataSource,
   };
 };
 ```
@@ -236,6 +286,7 @@ Configure your AppConfig to use the custom data source by setting:
 - `custom.id` matching your custom data source identifier from Step 4
 
 **Key FQDN-specific configuration:**
+
 ```json
 "collection": {
   "collectionId": "yourCustomCollectionId",
@@ -275,9 +326,11 @@ If the user specifically requests custom actions for your FQDN-based data source
 ## FQDN-Specific Implementation Checklist
 
 ### Core Requirements (Always Required)
+
 ✅ **Schema Extraction**: Used fqdn_schema tool to understand entity structure
 ✅ **Client Library**: Used client_lib tool to identify correct SDK package
 ✅ **Field Mapping**: Mapped FQDN field types to AutoPatterns field types
+✅ **Entity Info Mapping**: Mapped FQDN entity info to SchemaConfig properties (containsPii, extensible)
 ✅ **🛑 MANDATORY: Empty Query Operators**: Set `supportedQueryOperators: []` for ALL fields to avoid TypeScript errors
 ✅ **⚠️ CRITICAL: Field ID Conversion**: Converted individual field segments from snake_case to camelCase while preserving field path structure in SchemaConfig and AppConfig
 ✅ **AppConfig Update**: Set `entityTypeSource: "custom"` and provided custom.id
@@ -286,6 +339,7 @@ If the user specifically requests custom actions for your FQDN-based data source
 ✅ **⚠️ CRITICAL: Unimplemented Actions**: All schema actions contain helpful comments but throw unimplemented exceptions - **user must implement these actions themselves**
 
 ### Optional Enhancements (Only When Explicitly Requested)
+
 ⚠️ **Custom Actions**: Only implement if user specifically requests custom actions beyond standard CRUD
 ⚠️ **Column Overrides**: Only implement if user requests custom column rendering
 ⚠️ **Custom Components**: Only implement if user requests custom entity page components
@@ -311,6 +365,7 @@ For general implementation pitfalls, refer to the "Custom Overrides" section.
 **⚠️ IMPORTANT**: The following customizations should only be implemented when the user explicitly requests them. A basic dashboard page does not require these advanced features.
 
 For advanced customization options when specifically requested, refer to these sections:
+
 - "Collection Page Actions" - For custom collection-level actions
 - "Action Cell" - For custom row-level actions
 - "Bulk Actions" - For custom bulk operations

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/auto-patterns",
-  "version": "1.37.0",
+  "version": "1.38.0",
   "license": "UNLICENSED",
   "author": {
     "name": "Matvey Oklander",
@@ -36,7 +36,7 @@
   },
   "dependencies": {
     "@babel/runtime": "^7.28.4",
-    "@wix/data": "^1.0.290",
+    "@wix/data": "^1.0.294",
     "@wix/wix-ui-icons-common": "^3.87.3",
     "lodash": "^4.17.21"
   },
@@ -51,18 +51,18 @@
     "@types/node": "^16.18.126",
     "@types/node-fetch": "^2.6.13",
     "@types/react": "^16.14.66",
-    "@wix/crm": "^1.0.1022",
+    "@wix/crm": "^1.0.1045",
     "@wix/design-system": "^1.214.3",
-    "@wix/eslint-config-yoshi": "^6.158.0",
+    "@wix/eslint-config-yoshi": "^6.159.0",
     "@wix/fe-essentials-standalone": "^1.1380.0",
-    "@wix/jest-yoshi-preset": "^6.158.0",
+    "@wix/jest-yoshi-preset": "^6.159.0",
     "@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",
+    "@wix/sdk": "^1.17.1",
+    "@wix/sdk-testkit": ">=0.1.9",
+    "@wix/wix-data-items-common": "^1.0.242",
+    "@wix/wix-data-items-sdk": "^1.0.436",
+    "@wix/yoshi-flow-library": "^6.159.0",
+    "@wix/yoshi-style-dependencies": "^6.159.0",
     "chance": "^1.1.13",
     "date-fns": "^2.30.0",
     "express": "^4.21.2",
@@ -125,5 +125,5 @@
   "wallaby": {
     "autoDetect": true
   },
-  "falconPackageHash": "12b7738cf82cb4287ef766b8803a032af10223745f185ead7da74ffa"
+  "falconPackageHash": "a96a6c3b1913c3c54f13a26af4926aa889f4274aa141f24fc483dcd0"
 }