@wix/auto-patterns 1.36.0 → 1.38.0

package/mcp-docs/schema_config.md

@@ -29,19 +29,47 @@ export interface SchemaConfig {
       | { items: any[]; cursor?: string | null; total?: number | null }
       | { items: any[]; hasNext?: boolean; total?: number | null }
     >;
+    /**
+     * Reorder an entity within the collection.
+     * @param id The ID of the entity to move.
+     * @param params.moveAfterId The ID of the entity that should precede the moved entity, or null/undefined to move to start.
+     */
+    move?: (
+      id: string,
+      params: {
+        moveAfterId: string | null | undefined;
+      },
+    ) => Promise<void>;
   };
+  /**
+   * Whether the entity supports data extensions
+   * Maps to `info.extensible` in the collection schema - map only properties that are relevant or `null` if not extensible
+   */
+  extensible: {
+    /**
+     * Whether the entity supports filtering on data extensions
+     * Maps to `info.extensible.filterable` in the collection schema
+     */
+    filterable?: boolean;
+  } | null;
+  /**
+   * Whether the schema contains personally identifiable information (PII).
+   * Maps to `info.containsPii` in the collection schema
+   */
+  containsPii: boolean;
 }
 
 export interface Query {
-  limit: number;                    // Maximum number of items to return per request (controls page size)
-  offset?: number;                   // Number of items to skip from the beginning (for pagination)
-  page: number;                     // Current page number (1-based, works with limit for pagination)
-  search?: string;                  // Text search query applied to searchable fields
-  cursor?: string | null;           // Cursor-based pagination token (alternative to offset-based pagination)
-  filters: Record<string, any>;     // Field-specific filter conditions (keys = field IDs, values = filter criteria)
-  sort?: {                          // Sorting configuration for result ordering
-    fieldName: string;              // Field ID to sort by (must be sortable per field capabilities)
-    order: 'asc' | 'desc';         // Sort direction
+  limit: number; // Maximum number of items to return per request (controls page size)
+  offset?: number; // Number of items to skip from the beginning (for pagination)
+  page: number; // Current page number (1-based, works with limit for pagination)
+  search?: string; // Text search query applied to searchable fields
+  cursor?: string | null; // Cursor-based pagination token (alternative to offset-based pagination)
+  filters: Record<string, any>; // Field-specific filter conditions (keys = field IDs, values = filter criteria)
+  sort?: {
+    // Sorting configuration for result ordering
+    fieldName: string; // Field ID to sort by (must be sortable per field capabilities)
+    order: 'asc' | 'desc'; // Sort direction
   }[];
 }
 ```
@@ -92,43 +120,63 @@ export type Field = ReferenceField | NonReferenceField;
 ### Key Properties
 
 • **id** - `string`
-  - Collection identifier (e.g., "WixPets")
-  - Example: `schema.id === "WixPets"`
+
+- Collection identifier (e.g., "WixPets")
+- Example: `schema.id === "WixPets"`
 
 • **idField** - `string`
-  - Primary key field name (usually "_id")
-  - Required for all update/delete operations
-  - Example: `const id = item[schema.idField]`
+
+- Primary key field name (usually "\_id")
+- Required for all update/delete operations
+- Example: `const id = item[schema.idField]`
 
 • **displayField** - `string`
-  - Main field for displaying items (name, title, etc.)
-  - Used in UI components for item identification
-  - Example: `const label = item[schema.displayField]`
+
+- Main field for displaying items (name, title, etc.)
+- Used in UI components for item identification
+- Example: `const label = item[schema.displayField]`
 
 • **fields** - `Record<string, Field | undefined>`
-  - Complete field definitions with types and metadata
-  - Useful for dynamic form generation or validation
-  - Each field contains type information, validation rules, and capabilities
-  - Example: `schema.fields.name.type === 'SHORT_TEXT'`
+
+- Complete field definitions with types and metadata
+- Useful for dynamic form generation or validation
+- Each field contains type information, validation rules, and capabilities
+- Example: `schema.fields.name.type === 'SHORT_TEXT'`
 
 • **actions** - Server operation functions
-  - Pre-configured API calls for CRUD operations
-  - Use with optimistic actions for best UX
-  - All actions return Promises and handle server communication
-  - Example: `await schema.actions.update(item)`
+
+- Pre-configured API calls for CRUD operations
+- Use with optimistic actions for best UX
+- All actions return Promises and handle server communication
+- Example: `await schema.actions.update(item)`
+
+• **extensible** - `object | null`
+
+- Indicates if the entity supports data extensions
+
+• **extensible.filterable** - `boolean | undefined`
+
+- Indicates if filtering on data extensions is supported
+
+• **containsPii** - `boolean`
+
+- Indicates if the schema contains personally identifiable information (PII)
 
 ### Available Schema Actions
 
 #### Individual Entity Operations
+
 - **schema.actions.get(entityId)** - Retrieve a single entity by ID
 - **schema.actions.create(newEntity)** - Create a new entity
 - **schema.actions.update(updatedEntity)** - Update an existing entity
 - **schema.actions.delete(entityId)** - Delete a single entity by ID
 
 #### Bulk Operations
+
 - **schema.actions.bulkDelete(entityIds)** - Delete multiple entities by their IDs
 
 #### Query Operations
+
 - **schema.actions.find(query, options)** - Search and filter entities
   - `query`: Query object with pagination, filtering, sorting, and search criteria (see Query Interface section)
   - `options.searchableFieldIds`: Array of field IDs that support text search
@@ -155,6 +203,7 @@ Each field in the `fields` record contains:
 ### Reference Fields
 
 Reference fields have additional metadata:
+
 - **referenceMetadata.referencedCollectionId**: ID of the collection being referenced
 - Used for establishing relationships between different collections
 

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.36.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": "c61a8e7f9dc94713cb45b18fb6a83ac04a1418c6992bdb349e7a1dec"
+  "falconPackageHash": "a96a6c3b1913c3c54f13a26af4926aa889f4274aa141f24fc483dcd0"
 }