@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/03-PATTERN-GUIDES/error-handling/modules/error-handling-03-utf8-handling.md

@@ -1,456 +1,456 @@
-# Module 3: UTF-8 and Special Character Handling
-
-**Level:** Intermediate
-**Estimated Time:** 20 minutes
-
-## Overview
-
-The SDK provides automatic handling of UTF-8 encoding, Byte Order Marks (BOM), and special characters. This module explains how the SDK processes these edge cases to prevent parsing errors and ensure data integrity.
-
-## Learning Objectives
-
-By the end of this module, you will:
-- ✅ Understand how the SDK handles UTF-8 encoding automatically
-- ✅ Know what a BOM is and how it's handled
-- ✅ Learn how special XML characters are escaped
-- ✅ Recognize when encoding errors might occur
-- ✅ Handle international characters correctly
-
-## UTF-8 Support
-
-### Automatic Preprocessing
-
-The SDK automatically handles UTF-8 encoding with BOM removal in the XML parser:
-
-```typescript
-// Automatic preprocessing in XMLParserService
-private preprocessXML(xmlContent: string): string {
-  // Remove BOM (Byte Order Mark) if present
-  let cleaned = xmlContent.replace(/^\uFEFF/, '');
-
-  // Normalize line endings (Windows/Unix/Mac)
-  cleaned = cleaned.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
-
-  // Remove XML comments
-  cleaned = cleaned.replace(/<!--[\s\S]*?-->/g, '');
-
-  return cleaned.trim();
-}
-```
-
-### Supported Encodings
-
-The SDK supports the following encodings:
-
-| Encoding | Support | BOM Handling |
-|----------|---------|--------------|
-| ✅ UTF-8 (standard) | Full | N/A |
-| ✅ UTF-8 with BOM | Full | Automatic removal |
-| ✅ Unicode characters | Full | Direct support |
-| ❌ UTF-16 | Not supported | Convert to UTF-8 first |
-| ❌ ISO-8859-1 (Latin-1) | Not supported | Convert to UTF-8 first |
-
-### What is a BOM?
-
-A **BOM (Byte Order Mark)** is a special Unicode character (`U+FEFF`) that can appear at the start of a file to indicate:
-- The encoding used (UTF-8, UTF-16, etc.)
-- The byte order (big-endian or little-endian)
-
-**Example BOM in UTF-8**:
-```
-Hex: EF BB BF
-Character: U+FEFF
-```
-
-**Why BOMs cause problems**:
-- XML parsers may fail if BOM is present
-- BOM appears as invisible character in text editors
-- Can cause "unexpected character" errors
-
-**SDK Solution**: Automatically removes BOM before parsing
-
-## Unicode Character Support
-
-### International Characters
-
-The SDK fully supports Unicode characters:
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<order>
-  <customer>
-    <name>José García</name>
-    <email>josé@example.com</email>
-    <address>
-      <city>São Paulo</city>
-      <country>Brasil</country>
-    </address>
-  </customer>
-</order>
-```
-
-✅ **Result**: Parses correctly, all characters preserved
-
-### Emoji and Special Symbols
-
-```xml
-<order>
-  <customer>
-    <name>Customer 🎉</name>
-    <notes>Happy customer! ⭐⭐⭐⭐⭐</notes>
-  </customer>
-</order>
-```
-
-✅ **Result**: Parses correctly, emoji preserved
-
-### Chinese, Arabic, and Other Scripts
-
-```xml
-<order>
-  <customer>
-    <name>李明</name>              <!-- Chinese -->
-    <name>محمد علي</name>         <!-- Arabic -->
-    <name>Иван Петров</name>      <!-- Russian -->
-  </customer>
-</order>
-```
-
-✅ **Result**: All scripts parse correctly
-
-## Special Character Escaping
-
-### XML Special Characters
-
-XML has five special characters that must be escaped when used in text content:
-
-| Character | Escaped Form | Description |
-|-----------|--------------|-------------|
-| `&` | `&amp;` | Ampersand |
-| `<` | `&lt;` | Less than |
-| `>` | `&gt;` | Greater than |
-| `"` | `&quot;` | Double quote |
-| `'` | `&apos;` | Single quote (apostrophe) |
-
-### Automatic Escaping
-
-The SDK automatically escapes special characters when building XML:
-
-```typescript
-private escapeXML(str: string): string {
-  return str
-    .replace(/&/g, '&amp;')     // & → &amp;
-    .replace(/</g, '&lt;')      // < → &lt;
-    .replace(/>/g, '&gt;')      // > → &gt;
-    .replace(/"/g, '&quot;')    // " → &quot;
-    .replace(/'/g, '&apos;');   // ' → &apos;
-}
-```
-
-### Examples of Escaping
-
-| Input Value | Parsed Value | XML Output |
-|-------------|--------------|------------|
-| `Tom & Jerry` | `Tom & Jerry` | `Tom &amp; Jerry` |
-| `Price < $10` | `Price < $10` | `Price &lt; $10` |
-| `Size > 5"` | `Size > 5"` | `Size &gt; 5&quot;` |
-| `It's working` | `It's working` | `It&apos;s working` |
-| `<script>alert()</script>` | `<script>alert()</script>` | `&lt;script&gt;alert()&lt;/script&gt;` |
-
-### Complex Example
-
-```xml
-<order>
-  <customer>
-    <name>O'Reilly & Associates</name>
-    <notes>Items: "Book" & "DVD" (Price < $50)</notes>
-  </customer>
-</order>
-```
-
-**Parsed values**:
-```javascript
-{
-  customer: {
-    name: "O'Reilly & Associates",
-    notes: 'Items: "Book" & "DVD" (Price < $50)'
-  }
-}
-```
-
-**XML output** (if rebuilding):
-```xml
-<customer>
-  <name>O&apos;Reilly &amp; Associates</name>
-  <notes>Items: &quot;Book&quot; &amp; &quot;DVD&quot; (Price &lt; $50)</notes>
-</customer>
-```
-
-## Encoding Errors
-
-### When Encoding Errors Occur
-
-Encoding errors can occur when:
-1. File is not actually UTF-8 (e.g., ISO-8859-1, Windows-1252)
-2. File contains invalid byte sequences
-3. File is corrupted
-4. BOM doesn't match actual encoding
-
-### Example: Invalid UTF-8 Sequence
-
-```xml
-<!-- File saved as ISO-8859-1, not UTF-8 -->
-<order>
-  <customer>
-    <name>Café</name>  <!-- é encoded as 0xE9 (ISO-8859-1), not valid UTF-8 -->
-  </customer>
-</order>
-```
-
-**Result**:
-```typescript
-FileParsingError: Failed to parse XML: Invalid character encoding
-  code: ENCODING_ERROR
-  fileName: "order.xml"
-  context: {
-    position: 45,
-    character: "é"
-  }
-```
-
-**Solution**: Re-save file as UTF-8 or convert encoding:
-
-```bash
-# Convert ISO-8859-1 to UTF-8
-iconv -f ISO-8859-1 -t UTF-8 order.xml > order-utf8.xml
-```
-
-### Example: BOM Mismatch
-
-```xml
-<!-- UTF-16 BOM (FF FE) but file is UTF-8 -->
-<?xml version="1.0" encoding="UTF-8"?>
-<order>...</order>
-```
-
-**Result**:
-```typescript
-FileParsingError: Failed to parse XML: Encoding mismatch
-  code: ENCODING_ERROR
-```
-
-**Solution**: Ensure BOM matches actual encoding or remove BOM
-
-## Handling Encoding Errors
-
-### Detection
-
-```typescript
-import { FileParsingError, IngestionErrorCode } from '@fluentcommerce/fc-connect-sdk';
-
-try {
-  const parsed = await parser.parse(xmlContent);
-} catch (error) {
-  if (error instanceof FileParsingError &&
-      error.code === IngestionErrorCode.ENCODING_ERROR) {
-
-    // Encoding error detected
-    logger.error('File encoding issue:', {
-      fileName: error.fileName,
-      message: error.message
-    });
-
-    // Suggest fix to user
-    console.error(
-      'File appears to be in wrong encoding. ' +
-      'Please ensure file is saved as UTF-8.'
-    );
-  }
-}
-```
-
-### Automatic Conversion (Node.js)
-
-```typescript
-import { readFile } from 'fs/promises';
-import { decode } from 'iconv-lite';
-
-async function parseWithEncodingDetection(filePath: string) {
-  // Read file as buffer
-  const buffer = await readFile(filePath);
-
-  // Try UTF-8 first
-  try {
-    const utf8Content = buffer.toString('utf8');
-    return await parser.parse(utf8Content);
-  } catch (error) {
-    // If UTF-8 fails, try ISO-8859-1
-    try {
-      const isoContent = decode(buffer, 'ISO-8859-1');
-      return await parser.parse(isoContent);
-    } catch (error2) {
-      // If both fail, throw original error
-      throw error;
-    }
-  }
-}
-```
-
-## Best Practices
-
-### 1. Always Use UTF-8
-
-```typescript
-// ✅ CORRECT - Ensure files are UTF-8
-const xmlContent = await readFile('order.xml', 'utf8');
-
-// ❌ WRONG - Default encoding might not be UTF-8
-const xmlContent = await readFile('order.xml');  // Uses system default
-```
-
-### 2. Specify Encoding in XML Declaration
-
-```xml
-<!-- ✅ CORRECT - Explicit encoding declaration -->
-<?xml version="1.0" encoding="UTF-8"?>
-<order>...</order>
-
-<!-- ❌ WRONG - No encoding declaration -->
-<?xml version="1.0"?>
-<order>...</order>
-```
-
-### 3. Remove BOM When Possible
-
-Many text editors can save files without BOM:
-
-- **VS Code**: File → Preferences → Settings → "files.encoding" → "UTF-8"
-- **Notepad++**: Encoding → Encode in UTF-8 (without BOM)
-- **Sublime Text**: File → Save with Encoding → UTF-8
-
-### 4. Validate Encoding Before Processing
-
-```typescript
-function validateUTF8(buffer: Buffer): boolean {
-  try {
-    buffer.toString('utf8');
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-// Usage
-const fileBuffer = await readFile('order.xml');
-if (!validateUTF8(fileBuffer)) {
-  throw new Error('File is not valid UTF-8');
-}
-```
-
-### 5. Handle Special Characters Correctly
-
-```typescript
-// ✅ CORRECT - SDK handles escaping automatically
-const data = {
-  name: "O'Reilly & Associates",
-  notes: 'Price < $10'
-};
-// SDK automatically escapes when building XML/GraphQL
-
-// ❌ WRONG - Manual escaping not needed
-const data = {
-  name: "O&apos;Reilly &amp; Associates",  // Double-escaped!
-  notes: 'Price &lt; $10'
-};
-```
-
-## Common Issues and Solutions
-
-### Issue 1: "Unexpected character" Error
-
-**Symptom**:
-```
-FileParsingError: Unexpected character at position 0
-```
-
-**Cause**: BOM present at start of file
-
-**Solution**: SDK automatically removes BOM - no action needed. If error persists, file may be corrupted.
-
-### Issue 2: Garbled Characters in Output
-
-**Symptom**:
-```
-Customer name: "José García"  // Should be "José García"
-```
-
-**Cause**: File saved as ISO-8859-1 but read as UTF-8
-
-**Solution**: Re-save file as UTF-8 or convert encoding
-
-### Issue 3: Special Characters Cause Parse Error
-
-**Symptom**:
-```
-FileParsingError: Mismatched opening and closing tags
-```
-
-**Cause**: Unescaped `<` or `>` in text content
-
-**Solution**: SDK automatically escapes when building XML. If parsing existing XML, ensure it's valid.
-
-## Practice Exercise
-
-Create a function that handles UTF-8 files with or without BOM:
-
-```typescript
-import { XMLParserService, FileParsingError } from '@fluentcommerce/fc-connect-sdk';
-import { readFile } from 'fs/promises';
-
-async function parseUTF8File(filePath: string) {
-  try {
-    // Read file as UTF-8
-    const content = await readFile(filePath, 'utf8');
-
-    // SDK automatically removes BOM if present
-    const parser = new XMLParserService();
-    const result = await parser.parse(content);
-
-    console.log('✅ File parsed successfully');
-    return result;
-
-  } catch (error) {
-    if (error instanceof FileParsingError) {
-      console.error('❌ Parse error:', {
-        code: error.code,
-        message: error.message,
-        fileName: error.fileName
-      });
-
-      // Provide helpful error message
-      if (error.code === 'ENCODING_ERROR') {
-        console.error('Hint: Ensure file is saved as UTF-8');
-      }
-    }
-    throw error;
-  }
-}
-```
-
-## Key Takeaways
-
-- 🎯 SDK automatically removes UTF-8 BOM - no manual handling needed
-- 🎯 All Unicode characters are supported (emoji, Chinese, Arabic, etc.)
-- 🎯 XML special characters are automatically escaped when building XML
-- 🎯 Files should be saved as UTF-8 encoding
-- 🎯 Encoding errors are permanent - don't retry
-- 🎯 Include encoding declaration in XML: `<?xml version="1.0" encoding="UTF-8"?>`
-
-## Next Steps
-
-Continue to [Module 4: Error Scenarios →](./error-handling-04-error-scenarios.md) to see real-world examples of error handling.
-
----
-
-**Previous:** [← Module 2: Error Types](./error-handling-02-error-types.md)
-**Next:** [Module 4: Error Scenarios →](./error-handling-04-error-scenarios.md)
+# Module 3: UTF-8 and Special Character Handling
+
+**Level:** Intermediate
+**Estimated Time:** 20 minutes
+
+## Overview
+
+The SDK provides automatic handling of UTF-8 encoding, Byte Order Marks (BOM), and special characters. This module explains how the SDK processes these edge cases to prevent parsing errors and ensure data integrity.
+
+## Learning Objectives
+
+By the end of this module, you will:
+- ✅ Understand how the SDK handles UTF-8 encoding automatically
+- ✅ Know what a BOM is and how it's handled
+- ✅ Learn how special XML characters are escaped
+- ✅ Recognize when encoding errors might occur
+- ✅ Handle international characters correctly
+
+## UTF-8 Support
+
+### Automatic Preprocessing
+
+The SDK automatically handles UTF-8 encoding with BOM removal in the XML parser:
+
+```typescript
+// Automatic preprocessing in XMLParserService
+private preprocessXML(xmlContent: string): string {
+  // Remove BOM (Byte Order Mark) if present
+  let cleaned = xmlContent.replace(/^\uFEFF/, '');
+
+  // Normalize line endings (Windows/Unix/Mac)
+  cleaned = cleaned.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+
+  // Remove XML comments
+  cleaned = cleaned.replace(/<!--[\s\S]*?-->/g, '');
+
+  return cleaned.trim();
+}
+```
+
+### Supported Encodings
+
+The SDK supports the following encodings:
+
+| Encoding | Support | BOM Handling |
+|----------|---------|--------------|
+| ✅ UTF-8 (standard) | Full | N/A |
+| ✅ UTF-8 with BOM | Full | Automatic removal |
+| ✅ Unicode characters | Full | Direct support |
+| ❌ UTF-16 | Not supported | Convert to UTF-8 first |
+| ❌ ISO-8859-1 (Latin-1) | Not supported | Convert to UTF-8 first |
+
+### What is a BOM?
+
+A **BOM (Byte Order Mark)** is a special Unicode character (`U+FEFF`) that can appear at the start of a file to indicate:
+- The encoding used (UTF-8, UTF-16, etc.)
+- The byte order (big-endian or little-endian)
+
+**Example BOM in UTF-8**:
+```
+Hex: EF BB BF
+Character: U+FEFF
+```
+
+**Why BOMs cause problems**:
+- XML parsers may fail if BOM is present
+- BOM appears as invisible character in text editors
+- Can cause "unexpected character" errors
+
+**SDK Solution**: Automatically removes BOM before parsing
+
+## Unicode Character Support
+
+### International Characters
+
+The SDK fully supports Unicode characters:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<order>
+  <customer>
+    <name>José García</name>
+    <email>josé@example.com</email>
+    <address>
+      <city>São Paulo</city>
+      <country>Brasil</country>
+    </address>
+  </customer>
+</order>
+```
+
+✅ **Result**: Parses correctly, all characters preserved
+
+### Emoji and Special Symbols
+
+```xml
+<order>
+  <customer>
+    <name>Customer 🎉</name>
+    <notes>Happy customer! ⭐⭐⭐⭐⭐</notes>
+  </customer>
+</order>
+```
+
+✅ **Result**: Parses correctly, emoji preserved
+
+### Chinese, Arabic, and Other Scripts
+
+```xml
+<order>
+  <customer>
+    <name>李明</name>              <!-- Chinese -->
+    <name>محمد علي</name>         <!-- Arabic -->
+    <name>Иван Петров</name>      <!-- Russian -->
+  </customer>
+</order>
+```
+
+✅ **Result**: All scripts parse correctly
+
+## Special Character Escaping
+
+### XML Special Characters
+
+XML has five special characters that must be escaped when used in text content:
+
+| Character | Escaped Form | Description |
+|-----------|--------------|-------------|
+| `&` | `&amp;` | Ampersand |
+| `<` | `&lt;` | Less than |
+| `>` | `&gt;` | Greater than |
+| `"` | `&quot;` | Double quote |
+| `'` | `&apos;` | Single quote (apostrophe) |
+
+### Automatic Escaping
+
+The SDK automatically escapes special characters when building XML:
+
+```typescript
+private escapeXML(str: string): string {
+  return str
+    .replace(/&/g, '&amp;')     // & → &amp;
+    .replace(/</g, '&lt;')      // < → &lt;
+    .replace(/>/g, '&gt;')      // > → &gt;
+    .replace(/"/g, '&quot;')    // " → &quot;
+    .replace(/'/g, '&apos;');   // ' → &apos;
+}
+```
+
+### Examples of Escaping
+
+| Input Value | Parsed Value | XML Output |
+|-------------|--------------|------------|
+| `Tom & Jerry` | `Tom & Jerry` | `Tom &amp; Jerry` |
+| `Price < $10` | `Price < $10` | `Price &lt; $10` |
+| `Size > 5"` | `Size > 5"` | `Size &gt; 5&quot;` |
+| `It's working` | `It's working` | `It&apos;s working` |
+| `<script>alert()</script>` | `<script>alert()</script>` | `&lt;script&gt;alert()&lt;/script&gt;` |
+
+### Complex Example
+
+```xml
+<order>
+  <customer>
+    <name>O'Reilly & Associates</name>
+    <notes>Items: "Book" & "DVD" (Price < $50)</notes>
+  </customer>
+</order>
+```
+
+**Parsed values**:
+```javascript
+{
+  customer: {
+    name: "O'Reilly & Associates",
+    notes: 'Items: "Book" & "DVD" (Price < $50)'
+  }
+}
+```
+
+**XML output** (if rebuilding):
+```xml
+<customer>
+  <name>O&apos;Reilly &amp; Associates</name>
+  <notes>Items: &quot;Book&quot; &amp; &quot;DVD&quot; (Price &lt; $50)</notes>
+</customer>
+```
+
+## Encoding Errors
+
+### When Encoding Errors Occur
+
+Encoding errors can occur when:
+1. File is not actually UTF-8 (e.g., ISO-8859-1, Windows-1252)
+2. File contains invalid byte sequences
+3. File is corrupted
+4. BOM doesn't match actual encoding
+
+### Example: Invalid UTF-8 Sequence
+
+```xml
+<!-- File saved as ISO-8859-1, not UTF-8 -->
+<order>
+  <customer>
+    <name>Café</name>  <!-- é encoded as 0xE9 (ISO-8859-1), not valid UTF-8 -->
+  </customer>
+</order>
+```
+
+**Result**:
+```typescript
+FileParsingError: Failed to parse XML: Invalid character encoding
+  code: ENCODING_ERROR
+  fileName: "order.xml"
+  context: {
+    position: 45,
+    character: "é"
+  }
+```
+
+**Solution**: Re-save file as UTF-8 or convert encoding:
+
+```bash
+# Convert ISO-8859-1 to UTF-8
+iconv -f ISO-8859-1 -t UTF-8 order.xml > order-utf8.xml
+```
+
+### Example: BOM Mismatch
+
+```xml
+<!-- UTF-16 BOM (FF FE) but file is UTF-8 -->
+<?xml version="1.0" encoding="UTF-8"?>
+<order>...</order>
+```
+
+**Result**:
+```typescript
+FileParsingError: Failed to parse XML: Encoding mismatch
+  code: ENCODING_ERROR
+```
+
+**Solution**: Ensure BOM matches actual encoding or remove BOM
+
+## Handling Encoding Errors
+
+### Detection
+
+```typescript
+import { FileParsingError, IngestionErrorCode } from '@fluentcommerce/fc-connect-sdk';
+
+try {
+  const parsed = await parser.parse(xmlContent);
+} catch (error) {
+  if (error instanceof FileParsingError &&
+      error.code === IngestionErrorCode.ENCODING_ERROR) {
+
+    // Encoding error detected
+    logger.error('File encoding issue:', {
+      fileName: error.fileName,
+      message: error.message
+    });
+
+    // Suggest fix to user
+    console.error(
+      'File appears to be in wrong encoding. ' +
+      'Please ensure file is saved as UTF-8.'
+    );
+  }
+}
+```
+
+### Automatic Conversion (Node.js)
+
+```typescript
+import { readFile } from 'fs/promises';
+import { decode } from 'iconv-lite';
+
+async function parseWithEncodingDetection(filePath: string) {
+  // Read file as buffer
+  const buffer = await readFile(filePath);
+
+  // Try UTF-8 first
+  try {
+    const utf8Content = buffer.toString('utf8');
+    return await parser.parse(utf8Content);
+  } catch (error) {
+    // If UTF-8 fails, try ISO-8859-1
+    try {
+      const isoContent = decode(buffer, 'ISO-8859-1');
+      return await parser.parse(isoContent);
+    } catch (error2) {
+      // If both fail, throw original error
+      throw error;
+    }
+  }
+}
+```
+
+## Best Practices
+
+### 1. Always Use UTF-8
+
+```typescript
+// ✅ CORRECT - Ensure files are UTF-8
+const xmlContent = await readFile('order.xml', 'utf8');
+
+// ❌ WRONG - Default encoding might not be UTF-8
+const xmlContent = await readFile('order.xml');  // Uses system default
+```
+
+### 2. Specify Encoding in XML Declaration
+
+```xml
+<!-- ✅ CORRECT - Explicit encoding declaration -->
+<?xml version="1.0" encoding="UTF-8"?>
+<order>...</order>
+
+<!-- ❌ WRONG - No encoding declaration -->
+<?xml version="1.0"?>
+<order>...</order>
+```
+
+### 3. Remove BOM When Possible
+
+Many text editors can save files without BOM:
+
+- **VS Code**: File → Preferences → Settings → "files.encoding" → "UTF-8"
+- **Notepad++**: Encoding → Encode in UTF-8 (without BOM)
+- **Sublime Text**: File → Save with Encoding → UTF-8
+
+### 4. Validate Encoding Before Processing
+
+```typescript
+function validateUTF8(buffer: Buffer): boolean {
+  try {
+    buffer.toString('utf8');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Usage
+const fileBuffer = await readFile('order.xml');
+if (!validateUTF8(fileBuffer)) {
+  throw new Error('File is not valid UTF-8');
+}
+```
+
+### 5. Handle Special Characters Correctly
+
+```typescript
+// ✅ CORRECT - SDK handles escaping automatically
+const data = {
+  name: "O'Reilly & Associates",
+  notes: 'Price < $10'
+};
+// SDK automatically escapes when building XML/GraphQL
+
+// ❌ WRONG - Manual escaping not needed
+const data = {
+  name: "O&apos;Reilly &amp; Associates",  // Double-escaped!
+  notes: 'Price &lt; $10'
+};
+```
+
+## Common Issues and Solutions
+
+### Issue 1: "Unexpected character" Error
+
+**Symptom**:
+```
+FileParsingError: Unexpected character at position 0
+```
+
+**Cause**: BOM present at start of file
+
+**Solution**: SDK automatically removes BOM - no action needed. If error persists, file may be corrupted.
+
+### Issue 2: Garbled Characters in Output
+
+**Symptom**:
+```
+Customer name: "José García"  // Should be "José García"
+```
+
+**Cause**: File saved as ISO-8859-1 but read as UTF-8
+
+**Solution**: Re-save file as UTF-8 or convert encoding
+
+### Issue 3: Special Characters Cause Parse Error
+
+**Symptom**:
+```
+FileParsingError: Mismatched opening and closing tags
+```
+
+**Cause**: Unescaped `<` or `>` in text content
+
+**Solution**: SDK automatically escapes when building XML. If parsing existing XML, ensure it's valid.
+
+## Practice Exercise
+
+Create a function that handles UTF-8 files with or without BOM:
+
+```typescript
+import { XMLParserService, FileParsingError } from '@fluentcommerce/fc-connect-sdk';
+import { readFile } from 'fs/promises';
+
+async function parseUTF8File(filePath: string) {
+  try {
+    // Read file as UTF-8
+    const content = await readFile(filePath, 'utf8');
+
+    // SDK automatically removes BOM if present
+    const parser = new XMLParserService();
+    const result = await parser.parse(content);
+
+    console.log('✅ File parsed successfully');
+    return result;
+
+  } catch (error) {
+    if (error instanceof FileParsingError) {
+      console.error('❌ Parse error:', {
+        code: error.code,
+        message: error.message,
+        fileName: error.fileName
+      });
+
+      // Provide helpful error message
+      if (error.code === 'ENCODING_ERROR') {
+        console.error('Hint: Ensure file is saved as UTF-8');
+      }
+    }
+    throw error;
+  }
+}
+```
+
+## Key Takeaways
+
+- 🎯 SDK automatically removes UTF-8 BOM - no manual handling needed
+- 🎯 All Unicode characters are supported (emoji, Chinese, Arabic, etc.)
+- 🎯 XML special characters are automatically escaped when building XML
+- 🎯 Files should be saved as UTF-8 encoding
+- 🎯 Encoding errors are permanent - don't retry
+- 🎯 Include encoding declaration in XML: `<?xml version="1.0" encoding="UTF-8"?>`
+
+## Next Steps
+
+Continue to [Module 4: Error Scenarios →](./error-handling-04-error-scenarios.md) to see real-world examples of error handling.
+
+---
+
+**Previous:** [← Module 2: Error Types](./error-handling-02-error-types.md)
+**Next:** [Module 4: Error Scenarios →](./error-handling-04-error-scenarios.md)