@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/02-CORE-GUIDES/parsers/modules/02-core-guides-parsers-04-xml-parser.md

@@ -1,857 +1,857 @@
-# Module 4: XML Parser
-
-**Level:** Intermediate
-**Estimated Time:** 30 minutes
-
-## Overview
-
-This module covers the XML Parser (`XMLParserService`), essential for integrating with EDI feeds, B2B systems, and platforms like SFCC. You'll learn how to parse XML, handle attributes, use path resolution, generate XML from data, and integrate with SDK services.
-
-### Minimal Mode (start here)
-
-If you just need to parse XML, start with the simplest call:
-
-```typescript
-import { XMLParserService } from '@fluentcommerce/fc-connect-sdk';
-
-const parsed = await new XMLParserService().parse(xmlString, {
-  includeAttributes: false, // simplest shape
-  parseBooleans: true, // optional normalization
-  parseNumbers: true, // optional normalization
-});
-
-// Or use fast-xml-parser directly if you prefer; the SDK mapping works with any compatible shape.
-```
-
-Advanced options (attributes, selectors, streaming, path resolver) are optional—use only if needed.
-
-## Learning Objectives
-
-By the end of this module, you will:
-
-- ✅ Parse XML documents into JavaScript objects
-- ✅ Access elements and attributes directly from parsed structure
-- ✅ Generate XML from JavaScript objects using XMLBuilder
-- ✅ Handle large XML files with streaming
-- ✅ Transform XML data with UniversalMapper
-- ✅ Integrate with GraphQLMutationMapper for SFCC orders
-
-## What is XML?
-
-**XML (eXtensible Markup Language)** is a hierarchical markup format that:
-
-- Uses tags to define structure: `<element>value</element>`
-- Supports attributes: `<product id="123">`
-- Can represent complex nested data
-- Is self-describing with optional schemas
-
-**Example:**
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<products>
-  <product id="P001" category="electronics">
-    <sku>SKU001</sku>
-    <name>Wireless Mouse</name>
-    <price currency="USD">29.99</price>
-    <stock warehouse="WH-01">150</stock>
-  </product>
-</products>
-```
-
-## Basic XML Parsing
-
-### Simple Parsing
-
-```typescript
-import { XMLParserService } from '@fluentcommerce/fc-connect-sdk';
-
-const xmlParser = new XMLParserService();
-
-// Sample XML data
-const xmlContent = `
-<?xml version="1.0" encoding="UTF-8"?>
-<inventory>
-  <product>
-    <sku>SKU001</sku>
-    <name>Product 1</name>
-    <quantity>100</quantity>
-    <price>29.99</price>
-  </product>
-  <product>
-    <sku>SKU002</sku>
-    <name>Product 2</name>
-    <quantity>50</quantity>
-    <price>49.99</price>
-  </product>
-</inventory>
-`;
-
-// Parse XML
-const parsed = await xmlParser.parse(xmlContent);
-console.log('Parsed data:', parsed);
-
-// Access products
-const products = parsed.inventory?.product;
-console.log('Products:', products);
-```
-
-### Parsing with Attributes
-
-```typescript
-const xmlWithAttributes = `
-<?xml version="1.0" encoding="UTF-8"?>
-<catalog>
-  <product id="P001" category="electronics">
-    <name>Laptop</name>
-    <price currency="USD">999.99</price>
-    <stock warehouse="W01">25</stock>
-  </product>
-</catalog>
-`;
-
-const parsed = await xmlParser.parse(xmlWithAttributes);
-
-// Access attributes using @ prefix (NO underscore)
-// For simple parsing, access parsed structure directly
-const productId = parsed.catalog?.product?.['@id']; // 'P001'
-const category = parsed.catalog?.product?.['@category']; // 'electronics'
-const name = parsed.catalog?.product?.name; // 'Laptop'
-const price = parsed.catalog?.product?.price; // 999.99
-const currency = parsed.catalog?.product?.price?.['@currency']; // 'USD'
-const stock = parsed.catalog?.product?.stock; // 25
-const warehouse = parsed.catalog?.product?.stock?.['@warehouse']; // 'W01'
-```
-
-## XML Parser Output Reference
-
-### Understanding Parser Output Structure
-
-The XML parser transforms XML into JavaScript objects following these rules:
-
-**Root Element Becomes Top-Level Key:**
-```xml
-<root>
-  <data>value</data>
-</root>
-```
-**Output:**
-```javascript
-{
-  root: {
-    data: "value"
-  }
-}
-```
-
-**Attributes Prefixed with `@` (when `includeAttributes: true`):**
-```xml
-<product id="123" category="electronics">
-  <name>Laptop</name>
-</product>
-```
-**Output:**
-```javascript
-{
-  product: {
-    "@id": "123",
-    "@category": "electronics",
-    name: "Laptop"
-  }
-}
-```
-
-**Single vs Multiple Elements:**
-```xml
-<!-- Single element = object -->
-<products>
-  <product><sku>SKU-001</sku></product>
-</products>
-
-<!-- Multiple elements = array -->
-<products>
-  <product><sku>SKU-001</sku></product>
-  <product><sku>SKU-002</sku></product>
-</products>
-```
-**Output:**
-```javascript
-// Single
-{ products: { product: { sku: "SKU-001" } } }
-
-// Multiple
-{ products: { product: [{ sku: "SKU-001" }, { sku: "SKU-002" }] } }
-```
-
-**⚠️ Important:** Always normalize single elements to arrays:
-```typescript
-const products = parsed.products?.product;
-const records = Array.isArray(products) ? products : products ? [products] : [];
-```
-
-**Mixed Content (Attributes + Text):**
-```xml
-<price currency="USD">999.99</price>
-```
-**Output:**
-```javascript
-{
-  price: {
-    "@currency": "USD",
-    "#text": "999.99"  // Text content when element has attributes
-  }
-}
-```
-
-**Auto-Parsing (Default Behavior):**
-- Numbers: `"29.99"` → `29.99`
-- Booleans: `"true"` → `true`
-- Disable with: `parseNumbers: false`, `parseBooleans: false`
-
-## Accessing Parsed XML Data
-
-**For simple parsing:** Access the parsed structure directly using standard JavaScript property access.
-
-**For complex mapping:** Use `XMLPathResolver` from the mapping services layer (NOT exported from parsers). See `GraphQLMutationMapper` documentation for advanced path resolution with complex queries.
-
-### Path Syntax Reference (for reference only - use direct access for simple parsing)
-
-| Pattern                | Description        | XML Example                    | Path                  | Result         |
-| ---------------------- | ------------------ | ------------------------------ | --------------------- | -------------- |
-| `element`              | Element value      | `<sku>ABC123</sku>`            | `sku`                 | `'ABC123'`     |
-| `element@attr`         | Attribute value    | `<order id="123">`             | `order@id`            | `'123'`        |
-| `parent.child`         | Nested element     | `<order><ref>A1</ref></order>` | `order.ref`           | `'A1'`         |
-| `element[0]`           | Array index        | `<item>` repeated              | `items.item[0]`       | First item     |
-| `element.*`            | All array items    | `<item>` repeated              | `items.item.*`        | Array of all   |
-| `element[id=123]@attr` | Filter + attribute | With `id` attribute            | `item[id=123]@status` | Filtered value |
-
-### Working with Mixed Content
-
-When XML elements have both attributes and text content:
-
-```xml
-<price currency="USD">999.99</price>
-```
-
-```typescript
-// Direct access to parsed structure (recommended for simple parsing)
-const value = parsed.price; // 999.99
-const currency = parsed.price?.['@_currency']; // 'USD'
-
-// ℹ️ XMLPathResolver is part of the mapping services layer (not parsers)
-// For advanced path resolution with complex queries, see GraphQLMutationMapper documentation
-```
-
-### Best Practice
-
-```typescript
-// ✅ For simple parsing: Access parsed structure directly
-const orderDate = parsed.order?.['order-date']; // Simple and direct
-
-// ℹ️ For complex mapping with XMLPathResolver:
-// XMLPathResolver is part of the mapping services (NOT exported from parsers)
-// Import: import { GraphQLMutationMapper } from '@fluentcommerce/fc-connect-sdk';
-// See GraphQLMutationMapper documentation for advanced path resolution
-```
-
-## Generating XML from JSON
-
-The SDK provides `XMLBuilder` for creating XML from JavaScript objects.
-
-### Understanding the `#text` Pattern
-
-When generating XML, you use the `XMLBuilder` from `fast-xml-parser` with special keys:
-
-| JSON Key    | XML Output    | Purpose                    |
-| ----------- | ------------- | -------------------------- |
-| `@prefix`   | Attribute     | `<Order id="123">`         |
-| `#text`     | Text content  | `<ItemId>SKU001</ItemId>`  |
-| `fieldName` | Child element | `<Customer>...</Customer>` |
-
-**Why `#text`?** This is the standard convention used by `fast-xml-parser` to represent text content in JSON. When parsing XML, attributes use `@` prefix (e.g., `@id`), and when building XML, you use the same patterns.
-
-### Decision Tree - When to use `#text`:
-
-```
-Does the element have attributes?
-├─ NO  → Just use field name: "ItemId": "SKU001"
-│        Result: <ItemId>SKU001</ItemId>
-│
-└─ YES → Does it also have text content?
-    ├─ NO  → Just use @prefix: "@id": "123"
-    │        Result: <Order id="123"/>
-    │
-    └─ YES → Use BOTH @prefix AND #text
-             "@id": "9101", "#text": "MULTI-COLOR"
-             Result: <Color id="9101">MULTI-COLOR</Color>
-```
-
-### Simple XML Generation
-
-```typescript
-import { XMLBuilder } from 'fast-xml-parser';
-
-const builder = new XMLBuilder({
-  ignoreAttributes: false,
-  attributeNamePrefix: '@',
-  textNodeName: '#text',
-  format: true,
-  indentBy: '  ',
-});
-
-// Simple element with text
-const data = {
-  Order: {
-    ItemId: 'SKU001',
-  },
-};
-
-const xml = builder.build(data);
-// Output:
-// <Order>
-//   <ItemId>SKU001</ItemId>
-// </Order>
-```
-
-### XML with Attributes
-
-```typescript
-// Element with attributes only
-const data = {
-  Order: {
-    '@id': '12345',
-    '@status': 'confirmed',
-  },
-};
-
-const xml = builder.build(data);
-// Output:
-// <Order id="12345" status="confirmed"/>
-```
-
-### Mixed Content: Attributes AND Text
-
-**This is where `#text` is essential:**
-
-```typescript
-// Element with BOTH attribute AND text content
-const data = {
-  Color: {
-    '@id': '9101',
-    '#text': 'MULTI-COLOR',
-  },
-};
-
-const xml = builder.build(data);
-// Output:
-// <Product>
-//   <Color id="9101">MULTI-COLOR</Color>
-// </Product>
-```
-
-### Complex Example: Order with Multiple Patterns
-
-```typescript
-const orderData = {
-  Order: {
-    // Attributes on Order element
-    '@customerOrderId': '12345',
-    '@levelOfService': 'REGULAR',
-
-    // Child elements
-    Customer: {
-      '@customerId': '232',
-      Name: {
-        FirstName: 'John',
-        LastName: 'Doe',
-      },
-      EmailAddress: 'john@example.com',
-    },
-
-    // Element with attribute AND text
-    OrderSource: {
-      '@type': 'source',
-      '#text': 'WEBSTORE',
-    },
-
-    // Array of items
-    OrderItems: {
-      OrderItem: [
-        {
-          '@id': 'item1',
-          '@webLineId': '1',
-          ItemId: 'SKU001',
-          Quantity: 2,
-          Description: {
-            Description: 'Wireless Mouse',
-            Color: {
-              '@id': '9101',
-              '#text': 'Black',
-            },
-            Size: {
-              '@id': 'M',
-              '#text': 'Medium',
-            },
-          },
-        },
-      ],
-    },
-  },
-};
-
-const xml = builder.build(orderData, 'OrderDetailResponse');
-```
-
-**Generated XML:**
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<OrderDetailResponse>
-  <Order customerOrderId="12345" levelOfService="REGULAR">
-    <Customer customerId="232">
-      <Name>
-        <FirstName>John</FirstName>
-        <LastName>Doe</LastName>
-      </Name>
-      <EmailAddress>john@example.com</EmailAddress>
-    </Customer>
-    <OrderSource type="source">WEBSTORE</OrderSource>
-    <OrderItems>
-      <OrderItem id="item1" webLineId="1">
-        <ItemId>SKU001</ItemId>
-        <Quantity>2</Quantity>
-        <Description>
-          <Description>Wireless Mouse</Description>
-          <Color id="9101">Black</Color>
-          <Size id="M">Medium</Size>
-        </Description>
-      </OrderItem>
-    </OrderItems>
-  </Order>
-</OrderDetailResponse>
-```
-
-### Common Patterns Reference
-
-#### Pattern 1: Simple Text Element
-
-```typescript
-"ItemId": "SKU001"
-// → <ItemId>SKU001</ItemId>
-```
-
-#### Pattern 2: Attribute Only
-
-```typescript
-"DestinationTarget": {
-  "@ref": "dest-123"
-}
-// → <DestinationTarget ref="dest-123"/>
-```
-
-#### Pattern 3: Attribute + Text (`#text`)
-
-```typescript
-"Size": {
-  "@id": "1214",
-  "#text": "M 12.0/ W 14.0"
-}
-// → <Size id="1214">M 12.0/ W 14.0</Size>
-```
-
-#### Pattern 4: Nested Children
-
-```typescript
-"Customer": {
-  "@id": "232",
-  "Name": {
-    "FirstName": "John",
-    "LastName": "Doe"
-  }
-}
-// → <Customer id="232">
-//     <Name>
-//       <FirstName>John</FirstName>
-//       <LastName>Doe</LastName>
-//     </Name>
-//   </Customer>
-```
-
-#### Pattern 5: Arrays (Repeated Elements)
-
-```typescript
-"OrderItems": {
-  "OrderItem": [
-    { "ItemId": "SKU001" },
-    { "ItemId": "SKU002" }
-  ]
-}
-// → <OrderItems>
-//     <OrderItem><ItemId>SKU001</ItemId></OrderItem>
-//     <OrderItem><ItemId>SKU002</ItemId></OrderItem>
-//   </OrderItems>
-```
-
-## Streaming for Large Files
-
-Process large XML files efficiently:
-
-```typescript
-const largeXMLContent = `
-<?xml version="1.0" encoding="UTF-8"?>
-<products>
-  <product><sku>SKU001</sku><quantity>100</quantity></product>
-  <product><sku>SKU002</sku><quantity>200</quantity></product>
-  <!-- Thousands more products -->
-</products>
-`;
-
-async function processLargeXML() {
-  const xmlParser = new XMLParserService();
-
-  // Stream individual product elements
-  for await (const product of xmlParser.parseStreaming(largeXMLContent, {
-    itemPath: '//product', // XPath-like selector for repeating elements
-  })) {
-    console.log('Processing product:', product);
-
-    // Process each product individually to minimize memory usage
-    await processProduct(product);
-  }
-}
-
-async function processProduct(product: Record<string, unknown>) {
-  // Transform and send to Fluent Commerce
-  console.log(`Processing SKU: ${product.sku}`);
-}
-```
-
-## Configuration Options
-
-```typescript
-interface XMLParseOptions {
-  // Convert element names to lowercase
-  lowercaseKeys?: boolean;
-
-  // Normalize whitespace in text content
-  normalizeWhitespace?: boolean;
-
-  // Automatically parse numeric values
-  parseNumbers?: boolean;
-
-  // Automatically parse boolean values
-  parseBooleans?: boolean;
-
-  // Automatically parse attribute values (numbers/booleans)
-  parseAttributeValues?: boolean;
-
-  // Root element to start parsing from
-  rootElement?: string;
-
-  // Elements to always treat as arrays
-  arrayElements?: string[];
-
-  // Include XML attributes in output
-  includeAttributes?: boolean;
-
-  // Prefix for attribute keys (default: '@')
-  attributePrefix?: string;
-
-  // Key name for text content (default: '#text')
-  textKey?: string;
-
-  // Maximum parsing depth (default: 100)
-  maxDepth?: number;
-
-  // Whether to remove namespace prefixes
-  // Default: false (preserves namespaces like 'ns:element')
-  // When true: 'ns:element' becomes 'element'
-  removeNamespacePrefix?: boolean;
-}
-```
-
-### Example with All Options
-
-```typescript
-const options: XMLParseOptions = {
-  lowercaseKeys: true,
-  normalizeWhitespace: true,
-  parseNumbers: true,
-  parseBooleans: true,
-  rootElement: 'catalog',
-  arrayElements: ['product', 'category'],
-  includeAttributes: true,
-  attributePrefix: '_',
-  textKey: 'value',
-  maxDepth: 50,
-};
-
-const parsed = await xmlParser.parse(xmlContent, options);
-```
-
-## Transformation to Fluent Commerce Format
-
-### Inventory Update Example
-
-```typescript
-import { XMLParserService, UniversalMapper, createClient } from '@fluentcommerce/fc-connect-sdk';
-
-const xmlParser = new XMLParserService();
-const client = await createClient({ config });
-
-// XML from supplier
-const supplierXML = `
-<?xml version="1.0" encoding="UTF-8"?>
-<products>
-  <product>
-    <product_code>SUP-001</product_code>
-    <product_name>Wireless Mouse</product_name>
-    <stock_level>150</stock_level>
-    <warehouse_code>WH01</warehouse_code>
-  </product>
-</products>
-`;
-
-// Field mapping configuration
-const mappingConfig = {
-  fields: {
-    ref: {
-      source: 'product_code',
-      resolver: 'sdk.uppercase',
-      required: true,
-    },
-    name: {
-      source: 'product_name',
-    },
-    qty: {
-      source: 'stock_level',
-      resolver: 'sdk.parseInt',
-    },
-    locationRef: {
-      source: 'warehouse_code',
-    },
-  },
-};
-
-async function transformAndIngest() {
-  // Parse XML
-  const parsed = await xmlParser.parse(supplierXML);
-  const products = parsed.products?.product;
-
-  // Transform to Fluent format
-  const mapper = new UniversalMapper(mappingConfig);
-  const result = await mapper.map(products);
-
-  if (!result.success) {
-    console.error('Mapping errors:', result.errors);
-    throw new Error('Mapping failed');
-  }
-
-  // Send to Fluent Commerce (Batch API for INVENTORY only)
-  const job = await client.createJob({
-    name: 'xml-inventory-update',
-        retailerId: process.env.FLUENT_RETAILER_ID!,
-  });
-
-  await client.sendBatch(job.id, {
-    entities: result.data,
-  });
-}
-```
-
-### SFCC Order Integration with GraphQLMutationMapper
-
-For complex transformations like SFCC orders to Fluent GraphQL mutations:
-
-```typescript
-import {
-  XMLParserService,
-  GraphQLMutationMapper,
-  createClient,
-} from '@fluentcommerce/fc-connect-sdk';
-
-// SFCC order XML
-const sfccOrderXML = `<Order>...</Order>`;
-
-// XML → GraphQL mutation mapping
-const mappingConfig = {
-  mutation: 'createOrder',
-  rootPath: 'Order',
-  fields: {
-    ref: { xmlPath: '@customerOrderId', required: true },
-    type: { value: 'HD' },
-    retailerId: { value: '1' },
-    customer: {
-      email: { xmlPath: 'Customer.EmailAddress' },
-      firstName: { xmlPath: 'Customer.Name.FirstName' },
-      lastName: { xmlPath: 'Customer.Name.LastName' },
-    },
-    items: {
-      arrayPath: 'OrderItems.OrderItem',
-      fields: {
-        ref: { xmlPath: 'ItemId' },
-        quantity: { xmlPath: 'Quantity', resolver: 'sdk.parseInt' },
-        price: { xmlPath: 'Price', resolver: 'sdk.parseFloat' },
-      },
-    },
-  },
-};
-
-async function processSFCCOrder() {
-  // Parse XML
-  const xmlParser = new XMLParserService();
-  const parsed = await xmlParser.parse(sfccOrderXML);
-
-  // Transform to GraphQL mutation
-  const mapper = new GraphQLMutationMapper(mappingConfig);
-  const mutation = await mapper.map(parsed);
-
-  // Send to Fluent
-  const client = await createClient({ config });
-  const result = await client.graphql({
-    query: mutation.query,
-    variables: mutation.variables,
-  });
-
-  console.log('Order created:', result.data);
-}
-```
-
-## Error Handling
-
-```typescript
-import { FileParsingError } from '@fluentcommerce/fc-connect-sdk';
-
-async function robustXMLParsing(xmlContent: string) {
-  const xmlParser = new XMLParserService();
-
-  try {
-    // Validate first
-    const validation = xmlParser.validate(xmlContent);
-    if (!validation.valid) {
-      console.error('XML validation failed:', validation.errors);
-      return null;
-    }
-
-    // Parse with error handling
-    const parsed = await xmlParser.parse(xmlContent);
-    return parsed;
-  } catch (error) {
-    if (error instanceof FileParsingError) {
-      console.error('Parsing error:', error.message);
-      console.error('File:', error.fileName);
-      console.error('Context:', error.context);
-
-      // Handle specific error types
-      if (error.message.includes('Maximum depth exceeded')) {
-        console.error('XML structure too deep');
-      } else if (error.message.includes('Mismatched tags')) {
-        console.error('Malformed XML structure');
-      }
-    } else {
-      console.error('Unexpected error:', error);
-    }
-
-    return null;
-  }
-}
-```
-
-## Performance Considerations
-
-### Memory Management
-
-1. **Use Streaming for Large Files**: Process files over 10MB using streaming
-2. **Batch Processing**: Process items in batches to minimize memory usage
-3. **Selective Parsing**: Use selectors to parse only required elements
-
-```typescript
-// Memory-efficient processing
-async function processLargeInventoryFile(xmlContent: string) {
-  const xmlParser = new XMLParserService();
-
-  const batchSize = 100;
-  let batch = [];
-
-  for await (const item of xmlParser.parseStreaming(xmlContent, {
-    itemPath: '//product',
-  })) {
-    batch.push(item);
-
-    if (batch.length >= batchSize) {
-      await processBatch(batch);
-      batch = [];
-    }
-  }
-
-  // Process remaining items
-  if (batch.length > 0) {
-    await processBatch(batch);
-  }
-}
-```
-
-### Optimization Tips
-
-1. **Pre-validate XML**: Validate before parsing to avoid processing invalid data
-2. **Use Specific Selectors**: Target specific elements instead of parsing entire document
-3. **Disable Unused Features**: Turn off attribute parsing if not needed
-4. **Limit Parsing Depth**: Set maxDepth to prevent excessive recursion
-
-```typescript
-// Optimized parsing
-const optimizedOptions: XMLParseOptions = {
-  includeAttributes: false, // Skip if not needed
-  parseNumbers: false, // Skip automatic conversion
-  maxDepth: 10, // Limit recursion
-  normalizeWhitespace: false, // Skip if preserving formatting
-};
-```
-
-## Key Takeaways
-
-- 🎯 XML Parser handles hierarchical, tag-based data
-- 🎯 Access parsed structure directly for simple parsing (no special tools needed)
-- 🎯 Use `#text` key for elements with both attributes and text content
-- 🎯 Generate XML with `XMLBuilder` using `@prefix` for attributes
-- 🎯 Stream large files with `parseStreaming()` for memory efficiency
-- 🎯 Combine with `UniversalMapper` for simple transformations
-- 🎯 Use `GraphQLMutationMapper` (with XMLPathResolver) for complex SFCC order transformations
-
-## Practice Exercise
-
-**Challenge:** Parse this SFCC-style XML and transform it for Fluent:
-
-```xml
-<Order customerOrderId="ORD-12345">
-  <Customer>
-    <EmailAddress>customer@example.com</EmailAddress>
-    <Name>
-      <FirstName>John</FirstName>
-      <LastName>Doe</LastName>
-    </Name>
-  </Customer>
-  <OrderItems>
-    <OrderItem webLineId="1">
-      <ItemId>SKU001</ItemId>
-      <Quantity>2</Quantity>
-    </OrderItem>
-  </OrderItems>
-</Order>
-```
-
-**Requirements:**
-
-1. Parse the XML
-2. Extract orderId, customer email/name, items (using direct property access or GraphQLMutationMapper)
-3. Transform to Fluent format
-
-**Solution:** See [XML Examples](../examples/xml-parser-examples.ts)
-
-## Next Steps
-
-Continue to [Module 5: Parquet Parser →](./02-core-guides-parsers-05-parquet-parser.md) to learn columnar data parsing.
-
----
-
-**Module 4 Complete!** ✅
+# Module 4: XML Parser
+
+**Level:** Intermediate
+**Estimated Time:** 30 minutes
+
+## Overview
+
+This module covers the XML Parser (`XMLParserService`), essential for integrating with EDI feeds, B2B systems, and platforms like SFCC. You'll learn how to parse XML, handle attributes, use path resolution, generate XML from data, and integrate with SDK services.
+
+### Minimal Mode (start here)
+
+If you just need to parse XML, start with the simplest call:
+
+```typescript
+import { XMLParserService } from '@fluentcommerce/fc-connect-sdk';
+
+const parsed = await new XMLParserService().parse(xmlString, {
+  includeAttributes: false, // simplest shape
+  parseBooleans: true, // optional normalization
+  parseNumbers: true, // optional normalization
+});
+
+// Or use fast-xml-parser directly if you prefer; the SDK mapping works with any compatible shape.
+```
+
+Advanced options (attributes, selectors, streaming, path resolver) are optional—use only if needed.
+
+## Learning Objectives
+
+By the end of this module, you will:
+
+- ✅ Parse XML documents into JavaScript objects
+- ✅ Access elements and attributes directly from parsed structure
+- ✅ Generate XML from JavaScript objects using XMLBuilder
+- ✅ Handle large XML files with streaming
+- ✅ Transform XML data with UniversalMapper
+- ✅ Integrate with GraphQLMutationMapper for SFCC orders
+
+## What is XML?
+
+**XML (eXtensible Markup Language)** is a hierarchical markup format that:
+
+- Uses tags to define structure: `<element>value</element>`
+- Supports attributes: `<product id="123">`
+- Can represent complex nested data
+- Is self-describing with optional schemas
+
+**Example:**
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<products>
+  <product id="P001" category="electronics">
+    <sku>SKU001</sku>
+    <name>Wireless Mouse</name>
+    <price currency="USD">29.99</price>
+    <stock warehouse="WH-01">150</stock>
+  </product>
+</products>
+```
+
+## Basic XML Parsing
+
+### Simple Parsing
+
+```typescript
+import { XMLParserService } from '@fluentcommerce/fc-connect-sdk';
+
+const xmlParser = new XMLParserService();
+
+// Sample XML data
+const xmlContent = `
+<?xml version="1.0" encoding="UTF-8"?>
+<inventory>
+  <product>
+    <sku>SKU001</sku>
+    <name>Product 1</name>
+    <quantity>100</quantity>
+    <price>29.99</price>
+  </product>
+  <product>
+    <sku>SKU002</sku>
+    <name>Product 2</name>
+    <quantity>50</quantity>
+    <price>49.99</price>
+  </product>
+</inventory>
+`;
+
+// Parse XML
+const parsed = await xmlParser.parse(xmlContent);
+console.log('Parsed data:', parsed);
+
+// Access products
+const products = parsed.inventory?.product;
+console.log('Products:', products);
+```
+
+### Parsing with Attributes
+
+```typescript
+const xmlWithAttributes = `
+<?xml version="1.0" encoding="UTF-8"?>
+<catalog>
+  <product id="P001" category="electronics">
+    <name>Laptop</name>
+    <price currency="USD">999.99</price>
+    <stock warehouse="W01">25</stock>
+  </product>
+</catalog>
+`;
+
+const parsed = await xmlParser.parse(xmlWithAttributes);
+
+// Access attributes using @ prefix (NO underscore)
+// For simple parsing, access parsed structure directly
+const productId = parsed.catalog?.product?.['@id']; // 'P001'
+const category = parsed.catalog?.product?.['@category']; // 'electronics'
+const name = parsed.catalog?.product?.name; // 'Laptop'
+const price = parsed.catalog?.product?.price; // 999.99
+const currency = parsed.catalog?.product?.price?.['@currency']; // 'USD'
+const stock = parsed.catalog?.product?.stock; // 25
+const warehouse = parsed.catalog?.product?.stock?.['@warehouse']; // 'W01'
+```
+
+## XML Parser Output Reference
+
+### Understanding Parser Output Structure
+
+The XML parser transforms XML into JavaScript objects following these rules:
+
+**Root Element Becomes Top-Level Key:**
+```xml
+<root>
+  <data>value</data>
+</root>
+```
+**Output:**
+```javascript
+{
+  root: {
+    data: "value"
+  }
+}
+```
+
+**Attributes Prefixed with `@` (when `includeAttributes: true`):**
+```xml
+<product id="123" category="electronics">
+  <name>Laptop</name>
+</product>
+```
+**Output:**
+```javascript
+{
+  product: {
+    "@id": "123",
+    "@category": "electronics",
+    name: "Laptop"
+  }
+}
+```
+
+**Single vs Multiple Elements:**
+```xml
+<!-- Single element = object -->
+<products>
+  <product><sku>SKU-001</sku></product>
+</products>
+
+<!-- Multiple elements = array -->
+<products>
+  <product><sku>SKU-001</sku></product>
+  <product><sku>SKU-002</sku></product>
+</products>
+```
+**Output:**
+```javascript
+// Single
+{ products: { product: { sku: "SKU-001" } } }
+
+// Multiple
+{ products: { product: [{ sku: "SKU-001" }, { sku: "SKU-002" }] } }
+```
+
+**⚠️ Important:** Always normalize single elements to arrays:
+```typescript
+const products = parsed.products?.product;
+const records = Array.isArray(products) ? products : products ? [products] : [];
+```
+
+**Mixed Content (Attributes + Text):**
+```xml
+<price currency="USD">999.99</price>
+```
+**Output:**
+```javascript
+{
+  price: {
+    "@currency": "USD",
+    "#text": "999.99"  // Text content when element has attributes
+  }
+}
+```
+
+**Auto-Parsing (Default Behavior):**
+- Numbers: `"29.99"` → `29.99`
+- Booleans: `"true"` → `true`
+- Disable with: `parseNumbers: false`, `parseBooleans: false`
+
+## Accessing Parsed XML Data
+
+**For simple parsing:** Access the parsed structure directly using standard JavaScript property access.
+
+**For complex mapping:** Use `XMLPathResolver` from the mapping services layer (NOT exported from parsers). See `GraphQLMutationMapper` documentation for advanced path resolution with complex queries.
+
+### Path Syntax Reference (for reference only - use direct access for simple parsing)
+
+| Pattern                | Description        | XML Example                    | Path                  | Result         |
+| ---------------------- | ------------------ | ------------------------------ | --------------------- | -------------- |
+| `element`              | Element value      | `<sku>ABC123</sku>`            | `sku`                 | `'ABC123'`     |
+| `element@attr`         | Attribute value    | `<order id="123">`             | `order@id`            | `'123'`        |
+| `parent.child`         | Nested element     | `<order><ref>A1</ref></order>` | `order.ref`           | `'A1'`         |
+| `element[0]`           | Array index        | `<item>` repeated              | `items.item[0]`       | First item     |
+| `element.*`            | All array items    | `<item>` repeated              | `items.item.*`        | Array of all   |
+| `element[id=123]@attr` | Filter + attribute | With `id` attribute            | `item[id=123]@status` | Filtered value |
+
+### Working with Mixed Content
+
+When XML elements have both attributes and text content:
+
+```xml
+<price currency="USD">999.99</price>
+```
+
+```typescript
+// Direct access to parsed structure (recommended for simple parsing)
+const value = parsed.price; // 999.99
+const currency = parsed.price?.['@_currency']; // 'USD'
+
+// ℹ️ XMLPathResolver is part of the mapping services layer (not parsers)
+// For advanced path resolution with complex queries, see GraphQLMutationMapper documentation
+```
+
+### Best Practice
+
+```typescript
+// ✅ For simple parsing: Access parsed structure directly
+const orderDate = parsed.order?.['order-date']; // Simple and direct
+
+// ℹ️ For complex mapping with XMLPathResolver:
+// XMLPathResolver is part of the mapping services (NOT exported from parsers)
+// Import: import { GraphQLMutationMapper } from '@fluentcommerce/fc-connect-sdk';
+// See GraphQLMutationMapper documentation for advanced path resolution
+```
+
+## Generating XML from JSON
+
+The SDK provides `XMLBuilder` for creating XML from JavaScript objects.
+
+### Understanding the `#text` Pattern
+
+When generating XML, you use the `XMLBuilder` from `fast-xml-parser` with special keys:
+
+| JSON Key    | XML Output    | Purpose                    |
+| ----------- | ------------- | -------------------------- |
+| `@prefix`   | Attribute     | `<Order id="123">`         |
+| `#text`     | Text content  | `<ItemId>SKU001</ItemId>`  |
+| `fieldName` | Child element | `<Customer>...</Customer>` |
+
+**Why `#text`?** This is the standard convention used by `fast-xml-parser` to represent text content in JSON. When parsing XML, attributes use `@` prefix (e.g., `@id`), and when building XML, you use the same patterns.
+
+### Decision Tree - When to use `#text`:
+
+```
+Does the element have attributes?
+├─ NO  → Just use field name: "ItemId": "SKU001"
+│        Result: <ItemId>SKU001</ItemId>
+│
+└─ YES → Does it also have text content?
+    ├─ NO  → Just use @prefix: "@id": "123"
+    │        Result: <Order id="123"/>
+    │
+    └─ YES → Use BOTH @prefix AND #text
+             "@id": "9101", "#text": "MULTI-COLOR"
+             Result: <Color id="9101">MULTI-COLOR</Color>
+```
+
+### Simple XML Generation
+
+```typescript
+import { XMLBuilder } from 'fast-xml-parser';
+
+const builder = new XMLBuilder({
+  ignoreAttributes: false,
+  attributeNamePrefix: '@',
+  textNodeName: '#text',
+  format: true,
+  indentBy: '  ',
+});
+
+// Simple element with text
+const data = {
+  Order: {
+    ItemId: 'SKU001',
+  },
+};
+
+const xml = builder.build(data);
+// Output:
+// <Order>
+//   <ItemId>SKU001</ItemId>
+// </Order>
+```
+
+### XML with Attributes
+
+```typescript
+// Element with attributes only
+const data = {
+  Order: {
+    '@id': '12345',
+    '@status': 'confirmed',
+  },
+};
+
+const xml = builder.build(data);
+// Output:
+// <Order id="12345" status="confirmed"/>
+```
+
+### Mixed Content: Attributes AND Text
+
+**This is where `#text` is essential:**
+
+```typescript
+// Element with BOTH attribute AND text content
+const data = {
+  Color: {
+    '@id': '9101',
+    '#text': 'MULTI-COLOR',
+  },
+};
+
+const xml = builder.build(data);
+// Output:
+// <Product>
+//   <Color id="9101">MULTI-COLOR</Color>
+// </Product>
+```
+
+### Complex Example: Order with Multiple Patterns
+
+```typescript
+const orderData = {
+  Order: {
+    // Attributes on Order element
+    '@customerOrderId': '12345',
+    '@levelOfService': 'REGULAR',
+
+    // Child elements
+    Customer: {
+      '@customerId': '232',
+      Name: {
+        FirstName: 'John',
+        LastName: 'Doe',
+      },
+      EmailAddress: 'john@example.com',
+    },
+
+    // Element with attribute AND text
+    OrderSource: {
+      '@type': 'source',
+      '#text': 'WEBSTORE',
+    },
+
+    // Array of items
+    OrderItems: {
+      OrderItem: [
+        {
+          '@id': 'item1',
+          '@webLineId': '1',
+          ItemId: 'SKU001',
+          Quantity: 2,
+          Description: {
+            Description: 'Wireless Mouse',
+            Color: {
+              '@id': '9101',
+              '#text': 'Black',
+            },
+            Size: {
+              '@id': 'M',
+              '#text': 'Medium',
+            },
+          },
+        },
+      ],
+    },
+  },
+};
+
+const xml = builder.build(orderData, 'OrderDetailResponse');
+```
+
+**Generated XML:**
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<OrderDetailResponse>
+  <Order customerOrderId="12345" levelOfService="REGULAR">
+    <Customer customerId="232">
+      <Name>
+        <FirstName>John</FirstName>
+        <LastName>Doe</LastName>
+      </Name>
+      <EmailAddress>john@example.com</EmailAddress>
+    </Customer>
+    <OrderSource type="source">WEBSTORE</OrderSource>
+    <OrderItems>
+      <OrderItem id="item1" webLineId="1">
+        <ItemId>SKU001</ItemId>
+        <Quantity>2</Quantity>
+        <Description>
+          <Description>Wireless Mouse</Description>
+          <Color id="9101">Black</Color>
+          <Size id="M">Medium</Size>
+        </Description>
+      </OrderItem>
+    </OrderItems>
+  </Order>
+</OrderDetailResponse>
+```
+
+### Common Patterns Reference
+
+#### Pattern 1: Simple Text Element
+
+```typescript
+"ItemId": "SKU001"
+// → <ItemId>SKU001</ItemId>
+```
+
+#### Pattern 2: Attribute Only
+
+```typescript
+"DestinationTarget": {
+  "@ref": "dest-123"
+}
+// → <DestinationTarget ref="dest-123"/>
+```
+
+#### Pattern 3: Attribute + Text (`#text`)
+
+```typescript
+"Size": {
+  "@id": "1214",
+  "#text": "M 12.0/ W 14.0"
+}
+// → <Size id="1214">M 12.0/ W 14.0</Size>
+```
+
+#### Pattern 4: Nested Children
+
+```typescript
+"Customer": {
+  "@id": "232",
+  "Name": {
+    "FirstName": "John",
+    "LastName": "Doe"
+  }
+}
+// → <Customer id="232">
+//     <Name>
+//       <FirstName>John</FirstName>
+//       <LastName>Doe</LastName>
+//     </Name>
+//   </Customer>
+```
+
+#### Pattern 5: Arrays (Repeated Elements)
+
+```typescript
+"OrderItems": {
+  "OrderItem": [
+    { "ItemId": "SKU001" },
+    { "ItemId": "SKU002" }
+  ]
+}
+// → <OrderItems>
+//     <OrderItem><ItemId>SKU001</ItemId></OrderItem>
+//     <OrderItem><ItemId>SKU002</ItemId></OrderItem>
+//   </OrderItems>
+```
+
+## Streaming for Large Files
+
+Process large XML files efficiently:
+
+```typescript
+const largeXMLContent = `
+<?xml version="1.0" encoding="UTF-8"?>
+<products>
+  <product><sku>SKU001</sku><quantity>100</quantity></product>
+  <product><sku>SKU002</sku><quantity>200</quantity></product>
+  <!-- Thousands more products -->
+</products>
+`;
+
+async function processLargeXML() {
+  const xmlParser = new XMLParserService();
+
+  // Stream individual product elements
+  for await (const product of xmlParser.parseStreaming(largeXMLContent, {
+    itemPath: '//product', // XPath-like selector for repeating elements
+  })) {
+    console.log('Processing product:', product);
+
+    // Process each product individually to minimize memory usage
+    await processProduct(product);
+  }
+}
+
+async function processProduct(product: Record<string, unknown>) {
+  // Transform and send to Fluent Commerce
+  console.log(`Processing SKU: ${product.sku}`);
+}
+```
+
+## Configuration Options
+
+```typescript
+interface XMLParseOptions {
+  // Convert element names to lowercase
+  lowercaseKeys?: boolean;
+
+  // Normalize whitespace in text content
+  normalizeWhitespace?: boolean;
+
+  // Automatically parse numeric values
+  parseNumbers?: boolean;
+
+  // Automatically parse boolean values
+  parseBooleans?: boolean;
+
+  // Automatically parse attribute values (numbers/booleans)
+  parseAttributeValues?: boolean;
+
+  // Root element to start parsing from
+  rootElement?: string;
+
+  // Elements to always treat as arrays
+  arrayElements?: string[];
+
+  // Include XML attributes in output
+  includeAttributes?: boolean;
+
+  // Prefix for attribute keys (default: '@')
+  attributePrefix?: string;
+
+  // Key name for text content (default: '#text')
+  textKey?: string;
+
+  // Maximum parsing depth (default: 100)
+  maxDepth?: number;
+
+  // Whether to remove namespace prefixes
+  // Default: false (preserves namespaces like 'ns:element')
+  // When true: 'ns:element' becomes 'element'
+  removeNamespacePrefix?: boolean;
+}
+```
+
+### Example with All Options
+
+```typescript
+const options: XMLParseOptions = {
+  lowercaseKeys: true,
+  normalizeWhitespace: true,
+  parseNumbers: true,
+  parseBooleans: true,
+  rootElement: 'catalog',
+  arrayElements: ['product', 'category'],
+  includeAttributes: true,
+  attributePrefix: '_',
+  textKey: 'value',
+  maxDepth: 50,
+};
+
+const parsed = await xmlParser.parse(xmlContent, options);
+```
+
+## Transformation to Fluent Commerce Format
+
+### Inventory Update Example
+
+```typescript
+import { XMLParserService, UniversalMapper, createClient } from '@fluentcommerce/fc-connect-sdk';
+
+const xmlParser = new XMLParserService();
+const client = await createClient({ config });
+
+// XML from supplier
+const supplierXML = `
+<?xml version="1.0" encoding="UTF-8"?>
+<products>
+  <product>
+    <product_code>SUP-001</product_code>
+    <product_name>Wireless Mouse</product_name>
+    <stock_level>150</stock_level>
+    <warehouse_code>WH01</warehouse_code>
+  </product>
+</products>
+`;
+
+// Field mapping configuration
+const mappingConfig = {
+  fields: {
+    ref: {
+      source: 'product_code',
+      resolver: 'sdk.uppercase',
+      required: true,
+    },
+    name: {
+      source: 'product_name',
+    },
+    qty: {
+      source: 'stock_level',
+      resolver: 'sdk.parseInt',
+    },
+    locationRef: {
+      source: 'warehouse_code',
+    },
+  },
+};
+
+async function transformAndIngest() {
+  // Parse XML
+  const parsed = await xmlParser.parse(supplierXML);
+  const products = parsed.products?.product;
+
+  // Transform to Fluent format
+  const mapper = new UniversalMapper(mappingConfig);
+  const result = await mapper.map(products);
+
+  if (!result.success) {
+    console.error('Mapping errors:', result.errors);
+    throw new Error('Mapping failed');
+  }
+
+  // Send to Fluent Commerce (Batch API for INVENTORY only)
+  const job = await client.createJob({
+    name: 'xml-inventory-update',
+        retailerId: process.env.FLUENT_RETAILER_ID!,
+  });
+
+  await client.sendBatch(job.id, {
+    entities: result.data,
+  });
+}
+```
+
+### SFCC Order Integration with GraphQLMutationMapper
+
+For complex transformations like SFCC orders to Fluent GraphQL mutations:
+
+```typescript
+import {
+  XMLParserService,
+  GraphQLMutationMapper,
+  createClient,
+} from '@fluentcommerce/fc-connect-sdk';
+
+// SFCC order XML
+const sfccOrderXML = `<Order>...</Order>`;
+
+// XML → GraphQL mutation mapping
+const mappingConfig = {
+  mutation: 'createOrder',
+  rootPath: 'Order',
+  fields: {
+    ref: { xmlPath: '@customerOrderId', required: true },
+    type: { value: 'HD' },
+    retailerId: { value: '1' },
+    customer: {
+      email: { xmlPath: 'Customer.EmailAddress' },
+      firstName: { xmlPath: 'Customer.Name.FirstName' },
+      lastName: { xmlPath: 'Customer.Name.LastName' },
+    },
+    items: {
+      arrayPath: 'OrderItems.OrderItem',
+      fields: {
+        ref: { xmlPath: 'ItemId' },
+        quantity: { xmlPath: 'Quantity', resolver: 'sdk.parseInt' },
+        price: { xmlPath: 'Price', resolver: 'sdk.parseFloat' },
+      },
+    },
+  },
+};
+
+async function processSFCCOrder() {
+  // Parse XML
+  const xmlParser = new XMLParserService();
+  const parsed = await xmlParser.parse(sfccOrderXML);
+
+  // Transform to GraphQL mutation
+  const mapper = new GraphQLMutationMapper(mappingConfig);
+  const mutation = await mapper.map(parsed);
+
+  // Send to Fluent
+  const client = await createClient({ config });
+  const result = await client.graphql({
+    query: mutation.query,
+    variables: mutation.variables,
+  });
+
+  console.log('Order created:', result.data);
+}
+```
+
+## Error Handling
+
+```typescript
+import { FileParsingError } from '@fluentcommerce/fc-connect-sdk';
+
+async function robustXMLParsing(xmlContent: string) {
+  const xmlParser = new XMLParserService();
+
+  try {
+    // Validate first
+    const validation = xmlParser.validate(xmlContent);
+    if (!validation.valid) {
+      console.error('XML validation failed:', validation.errors);
+      return null;
+    }
+
+    // Parse with error handling
+    const parsed = await xmlParser.parse(xmlContent);
+    return parsed;
+  } catch (error) {
+    if (error instanceof FileParsingError) {
+      console.error('Parsing error:', error.message);
+      console.error('File:', error.fileName);
+      console.error('Context:', error.context);
+
+      // Handle specific error types
+      if (error.message.includes('Maximum depth exceeded')) {
+        console.error('XML structure too deep');
+      } else if (error.message.includes('Mismatched tags')) {
+        console.error('Malformed XML structure');
+      }
+    } else {
+      console.error('Unexpected error:', error);
+    }
+
+    return null;
+  }
+}
+```
+
+## Performance Considerations
+
+### Memory Management
+
+1. **Use Streaming for Large Files**: Process files over 10MB using streaming
+2. **Batch Processing**: Process items in batches to minimize memory usage
+3. **Selective Parsing**: Use selectors to parse only required elements
+
+```typescript
+// Memory-efficient processing
+async function processLargeInventoryFile(xmlContent: string) {
+  const xmlParser = new XMLParserService();
+
+  const batchSize = 100;
+  let batch = [];
+
+  for await (const item of xmlParser.parseStreaming(xmlContent, {
+    itemPath: '//product',
+  })) {
+    batch.push(item);
+
+    if (batch.length >= batchSize) {
+      await processBatch(batch);
+      batch = [];
+    }
+  }
+
+  // Process remaining items
+  if (batch.length > 0) {
+    await processBatch(batch);
+  }
+}
+```
+
+### Optimization Tips
+
+1. **Pre-validate XML**: Validate before parsing to avoid processing invalid data
+2. **Use Specific Selectors**: Target specific elements instead of parsing entire document
+3. **Disable Unused Features**: Turn off attribute parsing if not needed
+4. **Limit Parsing Depth**: Set maxDepth to prevent excessive recursion
+
+```typescript
+// Optimized parsing
+const optimizedOptions: XMLParseOptions = {
+  includeAttributes: false, // Skip if not needed
+  parseNumbers: false, // Skip automatic conversion
+  maxDepth: 10, // Limit recursion
+  normalizeWhitespace: false, // Skip if preserving formatting
+};
+```
+
+## Key Takeaways
+
+- 🎯 XML Parser handles hierarchical, tag-based data
+- 🎯 Access parsed structure directly for simple parsing (no special tools needed)
+- 🎯 Use `#text` key for elements with both attributes and text content
+- 🎯 Generate XML with `XMLBuilder` using `@prefix` for attributes
+- 🎯 Stream large files with `parseStreaming()` for memory efficiency
+- 🎯 Combine with `UniversalMapper` for simple transformations
+- 🎯 Use `GraphQLMutationMapper` (with XMLPathResolver) for complex SFCC order transformations
+
+## Practice Exercise
+
+**Challenge:** Parse this SFCC-style XML and transform it for Fluent:
+
+```xml
+<Order customerOrderId="ORD-12345">
+  <Customer>
+    <EmailAddress>customer@example.com</EmailAddress>
+    <Name>
+      <FirstName>John</FirstName>
+      <LastName>Doe</LastName>
+    </Name>
+  </Customer>
+  <OrderItems>
+    <OrderItem webLineId="1">
+      <ItemId>SKU001</ItemId>
+      <Quantity>2</Quantity>
+    </OrderItem>
+  </OrderItems>
+</Order>
+```
+
+**Requirements:**
+
+1. Parse the XML
+2. Extract orderId, customer email/name, items (using direct property access or GraphQLMutationMapper)
+3. Transform to Fluent format
+
+**Solution:** See [XML Examples](../examples/xml-parser-examples.ts)
+
+## Next Steps
+
+Continue to [Module 5: Parquet Parser →](./02-core-guides-parsers-05-parquet-parser.md) to learn columnar data parsing.
+
+---
+
+**Module 4 Complete!** ✅