@wix/auto-patterns 1.38.0 → 1.40.0

package/mcp-docs/wix_fqdn_custom_data_source.md

@@ -1,4 +1,4 @@
-# FQDN-Based Custom Data Source Implementation
+## Build a Custom Data Source from a Wix Business API FQDN (with Contacts v4 example)
 
 **🛑 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.
 
@@ -8,13 +8,44 @@
 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
 
-When implementing a custom data source based on a Wix Business API FQDN, you'll need to understand several key concepts and follow specific implementation patterns. This guide covers the complete process from schema extraction to creating a foundation structure that **you will need to complete**.
+This guide shows how to build an Auto-Patterns custom data source backed by a Wix Business API entity identified by its FQDN. You will:
 
-**⚠️ IMPORTANT**: This guide creates a foundation with helpful comments and unimplemented actions that throw exceptions. The actual data source implementation (CRUD operations) must be completed by you using the appropriate Wix Business API client library.
+- Discover schema and client library via the Business Schema MCP
+- Map the FQDN schema to a `SchemaConfig` (see `schema_config.md` for the full interface)
+- Implement actions (CRUD + find)
+- Wire the custom data source into your Auto-Patterns page
+
+> IMPORTANT: Always use the Business Schema MCP as the source of truth for your target FQDN.
+> - Run `client_lib` to determine the exact SDK/ambassador package to install and import
+> - Run `fqdn_info` to see available actions, pagination mode, and request/response structure
+> - (Optional) Run `fqdn_schema` for precise field shapes
+> Do not rely on this example without verifying all details for your specific FQDN via MCP.
 
 **📝 MINIMAL IMPLEMENTATION APPROACH**: This guide focuses on creating a basic, functional dashboard page. Custom overrides (actions, columns, components, etc.) should only be implemented when explicitly requested by the user. A simple dashboard page requires only the core custom data source implementation without any additional overrides.
 
-## Prerequisites: Required Tools and Knowledge
+### Non‑negotiable requirements (LLM guardrails)
+
+- You **MUST** derive the SDK package, action names, required fields, and pagination mode from Business Schema MCP.
+- You **MUST** install the package returned by `client_lib` before importing/using it.
+- You **MUST** map API snake_case field segments to camelCase segments in `SchemaConfig`, preserving dot paths.
+- You **MUST** set `supportedQueryOperators: []` for all fields in custom data sources.
+- You **MUST** return the correct pagination shape from `actions.find` based on the API’s paging mode.
+- You **MUST** pass required concurrency/identity fields (e.g., `revision` on Contacts v4 updates) exactly as specified by MCP.
+ - You **MUST** fully implement `SchemaConfig` (fields and actions). Do not leave placeholders; do not use `as any` to bypass typing.
+ - You **MUST NOT** create new custom entity types. Use SDK-exported types (from the ambassador/SDK package) or rely on inference. Avoid `any` that suppresses type errors.
+
+### LLM Quick‑Start Execution Plan (follow in order)
+
+1. **MUST** run `client_lib` on your FQDN and note the exact package name.
+2. **MUST** install that package (npm/yarn/pnpm) and import the correct client entry point.
+3. **MUST** run `fqdn_info` to list actions, required fields, and pagination type; use it to draft your actions.
+4. **MUST** run `fqdn_schema` if you need concrete field shapes; map fields to `SchemaConfig` with segment-wise snake_case→camelCase and preserved dot paths.
+5. **MUST** implement `actions` using the exact method names and payloads from MCP; add robust error handling.
+6. **MUST** implement `find` to return the correct pagination shape (cursor vs offset) per MCP.
+7. **MUST** register the custom data source and set matching `custom.id` in AppConfig.
+8. **MUST** keep `supportedQueryOperators: []` for all fields.
+
+### Prerequisites: Required Tools and Knowledge
 
 **🛑 ABSOLUTE REQUIREMENT - WixAutoPatternsGuide Content**:
 
@@ -26,6 +57,7 @@ When implementing a custom data source based on a Wix Business API FQDN, you'll
 **🛑 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_info` tool for extracting action information from FQDNs
 - `fqdn_schema` tool for extracting schema information from FQDNs
 - `client_lib` tool for determining the correct client library package
 
@@ -43,55 +75,65 @@ If you haven't already used the `WixAutoPatternsGuide` tool in this conversation
 
 **Without this foundational knowledge, you cannot successfully implement FQDN-based custom data sources.**
 
-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
-4. Return to this guide once the tools are available
+**Tool Installation:**
+- Business Schema MCP installed and available in your environment
+  - Tools used: `fqdn_info`, `fqdn_schema`, `client_lib`
+  - Installation: see the Business Schema MCP README (internal)
 
 **Tool Verification:**
 Before continuing, verify that you have access to:
 
+- `fqdn_info` tool - for extracting action and pagination information from FQDNs
 - `fqdn_schema` tool - for extracting entity schema from FQDNs
 - `client_lib` tool - for determining the correct SDK package to use
 
-## Step 1: Extract Schema Information
+### What you will build
 
-First, use the fqdn_schema tool to understand the structure of your target entity:
+We'll create a custom data source for Contacts using `wix.contacts.v4.contact` as an example. The same steps apply to any other FQDN.
 
-```
-Use fqdn_schema tool with your FQDN (e.g., "wix.bookings.v1.sessions")
-```
+---
 
-This will provide you with:
+## 1) Discover schema and SDK with Business Schema MCP
 
-- Entity field definitions
-- Available actions/operations
-- Field types and constraints
-- Relationships and references
+Use the MCP tools to examine the entity and determine which SDK package to use.
 
-## Step 2: Determine Client Library
+```text
+Call client_lib with: "wix.contacts.v4.contact" -> returns: @wix/crm
 
-Use the client_lib tool to identify the correct package for your FQDN:
+Call fqdn_info with:  "wix.contacts.v4.contact" -> see common methods like CreateContact, GetContact, UpdateContact, DeleteContact, QueryContacts (offset-based)
 
-```
-Use client_lib tool with your FQDN to get the appropriate SDK package
+Optionally call fqdn_schema for message shapes (Contact, CreateContactRequest, etc.)
 ```
 
-This will tell you which library to import for your custom data source implementation.
+Notes for Contacts v4:
+- Paging for `QueryContacts` is offset-based
+- Identifier in routes is `id` or `contactId` depending on the action; the entity carries an `id` field
 
-## Step 3: Map FQDN Schema to SchemaConfig
+Using other FQDNs: always run `client_lib` to get the exact package. Some entities use an ambassador package (e.g., `@wix/ambassador-<product>-<version>-<resource>`); install and import accordingly.
 
-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.
+LLM notes:
+- You **MUST NOT** guess method names or shapes; copy them from `fqdn_info`.
+- You **MUST NOT** assume pagination type; read it from `fqdn_info` and implement accordingly.
 
-**🛑 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:
+### Install the SDK package
 
-- 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
+For the Contacts v4 example:
+
+```bash
+npm i @wix/crm
+# or
+yarn add @wix/crm
+# or
+pnpm add @wix/crm
+```
+
+For other FQDNs, install the package returned by `client_lib`.
+
+---
+
+## 2) Map FQDN fields to SchemaConfig
+
+See `schema_config.md` for the interface. Derive your field list and types from Business Schema MCP (`fqdn_schema` / `fqdn_info`) for YOUR FQDN, then apply these **MUST** rules:
 
 ### ⚠️ CRITICAL: Field ID Conversion from snake_case to camelCase
 
@@ -107,6 +149,9 @@ Transform the FQDN schema from Step 1 into a AutoPatterns-compatible SchemaConfi
 - `last_activity.activity_date` → `lastActivity.activityDate` (NOT `lastActivityDate`)
 - `job_title` → `jobTitle`
 - `created_date` → `createdDate`
+- `info.job_title` → `info.jobTitle`
+- `info.name.first` → `info.name.first` (already camelCase, no change needed)
+- `info.name.last` → `info.name.last` (already camelCase, no change needed)
 
 This conversion ensures:
 
@@ -115,170 +160,260 @@ This conversion ensures:
 - **Proper field mapping** between configuration and data source
 - **Seamless integration** with AutoPatterns components
 
-For the complete SchemaConfig interface, field definitions, and implementation details, refer to the "Schema Config" section.
+**🛑 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
+
+**Additional Rules:**
+- You **MUST** choose:
+  - `idField`: typically `id`
+  - `displayField`: a meaningful label, e.g., `displayName`, or build from name fields
+
+Minimal example for a subset of Contacts fields:
+
+```ts
+import type { SchemaConfig } from "@wix/auto-patterns"; // refer to your local types
+
+const fields: SchemaConfig["fields"] = {
+  id: {
+    id: "id",
+    displayName: "ID",
+    type: "SHORT_TEXT",
+    validation: { required: true },
+    capabilities: { supportedQueryOperators: [], sortable: true }
+  },
+  displayName: {
+    id: "displayName",
+    displayName: "Display Name",
+    type: "SHORT_TEXT",
+    validation: { required: false },
+    capabilities: { supportedQueryOperators: [], sortable: true }
+  },
+  createdDate: {
+    id: "createdDate", // from created_date
+    displayName: "Created Date",
+    type: "DATETIME",
+    validation: { required: false },
+    capabilities: { supportedQueryOperators: [], sortable: true }
+  },
+  updatedDate: {
+    id: "updatedDate", // from updated_date
+    displayName: "Updated Date",
+    type: "DATETIME",
+    validation: { required: false },
+    capabilities: { supportedQueryOperators: [], sortable: true }
+  },
+  "name.first": {
+    id: "name.first",
+    displayName: "First Name",
+    type: "SHORT_TEXT",
+    validation: { required: false },
+    capabilities: { supportedQueryOperators: [], sortable: true }
+  },
+  "name.last": {
+    id: "name.last",
+    displayName: "Last Name",
+    type: "SHORT_TEXT",
+    validation: { required: false },
+    capabilities: { supportedQueryOperators: [], sortable: true }
+  },
+  "email.email": {
+    id: "email.email",
+    displayName: "Email",
+    type: "SHORT_TEXT",
+    validation: { required: false },
+    capabilities: { supportedQueryOperators: [], sortable: true }
+  },
+  "phone.phone": {
+    id: "phone.phone",
+    displayName: "Phone",
+    type: "SHORT_TEXT",
+    validation: { required: false },
+    capabilities: { supportedQueryOperators: [], sortable: true }
+  }
+};
+
+// Field mapping example ends here.
+// You MUST NOT ship a partial SchemaConfig. Implement the full SchemaConfig with actions (see section 3).
+```
+
+---
+
+## 3) Implement SchemaConfig actions
+
+Actions **MUST** call the correct Wix client library returned by `client_lib`. For Contacts v4 use `@wix/crm`. For any other FQDN, use MCP (`client_lib`, `fqdn_info`) to get the exact package and method names, then adapt the calls accordingly.
+
+**⚠️ IMPORTANT**: You have two implementation approaches available:
+
+1. **Full Implementation** (recommended for production): Complete working implementation with actual API calls
+2. **Foundation with Guidance** (recommended for scaffolding): Unimplemented actions with helpful comments and error throwing
+
+### Implementation Approach 1: Full Implementation
+
+Implementation **MUSTs**:
+- You **MUST** wrap HTTP calls with consistent error handling (e.g., `errorHandler` from `@wix/essentials`).
+- You **MUST** map outgoing payloads from camelCase (SchemaConfig/AppConfig) to API snake_case when required, and map responses back.
+- You **MUST** respect pagination mode:
+  - Cursor-based APIs: return `{ items, cursor, total? }`
+  - Offset-based APIs (Contacts v4): return `{ items, hasNext, total? }`
+- For Contacts v4 updates, you **MUST** pass both `contactId` and the latest `revision`.
+
+#### Example implementation (Contacts v4, offset-based):
+
+```ts
+import { contacts } from "@wix/crm";
+import type { SchemaConfig, Query } from "@wix/auto-patterns";
+// import { errorHandler } from "@wix/essentials"; // if used in your app shell
+
+// NOTE: Some SDKs expose methods directly off the named export (no client instantiation).
+// Always verify import/method patterns in MCP `client_lib` docs/examples.
+
+function toApiContact(input) {
+  // Map camelCase fields used in forms/UI back to API shapes as needed.
+  // Example only – adapt to your fields. Many v4 fields are snake_case.
+  return input;
+}
+
+function fromApiContact(api) {
+  // Map API response to the fields you exposed in SchemaConfig
+  return {
+    id: api.id ?? api._id,
+    displayName: api.display_name ?? api.displayName ?? api.info?.name?.first ?? api.info?.name?.last,
+    createdDate: api.created_date ?? api.createdDate,
+    updatedDate: api.updated_date ?? api.updatedDate,
+    primaryInfo: api.primary_info ?? api.primaryInfo,
+    info: api.info
+  };
+}
+
+export const contactsSchemaWithActions: SchemaConfig = {
+  id: "Contacts",
+  idField: "id",
+  displayField: "displayName",
+  // Provide the full fields object from section 2 in your implementation
+  fields,
+  actions: {
+    async get(entityId: string) {
+      const res = await contacts.getContact({ id: entityId });
+      // Some SDKs return the entity at the root (res) instead of res.contact — verify via MCP
+      return fromApiContact(res.contact ?? res);
+    },
+
+    async create(newEntity) {
+      const res = await contacts.createContact({ info: toApiContact(newEntity).info });
+      return fromApiContact(res.contact ?? res);
+    },
+
+    async update(updatedEntity) {
+      // v4 requires id and revision on updates
+      const { id, revision, info } = toApiContact(updatedEntity);
+      const res = await contacts.updateContact({ contactId: id, revision, info });
+      return fromApiContact(res.contact ?? res);
+    },
+
+    async delete(entityId: string) {
+      await contacts.deleteContact({ contactId: entityId });
+      return { id: entityId };
+    },
 
-## Step 4: Set Up Custom Data Source Structure
+    async bulkDelete(entityIds: string[]) {
+      // If bulk delete API is not available, fall back to per-entity updates as defined by MCP
+      await contacts.bulkDeleteContacts?.({ contactIds: entityIds })
+        ?? Promise.all(entityIds.map((id) => contacts.deleteContact({ contactId: id })));
+      return { ids: entityIds };
+    },
 
-Follow the complete custom data source implementation guide in the "Custom Overrides" section. The key FQDN-specific considerations are:
+    async find(query: Query) {
+      // Use QueryContacts (offset-based). Map Auto-Patterns Query to API query
+      const limit = query.limit ?? 25;
+      const offset = query.offset ?? (query.page ? (query.page - 1) * limit : 0);
+      const res = await contacts.queryContacts({
+        query: {
+          paging: { limit, offset },
+          // Map filters/sort/search into the API query as needed
+          filter: /* build from query.filters */ undefined,
+          sort: /* build from query.sort */ undefined,
+          search: query.search ?? undefined
+        }
+      });
+      const items = (res.contacts ?? []).map(fromApiContact);
+      const hasNext = res.paging?.hasNext ?? (items.length === limit);
+      return { items, hasNext, total: null };
+    }
+  }
+};
+```
 
-1. **Import the client library** identified in Step 2
-2. **Use the field mappings** from Step 3 in your SchemaConfig
-3. **⚠️ CRITICAL: DO NOT IMPLEMENT THE ACTIONS** - Instead, add guidance comments explaining how to use the imported client library for each CRUD operation, then throw an "unimplemented exception" error
-4. **⚠️ CRITICAL: Add Error Handling** - When implementing the actions, you MUST wrap all HTTP requests with proper error handling using `errorHandler` from `@wix/essentials` (see "Error Handling for HTTP Requests" section)
+Notes:
+- Update requires the latest `revision`. Make sure your UI carries it and you pass it when updating.
+- If you target other FQDNs, import and call the methods from the package returned by `client_lib`, and adapt pagination (cursor vs offset) accordingly.
+- **Validation warning**: You **MUST** verify that each method you plan to call exists in the SDK for your FQDN. Replace non-existent operations with the supported alternatives per MCP (for example, use `update*` to set an `archived` flag if no `archive*` exists).
+- **⚠️ CRITICAL: Add Error Handling** - When implementing the actions, you MUST wrap all HTTP requests with proper error handling using `errorHandler` from `@wix/essentials`
 
-**Important**: The schema actions should contain helpful comments but NOT actual implementations. Each action should throw an error indicating it's unimplemented and needs to be implemented by the user.
+---
+
+## 4) Set Up Custom Data Source Structure and Hook Pattern
 
 ### Custom Data Source Hook Implementation
 
-Create your custom data source with the hook pattern:
+Create your custom data source with the hook pattern for better React integration:
 
-In `components/customDataSources/myCustomDataSource.ts`:
+In `components/customDataSources/contactsDataSource.ts`:
 
 ```typescript
 import { SchemaConfig } from '@wix/auto-patterns/types';
+import { contacts } from "@wix/crm";
+// Choose your implementation approach from section 3 above
 
-export const myCustomDataSource = async (
+export const contactsDataSource = async (
   collectionId: string,
   context: any,
 ): Promise<SchemaConfig> => {
-  return {
-    id: 'myCustomCollection',
-    fields: {
-      // Field definitions based on your FQDN schema mapping
-    },
-    displayField: 'name',
-    idField: 'id',
-    actions: {
-      get: async (entityId: string) => {
-        // TODO: Implement using your FQDN client library
-        // Example:
-        // return errorHandler.withErrorHandler(
-        //   async () => {
-        //     return yourFQDNClient.getEntity(entityId);
-        //   },
-        //   {}
-        // );
-        // Remember to map the response fields from snake_case to camelCase
-        throw new Error(
-          'get action not implemented - user must implement this method',
-        );
-      },
-      create: async (newEntity: any) => {
-        // TODO: Implement using your FQDN client library
-        // Example:
-        // return errorHandler.withErrorHandler(
-        //   async () => {
-        //     return yourFQDNClient.createEntity(newEntity);
-        //   },
-        //   {}
-        // );
-        // Remember to map the request fields from camelCase to snake_case
-        throw new Error(
-          'create action not implemented - user must implement this method',
-        );
-      },
-      update: async (updatedEntity: any) => {
-        // TODO: Implement using your FQDN client library
-        // Example:
-        // return errorHandler.withErrorHandler(
-        //   async () => {
-        //     return yourFQDNClient.updateEntity(updatedEntity);
-        //   },
-        //   {}
-        // );
-        // Remember to map the request fields from camelCase to snake_case
-        throw new Error(
-          'update action not implemented - user must implement this method',
-        );
-      },
-      delete: async (entityId: string) => {
-        // TODO: Implement using your FQDN client library
-        // Example:
-        // return errorHandler.withErrorHandler(
-        //   async () => {
-        //     return yourFQDNClient.deleteEntity(entityId);
-        //   },
-        //   {}
-        // );
-        throw new Error(
-          'delete action not implemented - user must implement this method',
-        );
-      },
-      bulkDelete: async (entityIds: string[]) => {
-        // TODO: Implement using your FQDN client library
-        // Example:
-        // return errorHandler.withErrorHandler(
-        //   async () => {
-        //     return yourFQDNClient.bulkDeleteEntities(entityIds);
-        //   },
-        //   {}
-        // );
-        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
-        // Example:
-        // return errorHandler.withErrorHandler(
-        //   async () => {
-        //     return yourFQDNClient.queryEntities(query, options);
-        //   },
-        //   {}
-        // );
-        // Remember to map the response fields from snake_case to camelCase
-        // IMPORTANT: Return shape depends on pagination mode.
-        // 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',
-        );
-      },
-      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',
-        );
-      },
-    },
-  };
+  return contactsSchemaWithActions; // Your SchemaConfig from section 3
 };
 ```
 
 In `components/customDataSources/index.tsx`:
 
 ```typescript
-import { myCustomDataSource } from './myCustomDataSource';
+import { contactsDataSource } from './contactsDataSource';
 
 export const useCustomDataSources = () => {
   // You can access React context and other hooks here
   return {
-    myCustomDataSource,
+    contactsFqdn: contactsDataSource,
   };
 };
 ```
 
 For detailed implementation patterns, folder structure, and registration steps, refer to the **Custom Data Sources** section in "Custom Overrides".
 
-## Step 5: Update AppConfig
+## 5) Register the custom data source and wire AppConfig
+
+You **MUST** register the custom data source and reference it from AppConfig.
+
+### Register Custom Data Source
+
+In your main page component, use the hook to register your custom data source:
+
+```tsx
+import { AutoPatternsApp, AutoPatternsOverridesProvider } from "@wix/auto-patterns"; // adjust import path in your monorepo
+import { useCustomDataSources } from '../components/customDataSources';
+
+export function Page() {
+  const customDataSources = useCustomDataSources();
+
+  return (
+    <AutoPatternsOverridesProvider value={{ customDataSources }}>
+      <AutoPatternsApp configuration={config} />
+    </AutoPatternsOverridesProvider>
+  );
+}
+```
+
+### Update AppConfig
 
 Configure your AppConfig to use the custom data source by setting:
 
@@ -288,55 +423,73 @@ Configure your AppConfig to use the custom data source by setting:
 **Key FQDN-specific configuration:**
 
 ```json
-"collection": {
-  "collectionId": "yourCustomCollectionId",
-  "entityTypeSource": "custom",
-  "custom": {
-    "id": "yourCustomDataSourceId"
+{
+  "collection": {
+    "collectionId": "Contacts",
+    "entityTypeSource": "custom",
+    "custom": { "id": "contactsFqdn" },
+    "paginationMode": "offset" // v4 uses offset; use "cursor" for cursor-based APIs
   }
 }
 ```
 
 For complete AppConfig structure, configuration rules, and advanced options, refer to the "App Config Structure" section.
 
-## Step 6: Register Custom Data Source
+---
 
-In your main page component, use the hook to register your custom data source:
+## 6) Building queries, filters and sorts
 
-```tsx
-import { useCustomDataSources } from '../components/customDataSources';
+- Keep `supportedQueryOperators: []` on fields. Build server-side WQL/search inside `actions.find`
+- Map `Query.filters` to the API’s filter object
+- Map `Query.sort` to API sorting
 
-export default function YourPage() {
-  const customDataSources = useCustomDataSources();
+For Contacts v4, you **MUST** use `QueryContacts` (WQL) and map your UI query object to the API query. For other entities, use their recommended query/search method per MCP and map accordingly.
 
-  return (
-    <AutoPatternsOverridesProvider value={{ customDataSources }}>
-      <AutoPatternsApp configuration={config} />
-    </AutoPatternsOverridesProvider>
-  );
-}
-```
+---
+
+## 7) Error handling and robustness
+
+- Wrap all HTTP requests with a consistent error handler (e.g., `errorHandler` from `@wix/essentials`) in your app shell
+- Surface meaningful messages using your `displayField`
+- Handle retries or specific application codes (duplicate, permission, invalid argument) when appropriate
+
+---
+
+## 8) Contacts v4 field mapping reference (subset)
 
-## Step 7: Implement Custom Actions (Only if Explicitly Requested)
+Examples derived from `fqdn_info` and query/search patterns:
 
-**⚠️ IMPORTANT**: Custom actions should only be implemented when the user explicitly requests them. A basic dashboard page with standard CRUD operations does not require custom actions.
+- `id` → `id`
+- `display_name` → `displayName`
+- `created_date` → `createdDate`
+- `updated_date` → `updatedDate`
+- `info.name.first` → `info.name.first`
+- `info.name.last` → `info.name.last`
+- `primary_info.email` → `primaryInfo.email`
+- `info.job_title` → `info.jobTitle`
+- `last_activity.activity_date` → `lastActivity.activityDate`
+
+Follow the snake_case-to-camelCase-per-segment rule and preserve dot paths. Use the original API field names when calling the SDK; use the camelCased paths in `SchemaConfig`/AppConfig.
 
-If the user specifically requests custom actions for your FQDN-based data source, follow the action implementation patterns from the "Custom Overrides" section. Your custom actions will have access to the same SDK utilities, but remember that they will need to interact with your FQDN-based API directly since the SchemaConfig actions from Step 4 are left unimplemented for you to complete.
+---
 
-## FQDN-Specific Implementation Checklist
+## 9) FQDN-Specific Implementation Checklist
 
 ### Core Requirements (Always Required)
 
-✅ **Schema Extraction**: Used fqdn_schema tool to understand entity structure
+✅ **Schema Extraction**: Used fqdn_info and/or fqdn_schema tools 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
+✅ **Package Installation**: Installed the exact SDK package reported by `client_lib` (e.g., `@wix/crm` for Contacts v4)
+✅ **Implementation Choice**: Chose either full implementation or foundation with guidance approach
+✅ **Pagination Shape**: Return the correct pagination shape from `find` (cursor vs offset per MCP)
 ✅ **AppConfig Update**: Set `entityTypeSource: "custom"` and provided custom.id
-✅ **Custom Data Source Structure**: Followed "Custom Overrides" section for folder structure and registration
+✅ **Custom Data Source Structure**: Followed proper folder structure and registration
 ✅ **Hook Implementation**: Created useCustomDataSources hook for accessing React context
-✅ **⚠️ CRITICAL: Unimplemented Actions**: All schema actions contain helpful comments but throw unimplemented exceptions - **user must implement these actions themselves**
+✅ **Registration**: Registered the custom data source in `AutoPatternsOverridesProvider`
+✅ **Matching IDs**: Used matching `custom.id` in AppConfig
 
 ### Optional Enhancements (Only When Explicitly Requested)
 
@@ -345,11 +498,10 @@ If the user specifically requests custom actions for your FQDN-based data source
 ⚠️ **Custom Components**: Only implement if user requests custom entity page components
 ⚠️ **Bulk Operations**: Only implement if user requests custom bulk actions beyond standard bulk delete
 
-## Common FQDN-Specific Pitfalls to Avoid
+## 10) Common FQDN-Specific Pitfalls to Avoid
 
 - **⚠️ CRITICAL: Implementing Unnecessary Overrides**: Do NOT implement custom actions, column overrides, or custom components unless explicitly requested by the user - a basic dashboard page only needs the core custom data source
 - **⚠️ CRITICAL: Inconsistent Field ID Casing**: Failing to convert individual field segments from snake_case to camelCase while preserving field path structure in SchemaConfig and AppConfig - this is the most common mistake and will cause field mapping failures
-- **⚠️ CRITICAL: Implementing Actions**: DO NOT implement the schema actions - they should contain helpful comments and throw unimplemented exceptions for the user to complete
 - **🛑 CRITICAL: Query Operators MUST Be Empty Array**: You **MUST** use `supportedQueryOperators: []` (empty array) for all fields - attempting to specify actual operators will cause TypeScript compilation errors and is not supported for custom data sources
 - **Mismatched Field Types**: Ensure FQDN field types are correctly mapped to AutoPatterns types
 - **Wrong Client Library**: Use the exact client library returned by the client_lib tool
@@ -357,10 +509,15 @@ If the user specifically requests custom actions for your FQDN-based data source
 - **Display Field Selection**: Choose a display field that provides meaningful identification from your FQDN schema
 - **Custom Data Source ID Mismatch**: Ensure the custom.id in AppConfig matches your custom data source identifier
 - **Hook Registration**: Don't forget to register the custom data source through the useCustomDataSources hook
+- **Mixing snake_case and camelCase**: In `SchemaConfig`/AppConfig field ids
+- **Returning the wrong pagination shape**: From `find` action
+- **Forgetting to pass `revision`**: On updates (especially v4/v5 APIs)
+- **Using the wrong client library**: Always trust `client_lib` result
+- **Missing error handling**: When implementing actions, wrap HTTP calls with proper error handling
 
-For general implementation pitfalls, refer to the "Custom Overrides" section.
+---
 
-## Advanced Customization (Only When Explicitly Requested)
+## 11) Advanced Customization (Only When Explicitly Requested)
 
 **⚠️ IMPORTANT**: The following customizations should only be implemented when the user explicitly requests them. A basic dashboard page does not require these advanced features.
 
@@ -373,3 +530,10 @@ For advanced customization options when specifically requested, refer to these s
 - "Custom Overrides" - For column overrides and custom components
 
 By following these steps, you'll successfully implement a custom data source that integrates seamlessly with AutoPatternsApp while leveraging Wix Business APIs through their FQDNs.
+
+## 12) See also
+
+- `schema_config.md` – Full `SchemaConfig` interface and field types
+- `auto-patterns-guide.md` – End-to-end Auto-Patterns overview
+
+