@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

package/docs/02-CORE-GUIDES/mapping/graphql-mutation-mapping/modules/graphql-mutation-mapping-01-introduction.md

@@ -1,222 +1,222 @@
-# Introduction to GraphQL Mutation Mapping
-
-[← Back to GraphQL Mutation Mapping Guide](../graphql-mutation-mapping-readme.md)
-
-**Module 1 of 13** | **Level**: Beginner | **Time**: 10 minutes
-
----
-
-## Overview
-
-The GraphQL Mutation Mapping system provides a **generic**, **schema-driven**, **format-agnostic** way to transform **any** XML/JSON data into **any** GraphQL mutation inputs with full validation and type safety.
-
----
-
-## 🌟 Universal System - Not Just for Orders!
-
-**This system works for:**
-
-- ✅ **Any GraphQL mutation** (createOrder, updateInventory, createCustomer, etc.)
-- ✅ **Any XML source** (SFCC, Magento, SAP, custom XML feeds)
-- ✅ **Any JSON source** (Shopify, REST APIs, webhooks, database exports)
-- ✅ **Any target system** with a GraphQL API (not just Fluent Commerce)
-
-**SFCC order examples** are used in this guide for demonstration only. The same principles apply to **all** integrations.
-
----
-
-## Key Features
-
-- ✅ **Universal**: Works with **ANY** GraphQL mutation on **ANY** system
-- ✅ **Schema-Driven**: Validate mappings against your GraphQL schema using CLI tools
-- ✅ **Format-Agnostic**: Same mapping structure for XML and JSON (only paths differ)
-- ✅ **Source-Agnostic**: XML from SFCC, Magento, SAP, or JSON from Shopify, REST APIs
-- ✅ **Type-Safe**: Detects type mismatches, required fields, and array validation
-- ✅ **Flexible**: Supports nested objects, arrays, transformations, and custom hooks
-- ✅ **Debuggable**: Clear error messages with field paths and suggestions
-  See Module 03 for introspection/validation workflow (pre-deployment CLI).
-- ✅ **Operation Names**: Supports named operations for debugging
-
----
-
-## How It Works
-
-```
-XML/JSON Source Data
-        ↓
-Path Resolver (XML/JSON)
-        ↓
-Field Mapping
-        ↓
-Custom Hooks (Optional)
-        ↓
-GraphQL Mutation Payload { query, variables }
-```
-
----
-
-## Real-World Use Cases
-
-### E-Commerce Order Integration
-
-- **SFCC → Fluent Commerce**: XML orders from Salesforce Commerce Cloud
-- **Shopify → Fluent Commerce**: JSON webhooks from Shopify storefront
-- **Magento → Fluent Commerce**: XML exports from Magento platform
-
-### Inventory Management
-
-- **Product Catalog Sync**: XML/JSON product feeds → updateInventory mutations
-- **Stock Updates**: CSV → JSON → GraphQL batch inventory updates
-
-### Customer Management
-
-- **CRM Integration**: Customer data from Salesforce → createCustomer mutations
-- **Loyalty Programs**: Membership data → customer attribute updates
-
-### Master Data Management
-
-- **Location Data**: Store/warehouse master data → createLocation mutations
-- **Product Catalog**: Product master data → createProduct/updateProduct mutations
-
----
-
-## What Makes It Universal?
-
-### 1. Format-Agnostic Mapping
-
-**Same mapping structure for XML and JSON** - only the path syntax differs:
-
-**XML Path**: `order@order-no`
-**JSON Path**: `order.orderNo`
-
-**Same field configuration**:
-
-```json
-{
-  "ref": {
-    "source": "order@order-no", // or "order.orderNo" for JSON
-    "required": true
-  }
-}
-```
-
-### 2. Schema-Driven Validation (via CLI)
-
-Validate mappings against your GraphQL schema before deployment:
-
-```bash
-npx fc-connect introspect-schema --endpoint https://YOUR_API.com/graphql --output schema.json
-npx fc-connect validate-schema --mapping mapping.json --schema schema.json
-```
-
-See Module 03 for full validation and coverage workflow.
-
-### 3. Mutation-Agnostic
-
-**Works with ANY GraphQL mutation**:
-
-```json
-{
-  "mutation": "createOrder", // or "updateInventory"
-  "mutation": "createCustomer", // or "updateProduct"
-  "mutation": "createLocation", // or "updatePricing"
-  "mutation": "ANY_MUTATION" // ANY mutation in your schema!
-}
-```
-
----
-
-## Key Concepts
-
-### Mapping Configuration
-
-A **JSON configuration file** that defines:
-
-- **Source format** (XML or JSON)
-- **Target mutation** (any GraphQL mutation)
-- **Field mappings** (source paths → mutation arguments)
-- **Transformations** (custom resolvers, built-in helpers)
-- **Validation rules** (required fields, type constraints)
-
-### Path Resolvers
-
-Automatically extract data from source:
-
-- **XMLPathResolver**: Handles XML attributes, elements, arrays
-- **JSONPathResolver**: Handles JSON properties, nested objects, arrays
-
-### CLI Validation Tools
-
-Use CLI tools to validate mappings before deployment:
-
-- `introspect-schema`: Download GraphQL schema to file
-- `validate-schema`: Validate mapping against schema
-- `analyze-coverage`: Check which fields are mapped
-- `generate-mutation-mapping`: Generate starter configs
-
-See Module 03 for details.
-
-### Custom Resolvers
-
-Add custom transformation logic:
-
-- Simple transformations (parseFloat, uppercase)
-- Complex business logic (calculate totals, lookup references)
-- Async operations (API calls, database lookups)
-
----
-
-## When to Use This System
-
-### ✅ Use GraphQL Mutation Mapper When:
-
-- You need to transform **XML/JSON → GraphQL mutations**
-- Your source data structure differs from GraphQL schema
-- You need **schema validation** to catch errors early
-- You have **complex transformation** logic
-- You need **type-safe** transformations
-- You want **reusable** mapping configurations
-
-### ❌ Use Universal Mapper When:
-
-- You need to transform **CSV → JSON** or **JSON → JSON**
-- Your source data is tabular (rows and columns)
-- You don't need GraphQL schema validation
-- You need **simpler** field-to-field mapping
-
-**See**: [Universal Mapping Guide](../../mapping-readme.md) for CSV/JSON transformations
-
----
-
-## Examples in This Guide
-
-All examples use **SFCC (Salesforce Commerce Cloud) order data** to demonstrate patterns, but the same techniques apply to:
-
-- **Inventory feeds** from warehouse management systems
-- **Product catalogs** from PIM systems
-- **Customer data** from CRM systems
-- **Order data** from any e-commerce platform
-- **ANY data** from ANY system with XML/JSON output
-
----
-
-## Next Steps
-
-| **Next Module**                                       | **Description**                               |
-| ----------------------------------------------------- | --------------------------------------------- |
-| [02. Quick Start](../../../auto-pagination/modules/auto-pagination-02-quick-start.md)                | Installation, basic example, and usage        |
-| [03. Schema Validation](./graphql-mutation-mapping-03-schema-validation.md) ⚠️ | **CRITICAL** - Schema validation requirements |
-| [04. Mapping Patterns](./graphql-mutation-mapping-04-mapping-patterns.md)      | Two mapping patterns: map() vs mapWithNodes() |
-
----
-
-## Related Documentation
-
-- **[Universal Mapping Guide](../../mapping-readme.md)** - For CSV/JSON transformations
-- **[XML Parser Guide](../../../parsers/modules/02-core-guides-parsers-04-xml-parser.md)** - XML parsing details
-- **[JSON Parser Guide](../../../parsers/modules/02-core-guides-parsers-03-json-parser.md)** - JSON parsing details
-- **[API Reference](../../../api-reference/api-reference-readme.md)** - Complete API documentation
-
----
-
-[← Back to Guide](../graphql-mutation-mapping-readme.md) | [Next: Quick Start →](../../../auto-pagination/modules/auto-pagination-02-quick-start.md)
+# Introduction to GraphQL Mutation Mapping
+
+[← Back to GraphQL Mutation Mapping Guide](../graphql-mutation-mapping-readme.md)
+
+**Module 1 of 13** | **Level**: Beginner | **Time**: 10 minutes
+
+---
+
+## Overview
+
+The GraphQL Mutation Mapping system provides a **generic**, **schema-driven**, **format-agnostic** way to transform **any** XML/JSON data into **any** GraphQL mutation inputs with full validation and type safety.
+
+---
+
+## 🌟 Universal System - Not Just for Orders!
+
+**This system works for:**
+
+- ✅ **Any GraphQL mutation** (createOrder, updateInventory, createCustomer, etc.)
+- ✅ **Any XML source** (SFCC, Magento, SAP, custom XML feeds)
+- ✅ **Any JSON source** (Shopify, REST APIs, webhooks, database exports)
+- ✅ **Any target system** with a GraphQL API (not just Fluent Commerce)
+
+**SFCC order examples** are used in this guide for demonstration only. The same principles apply to **all** integrations.
+
+---
+
+## Key Features
+
+- ✅ **Universal**: Works with **ANY** GraphQL mutation on **ANY** system
+- ✅ **Schema-Driven**: Validate mappings against your GraphQL schema using CLI tools
+- ✅ **Format-Agnostic**: Same mapping structure for XML and JSON (only paths differ)
+- ✅ **Source-Agnostic**: XML from SFCC, Magento, SAP, or JSON from Shopify, REST APIs
+- ✅ **Type-Safe**: Detects type mismatches, required fields, and array validation
+- ✅ **Flexible**: Supports nested objects, arrays, transformations, and custom hooks
+- ✅ **Debuggable**: Clear error messages with field paths and suggestions
+  See Module 03 for introspection/validation workflow (pre-deployment CLI).
+- ✅ **Operation Names**: Supports named operations for debugging
+
+---
+
+## How It Works
+
+```
+XML/JSON Source Data
+        ↓
+Path Resolver (XML/JSON)
+        ↓
+Field Mapping
+        ↓
+Custom Hooks (Optional)
+        ↓
+GraphQL Mutation Payload { query, variables }
+```
+
+---
+
+## Real-World Use Cases
+
+### E-Commerce Order Integration
+
+- **SFCC → Fluent Commerce**: XML orders from Salesforce Commerce Cloud
+- **Shopify → Fluent Commerce**: JSON webhooks from Shopify storefront
+- **Magento → Fluent Commerce**: XML exports from Magento platform
+
+### Inventory Management
+
+- **Product Catalog Sync**: XML/JSON product feeds → updateInventory mutations
+- **Stock Updates**: CSV → JSON → GraphQL batch inventory updates
+
+### Customer Management
+
+- **CRM Integration**: Customer data from Salesforce → createCustomer mutations
+- **Loyalty Programs**: Membership data → customer attribute updates
+
+### Master Data Management
+
+- **Location Data**: Store/warehouse master data → createLocation mutations
+- **Product Catalog**: Product master data → createProduct/updateProduct mutations
+
+---
+
+## What Makes It Universal?
+
+### 1. Format-Agnostic Mapping
+
+**Same mapping structure for XML and JSON** - only the path syntax differs:
+
+**XML Path**: `order@order-no`
+**JSON Path**: `order.orderNo`
+
+**Same field configuration**:
+
+```json
+{
+  "ref": {
+    "source": "order@order-no", // or "order.orderNo" for JSON
+    "required": true
+  }
+}
+```
+
+### 2. Schema-Driven Validation (via CLI)
+
+Validate mappings against your GraphQL schema before deployment:
+
+```bash
+npx fc-connect introspect-schema --endpoint https://YOUR_API.com/graphql --output schema.json
+npx fc-connect validate-schema --mapping mapping.json --schema schema.json
+```
+
+See Module 03 for full validation and coverage workflow.
+
+### 3. Mutation-Agnostic
+
+**Works with ANY GraphQL mutation**:
+
+```json
+{
+  "mutation": "createOrder", // or "updateInventory"
+  "mutation": "createCustomer", // or "updateProduct"
+  "mutation": "createLocation", // or "updatePricing"
+  "mutation": "ANY_MUTATION" // ANY mutation in your schema!
+}
+```
+
+---
+
+## Key Concepts
+
+### Mapping Configuration
+
+A **JSON configuration file** that defines:
+
+- **Source format** (XML or JSON)
+- **Target mutation** (any GraphQL mutation)
+- **Field mappings** (source paths → mutation arguments)
+- **Transformations** (custom resolvers, built-in helpers)
+- **Validation rules** (required fields, type constraints)
+
+### Path Resolvers
+
+Automatically extract data from source:
+
+- **XMLPathResolver**: Handles XML attributes, elements, arrays
+- **JSONPathResolver**: Handles JSON properties, nested objects, arrays
+
+### CLI Validation Tools
+
+Use CLI tools to validate mappings before deployment:
+
+- `introspect-schema`: Download GraphQL schema to file
+- `validate-schema`: Validate mapping against schema
+- `analyze-coverage`: Check which fields are mapped
+- `generate-mutation-mapping`: Generate starter configs
+
+See Module 03 for details.
+
+### Custom Resolvers
+
+Add custom transformation logic:
+
+- Simple transformations (parseFloat, uppercase)
+- Complex business logic (calculate totals, lookup references)
+- Async operations (API calls, database lookups)
+
+---
+
+## When to Use This System
+
+### ✅ Use GraphQL Mutation Mapper When:
+
+- You need to transform **XML/JSON → GraphQL mutations**
+- Your source data structure differs from GraphQL schema
+- You need **schema validation** to catch errors early
+- You have **complex transformation** logic
+- You need **type-safe** transformations
+- You want **reusable** mapping configurations
+
+### ❌ Use Universal Mapper When:
+
+- You need to transform **CSV → JSON** or **JSON → JSON**
+- Your source data is tabular (rows and columns)
+- You don't need GraphQL schema validation
+- You need **simpler** field-to-field mapping
+
+**See**: [Universal Mapping Guide](../../mapping-readme.md) for CSV/JSON transformations
+
+---
+
+## Examples in This Guide
+
+All examples use **SFCC (Salesforce Commerce Cloud) order data** to demonstrate patterns, but the same techniques apply to:
+
+- **Inventory feeds** from warehouse management systems
+- **Product catalogs** from PIM systems
+- **Customer data** from CRM systems
+- **Order data** from any e-commerce platform
+- **ANY data** from ANY system with XML/JSON output
+
+---
+
+## Next Steps
+
+| **Next Module**                                       | **Description**                               |
+| ----------------------------------------------------- | --------------------------------------------- |
+| [02. Quick Start](../../../auto-pagination/modules/auto-pagination-02-quick-start.md)                | Installation, basic example, and usage        |
+| [03. Schema Validation](./graphql-mutation-mapping-03-schema-validation.md) ⚠️ | **CRITICAL** - Schema validation requirements |
+| [04. Mapping Patterns](./graphql-mutation-mapping-04-mapping-patterns.md)      | Two mapping patterns: map() vs mapWithNodes() |
+
+---
+
+## Related Documentation
+
+- **[Universal Mapping Guide](../../mapping-readme.md)** - For CSV/JSON transformations
+- **[XML Parser Guide](../../../parsers/modules/02-core-guides-parsers-04-xml-parser.md)** - XML parsing details
+- **[JSON Parser Guide](../../../parsers/modules/02-core-guides-parsers-03-json-parser.md)** - JSON parsing details
+- **[API Reference](../../../api-reference/api-reference-readme.md)** - Complete API documentation
+
+---
+
+[← Back to Guide](../graphql-mutation-mapping-readme.md) | [Next: Quick Start →](../../../auto-pagination/modules/auto-pagination-02-quick-start.md)