npm - @fluentcommerce/fc-connect-sdk - Versions diffs - 0.1.54 → 0.1.56 - Mend

@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (476) hide show

package/docs/02-CORE-GUIDES/mapping/graphql-mutation-mapping/modules/graphql-mutation-mapping-05-configuration-reference.md CHANGED Viewed

@@ -1,611 +1,611 @@
-# Configuration Reference
-[← Back to GraphQL Mutation Mapping Guide](../graphql-mutation-mapping-readme.md)
-**Module 5 of 13** | **Level**: Intermediate | **Time**: 15 minutes
----
-## Overview
-This module documents the complete mapping configuration structure used by `GraphQLMutationMapper`. There are **two distinct configuration patterns** (see [Module 04: Mapping Patterns](./graphql-mutation-mapping-04-mapping-patterns.md)):
-1. **Pattern 1 (Simple):** Uses `arguments` property - Direct mapping
-2. **Pattern 2 (Advanced):** Uses `fields` + optional `nodes` - Node extraction + mapping
----
-## Base Configuration Properties
-All mapping configurations share these top-level properties from the `MappingConfig` interface:
-| Property | Type | Required | Description |
-|----------|------|----------|-------------|
-| `version` | string | ✅ | Config version (use "1.0") |
-| `mutation` | string | ✅ | GraphQL mutation name (e.g., "createOrder") |
-| `operationName` | string | | Named operation for debugging/logging |
-| `sourceFormat` | `"xml"` \| `"json"` \| `"jsonl"` | ✅ | Input data format |
-| `schemaValidation` | boolean | | Enable schema validation (not used at runtime) |
-| `returnFields` | string[] | | Fields to return from mutation response |
-| `name` | string | | Human-readable configuration name |
-| `description` | string | | Configuration description/documentation |
-| `customTransforms` | Record<string, TransformFunction> | | Custom transformation functions |
-**Pattern 1 adds:**
-| Property | Type | Required | Description |
-|----------|------|----------|-------------|
-| `arguments` | Record<string, any> | ✅ | GraphQL mutation arguments mapping |
-**Pattern 2 adds (runtime extensions):**
-| Property | Type | Required | Description |
-|----------|------|----------|-------------|
-| `fields` | Record<string, FieldConfig> | ✅ | Field mapping configuration |
-| `nodes` | Record<string, NodeConfig> | | Named extractors for nested/encoded data |
----
-## Pattern 1: Simple Mapping Configuration
-Uses the `arguments` property for direct source-to-GraphQL mapping.
-### Structure
-```json
-{
-  "version": "1.0",
-  "mutation": "createOrder",
-  "operationName": "CreateOrder",
-  "sourceFormat": "json",
-  "schemaValidation": true,
-  "arguments": {
-    "input": {
-      "ref": { "source": "order.orderNo", "required": true },
-      "type": { "value": "STANDARD" },
-      "totalPrice": { "source": "order.total", "resolver": "sdk.parseFloat" },
-      "items": {
-        "_array": true,
-        "source": "order.lineItems",
-        "ref": { "source": "productId" },
-        "quantity": { "source": "qty", "resolver": "sdk.parseInt" }
-      }
-    }
-  },
-  "returnFields": ["id", "ref", "status"]
-}
-```
-### When to Use Pattern 1
-✅ Source data structure closely matches GraphQL schema
-✅ Direct field-to-field mapping (no complex extraction)
-✅ Source format is JSON or simple XML
-✅ No custom resolvers needed, or resolvers only need mapped fields
-See [Module 04: Mapping Patterns](./graphql-mutation-mapping-04-mapping-patterns.md#pattern-1-simple-mapping-map) for complete details.
----
-## Pattern 2: Advanced Mapping Configuration
-Uses `fields` (required) and `nodes` (optional) for extraction-then-mapping workflow.
-### Structure
-```json
-{
-  "version": "1.0",
-  "mutation": "createOrder",
-  "operationName": "CreateOrder",
-  "sourceFormat": "xml",
-  "schemaValidation": true,
-  "nodes": {
-    "orderDetails": {
-      "extract": "order.custom-attributes.custom-attribute@attribute-id=orderData",
-      "unescape": true,
-      "parse": "xml",
-      "required": true
-    }
-  },
-  "fields": {
-    "ref": { "source": "order@order-no", "required": true },
-    "type": { "source": "nodes.orderDetails.orderType" },
-    "totalPrice": {
-      "source": "order.totals.order-total",
-      "resolver": "sdk.parseFloat",
-      "required": true
-    },
-    "items": {
-      "_array": true,
-      "_type": "[OrderItemInput]!",
-      "source": "product-lineitems.product-lineitem",
-      "fields": {
-        "ref": { "source": "product-id", "required": true },
-        "quantity": { "source": "quantity", "resolver": "sdk.parseInt" }
-      }
-    }
-  },
-  "returnFields": ["id", "ref", "status"]
-}
-```
-### When to Use Pattern 2
-✅ Source contains nested/encoded data that needs extraction first
-✅ XML data with embedded XML strings (common in SFCC)
-✅ Custom resolvers need access to unmapped source fields
-✅ Multiple levels of data transformation required
-✅ HTML-encoded content needs unescaping
-See [Module 04: Mapping Patterns](./graphql-mutation-mapping-04-mapping-patterns.md#pattern-2-advanced-mapping-with-nodes-mapwithnodes) for complete details.
----
-## Field Configuration (FieldConfig)
-These properties define how individual fields are mapped. Used in BOTH patterns (inside `arguments` or `fields`).
-### Core Field Properties
-| Property | Type | Description | Example |
-|----------|------|-------------|---------|
-| `source` | string | Path to source data | `"order@order-no"` (XML)<br>`"order.orderNo"` (JSON) |
-| `value` | any | Static value | `"STANDARD"`, `123`, `true` |
-| `resolver` | string | Transformation function | `"sdk.parseInt"`, `"custom.calculateTotal"` |
-| `required` | boolean | Field is required (throw if missing). **Note:** With resolvers, validation timing depends on whether field has `source` - see mapping foundations guide. | `true` |
-| `defaultValue` | any | Default if source is null/undefined | `1`, `"UNKNOWN"` |
-| `fields` | Record<string, FieldConfig> | Nested object fields | See [Nested Objects](#nested-object-configuration) |
-### Internal Field Markers
-These properties are used internally by the mapper for type information and array handling:
-| Property | Type | Description | Usage |
-|----------|------|-------------|-------|
-| `_array` | boolean | Marks field as array | Arrays of items (line items, addresses, etc.) |
-| `_type` | string | GraphQL type annotation | `"String!"`, `"[OrderItemInput]!"` |
-| `_nested` | boolean | Marks field as nested object | Nested object structures |
-| `_autoWrap` | boolean | Wrap single value in array | Auto-convert single item → array |
-| `_validation` | object | Validation constraints | `{ "minItems": 1, "maxItems": 100 }` |
-**Note:** Use `resolver` for all transformations. See [Module 08: Custom Resolvers](./graphql-mutation-mapping-08-custom-resolvers.md) for details.
----
-## Node Configuration (NodeConfig)
-Used only in Pattern 2 for extracting and parsing nested/encoded data **before** field mapping.
-### Structure
-```typescript
-interface NodeConfig {
-  /** Path to extract data from source */
-  extract: string;
-  /** Decode HTML entities in extracted content */
-  unescape?: boolean;
-  /** Parse extracted string as XML or JSON */
-  parse?: 'xml' | 'json';
-  /** Documentation comment */
-  comment?: string;
-  /** Throw error if extraction returns null/undefined */
-  required?: boolean;
-}
-```
-### Examples
-**Extract and parse nested XML:**
-```json
-{
-  "nodes": {
-    "customData": {
-      "extract": "custom-attributes.custom-attribute@attribute-id=xmlData",
-      "unescape": true,
-      "parse": "xml",
-      "required": true
-    }
-  }
-}
-```
-**Extract and parse nested JSON:**
-```json
-{
-  "nodes": {
-    "metadata": {
-      "extract": "order.custom-attributes.metadata",
-      "parse": "json"
-    }
-  }
-}
-```
-**Reference extracted node in fields:**
-```json
-{
-  "fields": {
-    "orderType": { "source": "nodes.customData.orderType" }
-  }
-}
-```
----
-## Complete Configuration Examples
-### Minimal Configuration (Pattern 1)
-```json
-{
-  "version": "1.0",
-  "mutation": "createOrder",
-  "sourceFormat": "json",
-  "arguments": {
-    "input": {
-      "ref": { "source": "order.orderNo", "required": true },
-      "type": { "value": "STANDARD" }
-    }
-  }
-}
-```
-### Complete Configuration (Pattern 1)
-```json
-{
-  "version": "1.0",
-  "name": "SFCC Order Ingestion",
-  "description": "Maps SFCC JSON orders to Fluent GraphQL createOrder mutation",
-  "mutation": "createOrder",
-  "operationName": "CreateOrderFromSFCC",
-  "sourceFormat": "json",
-  "schemaValidation": true,
-  "arguments": {
-    "input": {
-      "ref": {
-        "source": "order.orderNo",
-        "required": true
-      },
-      "type": {
-        "value": "STANDARD",
-        "required": true
-      },
-      "retailer": {
-        "id": { "value": "${FLUENT_RETAILER_ID}" }
-      },
-      "customer": {
-        "ref": { "source": "customer.customerId", "required": true },
-        "email": {
-          "source": "customer.email",
-          "resolver": "sdk.lowercase",
-          "defaultValue": "unknown@example.com"
-        }
-      },
-      "totalPrice": {
-        "source": "order.total",
-        "resolver": "sdk.parseFloat",
-        "required": true
-      },
-      "items": {
-        "_array": true,
-        "_type": "[OrderItemInput]!",
-        "_autoWrap": true,
-        "source": "order.lineItems",
-        "ref": { "source": "productId", "required": true },
-        "quantity": { "source": "qty", "resolver": "sdk.parseInt" }
-      }
-    }
-  },
-  "returnFields": ["id", "ref", "status"]
-}
-```
-### Complete Configuration (Pattern 2 with Nodes)
-```json
-{
-  "version": "1.0",
-  "name": "SFCC Order with XML Nodes",
-  "description": "Extracts embedded XML from SFCC order, then maps to Fluent GraphQL",
-  "mutation": "createOrder",
-  "operationName": "CreateOrderFromSFCC",
-  "sourceFormat": "xml",
-  "schemaValidation": true,
-  "nodes": {
-    "orderDetails": {
-      "extract": "order.custom-attributes.custom-attribute@attribute-id=orderData",
-      "unescape": true,
-      "parse": "xml",
-      "required": true,
-      "comment": "Extracts and parses embedded order XML"
-    },
-    "shippingInfo": {
-      "extract": "order.custom-attributes.custom-attribute@attribute-id=shipping",
-      "unescape": true,
-      "parse": "xml",
-      "comment": "Extracts shipping details"
-    }
-  },
-  "fields": {
-    "ref": {
-      "source": "order@order-no",
-      "required": true,
-      "comment": "Order number from root XML"
-    },
-    "type": {
-      "source": "nodes.orderDetails.orderType",
-      "required": true,
-      "comment": "Order type from extracted node"
-    },
-    "retailer": {
-      "fields": {
-        "id": { "value": "${FLUENT_RETAILER_ID}" }
-      }
-    },
-    "customer": {
-      "fields": {
-        "ref": { "source": "customer.customer-no", "required": true },
-        "email": {
-          "source": "customer.customer-email",
-          "resolver": "sdk.lowercase",
-          "defaultValue": "unknown@example.com"
-        }
-      }
-    },
-    "totalPrice": {
-      "source": "order.totals.order-total",
-      "resolver": "sdk.parseFloat",
-      "required": true
-    },
-    "shippingMethod": {
-      "source": "nodes.shippingInfo.method",
-      "comment": "Shipping method from extracted shipping node"
-    },
-    "items": {
-      "_array": true,
-      "_type": "[OrderItemInput]!",
-      "_autoWrap": true,
-      "source": "product-lineitems.product-lineitem",
-      "fields": {
-        "ref": { "source": "product-id", "required": true },
-        "quantity": {
-          "source": "quantity",
-          "resolver": "sdk.parseInt",
-          "required": true
-        },
-        "price": {
-          "source": "price",
-          "resolver": "sdk.parseFloat"
-        }
-      }
-    }
-  },
-  "returnFields": ["id", "ref", "status", "type"]
-}
-```
----
-## Array Configuration
-Arrays require the `_array: true` marker and can be used in both patterns.
-### Pattern 1 (Simple)
-```json
-{
-  "arguments": {
-    "input": {
-      "items": {
-        "_array": true,
-        "_type": "[OrderItemInput]!",
-        "source": "order.lineItems",
-        "ref": { "source": "productId" },
-        "quantity": { "source": "qty", "resolver": "sdk.parseInt" }
-      }
-    }
-  }
-}
-```
-### Pattern 2 (Advanced)
-```json
-{
-  "fields": {
-    "items": {
-      "_array": true,
-      "_type": "[OrderItemInput]!",
-      "_autoWrap": true,
-      "_validation": { "minItems": 1, "maxItems": 100 },
-      "source": "product-lineitems.product-lineitem",
-      "fields": {
-        "ref": { "source": "product-id", "required": true },
-        "quantity": {
-          "source": "quantity",
-          "resolver": "sdk.parseInt",
-          "required": true,
-          "defaultValue": 1
-        }
-      }
-    }
-  }
-}
-```
-**Key Points:**
-- `_array: true` - Marks field as array
-- `_type` - GraphQL type annotation (e.g., `"[OrderItemInput]!"`)
-- `_autoWrap` - Auto-convert single object to array
-- `_validation` - Min/max item constraints
-- `source` - Path to array in source data
-- `fields` - Configuration for each array item
----
-## Nested Object Configuration
-Nested objects use the `fields` property to define child field mappings.
-### Pattern 1 (Simple)
-```json
-{
-  "arguments": {
-    "input": {
-      "customer": {
-        "ref": { "source": "customer.id", "required": true },
-        "email": { "source": "customer.email" },
-        "address": {
-          "street": { "source": "customer.address.street" },
-          "city": { "source": "customer.address.city" },
-          "country": { "source": "customer.address.country" }
-        }
-      }
-    }
-  }
-}
-```
-### Pattern 2 (Advanced)
-```json
-{
-  "fields": {
-    "customer": {
-      "_nested": true,
-      "fields": {
-        "ref": { "source": "customer.customer-no", "required": true },
-        "email": { "source": "customer.customer-email", "resolver": "sdk.lowercase" },
-        "address": {
-          "fields": {
-            "street": { "source": "customer.address.street" },
-            "city": { "source": "customer.address.city" },
-            "country": { "source": "customer.address.country" }
-          }
-        }
-      }
-    }
-  }
-}
-```
-**Nesting Levels:**
-- Level 1: `customer` (object)
-- Level 2: `address` (nested object inside customer)
-- Level 3: `street`, `city`, `country` (scalar fields)
----
-## Environment Variables
-Use `${VARIABLE_NAME}` syntax for environment variable substitution:
-```json
-{
-  "fields": {
-    "retailer": {
-      "fields": {
-        "id": { "value": "${FLUENT_RETAILER_ID}" }
-      }
-    },
-    "apiKey": {
-      "value": "${API_KEY}",
-      "comment": "API key from environment"
-    }
-  }
-}
-```
-**Supported in:**
-- ✅ `value` property
-- ❌ `source` property (use nodes for dynamic paths)
-- ❌ `resolver` property
----
-## Configuration Validation
-Before deployment, validate your configuration:
-```bash
-# 1. Introspect GraphQL schema
-npx fc-connect introspect-schema \
-  --url https://your-account.api.fluentcommerce.com/graphql \
-  --output fluent-schema.json
-# 2. Validate mapping against schema
-npx fc-connect validate-schema \
-  --mapping your-mapping.json \
-  --schema fluent-schema.json
-# 3. Check field coverage
-npx fc-connect analyze-coverage \
-  --mapping your-mapping.json \
-  --schema fluent-schema.json
-```
-See [Module 03: Schema Validation](./graphql-mutation-mapping-03-schema-validation.md) for complete CLI workflow.
----
-## Best Practices
-### ✅ DO
-- Use Pattern 1 for simple JSON/XML → GraphQL mapping
-- Use Pattern 2 when you need node extraction or full source context in resolvers
-- Document configurations with `name`, `description`, and field `comment` properties
-- Use `sdk.` resolvers for common transformations
-- Validate configurations before deployment
-- Use environment variables for credentials/IDs
-- Mark required fields explicitly
-### ❌ DON'T
-- Don't use Pattern 2 if you don't need nodes or advanced resolvers
-- Don't mix `arguments` and `fields` patterns in same config
-- Don't nest more than 3-4 levels deep (performance impact)
-- Don't hardcode credentials - use environment variables
-- Don't skip validation step before deployment
----
-## Key Takeaways
-✅ **Two patterns** - Simple (`arguments`) and Advanced (`fields` + `nodes`)
-✅ **Base properties** - version, mutation, sourceFormat always required
-✅ **Field markers** - `_array`, `_type`, `_nested` are FieldConfig properties, not top-level
-✅ **Node extraction** - Use `nodes` for nested/encoded XML strings (Pattern 2 only)
-✅ **Resolvers** - Use `sdk.` built-in or custom resolvers for transformations
-✅ **Validation** - Always validate with CLI tools before deployment
----
-## Navigation
-[← Previous: Mapping Patterns](./graphql-mutation-mapping-04-mapping-patterns.md) | [Back to Guide](../graphql-mutation-mapping-readme.md) | [Next: Path Syntax →](./graphql-mutation-mapping-06-path-syntax.md)
-## Related Documentation
-- [Module 03: Schema Validation](./graphql-mutation-mapping-03-schema-validation.md) - CLI validation workflow
-- [Module 04: Mapping Patterns](./graphql-mutation-mapping-04-mapping-patterns.md) - When to use each pattern
-- [Module 06: Path Syntax](./graphql-mutation-mapping-06-path-syntax.md) - XML and JSON path expressions
-- [Module 07: Array Handling](./graphql-mutation-mapping-07-array-handling.md) - Array mapping patterns
-- [Module 08: Custom Resolvers](./graphql-mutation-mapping-08-custom-resolvers.md) - Custom transformation functions
-- [Universal Mapping Guide](../../mapping-readme.md) - Universal mapping patterns
+# Configuration Reference
+[← Back to GraphQL Mutation Mapping Guide](../graphql-mutation-mapping-readme.md)
+**Module 5 of 13** | **Level**: Intermediate | **Time**: 15 minutes
+---
+## Overview
+This module documents the complete mapping configuration structure used by `GraphQLMutationMapper`. There are **two distinct configuration patterns** (see [Module 04: Mapping Patterns](./graphql-mutation-mapping-04-mapping-patterns.md)):
+1. **Pattern 1 (Simple):** Uses `arguments` property - Direct mapping
+2. **Pattern 2 (Advanced):** Uses `fields` + optional `nodes` - Node extraction + mapping
+---
+## Base Configuration Properties
+All mapping configurations share these top-level properties from the `MappingConfig` interface:
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `version` | string | ✅ | Config version (use "1.0") |
+| `mutation` | string | ✅ | GraphQL mutation name (e.g., "createOrder") |
+| `operationName` | string | | Named operation for debugging/logging |
+| `sourceFormat` | `"xml"` \| `"json"` \| `"jsonl"` | ✅ | Input data format |
+| `schemaValidation` | boolean | | Enable schema validation (not used at runtime) |
+| `returnFields` | string[] | | Fields to return from mutation response |
+| `name` | string | | Human-readable configuration name |
+| `description` | string | | Configuration description/documentation |
+| `customTransforms` | Record<string, TransformFunction> | | Custom transformation functions |
+**Pattern 1 adds:**
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `arguments` | Record<string, any> | ✅ | GraphQL mutation arguments mapping |
+**Pattern 2 adds (runtime extensions):**
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `fields` | Record<string, FieldConfig> | ✅ | Field mapping configuration |
+| `nodes` | Record<string, NodeConfig> | | Named extractors for nested/encoded data |
+---
+## Pattern 1: Simple Mapping Configuration
+Uses the `arguments` property for direct source-to-GraphQL mapping.
+### Structure
+```json
+{
+  "version": "1.0",
+  "mutation": "createOrder",
+  "operationName": "CreateOrder",
+  "sourceFormat": "json",
+  "schemaValidation": true,
+  "arguments": {
+    "input": {
+      "ref": { "source": "order.orderNo", "required": true },
+      "type": { "value": "STANDARD" },
+      "totalPrice": { "source": "order.total", "resolver": "sdk.parseFloat" },
+      "items": {
+        "_array": true,
+        "source": "order.lineItems",
+        "ref": { "source": "productId" },
+        "quantity": { "source": "qty", "resolver": "sdk.parseInt" }
+      }
+    }
+  },
+  "returnFields": ["id", "ref", "status"]
+}
+```
+### When to Use Pattern 1
+✅ Source data structure closely matches GraphQL schema
+✅ Direct field-to-field mapping (no complex extraction)
+✅ Source format is JSON or simple XML
+✅ No custom resolvers needed, or resolvers only need mapped fields
+See [Module 04: Mapping Patterns](./graphql-mutation-mapping-04-mapping-patterns.md#pattern-1-simple-mapping-map) for complete details.
+---
+## Pattern 2: Advanced Mapping Configuration
+Uses `fields` (required) and `nodes` (optional) for extraction-then-mapping workflow.
+### Structure
+```json
+{
+  "version": "1.0",
+  "mutation": "createOrder",
+  "operationName": "CreateOrder",
+  "sourceFormat": "xml",
+  "schemaValidation": true,
+  "nodes": {
+    "orderDetails": {
+      "extract": "order.custom-attributes.custom-attribute@attribute-id=orderData",
+      "unescape": true,
+      "parse": "xml",
+      "required": true
+    }
+  },
+  "fields": {
+    "ref": { "source": "order@order-no", "required": true },
+    "type": { "source": "nodes.orderDetails.orderType" },
+    "totalPrice": {
+      "source": "order.totals.order-total",
+      "resolver": "sdk.parseFloat",
+      "required": true
+    },
+    "items": {
+      "_array": true,
+      "_type": "[OrderItemInput]!",
+      "source": "product-lineitems.product-lineitem",
+      "fields": {
+        "ref": { "source": "product-id", "required": true },
+        "quantity": { "source": "quantity", "resolver": "sdk.parseInt" }
+      }
+    }
+  },
+  "returnFields": ["id", "ref", "status"]
+}
+```
+### When to Use Pattern 2
+✅ Source contains nested/encoded data that needs extraction first
+✅ XML data with embedded XML strings (common in SFCC)
+✅ Custom resolvers need access to unmapped source fields
+✅ Multiple levels of data transformation required
+✅ HTML-encoded content needs unescaping
+See [Module 04: Mapping Patterns](./graphql-mutation-mapping-04-mapping-patterns.md#pattern-2-advanced-mapping-with-nodes-mapwithnodes) for complete details.
+---
+## Field Configuration (FieldConfig)
+These properties define how individual fields are mapped. Used in BOTH patterns (inside `arguments` or `fields`).
+### Core Field Properties
+| Property | Type | Description | Example |
+|----------|------|-------------|---------|
+| `source` | string | Path to source data | `"order@order-no"` (XML)<br>`"order.orderNo"` (JSON) |
+| `value` | any | Static value | `"STANDARD"`, `123`, `true` |
+| `resolver` | string | Transformation function | `"sdk.parseInt"`, `"custom.calculateTotal"` |
+| `required` | boolean | Field is required (throw if missing). **Note:** With resolvers, validation timing depends on whether field has `source` - see mapping foundations guide. | `true` |
+| `defaultValue` | any | Default if source is null/undefined | `1`, `"UNKNOWN"` |
+| `fields` | Record<string, FieldConfig> | Nested object fields | See [Nested Objects](#nested-object-configuration) |
+### Internal Field Markers
+These properties are used internally by the mapper for type information and array handling:
+| Property | Type | Description | Usage |
+|----------|------|-------------|-------|
+| `_array` | boolean | Marks field as array | Arrays of items (line items, addresses, etc.) |
+| `_type` | string | GraphQL type annotation | `"String!"`, `"[OrderItemInput]!"` |
+| `_nested` | boolean | Marks field as nested object | Nested object structures |
+| `_autoWrap` | boolean | Wrap single value in array | Auto-convert single item → array |
+| `_validation` | object | Validation constraints | `{ "minItems": 1, "maxItems": 100 }` |
+**Note:** Use `resolver` for all transformations. See [Module 08: Custom Resolvers](./graphql-mutation-mapping-08-custom-resolvers.md) for details.
+---
+## Node Configuration (NodeConfig)
+Used only in Pattern 2 for extracting and parsing nested/encoded data **before** field mapping.
+### Structure
+```typescript
+interface NodeConfig {
+  /** Path to extract data from source */
+  extract: string;
+  /** Decode HTML entities in extracted content */
+  unescape?: boolean;
+  /** Parse extracted string as XML or JSON */
+  parse?: 'xml' | 'json';
+  /** Documentation comment */
+  comment?: string;
+  /** Throw error if extraction returns null/undefined */
+  required?: boolean;
+}
+```
+### Examples
+**Extract and parse nested XML:**
+```json
+{
+  "nodes": {
+    "customData": {
+      "extract": "custom-attributes.custom-attribute@attribute-id=xmlData",
+      "unescape": true,
+      "parse": "xml",
+      "required": true
+    }
+  }
+}
+```
+**Extract and parse nested JSON:**
+```json
+{
+  "nodes": {
+    "metadata": {
+      "extract": "order.custom-attributes.metadata",
+      "parse": "json"
+    }
+  }
+}
+```
+**Reference extracted node in fields:**
+```json
+{
+  "fields": {
+    "orderType": { "source": "nodes.customData.orderType" }
+  }
+}
+```
+---
+## Complete Configuration Examples
+### Minimal Configuration (Pattern 1)
+```json
+{
+  "version": "1.0",
+  "mutation": "createOrder",
+  "sourceFormat": "json",
+  "arguments": {
+    "input": {
+      "ref": { "source": "order.orderNo", "required": true },
+      "type": { "value": "STANDARD" }
+    }
+  }
+}
+```
+### Complete Configuration (Pattern 1)
+```json
+{
+  "version": "1.0",
+  "name": "SFCC Order Ingestion",
+  "description": "Maps SFCC JSON orders to Fluent GraphQL createOrder mutation",
+  "mutation": "createOrder",
+  "operationName": "CreateOrderFromSFCC",
+  "sourceFormat": "json",
+  "schemaValidation": true,
+  "arguments": {
+    "input": {
+      "ref": {
+        "source": "order.orderNo",
+        "required": true
+      },
+      "type": {
+        "value": "STANDARD",
+        "required": true
+      },
+      "retailer": {
+        "id": { "value": "${FLUENT_RETAILER_ID}" }
+      },
+      "customer": {
+        "ref": { "source": "customer.customerId", "required": true },
+        "email": {
+          "source": "customer.email",
+          "resolver": "sdk.lowercase",
+          "defaultValue": "unknown@example.com"
+        }
+      },
+      "totalPrice": {
+        "source": "order.total",
+        "resolver": "sdk.parseFloat",
+        "required": true
+      },
+      "items": {
+        "_array": true,
+        "_type": "[OrderItemInput]!",
+        "_autoWrap": true,
+        "source": "order.lineItems",
+        "ref": { "source": "productId", "required": true },
+        "quantity": { "source": "qty", "resolver": "sdk.parseInt" }
+      }
+    }
+  },
+  "returnFields": ["id", "ref", "status"]
+}
+```
+### Complete Configuration (Pattern 2 with Nodes)
+```json
+{
+  "version": "1.0",
+  "name": "SFCC Order with XML Nodes",
+  "description": "Extracts embedded XML from SFCC order, then maps to Fluent GraphQL",
+  "mutation": "createOrder",
+  "operationName": "CreateOrderFromSFCC",
+  "sourceFormat": "xml",
+  "schemaValidation": true,
+  "nodes": {
+    "orderDetails": {
+      "extract": "order.custom-attributes.custom-attribute@attribute-id=orderData",
+      "unescape": true,
+      "parse": "xml",
+      "required": true,
+      "comment": "Extracts and parses embedded order XML"
+    },
+    "shippingInfo": {
+      "extract": "order.custom-attributes.custom-attribute@attribute-id=shipping",
+      "unescape": true,
+      "parse": "xml",
+      "comment": "Extracts shipping details"
+    }
+  },
+  "fields": {
+    "ref": {
+      "source": "order@order-no",
+      "required": true,
+      "comment": "Order number from root XML"
+    },
+    "type": {
+      "source": "nodes.orderDetails.orderType",
+      "required": true,
+      "comment": "Order type from extracted node"
+    },
+    "retailer": {
+      "fields": {
+        "id": { "value": "${FLUENT_RETAILER_ID}" }
+      }
+    },
+    "customer": {
+      "fields": {
+        "ref": { "source": "customer.customer-no", "required": true },
+        "email": {
+          "source": "customer.customer-email",
+          "resolver": "sdk.lowercase",
+          "defaultValue": "unknown@example.com"
+        }
+      }
+    },
+    "totalPrice": {
+      "source": "order.totals.order-total",
+      "resolver": "sdk.parseFloat",
+      "required": true
+    },
+    "shippingMethod": {
+      "source": "nodes.shippingInfo.method",
+      "comment": "Shipping method from extracted shipping node"
+    },
+    "items": {
+      "_array": true,
+      "_type": "[OrderItemInput]!",
+      "_autoWrap": true,
+      "source": "product-lineitems.product-lineitem",
+      "fields": {
+        "ref": { "source": "product-id", "required": true },
+        "quantity": {
+          "source": "quantity",
+          "resolver": "sdk.parseInt",
+          "required": true
+        },
+        "price": {
+          "source": "price",
+          "resolver": "sdk.parseFloat"
+        }
+      }
+    }
+  },
+  "returnFields": ["id", "ref", "status", "type"]
+}
+```
+---
+## Array Configuration
+Arrays require the `_array: true` marker and can be used in both patterns.
+### Pattern 1 (Simple)
+```json
+{
+  "arguments": {
+    "input": {
+      "items": {
+        "_array": true,
+        "_type": "[OrderItemInput]!",
+        "source": "order.lineItems",
+        "ref": { "source": "productId" },
+        "quantity": { "source": "qty", "resolver": "sdk.parseInt" }
+      }
+    }
+  }
+}
+```
+### Pattern 2 (Advanced)
+```json
+{
+  "fields": {
+    "items": {
+      "_array": true,
+      "_type": "[OrderItemInput]!",
+      "_autoWrap": true,
+      "_validation": { "minItems": 1, "maxItems": 100 },
+      "source": "product-lineitems.product-lineitem",
+      "fields": {
+        "ref": { "source": "product-id", "required": true },
+        "quantity": {
+          "source": "quantity",
+          "resolver": "sdk.parseInt",
+          "required": true,
+          "defaultValue": 1
+        }
+      }
+    }
+  }
+}
+```
+**Key Points:**
+- `_array: true` - Marks field as array
+- `_type` - GraphQL type annotation (e.g., `"[OrderItemInput]!"`)
+- `_autoWrap` - Auto-convert single object to array
+- `_validation` - Min/max item constraints
+- `source` - Path to array in source data
+- `fields` - Configuration for each array item
+---
+## Nested Object Configuration
+Nested objects use the `fields` property to define child field mappings.
+### Pattern 1 (Simple)
+```json
+{
+  "arguments": {
+    "input": {
+      "customer": {
+        "ref": { "source": "customer.id", "required": true },
+        "email": { "source": "customer.email" },
+        "address": {
+          "street": { "source": "customer.address.street" },
+          "city": { "source": "customer.address.city" },
+          "country": { "source": "customer.address.country" }
+        }
+      }
+    }
+  }
+}
+```
+### Pattern 2 (Advanced)
+```json
+{
+  "fields": {
+    "customer": {
+      "_nested": true,
+      "fields": {
+        "ref": { "source": "customer.customer-no", "required": true },
+        "email": { "source": "customer.customer-email", "resolver": "sdk.lowercase" },
+        "address": {
+          "fields": {
+            "street": { "source": "customer.address.street" },
+            "city": { "source": "customer.address.city" },
+            "country": { "source": "customer.address.country" }
+          }
+        }
+      }
+    }
+  }
+}
+```
+**Nesting Levels:**
+- Level 1: `customer` (object)
+- Level 2: `address` (nested object inside customer)
+- Level 3: `street`, `city`, `country` (scalar fields)
+---
+## Environment Variables
+Use `${VARIABLE_NAME}` syntax for environment variable substitution:
+```json
+{
+  "fields": {
+    "retailer": {
+      "fields": {
+        "id": { "value": "${FLUENT_RETAILER_ID}" }
+      }
+    },
+    "apiKey": {
+      "value": "${API_KEY}",
+      "comment": "API key from environment"
+    }
+  }
+}
+```
+**Supported in:**
+- ✅ `value` property
+- ❌ `source` property (use nodes for dynamic paths)
+- ❌ `resolver` property
+---
+## Configuration Validation
+Before deployment, validate your configuration:
+```bash
+# 1. Introspect GraphQL schema
+npx fc-connect introspect-schema \
+  --url https://your-account.api.fluentcommerce.com/graphql \
+  --output fluent-schema.json
+# 2. Validate mapping against schema
+npx fc-connect validate-schema \
+  --mapping your-mapping.json \
+  --schema fluent-schema.json
+# 3. Check field coverage
+npx fc-connect analyze-coverage \
+  --mapping your-mapping.json \
+  --schema fluent-schema.json
+```
+See [Module 03: Schema Validation](./graphql-mutation-mapping-03-schema-validation.md) for complete CLI workflow.
+---
+## Best Practices
+### ✅ DO
+- Use Pattern 1 for simple JSON/XML → GraphQL mapping
+- Use Pattern 2 when you need node extraction or full source context in resolvers
+- Document configurations with `name`, `description`, and field `comment` properties
+- Use `sdk.` resolvers for common transformations
+- Validate configurations before deployment
+- Use environment variables for credentials/IDs
+- Mark required fields explicitly
+### ❌ DON'T
+- Don't use Pattern 2 if you don't need nodes or advanced resolvers
+- Don't mix `arguments` and `fields` patterns in same config
+- Don't nest more than 3-4 levels deep (performance impact)
+- Don't hardcode credentials - use environment variables
+- Don't skip validation step before deployment
+---
+## Key Takeaways
+✅ **Two patterns** - Simple (`arguments`) and Advanced (`fields` + `nodes`)
+✅ **Base properties** - version, mutation, sourceFormat always required
+✅ **Field markers** - `_array`, `_type`, `_nested` are FieldConfig properties, not top-level
+✅ **Node extraction** - Use `nodes` for nested/encoded XML strings (Pattern 2 only)
+✅ **Resolvers** - Use `sdk.` built-in or custom resolvers for transformations
+✅ **Validation** - Always validate with CLI tools before deployment
+---
+## Navigation
+[← Previous: Mapping Patterns](./graphql-mutation-mapping-04-mapping-patterns.md) | [Back to Guide](../graphql-mutation-mapping-readme.md) | [Next: Path Syntax →](./graphql-mutation-mapping-06-path-syntax.md)
+## Related Documentation
+- [Module 03: Schema Validation](./graphql-mutation-mapping-03-schema-validation.md) - CLI validation workflow
+- [Module 04: Mapping Patterns](./graphql-mutation-mapping-04-mapping-patterns.md) - When to use each pattern
+- [Module 06: Path Syntax](./graphql-mutation-mapping-06-path-syntax.md) - XML and JSON path expressions
+- [Module 07: Array Handling](./graphql-mutation-mapping-07-array-handling.md) - Array mapping patterns
+- [Module 08: Custom Resolvers](./graphql-mutation-mapping-08-custom-resolvers.md) - Custom transformation functions
+- [Universal Mapping Guide](../../mapping-readme.md) - Universal mapping patterns