@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/02-CORE-GUIDES/mapping/graphql-mutation-mapping/graphql-mutation-mapping-quick-reference.md

@@ -1,463 +1,463 @@
-# GraphQL Mutation Mapping Quick Reference
-
-## Quick Reference (GraphQL-Specific Essentials)
-
-## Import Statement
-
-```typescript
-import { GraphQLMutationMapper } from '@fluentcommerce/fc-connect-sdk';
-```
-
-## Basic Usage
-
-```typescript
-// 1. Load mapping configuration
-import mappingConfig from './mappings/sfcc-order-to-fluent.json';
-
-// 2. Initialize mapper
-const mapper = new GraphQLMutationMapper(mappingConfig, logger, { fluentClient: fluentClient });
-
-// 3. Transform source data
-const payload = await mapper.map(xmlOrJsonData);
-
-// 4. Execute mutation
-const result = await fluentClient.graphql(payload);
-```
-
-## Mapping Configuration Structure
-
-**Note:** The `returnFields` array specifies which fields are returned in the GraphQL mutation response. These fields are available in `result.data.createOrder` (or `result.data.createLocation`, etc.) after executing the mutation. If omitted, defaults to `["id", "ref"]` for fields-based patterns and `["id"]` for arguments-based patterns.
-
-```json
-{
-  "version": "1.0",
-  "mutation": "createOrder",
-  "operationName": "CreateOrderFromSFCC",
-  "sourceFormat": "xml",
-  "returnFields": ["id", "ref", "status"],
-
-  "arguments": {
-    "input": {
-      "_type": "CreateOrderInput!",
-
-      "ref": { "source": "order@order-no", "required": true },
-      "type": { "value": "STANDARD", "required": true },
-      "totalPrice": { "source": "totals.order-total", "resolver": "sdk.parseFloat" },
-
-      "items": {
-        "_array": true,
-        "_type": "[OrderItemInput]!",
-        "source": "product-lineitems.product-lineitem",
-
-        "ref": { "source": "@lineitem-id", "required": true },
-        "quantity": { "source": "quantity", "resolver": "sdk.parseInt" }
-      }
-    }
-  }
-}
-```
-
-## Path Syntax Quick Reference
-
-### XML Paths
-
-| Pattern        | Example          | Description                 |
-| -------------- | ---------------- | --------------------------- |
-| `element`      | `order-date`     | Element value               |
-| `element@attr` | `order@order-no` | Attribute (NO dot before @) |
-| `parent.child` | `customer.email` | Nested element              |
-| `array[0]`     | `items[0].sku`   | Array index                 |
-| `array.*`      | `items.*.sku`    | All array items             |
-| `nested@attr`  | `customer@id`    | Nested attribute            |
-
-**CRITICAL**: Use `element@attribute` NOT `element.@attribute`
-
-### JSON Paths
-
-| Pattern        | Example              | Description     |
-| -------------- | -------------------- | --------------- |
-| `property`     | `orderNo`            | Property value  |
-| `parent.child` | `customer.email`     | Nested property |
-| `array[0]`     | `items[0].productId` | Array index     |
-| `array.*`      | `items.*.productId`  | All items       |
-
-## XML Attribute Access (CRITICAL)
-
-```json
-{
-  "customerId": { "source": "customer@id" },
-  "orderId": { "source": "order@orderNumber" },
-  "itemRef": { "source": "order.items.item@id" }
-}
-```
-
-**Common Mistakes**:
-
-- ❌ `"customer.@id"` (extra dot)
-- ❌ `"customer['@id']"` (bracket notation)
-- ✅ `"customer@id"` (correct)
-- ✅ `"order.items.item@id"` (nested)
-
-## SDK Resolvers
-
-| Resolver         | Input             | Output            | Use Case             |
-| ---------------- | ----------------- | ----------------- | -------------------- |
-| `sdk.parseInt`   | `"123"`           | `123`             | Quantities, counts   |
-| `sdk.parseFloat` | `"29.99"`         | `29.99`           | Prices, decimals     |
-| `sdk.uppercase`  | `"abc"`           | `"ABC"`           | Status codes         |
-| `sdk.lowercase`  | `"ABC@EMAIL.COM"` | `"abc@email.com"` | Email normalization  |
-| `sdk.trim`       | `" text "`        | `"text"`          | Clean whitespace     |
-| `sdk.formatDate` | Various           | ISO string        | Date standardization |
-| `sdk.boolean`    | `"true"`, `1`     | `true`            | Boolean conversion   |
-| `sdk.toString`   | `123`             | `"123"`           | String conversion    |
-
-## Array Handling
-
-### Basic Array
-
-```json
-{
-  "items": {
-    "_array": true,
-    "_type": "[OrderItemInput]!",
-    "source": "product-lineitems.product-lineitem",
-
-    "ref": { "source": "@lineitem-id", "required": true },
-    "productRef": { "source": "product-id", "required": true },
-    "quantity": { "source": "quantity", "resolver": "sdk.parseInt" }
-  }
-}
-```
-
-### Array with Validation
-
-```json
-{
-  "items": {
-    "_array": true,
-    "_validation": {
-      "minItems": 1,
-      "maxItems": 100,
-      "each": {
-        "quantity": { "required": true, "min": 1 }
-      }
-    }
-  }
-}
-```
-
-### Auto-Wrap Single Items
-
-```json
-{
-  "items": {
-    "_array": true,
-    "_autoWrap": true,
-    "source": "product-lineitem"
-  }
-}
-```
-
-## Field Configuration Options
-
-| Option         | Type    | Description             | Example               |
-| -------------- | ------- | ----------------------- | --------------------- |
-| `source`       | string  | Source path             | `"customer.email"`    |
-| `value`        | any     | Static value            | `"STANDARD"`          |
-| `resolver`     | string  | Transformation function | `"sdk.parseInt"`      |
-| `required`     | boolean | Field is required (see note below) | `true`                |
-| `defaultValue` | any     | Default if missing      | `"USD"`               |
-| `_array`       | boolean | Field is array          | `true`                |
-| `_type`        | string  | GraphQL type            | `"[OrderItemInput]!"` |
-
-**Note on `required` with resolvers:**
-- Fields with `source`: Validated **before** resolver execution
-- Resolver-only fields (no `source`): Validated **after** resolver execution
-- Resolvers can return `null`, `undefined`, or empty strings - `required: true` validates after resolver runs to catch these cases
-
-## Custom Resolvers
-
-```typescript
-// Initialize mapper
-const mapper = new GraphQLMutationMapper(mappingConfig, logger, { fluentClient: fluentClient });
-
-// Define custom resolvers
-const customResolvers = {
-  'custom.calculateTax': (value, sourceData, config, helpers) => {
-    return helpers.parseFloatSafe(value, 0) * 0.1;
-  },
-  'custom.mapStatus': (value, sourceData, config, helpers) => {
-    void sourceData; void config; void helpers;
-    const statusMap = { in_stock: 'AVAILABLE', out: 'ON_HOLD' };
-    return statusMap[value] || 'AVAILABLE';
-  },
-  'custom.fullName': (value, sourceData, config, helpers) => {
-    void value; void config; void helpers;
-    return `${sourceData.firstName} ${sourceData.lastName}`.trim();
-  },
-};
-
-// Use with mapWithNodes (Pattern 2)
-const result = await mapper.mapWithNodes(sourceData, customResolvers, { fluentClient });
-```
-
-## Variables and Hooks
-
-### Using Environment Variables
-
-```json
-{
-  "retailer": {
-    "fields": {
-      "id": { "value": "${FLUENT_RETAILER_ID}", "required": true }
-    }
-  }
-}
-```
-
-### Pre/Post Processing Hooks
-
-```typescript
-const mapper = new GraphQLMutationMapper(mappingConfig, fluentClient, logger, {
-  hooks: {
-    beforeMapping: async sourceData => {
-      console.log('Processing:', sourceData);
-      return sourceData;
-    },
-    afterMapping: async mappedData => {
-      console.log('Mapped:', mappedData);
-      return mappedData;
-    },
-    onError: async (error, sourceData) => {
-      console.error('Mapping failed:', error);
-      throw error;
-    },
-  },
-});
-```
-
-## Arguments vs Nodes Decision Table
-
-| Your GraphQL Needs             | Use                        | Configuration                                          |
-| ------------------------------ | -------------------------- | ------------------------------------------------------ |
-| Single mutation with variables | `arguments`                | `"arguments": { "input": { ... } }`                    |
-| Multiple parallel mutations    | `nodes`                    | `"nodes": [ { "mutation": "...", "arguments": ... } ]` |
-| Conditional mutations          | `nodes` with conditions    | `"condition": "status === 'active'"`                   |
-| Batch operations               | `nodes` with array mapping | Map array to multiple nodes                            |
-
-### Arguments Pattern (Single Mutation)
-
-```json
-{
-  "mutation": "createOrder",
-  "arguments": {
-    "input": {
-      "ref": { "source": "order@order-no" }
-    }
-  }
-}
-```
-
-### Nodes Pattern (Multiple Mutations)
-
-```json
-{
-  "nodes": [
-    {
-      "mutation": "createOrder",
-      "arguments": { "input": { "ref": { "source": "order@id" } } }
-    },
-    {
-      "mutation": "createFulfilment",
-      "arguments": { "input": { "orderRef": { "source": "order@id" } } }
-    }
-  ]
-}
-```
-
-## Error Handling
-
-```typescript
-try {
-  const payload = await mapper.map(sourceData);
-  const result = await fluentClient.graphql(payload);
-
-  if (result.errors) {
-    console.error('GraphQL errors:', result.errors);
-  }
-} catch (error) {
-  if (error.code === 'MAPPING_ERROR') {
-    console.error('Field mapping failed:', error.details);
-  } else if (error.code === 'VALIDATION_ERROR') {
-    console.error('Schema validation failed:', error.errors);
-  }
-}
-```
-
-## Common Patterns
-
-### Pattern 1: Static Value
-
-```json
-{
-  "type": { "value": "STANDARD", "required": true }
-}
-```
-
-### Pattern 2: Direct Mapping
-
-```json
-{
-  "ref": { "source": "order@order-no", "required": true }
-}
-```
-
-### Pattern 3: Mapped with Transformation
-
-```json
-{
-  "qty": { "source": "quantity", "resolver": "sdk.parseInt", "required": true }
-}
-```
-
-### Pattern 4: Nested Object
-
-```json
-{
-  "customer": {
-    "fields": {
-      "email": { "source": "customer.customer-email" },
-      "firstName": { "source": "customer.name.first-name" }
-    }
-  }
-}
-```
-
-### Pattern 5: Array Mapping
-
-```json
-{
-  "items": {
-    "_array": true,
-    "source": "product-lineitems.product-lineitem",
-    "ref": { "source": "@lineitem-id" }
-  }
-}
-```
-
-## Schema Validation
-
-```bash
-# Validate mapping against schema
-npx fc-connect validate-schema \
-  --mapping mappings/sfcc-order-to-fluent.json \
-  --schema schema.json
-
-# Generate mutation mapping from schema
-npx @fluentcommerce/fc-connect-sdk generate-mutation-mapping \
-  --schema schema.json \
-  --mutation createOrder \
-  --output mappings/
-```
-
-## Versori Platform Compatibility
-
-**XMLPathResolver supports both raw XML and pre-parsed objects:**
-
-```typescript
-// Scenario 1: Raw XML string (standalone)
-const xmlString = '<order order-no="12345">...</order>';
-mapper.map(xmlString); // ✅ Auto-parses
-
-// Scenario 2: Versori pre-parsed object
-const versoriData = { order: { $: { 'order-no': '12345' } } };
-mapper.map(versoriData); // ✅ Handles $ attribute structure
-
-// SAME mapping config works for BOTH!
-```
-
-## Troubleshooting Quick Fixes
-
-| Error                          | Cause                   | Solution                       |
-| ------------------------------ | ----------------------- | ------------------------------ |
-| `Path not found: customer.@id` | Dot before @            | Use `customer@id`              |
-| `Required field missing: ref`  | Source path wrong       | Verify XML/JSON structure      |
-| `Type mismatch: expected Int`  | String not converted    | Add `resolver: "sdk.parseInt"` |
-| `Array expected, got object`   | Single item not wrapped | Add `_autoWrap: true`          |
-| `Validation failed`            | Schema mismatch         | Run `validate-schema` CLI      |
-
-## Complete Example
-
-```json
-{
-  "version": "1.0",
-  "mutation": "createOrder",
-  "operationName": "CreateOrderFromSFCC",
-  "sourceFormat": "xml",
-  "returnFields": ["id", "ref", "status", "totalPrice"],
-
-  "arguments": {
-    "input": {
-      "_type": "CreateOrderInput!",
-
-      "ref": {
-        "source": "order@order-no",
-        "required": true
-      },
-
-      "type": {
-        "value": "STANDARD",
-        "required": true
-      },
-
-      "retailer": {
-        "fields": {
-          "id": { "value": "${FLUENT_RETAILER_ID}", "required": true }
-        }
-      },
-
-      "customer": {
-        "fields": {
-          "ref": { "source": "customer.customer-no", "required": true },
-          "email": { "source": "customer.customer-email", "resolver": "sdk.lowercase" }
-        }
-      },
-
-      "totalPrice": {
-        "source": "totals.order-total.gross-price",
-        "resolver": "sdk.parseFloat",
-        "required": true
-      },
-
-      "currency": {
-        "source": "currency",
-        "defaultValue": "USD",
-        "required": true
-      },
-
-      "items": {
-        "_array": true,
-        "_type": "[OrderItemInput]!",
-        "source": "product-lineitems.product-lineitem",
-        "_autoWrap": true,
-
-        "ref": { "source": "@lineitem-id", "required": true },
-        "productRef": { "source": "product-id", "required": true },
-        "quantity": { "source": "quantity", "resolver": "sdk.parseInt", "required": true },
-        "price": { "source": "base-price", "resolver": "sdk.parseFloat", "required": true }
-      }
-    }
-  }
-}
-```
-
----
-
-**See Full Documentation:**
-
-- [GraphQL Mutation Mapping Guide Index](./graphql-mutation-mapping-readme.md)
-- [Module 02: Quick Start](../../auto-pagination/modules/auto-pagination-02-quick-start.md)
-- [Module 06: Path Syntax](./modules/graphql-mutation-mapping-06-path-syntax.md)
-- [Module 08: Custom Resolvers](./modules/graphql-mutation-mapping-08-custom-resolvers.md)
-- [Module 11: Error Handling](./modules/graphql-mutation-mapping-11-error-handling.md)
-- [Module 12: Arguments vs Nodes](./modules/graphql-mutation-mapping-12-arguments-vs-nodes.md)
+# GraphQL Mutation Mapping Quick Reference
+
+## Quick Reference (GraphQL-Specific Essentials)
+
+## Import Statement
+
+```typescript
+import { GraphQLMutationMapper } from '@fluentcommerce/fc-connect-sdk';
+```
+
+## Basic Usage
+
+```typescript
+// 1. Load mapping configuration
+import mappingConfig from './mappings/sfcc-order-to-fluent.json';
+
+// 2. Initialize mapper
+const mapper = new GraphQLMutationMapper(mappingConfig, logger, { fluentClient: fluentClient });
+
+// 3. Transform source data
+const payload = await mapper.map(xmlOrJsonData);
+
+// 4. Execute mutation
+const result = await fluentClient.graphql(payload);
+```
+
+## Mapping Configuration Structure
+
+**Note:** The `returnFields` array specifies which fields are returned in the GraphQL mutation response. These fields are available in `result.data.createOrder` (or `result.data.createLocation`, etc.) after executing the mutation. If omitted, defaults to `["id", "ref"]` for fields-based patterns and `["id"]` for arguments-based patterns.
+
+```json
+{
+  "version": "1.0",
+  "mutation": "createOrder",
+  "operationName": "CreateOrderFromSFCC",
+  "sourceFormat": "xml",
+  "returnFields": ["id", "ref", "status"],
+
+  "arguments": {
+    "input": {
+      "_type": "CreateOrderInput!",
+
+      "ref": { "source": "order@order-no", "required": true },
+      "type": { "value": "STANDARD", "required": true },
+      "totalPrice": { "source": "totals.order-total", "resolver": "sdk.parseFloat" },
+
+      "items": {
+        "_array": true,
+        "_type": "[OrderItemInput]!",
+        "source": "product-lineitems.product-lineitem",
+
+        "ref": { "source": "@lineitem-id", "required": true },
+        "quantity": { "source": "quantity", "resolver": "sdk.parseInt" }
+      }
+    }
+  }
+}
+```
+
+## Path Syntax Quick Reference
+
+### XML Paths
+
+| Pattern        | Example          | Description                 |
+| -------------- | ---------------- | --------------------------- |
+| `element`      | `order-date`     | Element value               |
+| `element@attr` | `order@order-no` | Attribute (NO dot before @) |
+| `parent.child` | `customer.email` | Nested element              |
+| `array[0]`     | `items[0].sku`   | Array index                 |
+| `array.*`      | `items.*.sku`    | All array items             |
+| `nested@attr`  | `customer@id`    | Nested attribute            |
+
+**CRITICAL**: Use `element@attribute` NOT `element.@attribute`
+
+### JSON Paths
+
+| Pattern        | Example              | Description     |
+| -------------- | -------------------- | --------------- |
+| `property`     | `orderNo`            | Property value  |
+| `parent.child` | `customer.email`     | Nested property |
+| `array[0]`     | `items[0].productId` | Array index     |
+| `array.*`      | `items.*.productId`  | All items       |
+
+## XML Attribute Access (CRITICAL)
+
+```json
+{
+  "customerId": { "source": "customer@id" },
+  "orderId": { "source": "order@orderNumber" },
+  "itemRef": { "source": "order.items.item@id" }
+}
+```
+
+**Common Mistakes**:
+
+- ❌ `"customer.@id"` (extra dot)
+- ❌ `"customer['@id']"` (bracket notation)
+- ✅ `"customer@id"` (correct)
+- ✅ `"order.items.item@id"` (nested)
+
+## SDK Resolvers
+
+| Resolver         | Input             | Output            | Use Case             |
+| ---------------- | ----------------- | ----------------- | -------------------- |
+| `sdk.parseInt`   | `"123"`           | `123`             | Quantities, counts   |
+| `sdk.parseFloat` | `"29.99"`         | `29.99`           | Prices, decimals     |
+| `sdk.uppercase`  | `"abc"`           | `"ABC"`           | Status codes         |
+| `sdk.lowercase`  | `"ABC@EMAIL.COM"` | `"abc@email.com"` | Email normalization  |
+| `sdk.trim`       | `" text "`        | `"text"`          | Clean whitespace     |
+| `sdk.formatDate` | Various           | ISO string        | Date standardization |
+| `sdk.boolean`    | `"true"`, `1`     | `true`            | Boolean conversion   |
+| `sdk.toString`   | `123`             | `"123"`           | String conversion    |
+
+## Array Handling
+
+### Basic Array
+
+```json
+{
+  "items": {
+    "_array": true,
+    "_type": "[OrderItemInput]!",
+    "source": "product-lineitems.product-lineitem",
+
+    "ref": { "source": "@lineitem-id", "required": true },
+    "productRef": { "source": "product-id", "required": true },
+    "quantity": { "source": "quantity", "resolver": "sdk.parseInt" }
+  }
+}
+```
+
+### Array with Validation
+
+```json
+{
+  "items": {
+    "_array": true,
+    "_validation": {
+      "minItems": 1,
+      "maxItems": 100,
+      "each": {
+        "quantity": { "required": true, "min": 1 }
+      }
+    }
+  }
+}
+```
+
+### Auto-Wrap Single Items
+
+```json
+{
+  "items": {
+    "_array": true,
+    "_autoWrap": true,
+    "source": "product-lineitem"
+  }
+}
+```
+
+## Field Configuration Options
+
+| Option         | Type    | Description             | Example               |
+| -------------- | ------- | ----------------------- | --------------------- |
+| `source`       | string  | Source path             | `"customer.email"`    |
+| `value`        | any     | Static value            | `"STANDARD"`          |
+| `resolver`     | string  | Transformation function | `"sdk.parseInt"`      |
+| `required`     | boolean | Field is required (see note below) | `true`                |
+| `defaultValue` | any     | Default if missing      | `"USD"`               |
+| `_array`       | boolean | Field is array          | `true`                |
+| `_type`        | string  | GraphQL type            | `"[OrderItemInput]!"` |
+
+**Note on `required` with resolvers:**
+- Fields with `source`: Validated **before** resolver execution
+- Resolver-only fields (no `source`): Validated **after** resolver execution
+- Resolvers can return `null`, `undefined`, or empty strings - `required: true` validates after resolver runs to catch these cases
+
+## Custom Resolvers
+
+```typescript
+// Initialize mapper
+const mapper = new GraphQLMutationMapper(mappingConfig, logger, { fluentClient: fluentClient });
+
+// Define custom resolvers
+const customResolvers = {
+  'custom.calculateTax': (value, sourceData, config, helpers) => {
+    return helpers.parseFloatSafe(value, 0) * 0.1;
+  },
+  'custom.mapStatus': (value, sourceData, config, helpers) => {
+    void sourceData; void config; void helpers;
+    const statusMap = { in_stock: 'AVAILABLE', out: 'ON_HOLD' };
+    return statusMap[value] || 'AVAILABLE';
+  },
+  'custom.fullName': (value, sourceData, config, helpers) => {
+    void value; void config; void helpers;
+    return `${sourceData.firstName} ${sourceData.lastName}`.trim();
+  },
+};
+
+// Use with mapWithNodes (Pattern 2)
+const result = await mapper.mapWithNodes(sourceData, customResolvers, { fluentClient });
+```
+
+## Variables and Hooks
+
+### Using Environment Variables
+
+```json
+{
+  "retailer": {
+    "fields": {
+      "id": { "value": "${FLUENT_RETAILER_ID}", "required": true }
+    }
+  }
+}
+```
+
+### Pre/Post Processing Hooks
+
+```typescript
+const mapper = new GraphQLMutationMapper(mappingConfig, fluentClient, logger, {
+  hooks: {
+    beforeMapping: async sourceData => {
+      console.log('Processing:', sourceData);
+      return sourceData;
+    },
+    afterMapping: async mappedData => {
+      console.log('Mapped:', mappedData);
+      return mappedData;
+    },
+    onError: async (error, sourceData) => {
+      console.error('Mapping failed:', error);
+      throw error;
+    },
+  },
+});
+```
+
+## Arguments vs Nodes Decision Table
+
+| Your GraphQL Needs             | Use                        | Configuration                                          |
+| ------------------------------ | -------------------------- | ------------------------------------------------------ |
+| Single mutation with variables | `arguments`                | `"arguments": { "input": { ... } }`                    |
+| Multiple parallel mutations    | `nodes`                    | `"nodes": [ { "mutation": "...", "arguments": ... } ]` |
+| Conditional mutations          | `nodes` with conditions    | `"condition": "status === 'active'"`                   |
+| Batch operations               | `nodes` with array mapping | Map array to multiple nodes                            |
+
+### Arguments Pattern (Single Mutation)
+
+```json
+{
+  "mutation": "createOrder",
+  "arguments": {
+    "input": {
+      "ref": { "source": "order@order-no" }
+    }
+  }
+}
+```
+
+### Nodes Pattern (Multiple Mutations)
+
+```json
+{
+  "nodes": [
+    {
+      "mutation": "createOrder",
+      "arguments": { "input": { "ref": { "source": "order@id" } } }
+    },
+    {
+      "mutation": "createFulfilment",
+      "arguments": { "input": { "orderRef": { "source": "order@id" } } }
+    }
+  ]
+}
+```
+
+## Error Handling
+
+```typescript
+try {
+  const payload = await mapper.map(sourceData);
+  const result = await fluentClient.graphql(payload);
+
+  if (result.errors) {
+    console.error('GraphQL errors:', result.errors);
+  }
+} catch (error) {
+  if (error.code === 'MAPPING_ERROR') {
+    console.error('Field mapping failed:', error.details);
+  } else if (error.code === 'VALIDATION_ERROR') {
+    console.error('Schema validation failed:', error.errors);
+  }
+}
+```
+
+## Common Patterns
+
+### Pattern 1: Static Value
+
+```json
+{
+  "type": { "value": "STANDARD", "required": true }
+}
+```
+
+### Pattern 2: Direct Mapping
+
+```json
+{
+  "ref": { "source": "order@order-no", "required": true }
+}
+```
+
+### Pattern 3: Mapped with Transformation
+
+```json
+{
+  "qty": { "source": "quantity", "resolver": "sdk.parseInt", "required": true }
+}
+```
+
+### Pattern 4: Nested Object
+
+```json
+{
+  "customer": {
+    "fields": {
+      "email": { "source": "customer.customer-email" },
+      "firstName": { "source": "customer.name.first-name" }
+    }
+  }
+}
+```
+
+### Pattern 5: Array Mapping
+
+```json
+{
+  "items": {
+    "_array": true,
+    "source": "product-lineitems.product-lineitem",
+    "ref": { "source": "@lineitem-id" }
+  }
+}
+```
+
+## Schema Validation
+
+```bash
+# Validate mapping against schema
+npx fc-connect validate-schema \
+  --mapping mappings/sfcc-order-to-fluent.json \
+  --schema schema.json
+
+# Generate mutation mapping from schema
+npx @fluentcommerce/fc-connect-sdk generate-mutation-mapping \
+  --schema schema.json \
+  --mutation createOrder \
+  --output mappings/
+```
+
+## Versori Platform Compatibility
+
+**XMLPathResolver supports both raw XML and pre-parsed objects:**
+
+```typescript
+// Scenario 1: Raw XML string (standalone)
+const xmlString = '<order order-no="12345">...</order>';
+mapper.map(xmlString); // ✅ Auto-parses
+
+// Scenario 2: Versori pre-parsed object
+const versoriData = { order: { $: { 'order-no': '12345' } } };
+mapper.map(versoriData); // ✅ Handles $ attribute structure
+
+// SAME mapping config works for BOTH!
+```
+
+## Troubleshooting Quick Fixes
+
+| Error                          | Cause                   | Solution                       |
+| ------------------------------ | ----------------------- | ------------------------------ |
+| `Path not found: customer.@id` | Dot before @            | Use `customer@id`              |
+| `Required field missing: ref`  | Source path wrong       | Verify XML/JSON structure      |
+| `Type mismatch: expected Int`  | String not converted    | Add `resolver: "sdk.parseInt"` |
+| `Array expected, got object`   | Single item not wrapped | Add `_autoWrap: true`          |
+| `Validation failed`            | Schema mismatch         | Run `validate-schema` CLI      |
+
+## Complete Example
+
+```json
+{
+  "version": "1.0",
+  "mutation": "createOrder",
+  "operationName": "CreateOrderFromSFCC",
+  "sourceFormat": "xml",
+  "returnFields": ["id", "ref", "status", "totalPrice"],
+
+  "arguments": {
+    "input": {
+      "_type": "CreateOrderInput!",
+
+      "ref": {
+        "source": "order@order-no",
+        "required": true
+      },
+
+      "type": {
+        "value": "STANDARD",
+        "required": true
+      },
+
+      "retailer": {
+        "fields": {
+          "id": { "value": "${FLUENT_RETAILER_ID}", "required": true }
+        }
+      },
+
+      "customer": {
+        "fields": {
+          "ref": { "source": "customer.customer-no", "required": true },
+          "email": { "source": "customer.customer-email", "resolver": "sdk.lowercase" }
+        }
+      },
+
+      "totalPrice": {
+        "source": "totals.order-total.gross-price",
+        "resolver": "sdk.parseFloat",
+        "required": true
+      },
+
+      "currency": {
+        "source": "currency",
+        "defaultValue": "USD",
+        "required": true
+      },
+
+      "items": {
+        "_array": true,
+        "_type": "[OrderItemInput]!",
+        "source": "product-lineitems.product-lineitem",
+        "_autoWrap": true,
+
+        "ref": { "source": "@lineitem-id", "required": true },
+        "productRef": { "source": "product-id", "required": true },
+        "quantity": { "source": "quantity", "resolver": "sdk.parseInt", "required": true },
+        "price": { "source": "base-price", "resolver": "sdk.parseFloat", "required": true }
+      }
+    }
+  }
+}
+```
+
+---
+
+**See Full Documentation:**
+
+- [GraphQL Mutation Mapping Guide Index](./graphql-mutation-mapping-readme.md)
+- [Module 02: Quick Start](../../auto-pagination/modules/auto-pagination-02-quick-start.md)
+- [Module 06: Path Syntax](./modules/graphql-mutation-mapping-06-path-syntax.md)
+- [Module 08: Custom Resolvers](./modules/graphql-mutation-mapping-08-custom-resolvers.md)
+- [Module 11: Error Handling](./modules/graphql-mutation-mapping-11-error-handling.md)
+- [Module 12: Arguments vs Nodes](./modules/graphql-mutation-mapping-12-arguments-vs-nodes.md)