@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

package/docs/02-CORE-GUIDES/mapping/graphql-mutation-mapping/modules/graphql-mutation-mapping-09-advanced-patterns.md

@@ -1,427 +1,427 @@
-# Advanced Patterns
-
-[← Back to GraphQL Mutation Mapping Guide](../graphql-mutation-mapping-readme.md)
-
-**Module 9 of 13** | **Level**: Advanced | **Time**: 20 minutes
-
----
-
-## Advanced Mapping Patterns
-
-This module covers advanced techniques for handling complex data transformations and mapping scenarios.
-
-## Relative Paths in Arrays
-
-When mapping array items, use `$.` prefix for paths relative to the current item:
-
-```json
-{
-  "items": {
-    "source": "order.lineItems.item",
-    "isArray": true,
-    "fields": {
-      "ref": { "source": "$.sku" },                    // Relative to current item
-      "quantity": { "source": "$.quantity" },          // Relative to current item
-      "currency": { "source": "order.currency" }       // Absolute path from root
-    }
-  }
-}
-```
-
-**Benefits:**
-- ✅ Clear and concise (avoids repeating full path)
-- ✅ Works with nested arrays
-- ✅ Easy to read and maintain
-
-**Example with nested arrays:**
-```json
-{
-  "orders": {
-    "source": "data.orders.order",
-    "isArray": true,
-    "fields": {
-      "ref": { "source": "$.orderNumber" },
-      "items": {
-        "source": "$.lineItems.item",
-        "isArray": true,
-        "fields": {
-          "sku": { "source": "$.productId" },          // Relative to item
-          "orderRef": { "source": "data.orders.order.orderNumber" }  // Absolute from root
-        }
-      }
-    }
-  }
-}
-```
-
-## Reference Resolution Pattern
-
-Resolve references between entities using custom resolvers:
-
-**Example: Billing address references shipping address by ID**
-
-```xml
-<order order-no="ORD-123">
-  <shipping>
-    <addresses>
-      <address id="addr-123">
-        <street>123 Main St</street>
-        <city>Springfield</city>
-      </address>
-      <address id="addr-456">
-        <street>456 Oak Ave</street>
-        <city>Rivertown</city>
-      </address>
-    </addresses>
-  </shipping>
-  <billing>
-    <addressRef>addr-123</addressRef>
-  </billing>
-</order>
-```
-
-**Mapping with custom resolver:**
-
-✅ **Validated against schema:** [`docs/schema/fluent-commerce-schema.json`](../../../../04-REFERENCE/schema/fluent-commerce-schema.json) → `Mutation.createOrder`
-
-```json
-{
-  "version": "1.0",
-  "mutation": "createOrder",
-  "sourceFormat": "xml",
-  "comment": "✅ Reference resolution pattern for billing address lookup",
-  "arguments": {
-    "input": {
-      "ref": {
-        "source": "order@order-no",
-        "required": true,
-        "comment": "✅ Maps to CreateOrderInput.ref (String! required)"
-      },
-      "type": {
-        "value": "STANDARD",
-        "required": true,
-        "comment": "✅ Maps to CreateOrderInput.type (OrderType! required)"
-      },
-      "retailer": {
-        "fields": {
-          "id": {
-            "value": "1",
-            "comment": "✅ Maps to CreateOrderInput.retailer.id (ID! required)"
-          }
-        }
-      },
-      "billingAddress": {
-        "resolver": "custom.resolveBillingAddress",
-        "comment": "✅ Custom resolver - looks up address by reference ID from shipping addresses array"
-      }
-    }
-  }
-}
-```
-
-**Custom resolver implementation:**
-
-```typescript
-const customResolvers = {
-  'custom.resolveBillingAddress': (data: any, config: any, helpers: any) => {
-    // 1. Get the reference ID
-    const billingRef = helpers.get(data, 'order.billing.addressRef');
-
-    // 2. Get all addresses
-    const addresses = helpers.ensureArray(
-      helpers.get(data, 'order.shipping.addresses.address')
-    );
-
-    // 3. Find matching address by ID
-    const billingAddress = addresses.find(addr => addr['@id'] === billingRef);
-
-    if (!billingAddress) {
-      helpers.logger.warn(`Billing address reference '${billingRef}' not found`);
-      return null;
-    }
-
-    // 4. Transform to target format
-    return {
-      street: billingAddress.street,
-      city: billingAddress.city,
-      country: billingAddress.country || config.defaultCountry
-    };
-  }
-};
-```
-
-**Real-world use cases:**
-- **E-commerce:** Product variant → product details, category ID → category path
-- **Shipping:** Package → shipment lookup, carrier code → carrier details
-- **Inventory:** Location ref → location details, warehouse ID → warehouse name
-- **Any system with linked data**
-
-## Dot-Notation for Nested Objects
-
-Create nested GraphQL objects using dot notation in field names:
-
-```json
-{
-  "customer.id": { "source": "customerId" },
-  "customer.email": { "source": "email" },
-  "customer.address.street": { "source": "billingAddress.street" },
-  "customer.address.city": { "source": "billingAddress.city" }
-}
-```
-
-**SDK automatically converts to:**
-```json
-{
-  "customer": {
-    "id": "123",
-    "email": "customer@example.com",
-    "address": {
-      "street": "123 Main St",
-      "city": "Springfield"
-    }
-  }
-}
-```
-
-**Benefits:**
-- ✅ Flatter mapping configuration (easier to read)
-- ✅ Works with any GraphQL schema
-- ✅ Automatic nesting (no manual object construction)
-
-## XPath-Like Filtering
-
-Filter arrays by attribute values:
-
-```json
-{
-  "specialAttribute": {
-    "source": "order.customAttributes.attribute[attributeId=deliveryDate]"
-  }
-}
-```
-
-**Example use cases:**
-- Extract specific custom attribute: `attribute[id=loyaltyPoints]`
-- Filter by type: `item[type=physical]`
-- Select by status: `shipment[status=pending]`
-
-**XML Example:**
-```xml
-<order>
-  <customAttributes>
-    <attribute attributeId="deliveryDate">2025-10-25</attribute>
-    <attribute attributeId="giftMessage">Happy Birthday!</attribute>
-    <attribute attributeId="loyaltyPoints">500</attribute>
-  </customAttributes>
-</order>
-```
-
-**Mapping:**
-```json
-{
-  "deliveryDate": {
-    "source": "order.customAttributes.attribute[attributeId=deliveryDate]"
-  },
-  "giftMessage": {
-    "source": "order.customAttributes.attribute[attributeId=giftMessage]"
-  },
-  "loyaltyPoints": {
-    "source": "order.customAttributes.attribute[attributeId=loyaltyPoints]",
-    "resolver": "sdk.parseInt"
-  }
-}
-```
-
-## Embedded XML/JSON (Nodes Pattern)
-
-Extract and parse nested or HTML-encoded data:
-
-✅ **Validated against schema:** [`docs/schema/fluent-commerce-schema.json`](../../../../04-REFERENCE/schema/fluent-commerce-schema.json) → `Mutation.createOrder`
-
-**Business Context:** Many systems store custom data as HTML-encoded XML strings in custom attributes.
-
-```json
-{
-  "version": "1.0",
-  "mutation": "createOrder",
-  "sourceFormat": "xml",
-  "comment": "✅ Extract and parse HTML-encoded metadata from SFCC custom attributes",
-  "nodes": {
-    "metadata": {
-      "extract": "order.customData.metadata",
-      "unescape": true,
-      "parse": "xml",
-      "comment": "Extract HTML-encoded XML from custom field (common in e-commerce platforms)"
-    }
-  },
-  "arguments": {
-    "input": {
-      "ref": {
-        "source": "order@orderNo",
-        "required": true,
-        "comment": "✅ Maps to CreateOrderInput.ref (String! required)"
-      },
-      "type": {
-        "value": "STANDARD",
-        "required": true,
-        "comment": "✅ Maps to CreateOrderInput.type (OrderType! required)"
-      },
-      "retailer": {
-        "fields": {
-          "id": {
-            "value": "1",
-            "comment": "✅ Maps to CreateOrderInput.retailer.id (ID! required)"
-          }
-        }
-      },
-      "priority": {
-        "source": "$metadata.priority",
-        "comment": "✅ Maps to CreateOrderInput.attributes.priority (JSON optional) - Extracted from parsed metadata node"
-      },
-      "tags": {
-        "_array": true,
-        "source": "$metadata.tags.tag",
-        "comment": "✅ Maps to CreateOrderInput.attributes.tags (JSON optional) - Array from metadata"
-      }
-    }
-  }
-}
-```
-
-**Real-world examples:**
-- E-commerce platforms with custom attributes (encoded JSON/XML)
-- Older systems with serialized data
-- API responses with nested structures
-- Any system where data is stored as strings
-
-**See also:** [Nodes Pattern Guide](./graphql-mutation-mapping-07-array-handling.md) for complete documentation.
-
-## Pattern: Multi-Level Array Mapping
-
-**Challenge:** Mapping orders with nested line items and fulfillments
-
-**XML Source:**
-```xml
-<orders>
-  <order order-no="ORD-1">
-    <items>
-      <item item-id="ITEM-1">
-        <fulfillments>
-          <fulfillment fulfillment-id="FF-1">
-            <quantity>5</quantity>
-          </fulfillment>
-          <fulfillment fulfillment-id="FF-2">
-            <quantity>3</quantity>
-          </fulfillment>
-        </fulfillments>
-      </item>
-    </items>
-  </order>
-</orders>
-```
-
-**Mapping:**
-```json
-{
-  "orders": {
-    "_array": true,
-    "source": "orders.order",
-    "fields": {
-      "ref": { "source": "$.@order-no" },
-      "items": {
-        "_array": true,
-        "source": "$.items.item",
-        "fields": {
-          "ref": { "source": "$.@item-id" },
-          "fulfillments": {
-            "_array": true,
-            "source": "$.fulfillments.fulfillment",
-            "fields": {
-              "id": { "source": "$.@fulfillment-id" },
-              "quantity": {
-                "source": "$.quantity",
-                "resolver": "sdk.parseInt"
-              }
-            }
-          }
-        }
-      }
-    }
-  }
-}
-```
-
-## Pattern: Conditional Field Mapping
-
-**Challenge:** Include field only if source data meets condition
-
-**Custom Resolver:**
-```typescript
-'custom.conditionalDiscount': (value, data, config, helpers) => {
-  const totalPrice = helpers.parseFloatSafe(
-    helpers.get(data, 'order.total'),
-    0
-  );
-
-  const isPremiumCustomer = helpers.get(data, 'customer.tier') === 'PREMIUM';
-
-  // Only apply discount for premium customers with orders > $100
-  if (isPremiumCustomer && totalPrice > 100) {
-    return totalPrice * 0.1; // 10% discount
-  }
-
-  return 0;
-}
-```
-
-**Mapping:**
-```json
-{
-  "discount": {
-    "resolver": "custom.conditionalDiscount"
-  }
-}
-```
-
-## Pattern: Data Aggregation
-
-**Challenge:** Aggregate data from multiple sources
-
-**Custom Resolver:**
-```typescript
-'custom.aggregateInventory': (value, data, config, helpers) => {
-  const locations = helpers.ensureArray(
-    helpers.get(data, 'inventory.locations.location')
-  );
-
-  // Sum quantities across all locations
-  const totalQuantity = helpers.sum(
-    locations.map(loc => ({
-      qty: helpers.parseIntSafe(loc.quantity, 0)
-    })),
-    'qty'
-  );
-
-  // Group by status
-  const byStatus = helpers.groupBy(locations, 'status');
-
-  return {
-    totalQuantity,
-    availableQuantity: helpers.sum(byStatus.AVAILABLE || [], 'quantity'),
-    reservedQuantity: helpers.sum(byStatus.RESERVED || [], 'quantity')
-  };
-}
-```
-
----
-
-## Navigation
-
-[← Previous: Custom Resolvers](./graphql-mutation-mapping-08-custom-resolvers.md) | [Back to Guide](../graphql-mutation-mapping-readme.md) | [Next: Hooks and Variables →](./graphql-mutation-mapping-10-hooks-and-variables.md)
-
-## Related Documentation
-
-- [Module 08: Custom Resolvers](./graphql-mutation-mapping-08-custom-resolvers.md) - Custom transformation functions
-- [Module 06: Path Syntax](./graphql-mutation-mapping-06-path-syntax.md) - Path resolution patterns
-- [Module 07: Array Handling](./graphql-mutation-mapping-07-array-handling.md) - Array mapping basics
-- [Nodes Pattern Guide](./graphql-mutation-mapping-07-array-handling.md) - Embedded data extraction
+# Advanced Patterns
+
+[← Back to GraphQL Mutation Mapping Guide](../graphql-mutation-mapping-readme.md)
+
+**Module 9 of 13** | **Level**: Advanced | **Time**: 20 minutes
+
+---
+
+## Advanced Mapping Patterns
+
+This module covers advanced techniques for handling complex data transformations and mapping scenarios.
+
+## Relative Paths in Arrays
+
+When mapping array items, use `$.` prefix for paths relative to the current item:
+
+```json
+{
+  "items": {
+    "source": "order.lineItems.item",
+    "isArray": true,
+    "fields": {
+      "ref": { "source": "$.sku" },                    // Relative to current item
+      "quantity": { "source": "$.quantity" },          // Relative to current item
+      "currency": { "source": "order.currency" }       // Absolute path from root
+    }
+  }
+}
+```
+
+**Benefits:**
+- ✅ Clear and concise (avoids repeating full path)
+- ✅ Works with nested arrays
+- ✅ Easy to read and maintain
+
+**Example with nested arrays:**
+```json
+{
+  "orders": {
+    "source": "data.orders.order",
+    "isArray": true,
+    "fields": {
+      "ref": { "source": "$.orderNumber" },
+      "items": {
+        "source": "$.lineItems.item",
+        "isArray": true,
+        "fields": {
+          "sku": { "source": "$.productId" },          // Relative to item
+          "orderRef": { "source": "data.orders.order.orderNumber" }  // Absolute from root
+        }
+      }
+    }
+  }
+}
+```
+
+## Reference Resolution Pattern
+
+Resolve references between entities using custom resolvers:
+
+**Example: Billing address references shipping address by ID**
+
+```xml
+<order order-no="ORD-123">
+  <shipping>
+    <addresses>
+      <address id="addr-123">
+        <street>123 Main St</street>
+        <city>Springfield</city>
+      </address>
+      <address id="addr-456">
+        <street>456 Oak Ave</street>
+        <city>Rivertown</city>
+      </address>
+    </addresses>
+  </shipping>
+  <billing>
+    <addressRef>addr-123</addressRef>
+  </billing>
+</order>
+```
+
+**Mapping with custom resolver:**
+
+✅ **Validated against schema:** [`docs/schema/fluent-commerce-schema.json`](../../../../04-REFERENCE/schema/fluent-commerce-schema.json) → `Mutation.createOrder`
+
+```json
+{
+  "version": "1.0",
+  "mutation": "createOrder",
+  "sourceFormat": "xml",
+  "comment": "✅ Reference resolution pattern for billing address lookup",
+  "arguments": {
+    "input": {
+      "ref": {
+        "source": "order@order-no",
+        "required": true,
+        "comment": "✅ Maps to CreateOrderInput.ref (String! required)"
+      },
+      "type": {
+        "value": "STANDARD",
+        "required": true,
+        "comment": "✅ Maps to CreateOrderInput.type (OrderType! required)"
+      },
+      "retailer": {
+        "fields": {
+          "id": {
+            "value": "1",
+            "comment": "✅ Maps to CreateOrderInput.retailer.id (ID! required)"
+          }
+        }
+      },
+      "billingAddress": {
+        "resolver": "custom.resolveBillingAddress",
+        "comment": "✅ Custom resolver - looks up address by reference ID from shipping addresses array"
+      }
+    }
+  }
+}
+```
+
+**Custom resolver implementation:**
+
+```typescript
+const customResolvers = {
+  'custom.resolveBillingAddress': (data: any, config: any, helpers: any) => {
+    // 1. Get the reference ID
+    const billingRef = helpers.get(data, 'order.billing.addressRef');
+
+    // 2. Get all addresses
+    const addresses = helpers.ensureArray(
+      helpers.get(data, 'order.shipping.addresses.address')
+    );
+
+    // 3. Find matching address by ID
+    const billingAddress = addresses.find(addr => addr['@id'] === billingRef);
+
+    if (!billingAddress) {
+      helpers.logger.warn(`Billing address reference '${billingRef}' not found`);
+      return null;
+    }
+
+    // 4. Transform to target format
+    return {
+      street: billingAddress.street,
+      city: billingAddress.city,
+      country: billingAddress.country || config.defaultCountry
+    };
+  }
+};
+```
+
+**Real-world use cases:**
+- **E-commerce:** Product variant → product details, category ID → category path
+- **Shipping:** Package → shipment lookup, carrier code → carrier details
+- **Inventory:** Location ref → location details, warehouse ID → warehouse name
+- **Any system with linked data**
+
+## Dot-Notation for Nested Objects
+
+Create nested GraphQL objects using dot notation in field names:
+
+```json
+{
+  "customer.id": { "source": "customerId" },
+  "customer.email": { "source": "email" },
+  "customer.address.street": { "source": "billingAddress.street" },
+  "customer.address.city": { "source": "billingAddress.city" }
+}
+```
+
+**SDK automatically converts to:**
+```json
+{
+  "customer": {
+    "id": "123",
+    "email": "customer@example.com",
+    "address": {
+      "street": "123 Main St",
+      "city": "Springfield"
+    }
+  }
+}
+```
+
+**Benefits:**
+- ✅ Flatter mapping configuration (easier to read)
+- ✅ Works with any GraphQL schema
+- ✅ Automatic nesting (no manual object construction)
+
+## XPath-Like Filtering
+
+Filter arrays by attribute values:
+
+```json
+{
+  "specialAttribute": {
+    "source": "order.customAttributes.attribute[attributeId=deliveryDate]"
+  }
+}
+```
+
+**Example use cases:**
+- Extract specific custom attribute: `attribute[id=loyaltyPoints]`
+- Filter by type: `item[type=physical]`
+- Select by status: `shipment[status=pending]`
+
+**XML Example:**
+```xml
+<order>
+  <customAttributes>
+    <attribute attributeId="deliveryDate">2025-10-25</attribute>
+    <attribute attributeId="giftMessage">Happy Birthday!</attribute>
+    <attribute attributeId="loyaltyPoints">500</attribute>
+  </customAttributes>
+</order>
+```
+
+**Mapping:**
+```json
+{
+  "deliveryDate": {
+    "source": "order.customAttributes.attribute[attributeId=deliveryDate]"
+  },
+  "giftMessage": {
+    "source": "order.customAttributes.attribute[attributeId=giftMessage]"
+  },
+  "loyaltyPoints": {
+    "source": "order.customAttributes.attribute[attributeId=loyaltyPoints]",
+    "resolver": "sdk.parseInt"
+  }
+}
+```
+
+## Embedded XML/JSON (Nodes Pattern)
+
+Extract and parse nested or HTML-encoded data:
+
+✅ **Validated against schema:** [`docs/schema/fluent-commerce-schema.json`](../../../../04-REFERENCE/schema/fluent-commerce-schema.json) → `Mutation.createOrder`
+
+**Business Context:** Many systems store custom data as HTML-encoded XML strings in custom attributes.
+
+```json
+{
+  "version": "1.0",
+  "mutation": "createOrder",
+  "sourceFormat": "xml",
+  "comment": "✅ Extract and parse HTML-encoded metadata from SFCC custom attributes",
+  "nodes": {
+    "metadata": {
+      "extract": "order.customData.metadata",
+      "unescape": true,
+      "parse": "xml",
+      "comment": "Extract HTML-encoded XML from custom field (common in e-commerce platforms)"
+    }
+  },
+  "arguments": {
+    "input": {
+      "ref": {
+        "source": "order@orderNo",
+        "required": true,
+        "comment": "✅ Maps to CreateOrderInput.ref (String! required)"
+      },
+      "type": {
+        "value": "STANDARD",
+        "required": true,
+        "comment": "✅ Maps to CreateOrderInput.type (OrderType! required)"
+      },
+      "retailer": {
+        "fields": {
+          "id": {
+            "value": "1",
+            "comment": "✅ Maps to CreateOrderInput.retailer.id (ID! required)"
+          }
+        }
+      },
+      "priority": {
+        "source": "$metadata.priority",
+        "comment": "✅ Maps to CreateOrderInput.attributes.priority (JSON optional) - Extracted from parsed metadata node"
+      },
+      "tags": {
+        "_array": true,
+        "source": "$metadata.tags.tag",
+        "comment": "✅ Maps to CreateOrderInput.attributes.tags (JSON optional) - Array from metadata"
+      }
+    }
+  }
+}
+```
+
+**Real-world examples:**
+- E-commerce platforms with custom attributes (encoded JSON/XML)
+- Older systems with serialized data
+- API responses with nested structures
+- Any system where data is stored as strings
+
+**See also:** [Nodes Pattern Guide](./graphql-mutation-mapping-07-array-handling.md) for complete documentation.
+
+## Pattern: Multi-Level Array Mapping
+
+**Challenge:** Mapping orders with nested line items and fulfillments
+
+**XML Source:**
+```xml
+<orders>
+  <order order-no="ORD-1">
+    <items>
+      <item item-id="ITEM-1">
+        <fulfillments>
+          <fulfillment fulfillment-id="FF-1">
+            <quantity>5</quantity>
+          </fulfillment>
+          <fulfillment fulfillment-id="FF-2">
+            <quantity>3</quantity>
+          </fulfillment>
+        </fulfillments>
+      </item>
+    </items>
+  </order>
+</orders>
+```
+
+**Mapping:**
+```json
+{
+  "orders": {
+    "_array": true,
+    "source": "orders.order",
+    "fields": {
+      "ref": { "source": "$.@order-no" },
+      "items": {
+        "_array": true,
+        "source": "$.items.item",
+        "fields": {
+          "ref": { "source": "$.@item-id" },
+          "fulfillments": {
+            "_array": true,
+            "source": "$.fulfillments.fulfillment",
+            "fields": {
+              "id": { "source": "$.@fulfillment-id" },
+              "quantity": {
+                "source": "$.quantity",
+                "resolver": "sdk.parseInt"
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Pattern: Conditional Field Mapping
+
+**Challenge:** Include field only if source data meets condition
+
+**Custom Resolver:**
+```typescript
+'custom.conditionalDiscount': (value, data, config, helpers) => {
+  const totalPrice = helpers.parseFloatSafe(
+    helpers.get(data, 'order.total'),
+    0
+  );
+
+  const isPremiumCustomer = helpers.get(data, 'customer.tier') === 'PREMIUM';
+
+  // Only apply discount for premium customers with orders > $100
+  if (isPremiumCustomer && totalPrice > 100) {
+    return totalPrice * 0.1; // 10% discount
+  }
+
+  return 0;
+}
+```
+
+**Mapping:**
+```json
+{
+  "discount": {
+    "resolver": "custom.conditionalDiscount"
+  }
+}
+```
+
+## Pattern: Data Aggregation
+
+**Challenge:** Aggregate data from multiple sources
+
+**Custom Resolver:**
+```typescript
+'custom.aggregateInventory': (value, data, config, helpers) => {
+  const locations = helpers.ensureArray(
+    helpers.get(data, 'inventory.locations.location')
+  );
+
+  // Sum quantities across all locations
+  const totalQuantity = helpers.sum(
+    locations.map(loc => ({
+      qty: helpers.parseIntSafe(loc.quantity, 0)
+    })),
+    'qty'
+  );
+
+  // Group by status
+  const byStatus = helpers.groupBy(locations, 'status');
+
+  return {
+    totalQuantity,
+    availableQuantity: helpers.sum(byStatus.AVAILABLE || [], 'quantity'),
+    reservedQuantity: helpers.sum(byStatus.RESERVED || [], 'quantity')
+  };
+}
+```
+
+---
+
+## Navigation
+
+[← Previous: Custom Resolvers](./graphql-mutation-mapping-08-custom-resolvers.md) | [Back to Guide](../graphql-mutation-mapping-readme.md) | [Next: Hooks and Variables →](./graphql-mutation-mapping-10-hooks-and-variables.md)
+
+## Related Documentation
+
+- [Module 08: Custom Resolvers](./graphql-mutation-mapping-08-custom-resolvers.md) - Custom transformation functions
+- [Module 06: Path Syntax](./graphql-mutation-mapping-06-path-syntax.md) - Path resolution patterns
+- [Module 07: Array Handling](./graphql-mutation-mapping-07-array-handling.md) - Array mapping basics
+- [Nodes Pattern Guide](./graphql-mutation-mapping-07-array-handling.md) - Embedded data extraction