@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/02-CORE-GUIDES/mapping/modules/mapping-04-use-cases.md

@@ -1,891 +1,891 @@
-# Module 4: Use Cases
-
-**Real-world transformation scenarios**
-
-**Level:** Intermediate
-**Time:** 45 minutes
-**Prerequisites:** [Module 3: Schema Validation](./mapping-03-schema-validation.md)
-
----
-
-## Learning Objectives
-
-After completing this module, you will:
-
-- ✅ Implement CSV ingestion to Fluent Batch API
-- ✅ Transform XML to GraphQL mutations for order creation
-- ✅ Generate XML from Fluent data for external APIs
-- ✅ Extract GraphQL data to Parquet format
-- ✅ Understand real-world connector patterns
-
----
-
-## Use Case 1: CSV Ingestion → Fluent Batch API
-
-**Scenario:** Import inventory positions from CSV files to Fluent Commerce
-
-### Source Data
-
-**CSV Format:**
-
-```csv
-sku,location,quantity,status
-PROD-001,WAREHOUSE-A,100,active
-PROD-002,WAREHOUSE-A,50,reserved
-PROD-003,WAREHOUSE-B,200,active
-```
-
-### Mapping Configuration
-
-**File: `config/inventory-ingestion.json`**
-
-```json
-{
-  "direction": "ingest",
-  "sourceFormat": "csv",
-  "mutation": "upsertInventoryPosition",
-  "comment": "✅ Validated against schema: docs/schema/fluent-commerce-schema.json → Mutation.upsertInventoryPosition",
-
-  "fields": {
-    "ref": {
-      "source": "sku",
-      "required": true,
-      "comment": "✅ UpsertInventoryPositionInput.ref (String! required) - unique position identifier"
-    },
-    "productRef": {
-      "source": "sku",
-      "required": true,
-      "comment": "✅ UpsertInventoryPositionInput.productRef (String! required)"
-    },
-    "locationRef": {
-      "source": "location",
-      "required": true,
-      "comment": "✅ UpsertInventoryPositionInput.locationRef (String! required)"
-    },
-    "qty": {
-      "source": "quantity",
-      "resolver": "sdk.parseInt",
-      "required": true,
-      "comment": "✅ UpsertInventoryPositionInput.qty (Int! required)"
-    },
-    "status": {
-      "source": "status",
-      "resolver": "sdk.uppercase",
-      "defaultValue": "AVAILABLE",
-      "comment": "✅ UpsertInventoryPositionInput.status (String) - e.g., AVAILABLE, RESERVED"
-    }
-  }
-}
-```
-
-### Implementation
-
-```typescript
-import { UniversalMapper, CSVParserService, createClient } from '@fluentcommerce/fc-connect-sdk';
-import * as fs from 'fs';
-
-// Load mapping configuration
-const mappingConfig = JSON.parse(fs.readFileSync('./config/inventory-ingestion.json', 'utf-8'));
-
-// Load and parse CSV
-const csvContent = fs.readFileSync('./data/inventory.csv', 'utf-8');
-const parser = new CSVParserService();
-const records = await parser.parse(csvContent);
-
-// Create mapper
-const mapper = new UniversalMapper(mappingConfig);
-
-// Process each CSV row
-const batchEntities = [];
-for (const row of records) {
-  const result = await mapper.map(row);
-
-  if (result.success) {
-    batchEntities.push(result.data);
-  } else {
-    console.error('Mapping failed for row:', row);
-    console.error('Errors:', result.errors);
-  }
-}
-
-// Create Fluent client
-const client = await createClient({
-  config: {
-    baseUrl: process.env.FLUENT_BASE_URL!,
-    clientId: process.env.FLUENT_CLIENT_ID!,
-    clientSecret: process.env.FLUENT_CLIENT_SECRET!,
-    username: process.env.FLUENT_USERNAME!,
-    password: process.env.FLUENT_PASSWORD!,
-    retailerId: process.env.FLUENT_RETAILER_ID!,
-  },
-});
-
-// Create batch job
-const job = await client.createJob({
-  name: 'inventory-update',
-  retailerId: process.env.FLUENT_RETAILER_ID!,
-});
-
-// Send batch to Fluent Commerce
-await client.sendBatch(job.id, {
-  action: 'UPSERT',
-  entityType: 'INVENTORY',
-  source: 'CSV_IMPORT',
-  event: 'INVENTORY_UPDATE',
-  entities: batchEntities,
-});
-
-console.log(`✅ Successfully processed ${batchEntities.length} inventory positions`);
-```
-
-### Key Points
-
-- **Batch Processing:** Efficient for high-volume imports (1000s of records)
-- **Validation:** `required: true` catches missing data before API calls
-- **Resolvers:** `sdk.parseInt` ensures numeric types, `sdk.uppercase` normalizes status
-- **Error Handling:** Individual row failures don't stop the entire batch
-
-**Schema Reference:**
-
-- Mutation: `upsertInventoryPosition(input: UpsertInventoryPositionInput!): InventoryPosition`
-- See [`docs/schema/fluent-commerce-schema.json`](../../../04-REFERENCE/schema/fluent-commerce-schema.json) → `inputs.UpsertInventoryPositionInput`
-
----
-
-## Use Case 2: XML → GraphQL Mutation
-
-**Scenario:** Transform SFCC order XML to Fluent order mutation
-
-### Source Data
-
-**SFCC Order XML:**
-
-```xml
-<order id="ORD-123" type="standard">
-  <customer email="john@example.com" />
-  <total currency="USD">99.99</total>
-  <items>
-    <item id="ITEM-1" sku="PROD-001" qty="2" unitPrice="49.99" />
-  </items>
-</order>
-```
-
-### Mapping Configuration
-
-**File: `mappings/sfcc-order-to-fluent.json`**
-
-```json
-{
-  "direction": "ingest",
-  "sourceFormat": "xml",
-  "mutation": "createOrder",
-  "comment": "✅ Validated against schema: docs/schema/fluent-commerce-schema.json → Mutation.createOrder",
-
-  "fields": {
-    "ref": {
-      "source": "order@id",
-      "required": true,
-      "comment": "✅ CreateOrderInput.ref (String! required)"
-    },
-    "type": {
-      "source": "order@type",
-      "resolver": "custom.mapOrderType",
-      "comment": "✅ CreateOrderInput.type (OrderType! enum required) - maps 'standard' → 'STANDARD'"
-    },
-    "retailer": {
-      "fields": {
-        "id": {
-          "value": "1",
-          "comment": "✅ CreateOrderInput.retailer (RetailerInput! required)"
-        }
-      }
-    },
-    "customer": {
-      "fields": {
-        "email": {
-          "source": "order.customer@email",
-          "resolver": "sdk.lowercase",
-          "comment": "✅ CreateOrderInput.customer.email (String!)"
-        }
-      }
-    },
-    "totalPrice": {
-      "source": "order.total",
-      "resolver": "sdk.parseFloat",
-      "required": true,
-      "comment": "✅ CreateOrderInput.totalPrice (Float! required)"
-    },
-    "currency": {
-      "source": "order.total@currency",
-      "defaultValue": "USD",
-      "comment": "✅ CreateOrderInput.currency (String! required)"
-    },
-    "items": {
-      "source": "order.items.item",
-      "isArray": true,
-      "comment": "✅ CreateOrderInput.items ([OrderItemInput]! required)",
-      "fields": {
-        "ref": {
-          "source": "$.@id",
-          "required": true,
-          "comment": "✅ OrderItemInput.ref (String! required)"
-        },
-        "productRef": {
-          "source": "$.@sku",
-          "required": true,
-          "comment": "✅ OrderItemInput.productRef (String! required)"
-        },
-        "quantity": {
-          "source": "$.@qty",
-          "resolver": "sdk.parseInt",
-          "required": true,
-          "comment": "✅ OrderItemInput.quantity (Int! required)"
-        },
-        "price": {
-          "source": "$.@unitPrice",
-          "resolver": "sdk.parseFloat",
-          "required": true,
-          "comment": "✅ OrderItemInput.price (Float! required)"
-        },
-        "totalPrice": {
-          "resolver": "custom.calculateItemTotal",
-          "required": true,
-          "comment": "✅ OrderItemInput.totalPrice (Float! required) - calculated from qty * price"
-        },
-        "currency": {
-          "source": "order.total@currency",
-          "required": true,
-          "comment": "✅ OrderItemInput.currency (String! required)"
-        }
-      }
-    }
-  }
-}
-```
-
-### Implementation
-
-```typescript
-import { GraphQLMutationMapper } from '@fluentcommerce/fc-connect-sdk';
-
-// Load mapping configuration
-const mappingConfig = JSON.parse(fs.readFileSync('./mappings/sfcc-order-to-fluent.json', 'utf-8'));
-
-// Custom resolvers for business logic
-const customResolvers = {
-  'custom.mapOrderType': (value: string) => {
-    // Map SFCC order types to Fluent OrderType enum
-    const typeMap: Record<string, string> = {
-      standard: 'STANDARD',
-      express: 'HD',
-      'store-pickup': 'CC',
-    };
-    return typeMap[value.toLowerCase()] || 'STANDARD';
-  },
-
-  'custom.calculateItemTotal': (value: any, sourceData: any, config: any, helpers: any) => {
-    // Calculate item total from quantity and price
-    const qty = helpers.parseIntSafe(sourceData['@qty'], 0);
-    const price = helpers.parseFloatSafe(sourceData['@unitPrice'], 0);
-    return qty * price;
-  },
-};
-
-// Create mapper
-const mapper = new GraphQLMutationMapper(mappingConfig, logger, { fluentClient: client });
-
-// Parse XML and map to mutation
-const payload = await mapper.mapWithNodes(xmlData, customResolvers);
-
-if (payload.success) {
-  // ✅ Execute GraphQL mutation (mapper only generates payload, you must execute)
-  const result = await client.graphql(payload.data);
-  console.log('Order created:', result.data.createOrder.id);
-} else {
-  console.error('Mapping failed:', payload.errors);
-}
-```
-
-### Key Points
-
-- **XML Attributes:** Use `@` prefix for attributes (e.g., `order@id`)
-- **XML Nested Paths:** Use dot notation (e.g., `order.customer@email`)
-- **Array Context:** `$.@id` references current array item
-- **Custom Resolvers:** Business logic for type mapping and calculations
-- **GraphQL Execution:** `GraphQLMutationMapper` generates the mutation payload only - you must call `client.graphql(payload)` to execute
-
-**Schema Reference:**
-
-- Mutation: `createOrder(input: CreateOrderInput!): Order!`
-- See [`docs/schema/fluent-commerce-schema.json`](../../../04-REFERENCE/schema/fluent-commerce-schema.json) → `inputs.CreateOrderInput`
-
----
-
-## Use Case 3: Fluent → XML Generation (SFCC Order Detail)
-
-**Scenario:** Generate SFCC-compatible XML from Fluent order data
-
-### Source Data
-
-**Fluent GraphQL Response:**
-
-```json
-{
-  "order": {
-    "ref": "ORD-2025-001",
-    "customer": {
-      "id": "232",
-      "firstName": "Justin",
-      "lastName": "Kerr"
-    },
-    "items": [
-      {
-        "id": "ITEM-1",
-        "productRef": "SKU-WM-001",
-        "color": { "id": "9101", "value": "MULTI-COLOR" },
-        "quantity": 2,
-        "price": 49.99
-      }
-    ]
-  }
-}
-```
-
-### Mapping Configuration
-
-**File: `config/fluent-to-xml.json`**
-
-```json
-{
-  "direction": "extract",
-  "sourceFormat": "graphql",
-  "targetFormat": "xml",
-  "comment": "Generate SFCC-compatible XML from Fluent order data",
-
-  "fields": {
-    "@xmlns": {
-      "value": "http://api.gsicommerce.com/schema/checkout/1.0",
-      "comment": "XML namespace for SFCC"
-    },
-    "Customer": {
-      "fields": {
-        "@customerId": {
-          "source": "customer.id",
-          "comment": "Customer ID as XML attribute"
-        },
-        "Name": {
-          "fields": {
-            "FirstName": {
-              "source": "customer.firstName",
-              "comment": "Simple element with text content"
-            },
-            "LastName": {
-              "source": "customer.lastName"
-            }
-          }
-        }
-      }
-    },
-    "OrderLines": {
-      "fields": {
-        "OrderLine": {
-          "source": "items",
-          "isArray": true,
-          "comment": "Array of order line items",
-          "fields": {
-            "@itemId": {
-              "source": "id",
-              "comment": "Item ID as XML attribute"
-            },
-            "ProductRef": {
-              "source": "productRef",
-              "comment": "Simple element - no attributes"
-            },
-            "Color": {
-              "fields": {
-                "@id": {
-                  "source": "color.id",
-                  "comment": "Color ID as attribute"
-                },
-                "#text": {
-                  "source": "color.value",
-                  "comment": "⚠️ Use #text for text content when element has attributes"
-                }
-              }
-            },
-            "Quantity": {
-              "source": "quantity",
-              "resolver": "sdk.toString"
-            }
-          }
-        }
-      }
-    }
-  }
-}
-```
-
-### XML Output Patterns
-
-| Pattern              | JSON Mapping                       | XML Output                                 |
-| -------------------- | ---------------------------------- | ------------------------------------------ |
-| **Simple Element**   | `"ItemId": { "source": "id" }`     | `<ItemId>SKU001</ItemId>`                  |
-| **Attribute Only**   | `"@orderId": { "source": "ref" }`  | `<Order orderId="12345"/>`                 |
-| **Attribute + Text** | `"@id": {...}, "#text": {...}`     | `<Color id="9101">MULTI-COLOR</Color>`     |
-| **Nested Elements**  | `"fields": { "FirstName": {...} }` | `<Name><FirstName>John</FirstName></Name>` |
-| **Array**            | `"isArray": true, "fields": {...}` | Multiple `<OrderLine>` elements            |
-
-### Decision Tree - When to use `#text`
-
-```
-Does the XML element need attributes (@id, @status, etc.)?
-├─ NO  → Just use field name
-│        "ItemId": { "source": "id" }
-│        Result: <ItemId>SKU001</ItemId>
-│
-└─ YES → Does it ALSO have text content?
-    ├─ NO  → Just use @prefix
-    │        "@orderId": { "source": "ref" }
-    │        Result: <Order orderId="12345"/>
-    │
-    └─ YES → Use BOTH @prefix AND #text ⚠️
-             "@id": { "source": "color.id" }
-             "#text": { "source": "color.value" }
-             Result: <Color id="9101">MULTI-COLOR</Color>
-```
-
-### Common Mistake
-
-```json
-// ❌ WRONG - Will create nested <value> element
-"Color": {
-  "fields": {
-    "@id": { "source": "color.id" },
-    "value": { "source": "color.value" }
-  }
-}
-// Output: <Color id="9101"><value>MULTI-COLOR</value></Color>
-
-// ✅ CORRECT - Use #text for text content
-"Color": {
-  "fields": {
-    "@id": { "source": "color.id" },
-    "#text": { "source": "color.value" }
-  }
-}
-// Output: <Color id="9101">MULTI-COLOR</Color>
-```
-
-### Implementation
-
-```typescript
-import { UniversalMapper, XMLBuilder } from '@fluentcommerce/fc-connect-sdk';
-
-// Load mapping configuration
-const mappingConfig = JSON.parse(fs.readFileSync('./config/fluent-to-xml.json', 'utf-8'));
-
-// Create mapper (no GraphQL execution - just transformation)
-const mapper = new UniversalMapper(mappingConfig);
-
-// Map Fluent data to XML structure
-const result = await mapper.map(fluentOrderData);
-
-if (result.success) {
-  // Generate XML
-  const builder = new XMLBuilder({
-    prettyPrint: true,
-    xmlDeclaration: true,
-  });
-  const xml = builder.build(result.data, 'OrderDetailResponse');
-
-  console.log('Generated XML:', xml);
-
-  // Save or send to external system
-  await s3.uploadFile('order-detail.xml', xml);
-}
-```
-
-### Generated XML Output
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<OrderDetailResponse xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
-  <Customer customerId="232">
-    <Name>
-      <FirstName>Justin</FirstName>
-      <LastName>Kerr</LastName>
-    </Name>
-  </Customer>
-  <OrderLines>
-    <OrderLine itemId="ITEM-1">
-      <ProductRef>SKU-WM-001</ProductRef>
-      <Color id="9101">MULTI-COLOR</Color>
-      <Quantity>2</Quantity>
-    </OrderLine>
-  </OrderLines>
-</OrderDetailResponse>
-```
-
-### Key Points
-
-- **No GraphQL Execution:** `UniversalMapper` only transforms data
-- **XML Attributes:** Use `@` prefix for attributes
-- **XML Text Content:** Use `#text` when element has both attributes and text
-- **Arrays:** Use `isArray: true` to map array elements
-- **XMLBuilder:** Handles formatting, namespaces, and declarations
-
-📖 **For detailed XML patterns**, see [XML Parser Guide](../../parsers/modules/parsers-04-xml-parser.md)
-
----
-
-## Use Case 4: Fluent GraphQL → Parquet Extraction
-
-**Scenario:** Export inventory positions to data lake in Parquet format
-
-### Source Data
-
-**GraphQL Query:**
-
-```graphql
-query ExtractInventoryPositions($after: String, $first: Int!) {
-  inventoryPositions(after: $after, first: $first) {
-    pageInfo {
-      hasNextPage
-    }
-    edges {
-      cursor
-      node {
-        id
-        ref
-        productRef
-        locationRef
-        qty
-        updatedOn
-        product {
-          name
-          gtin
-          catalogue {
-            ref
-          }
-        }
-        location {
-          name
-        }
-      }
-    }
-  }
-}
-```
-
-**GraphQL Response:**
-
-```json
-{
-  "inventoryPositions": {
-    "edges": [
-      {
-        "node": {
-          "id": "POS-1",
-          "ref": "WH-001:PROD-001",
-          "productRef": "PROD-001",
-          "locationRef": "WH-001",
-          "qty": 50,
-          "updatedOn": "2024-01-15T10:30:00Z",
-          "product": {
-            "name": "Widget Master 3000",
-            "gtin": "1234567890123",
-            "catalogue": {
-              "ref": "MAIN"
-            }
-          },
-          "location": {
-            "name": "Springfield Distribution Center"
-          }
-        }
-      }
-    ]
-  }
-}
-```
-
-### Mapping Configuration
-
-**File: `config/extraction-mappings.json`**
-
-```json
-{
-  "direction": "extract",
-  "sourceFormat": "graphql",
-  "targetFormat": "parquet",
-  "comment": "✅ Extract inventory from Fluent query response to Parquet format",
-
-  "fields": {
-    "position_id": {
-      "source": "id",
-      "comment": "✅ From InventoryPosition.id (ID!)"
-    },
-    "position_ref": {
-      "source": "ref",
-      "comment": "✅ From InventoryPosition.ref (String!)"
-    },
-    "sku": {
-      "source": "productRef",
-      "comment": "✅ From InventoryPosition.productRef (String!)"
-    },
-    "warehouse": {
-      "source": "locationRef",
-      "comment": "✅ From InventoryPosition.locationRef (String!)"
-    },
-    "available_qty": {
-      "source": "qty",
-      "comment": "✅ From InventoryPosition.qty (Int!)"
-    },
-    "product_name": {
-      "source": "product.name",
-      "comment": "✅ From InventoryPosition.product.name (String) - nested"
-    },
-    "product_gtin": {
-      "source": "product.gtin",
-      "comment": "✅ From InventoryPosition.product.gtin (String) - nested"
-    },
-    "catalogue": {
-      "source": "product.catalogue.ref",
-      "comment": "✅ From InventoryPosition.product.catalogue.ref (String!) - deeply nested"
-    },
-    "warehouse_name": {
-      "source": "location.name",
-      "comment": "✅ From InventoryPosition.location.name (String!) - nested"
-    },
-    "updated_at": {
-      "source": "updatedOn",
-      "comment": "✅ From InventoryPosition.updatedOn (DateTime)"
-    }
-  }
-}
-```
-
-### Implementation
-
-```typescript
-import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-import { writeParquetFile } from './utils/parquet-writer';
-
-// Load mapping configuration
-const mappingConfig = JSON.parse(fs.readFileSync('./config/extraction-mappings.json', 'utf-8'));
-
-// Create mapper
-const mapper = new UniversalMapper(mappingConfig);
-
-// Query Fluent Commerce (with pagination)
-const allRecords = [];
-let hasNextPage = true;
-let cursor = null;
-
-while (hasNextPage) {
-  const result = await client.graphql({
-    query: extractionQuery,
-    variables: { after: cursor, first: 100 },
-  });
-
-  const edges = result.data.inventoryPositions.edges;
-
-  // Process each GraphQL node
-  for (const edge of edges) {
-    const mapResult = await mapper.map(edge.node);
-
-    if (mapResult.success) {
-      allRecords.push(mapResult.data);
-    } else {
-      console.error('Mapping failed for node:', edge.node.id);
-      console.error('Errors:', mapResult.errors);
-    }
-  }
-
-  // Check pagination
-  hasNextPage = result.data.inventoryPositions.pageInfo.hasNextPage;
-  cursor = edges[edges.length - 1]?.cursor;
-}
-
-// Write to Parquet file
-await writeParquetFile('inventory-positions.parquet', allRecords, {
-  schema: {
-    position_id: { type: 'UTF8' },
-    position_ref: { type: 'UTF8' },
-    sku: { type: 'UTF8' },
-    warehouse: { type: 'UTF8' },
-    available_qty: { type: 'INT32' },
-    product_name: { type: 'UTF8' },
-    product_gtin: { type: 'UTF8' },
-    catalogue: { type: 'UTF8' },
-    warehouse_name: { type: 'UTF8' },
-    updated_at: { type: 'TIMESTAMP_MILLIS' },
-  },
-});
-
-console.log(`✅ Extracted ${allRecords.length} inventory positions to Parquet`);
-```
-
-### Parquet Output
-
-The Parquet file will contain columnar data optimized for analytics:
-
-| position_id | sku      | warehouse | available_qty | product_name       | warehouse_name                  |
-| ----------- | -------- | --------- | ------------- | ------------------ | ------------------------------- |
-| POS-1       | PROD-001 | WH-001    | 50            | Widget Master 3000 | Springfield Distribution Center |
-| POS-2       | PROD-002 | WH-001    | 150           | Keyboard Elite     | Springfield Distribution Center |
-
-### Key Points
-
-- **Nested Field Access:** Use dot notation for nested GraphQL fields
-- **GraphQL Pagination:** Handle `edges` and `nodes` structure
-- **No GraphQL Execution:** Mapper only transforms pre-fetched data
-- **Parquet Schema:** Define column types for efficient storage
-- **Data Lake Ready:** Columnar format for analytics and BI tools
-
-**Schema Reference:**
-
-- Query: `inventoryPositions(first: Int, after: String): InventoryPositionConnection!`
-- See [`docs/schema/fluent-commerce-schema.json`](../../../04-REFERENCE/schema/fluent-commerce-schema.json) → `types.InventoryPosition`
-
----
-
-## Comparison Matrix
-
-| Use Case             | Direction | Source Format | Target Format | GraphQL Execution | Component                          | Platform |
-| -------------------- | --------- | ------------- | ------------- | ----------------- | ---------------------------------- | -------- |
-| **CSV → Fluent**     | `ingest`  | CSV           | N/A           | ❌ No (generates payload) | `UniversalMapper` + Batch API      | Standalone |
-| **XML → Fluent**     | `ingest`  | XML           | N/A           | ❌ No (generates payload) | `GraphQLMutationMapper`            | Standalone |
-| **Fluent → XML**     | `extract` | GraphQL       | XML           | ❌ No             | `UniversalMapper` + `XMLBuilder`   | Standalone |
-| **Fluent → Parquet** | `extract` | GraphQL       | Parquet       | ❌ No             | `UniversalMapper` + Parquet writer | Standalone |
-
-**Note:** For `ingest` direction, mappers generate GraphQL payloads but do NOT execute them. You must call `client.graphql(payload)` separately.
-
----
-
-## Key Takeaways
-
-1. **Same Pattern Everywhere:** All use cases use the same `fields` mapping structure
-2. **Direction Matters:** `ingest` executes mutations, `extract` only transforms
-3. **Resolvers Are Universal:** SDK resolvers work across all formats
-4. **Custom Logic:** Use custom resolvers for business-specific transformations
-5. **Validation First:** Always validate against schema before deployment
-
----
-
-## Practice Exercise
-
-**Task:** Create a mapping for extracting Fluent orders to JSON for a data warehouse.
-
-**Requirements:**
-
-1. Query orders with customer and items
-2. Flatten nested customer data
-3. Map items array
-4. Include calculated fields (item totals)
-5. Format dates as ISO8601
-
-<details>
-<summary>Click to see solution</summary>
-
-**Mapping Configuration:**
-
-```json
-{
-  "direction": "extract",
-  "sourceFormat": "graphql",
-  "targetFormat": "json",
-
-  "fields": {
-    "order_id": {
-      "source": "id"
-    },
-    "order_ref": {
-      "source": "ref"
-    },
-    "customer_id": {
-      "source": "customer.id"
-    },
-    "customer_email": {
-      "source": "customer.email",
-      "resolver": "sdk.lowercase"
-    },
-    "customer_name": {
-      "resolver": "custom.fullName"
-    },
-    "total_price": {
-      "source": "totalPrice",
-      "resolver": "sdk.parseFloat"
-    },
-    "created_at": {
-      "source": "createdOn",
-      "resolver": "sdk.formatDate"
-    },
-    "items": {
-      "source": "items",
-      "isArray": true,
-      "fields": {
-        "item_ref": {
-          "source": "ref"
-        },
-        "product_ref": {
-          "source": "productRef"
-        },
-        "quantity": {
-          "source": "quantity",
-          "resolver": "sdk.parseInt"
-        },
-        "unit_price": {
-          "source": "price",
-          "resolver": "sdk.parseFloat"
-        },
-        "total_price": {
-          "resolver": "custom.calculateItemTotal"
-        }
-      }
-    }
-  }
-}
-```
-
-**Custom Resolvers:**
-
-```typescript
-const customResolvers = {
-  'custom.fullName': (value: any, sourceData: any, config: any, helpers: any) => {
-    const firstName = helpers.get(sourceData, 'customer.firstName', '');
-    const lastName = helpers.get(sourceData, 'customer.lastName', '');
-    return `${firstName} ${lastName}`.trim();
-  },
-
-  'custom.calculateItemTotal': (value: any, sourceData: any, config: any, helpers: any) => {
-    const qty = helpers.parseIntSafe(sourceData.quantity, 0);
-    const price = helpers.parseFloatSafe(sourceData.price, 0);
-    return qty * price;
-  },
-};
-```
-
-</details>
-
----
-
-## Next Steps
-
-Now that you've seen real-world use cases, you're ready for advanced patterns:
-
-→ Continue to [Module 5: Advanced Patterns](./mapping-05-advanced-patterns.md)
-
-**Alternative paths:**
-
-- Review [Helpers & Resolvers](./mapping-06-helpers-resolvers.md) for complete helper documentation
-- Check [API Reference](../api-reference/readme.md) for TypeScript usage
-
----
-
-[← Back to Schema Validation](./mapping-03-schema-validation.md) | [Next: Advanced Patterns →](./mapping-05-advanced-patterns.md)
-
-
-
-
-
-
+# Module 4: Use Cases
+
+**Real-world transformation scenarios**
+
+**Level:** Intermediate
+**Time:** 45 minutes
+**Prerequisites:** [Module 3: Schema Validation](./mapping-03-schema-validation.md)
+
+---
+
+## Learning Objectives
+
+After completing this module, you will:
+
+- ✅ Implement CSV ingestion to Fluent Batch API
+- ✅ Transform XML to GraphQL mutations for order creation
+- ✅ Generate XML from Fluent data for external APIs
+- ✅ Extract GraphQL data to Parquet format
+- ✅ Understand real-world connector patterns
+
+---
+
+## Use Case 1: CSV Ingestion → Fluent Batch API
+
+**Scenario:** Import inventory positions from CSV files to Fluent Commerce
+
+### Source Data
+
+**CSV Format:**
+
+```csv
+sku,location,quantity,status
+PROD-001,WAREHOUSE-A,100,active
+PROD-002,WAREHOUSE-A,50,reserved
+PROD-003,WAREHOUSE-B,200,active
+```
+
+### Mapping Configuration
+
+**File: `config/inventory-ingestion.json`**
+
+```json
+{
+  "direction": "ingest",
+  "sourceFormat": "csv",
+  "mutation": "upsertInventoryPosition",
+  "comment": "✅ Validated against schema: docs/schema/fluent-commerce-schema.json → Mutation.upsertInventoryPosition",
+
+  "fields": {
+    "ref": {
+      "source": "sku",
+      "required": true,
+      "comment": "✅ UpsertInventoryPositionInput.ref (String! required) - unique position identifier"
+    },
+    "productRef": {
+      "source": "sku",
+      "required": true,
+      "comment": "✅ UpsertInventoryPositionInput.productRef (String! required)"
+    },
+    "locationRef": {
+      "source": "location",
+      "required": true,
+      "comment": "✅ UpsertInventoryPositionInput.locationRef (String! required)"
+    },
+    "qty": {
+      "source": "quantity",
+      "resolver": "sdk.parseInt",
+      "required": true,
+      "comment": "✅ UpsertInventoryPositionInput.qty (Int! required)"
+    },
+    "status": {
+      "source": "status",
+      "resolver": "sdk.uppercase",
+      "defaultValue": "AVAILABLE",
+      "comment": "✅ UpsertInventoryPositionInput.status (String) - e.g., AVAILABLE, RESERVED"
+    }
+  }
+}
+```
+
+### Implementation
+
+```typescript
+import { UniversalMapper, CSVParserService, createClient } from '@fluentcommerce/fc-connect-sdk';
+import * as fs from 'fs';
+
+// Load mapping configuration
+const mappingConfig = JSON.parse(fs.readFileSync('./config/inventory-ingestion.json', 'utf-8'));
+
+// Load and parse CSV
+const csvContent = fs.readFileSync('./data/inventory.csv', 'utf-8');
+const parser = new CSVParserService();
+const records = await parser.parse(csvContent);
+
+// Create mapper
+const mapper = new UniversalMapper(mappingConfig);
+
+// Process each CSV row
+const batchEntities = [];
+for (const row of records) {
+  const result = await mapper.map(row);
+
+  if (result.success) {
+    batchEntities.push(result.data);
+  } else {
+    console.error('Mapping failed for row:', row);
+    console.error('Errors:', result.errors);
+  }
+}
+
+// Create Fluent client
+const client = await createClient({
+  config: {
+    baseUrl: process.env.FLUENT_BASE_URL!,
+    clientId: process.env.FLUENT_CLIENT_ID!,
+    clientSecret: process.env.FLUENT_CLIENT_SECRET!,
+    username: process.env.FLUENT_USERNAME!,
+    password: process.env.FLUENT_PASSWORD!,
+    retailerId: process.env.FLUENT_RETAILER_ID!,
+  },
+});
+
+// Create batch job
+const job = await client.createJob({
+  name: 'inventory-update',
+  retailerId: process.env.FLUENT_RETAILER_ID!,
+});
+
+// Send batch to Fluent Commerce
+await client.sendBatch(job.id, {
+  action: 'UPSERT',
+  entityType: 'INVENTORY',
+  source: 'CSV_IMPORT',
+  event: 'INVENTORY_UPDATE',
+  entities: batchEntities,
+});
+
+console.log(`✅ Successfully processed ${batchEntities.length} inventory positions`);
+```
+
+### Key Points
+
+- **Batch Processing:** Efficient for high-volume imports (1000s of records)
+- **Validation:** `required: true` catches missing data before API calls
+- **Resolvers:** `sdk.parseInt` ensures numeric types, `sdk.uppercase` normalizes status
+- **Error Handling:** Individual row failures don't stop the entire batch
+
+**Schema Reference:**
+
+- Mutation: `upsertInventoryPosition(input: UpsertInventoryPositionInput!): InventoryPosition`
+- See [`docs/schema/fluent-commerce-schema.json`](../../../04-REFERENCE/schema/fluent-commerce-schema.json) → `inputs.UpsertInventoryPositionInput`
+
+---
+
+## Use Case 2: XML → GraphQL Mutation
+
+**Scenario:** Transform SFCC order XML to Fluent order mutation
+
+### Source Data
+
+**SFCC Order XML:**
+
+```xml
+<order id="ORD-123" type="standard">
+  <customer email="john@example.com" />
+  <total currency="USD">99.99</total>
+  <items>
+    <item id="ITEM-1" sku="PROD-001" qty="2" unitPrice="49.99" />
+  </items>
+</order>
+```
+
+### Mapping Configuration
+
+**File: `mappings/sfcc-order-to-fluent.json`**
+
+```json
+{
+  "direction": "ingest",
+  "sourceFormat": "xml",
+  "mutation": "createOrder",
+  "comment": "✅ Validated against schema: docs/schema/fluent-commerce-schema.json → Mutation.createOrder",
+
+  "fields": {
+    "ref": {
+      "source": "order@id",
+      "required": true,
+      "comment": "✅ CreateOrderInput.ref (String! required)"
+    },
+    "type": {
+      "source": "order@type",
+      "resolver": "custom.mapOrderType",
+      "comment": "✅ CreateOrderInput.type (OrderType! enum required) - maps 'standard' → 'STANDARD'"
+    },
+    "retailer": {
+      "fields": {
+        "id": {
+          "value": "1",
+          "comment": "✅ CreateOrderInput.retailer (RetailerInput! required)"
+        }
+      }
+    },
+    "customer": {
+      "fields": {
+        "email": {
+          "source": "order.customer@email",
+          "resolver": "sdk.lowercase",
+          "comment": "✅ CreateOrderInput.customer.email (String!)"
+        }
+      }
+    },
+    "totalPrice": {
+      "source": "order.total",
+      "resolver": "sdk.parseFloat",
+      "required": true,
+      "comment": "✅ CreateOrderInput.totalPrice (Float! required)"
+    },
+    "currency": {
+      "source": "order.total@currency",
+      "defaultValue": "USD",
+      "comment": "✅ CreateOrderInput.currency (String! required)"
+    },
+    "items": {
+      "source": "order.items.item",
+      "isArray": true,
+      "comment": "✅ CreateOrderInput.items ([OrderItemInput]! required)",
+      "fields": {
+        "ref": {
+          "source": "$.@id",
+          "required": true,
+          "comment": "✅ OrderItemInput.ref (String! required)"
+        },
+        "productRef": {
+          "source": "$.@sku",
+          "required": true,
+          "comment": "✅ OrderItemInput.productRef (String! required)"
+        },
+        "quantity": {
+          "source": "$.@qty",
+          "resolver": "sdk.parseInt",
+          "required": true,
+          "comment": "✅ OrderItemInput.quantity (Int! required)"
+        },
+        "price": {
+          "source": "$.@unitPrice",
+          "resolver": "sdk.parseFloat",
+          "required": true,
+          "comment": "✅ OrderItemInput.price (Float! required)"
+        },
+        "totalPrice": {
+          "resolver": "custom.calculateItemTotal",
+          "required": true,
+          "comment": "✅ OrderItemInput.totalPrice (Float! required) - calculated from qty * price"
+        },
+        "currency": {
+          "source": "order.total@currency",
+          "required": true,
+          "comment": "✅ OrderItemInput.currency (String! required)"
+        }
+      }
+    }
+  }
+}
+```
+
+### Implementation
+
+```typescript
+import { GraphQLMutationMapper } from '@fluentcommerce/fc-connect-sdk';
+
+// Load mapping configuration
+const mappingConfig = JSON.parse(fs.readFileSync('./mappings/sfcc-order-to-fluent.json', 'utf-8'));
+
+// Custom resolvers for business logic
+const customResolvers = {
+  'custom.mapOrderType': (value: string) => {
+    // Map SFCC order types to Fluent OrderType enum
+    const typeMap: Record<string, string> = {
+      standard: 'STANDARD',
+      express: 'HD',
+      'store-pickup': 'CC',
+    };
+    return typeMap[value.toLowerCase()] || 'STANDARD';
+  },
+
+  'custom.calculateItemTotal': (value: any, sourceData: any, config: any, helpers: any) => {
+    // Calculate item total from quantity and price
+    const qty = helpers.parseIntSafe(sourceData['@qty'], 0);
+    const price = helpers.parseFloatSafe(sourceData['@unitPrice'], 0);
+    return qty * price;
+  },
+};
+
+// Create mapper
+const mapper = new GraphQLMutationMapper(mappingConfig, logger, { fluentClient: client });
+
+// Parse XML and map to mutation
+const payload = await mapper.mapWithNodes(xmlData, customResolvers);
+
+if (payload.success) {
+  // ✅ Execute GraphQL mutation (mapper only generates payload, you must execute)
+  const result = await client.graphql(payload.data);
+  console.log('Order created:', result.data.createOrder.id);
+} else {
+  console.error('Mapping failed:', payload.errors);
+}
+```
+
+### Key Points
+
+- **XML Attributes:** Use `@` prefix for attributes (e.g., `order@id`)
+- **XML Nested Paths:** Use dot notation (e.g., `order.customer@email`)
+- **Array Context:** `$.@id` references current array item
+- **Custom Resolvers:** Business logic for type mapping and calculations
+- **GraphQL Execution:** `GraphQLMutationMapper` generates the mutation payload only - you must call `client.graphql(payload)` to execute
+
+**Schema Reference:**
+
+- Mutation: `createOrder(input: CreateOrderInput!): Order!`
+- See [`docs/schema/fluent-commerce-schema.json`](../../../04-REFERENCE/schema/fluent-commerce-schema.json) → `inputs.CreateOrderInput`
+
+---
+
+## Use Case 3: Fluent → XML Generation (SFCC Order Detail)
+
+**Scenario:** Generate SFCC-compatible XML from Fluent order data
+
+### Source Data
+
+**Fluent GraphQL Response:**
+
+```json
+{
+  "order": {
+    "ref": "ORD-2025-001",
+    "customer": {
+      "id": "232",
+      "firstName": "Justin",
+      "lastName": "Kerr"
+    },
+    "items": [
+      {
+        "id": "ITEM-1",
+        "productRef": "SKU-WM-001",
+        "color": { "id": "9101", "value": "MULTI-COLOR" },
+        "quantity": 2,
+        "price": 49.99
+      }
+    ]
+  }
+}
+```
+
+### Mapping Configuration
+
+**File: `config/fluent-to-xml.json`**
+
+```json
+{
+  "direction": "extract",
+  "sourceFormat": "graphql",
+  "targetFormat": "xml",
+  "comment": "Generate SFCC-compatible XML from Fluent order data",
+
+  "fields": {
+    "@xmlns": {
+      "value": "http://api.gsicommerce.com/schema/checkout/1.0",
+      "comment": "XML namespace for SFCC"
+    },
+    "Customer": {
+      "fields": {
+        "@customerId": {
+          "source": "customer.id",
+          "comment": "Customer ID as XML attribute"
+        },
+        "Name": {
+          "fields": {
+            "FirstName": {
+              "source": "customer.firstName",
+              "comment": "Simple element with text content"
+            },
+            "LastName": {
+              "source": "customer.lastName"
+            }
+          }
+        }
+      }
+    },
+    "OrderLines": {
+      "fields": {
+        "OrderLine": {
+          "source": "items",
+          "isArray": true,
+          "comment": "Array of order line items",
+          "fields": {
+            "@itemId": {
+              "source": "id",
+              "comment": "Item ID as XML attribute"
+            },
+            "ProductRef": {
+              "source": "productRef",
+              "comment": "Simple element - no attributes"
+            },
+            "Color": {
+              "fields": {
+                "@id": {
+                  "source": "color.id",
+                  "comment": "Color ID as attribute"
+                },
+                "#text": {
+                  "source": "color.value",
+                  "comment": "⚠️ Use #text for text content when element has attributes"
+                }
+              }
+            },
+            "Quantity": {
+              "source": "quantity",
+              "resolver": "sdk.toString"
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### XML Output Patterns
+
+| Pattern              | JSON Mapping                       | XML Output                                 |
+| -------------------- | ---------------------------------- | ------------------------------------------ |
+| **Simple Element**   | `"ItemId": { "source": "id" }`     | `<ItemId>SKU001</ItemId>`                  |
+| **Attribute Only**   | `"@orderId": { "source": "ref" }`  | `<Order orderId="12345"/>`                 |
+| **Attribute + Text** | `"@id": {...}, "#text": {...}`     | `<Color id="9101">MULTI-COLOR</Color>`     |
+| **Nested Elements**  | `"fields": { "FirstName": {...} }` | `<Name><FirstName>John</FirstName></Name>` |
+| **Array**            | `"isArray": true, "fields": {...}` | Multiple `<OrderLine>` elements            |
+
+### Decision Tree - When to use `#text`
+
+```
+Does the XML element need attributes (@id, @status, etc.)?
+├─ NO  → Just use field name
+│        "ItemId": { "source": "id" }
+│        Result: <ItemId>SKU001</ItemId>
+│
+└─ YES → Does it ALSO have text content?
+    ├─ NO  → Just use @prefix
+    │        "@orderId": { "source": "ref" }
+    │        Result: <Order orderId="12345"/>
+    │
+    └─ YES → Use BOTH @prefix AND #text ⚠️
+             "@id": { "source": "color.id" }
+             "#text": { "source": "color.value" }
+             Result: <Color id="9101">MULTI-COLOR</Color>
+```
+
+### Common Mistake
+
+```json
+// ❌ WRONG - Will create nested <value> element
+"Color": {
+  "fields": {
+    "@id": { "source": "color.id" },
+    "value": { "source": "color.value" }
+  }
+}
+// Output: <Color id="9101"><value>MULTI-COLOR</value></Color>
+
+// ✅ CORRECT - Use #text for text content
+"Color": {
+  "fields": {
+    "@id": { "source": "color.id" },
+    "#text": { "source": "color.value" }
+  }
+}
+// Output: <Color id="9101">MULTI-COLOR</Color>
+```
+
+### Implementation
+
+```typescript
+import { UniversalMapper, XMLBuilder } from '@fluentcommerce/fc-connect-sdk';
+
+// Load mapping configuration
+const mappingConfig = JSON.parse(fs.readFileSync('./config/fluent-to-xml.json', 'utf-8'));
+
+// Create mapper (no GraphQL execution - just transformation)
+const mapper = new UniversalMapper(mappingConfig);
+
+// Map Fluent data to XML structure
+const result = await mapper.map(fluentOrderData);
+
+if (result.success) {
+  // Generate XML
+  const builder = new XMLBuilder({
+    prettyPrint: true,
+    xmlDeclaration: true,
+  });
+  const xml = builder.build(result.data, 'OrderDetailResponse');
+
+  console.log('Generated XML:', xml);
+
+  // Save or send to external system
+  await s3.uploadFile('order-detail.xml', xml);
+}
+```
+
+### Generated XML Output
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<OrderDetailResponse xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
+  <Customer customerId="232">
+    <Name>
+      <FirstName>Justin</FirstName>
+      <LastName>Kerr</LastName>
+    </Name>
+  </Customer>
+  <OrderLines>
+    <OrderLine itemId="ITEM-1">
+      <ProductRef>SKU-WM-001</ProductRef>
+      <Color id="9101">MULTI-COLOR</Color>
+      <Quantity>2</Quantity>
+    </OrderLine>
+  </OrderLines>
+</OrderDetailResponse>
+```
+
+### Key Points
+
+- **No GraphQL Execution:** `UniversalMapper` only transforms data
+- **XML Attributes:** Use `@` prefix for attributes
+- **XML Text Content:** Use `#text` when element has both attributes and text
+- **Arrays:** Use `isArray: true` to map array elements
+- **XMLBuilder:** Handles formatting, namespaces, and declarations
+
+📖 **For detailed XML patterns**, see [XML Parser Guide](../../parsers/modules/parsers-04-xml-parser.md)
+
+---
+
+## Use Case 4: Fluent GraphQL → Parquet Extraction
+
+**Scenario:** Export inventory positions to data lake in Parquet format
+
+### Source Data
+
+**GraphQL Query:**
+
+```graphql
+query ExtractInventoryPositions($after: String, $first: Int!) {
+  inventoryPositions(after: $after, first: $first) {
+    pageInfo {
+      hasNextPage
+    }
+    edges {
+      cursor
+      node {
+        id
+        ref
+        productRef
+        locationRef
+        qty
+        updatedOn
+        product {
+          name
+          gtin
+          catalogue {
+            ref
+          }
+        }
+        location {
+          name
+        }
+      }
+    }
+  }
+}
+```
+
+**GraphQL Response:**
+
+```json
+{
+  "inventoryPositions": {
+    "edges": [
+      {
+        "node": {
+          "id": "POS-1",
+          "ref": "WH-001:PROD-001",
+          "productRef": "PROD-001",
+          "locationRef": "WH-001",
+          "qty": 50,
+          "updatedOn": "2024-01-15T10:30:00Z",
+          "product": {
+            "name": "Widget Master 3000",
+            "gtin": "1234567890123",
+            "catalogue": {
+              "ref": "MAIN"
+            }
+          },
+          "location": {
+            "name": "Springfield Distribution Center"
+          }
+        }
+      }
+    ]
+  }
+}
+```
+
+### Mapping Configuration
+
+**File: `config/extraction-mappings.json`**
+
+```json
+{
+  "direction": "extract",
+  "sourceFormat": "graphql",
+  "targetFormat": "parquet",
+  "comment": "✅ Extract inventory from Fluent query response to Parquet format",
+
+  "fields": {
+    "position_id": {
+      "source": "id",
+      "comment": "✅ From InventoryPosition.id (ID!)"
+    },
+    "position_ref": {
+      "source": "ref",
+      "comment": "✅ From InventoryPosition.ref (String!)"
+    },
+    "sku": {
+      "source": "productRef",
+      "comment": "✅ From InventoryPosition.productRef (String!)"
+    },
+    "warehouse": {
+      "source": "locationRef",
+      "comment": "✅ From InventoryPosition.locationRef (String!)"
+    },
+    "available_qty": {
+      "source": "qty",
+      "comment": "✅ From InventoryPosition.qty (Int!)"
+    },
+    "product_name": {
+      "source": "product.name",
+      "comment": "✅ From InventoryPosition.product.name (String) - nested"
+    },
+    "product_gtin": {
+      "source": "product.gtin",
+      "comment": "✅ From InventoryPosition.product.gtin (String) - nested"
+    },
+    "catalogue": {
+      "source": "product.catalogue.ref",
+      "comment": "✅ From InventoryPosition.product.catalogue.ref (String!) - deeply nested"
+    },
+    "warehouse_name": {
+      "source": "location.name",
+      "comment": "✅ From InventoryPosition.location.name (String!) - nested"
+    },
+    "updated_at": {
+      "source": "updatedOn",
+      "comment": "✅ From InventoryPosition.updatedOn (DateTime)"
+    }
+  }
+}
+```
+
+### Implementation
+
+```typescript
+import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+import { writeParquetFile } from './utils/parquet-writer';
+
+// Load mapping configuration
+const mappingConfig = JSON.parse(fs.readFileSync('./config/extraction-mappings.json', 'utf-8'));
+
+// Create mapper
+const mapper = new UniversalMapper(mappingConfig);
+
+// Query Fluent Commerce (with pagination)
+const allRecords = [];
+let hasNextPage = true;
+let cursor = null;
+
+while (hasNextPage) {
+  const result = await client.graphql({
+    query: extractionQuery,
+    variables: { after: cursor, first: 100 },
+  });
+
+  const edges = result.data.inventoryPositions.edges;
+
+  // Process each GraphQL node
+  for (const edge of edges) {
+    const mapResult = await mapper.map(edge.node);
+
+    if (mapResult.success) {
+      allRecords.push(mapResult.data);
+    } else {
+      console.error('Mapping failed for node:', edge.node.id);
+      console.error('Errors:', mapResult.errors);
+    }
+  }
+
+  // Check pagination
+  hasNextPage = result.data.inventoryPositions.pageInfo.hasNextPage;
+  cursor = edges[edges.length - 1]?.cursor;
+}
+
+// Write to Parquet file
+await writeParquetFile('inventory-positions.parquet', allRecords, {
+  schema: {
+    position_id: { type: 'UTF8' },
+    position_ref: { type: 'UTF8' },
+    sku: { type: 'UTF8' },
+    warehouse: { type: 'UTF8' },
+    available_qty: { type: 'INT32' },
+    product_name: { type: 'UTF8' },
+    product_gtin: { type: 'UTF8' },
+    catalogue: { type: 'UTF8' },
+    warehouse_name: { type: 'UTF8' },
+    updated_at: { type: 'TIMESTAMP_MILLIS' },
+  },
+});
+
+console.log(`✅ Extracted ${allRecords.length} inventory positions to Parquet`);
+```
+
+### Parquet Output
+
+The Parquet file will contain columnar data optimized for analytics:
+
+| position_id | sku      | warehouse | available_qty | product_name       | warehouse_name                  |
+| ----------- | -------- | --------- | ------------- | ------------------ | ------------------------------- |
+| POS-1       | PROD-001 | WH-001    | 50            | Widget Master 3000 | Springfield Distribution Center |
+| POS-2       | PROD-002 | WH-001    | 150           | Keyboard Elite     | Springfield Distribution Center |
+
+### Key Points
+
+- **Nested Field Access:** Use dot notation for nested GraphQL fields
+- **GraphQL Pagination:** Handle `edges` and `nodes` structure
+- **No GraphQL Execution:** Mapper only transforms pre-fetched data
+- **Parquet Schema:** Define column types for efficient storage
+- **Data Lake Ready:** Columnar format for analytics and BI tools
+
+**Schema Reference:**
+
+- Query: `inventoryPositions(first: Int, after: String): InventoryPositionConnection!`
+- See [`docs/schema/fluent-commerce-schema.json`](../../../04-REFERENCE/schema/fluent-commerce-schema.json) → `types.InventoryPosition`
+
+---
+
+## Comparison Matrix
+
+| Use Case             | Direction | Source Format | Target Format | GraphQL Execution | Component                          | Platform |
+| -------------------- | --------- | ------------- | ------------- | ----------------- | ---------------------------------- | -------- |
+| **CSV → Fluent**     | `ingest`  | CSV           | N/A           | ❌ No (generates payload) | `UniversalMapper` + Batch API      | Standalone |
+| **XML → Fluent**     | `ingest`  | XML           | N/A           | ❌ No (generates payload) | `GraphQLMutationMapper`            | Standalone |
+| **Fluent → XML**     | `extract` | GraphQL       | XML           | ❌ No             | `UniversalMapper` + `XMLBuilder`   | Standalone |
+| **Fluent → Parquet** | `extract` | GraphQL       | Parquet       | ❌ No             | `UniversalMapper` + Parquet writer | Standalone |
+
+**Note:** For `ingest` direction, mappers generate GraphQL payloads but do NOT execute them. You must call `client.graphql(payload)` separately.
+
+---
+
+## Key Takeaways
+
+1. **Same Pattern Everywhere:** All use cases use the same `fields` mapping structure
+2. **Direction Matters:** `ingest` executes mutations, `extract` only transforms
+3. **Resolvers Are Universal:** SDK resolvers work across all formats
+4. **Custom Logic:** Use custom resolvers for business-specific transformations
+5. **Validation First:** Always validate against schema before deployment
+
+---
+
+## Practice Exercise
+
+**Task:** Create a mapping for extracting Fluent orders to JSON for a data warehouse.
+
+**Requirements:**
+
+1. Query orders with customer and items
+2. Flatten nested customer data
+3. Map items array
+4. Include calculated fields (item totals)
+5. Format dates as ISO8601
+
+<details>
+<summary>Click to see solution</summary>
+
+**Mapping Configuration:**
+
+```json
+{
+  "direction": "extract",
+  "sourceFormat": "graphql",
+  "targetFormat": "json",
+
+  "fields": {
+    "order_id": {
+      "source": "id"
+    },
+    "order_ref": {
+      "source": "ref"
+    },
+    "customer_id": {
+      "source": "customer.id"
+    },
+    "customer_email": {
+      "source": "customer.email",
+      "resolver": "sdk.lowercase"
+    },
+    "customer_name": {
+      "resolver": "custom.fullName"
+    },
+    "total_price": {
+      "source": "totalPrice",
+      "resolver": "sdk.parseFloat"
+    },
+    "created_at": {
+      "source": "createdOn",
+      "resolver": "sdk.formatDate"
+    },
+    "items": {
+      "source": "items",
+      "isArray": true,
+      "fields": {
+        "item_ref": {
+          "source": "ref"
+        },
+        "product_ref": {
+          "source": "productRef"
+        },
+        "quantity": {
+          "source": "quantity",
+          "resolver": "sdk.parseInt"
+        },
+        "unit_price": {
+          "source": "price",
+          "resolver": "sdk.parseFloat"
+        },
+        "total_price": {
+          "resolver": "custom.calculateItemTotal"
+        }
+      }
+    }
+  }
+}
+```
+
+**Custom Resolvers:**
+
+```typescript
+const customResolvers = {
+  'custom.fullName': (value: any, sourceData: any, config: any, helpers: any) => {
+    const firstName = helpers.get(sourceData, 'customer.firstName', '');
+    const lastName = helpers.get(sourceData, 'customer.lastName', '');
+    return `${firstName} ${lastName}`.trim();
+  },
+
+  'custom.calculateItemTotal': (value: any, sourceData: any, config: any, helpers: any) => {
+    const qty = helpers.parseIntSafe(sourceData.quantity, 0);
+    const price = helpers.parseFloatSafe(sourceData.price, 0);
+    return qty * price;
+  },
+};
+```
+
+</details>
+
+---
+
+## Next Steps
+
+Now that you've seen real-world use cases, you're ready for advanced patterns:
+
+→ Continue to [Module 5: Advanced Patterns](./mapping-05-advanced-patterns.md)
+
+**Alternative paths:**
+
+- Review [Helpers & Resolvers](./mapping-06-helpers-resolvers.md) for complete helper documentation
+- Check [API Reference](../api-reference/readme.md) for TypeScript usage
+
+---
+
+[← Back to Schema Validation](./mapping-03-schema-validation.md) | [Next: Advanced Patterns →](./mapping-05-advanced-patterns.md)
+
+
+
+
+
+