@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

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

@@ -1,362 +1,362 @@
-# Module 1: Foundations
-
-**Level:** Beginner
-**Estimated Time:** 15 minutes
-
-## Overview
-
-This module covers the fundamental principles of error handling in the Fluent Connect SDK, including the fail-fast philosophy that ensures data integrity by preventing partial or corrupt data from being created.
-
-## Learning Objectives
-
-By the end of this module, you will:
-- ✅ Understand the fail-fast error handling philosophy
-- ✅ Know why preventing partial data is critical
-- ✅ Understand the error propagation chain
-- ✅ Recognize the three core principles of SDK error handling
-
-## The Fail-Fast Philosophy
-
-### The Problem: Partial Data Corruption
-
-In traditional error handling, errors might occur after some data has already been written:
-
-```typescript
-// ❌ RISKY: Without fail-fast protection
-async function processOrder(data: any) {
-  const order = await createOrder(data.order);           // ✅ Created
-  const customer = await createCustomer(data.customer);  // ✅ Created
-  const items = await createItems(data.items);           // ❌ FAILS HERE!
-
-  // Now what? Order and customer exist, but items don't
-  // Partial data = corrupt state = data integrity violation
-}
-```
-
-**Result**: You have an order and customer in Fluent, but no items. Your data is now in an inconsistent state.
-
-### The Solution: Fail-Fast Guarantee
-
-The SDK prevents this by **validating everything before executing any mutations**:
-
-```typescript
-// ✅ SAFE: With fail-fast protection
-async function processOrder(xmlContent: string) {
-  try {
-    // Step 1: Parse XML (validate structure)
-    const parsed = await parser.parse(xmlContent);
-
-    // Step 2: Map to mutation variables (validate fields)
-    const payload = await mapper.map(parsed);
-
-    // Step 3: Execute mutation (ONLY if Steps 1 and 2 succeed)
-    const result = await client.graphql(payload);
-
-    return result.data;  // ✅ Complete data or nothing
-
-  } catch (error) {
-    // Error at ANY step = NO data sent to Fluent
-    // NO partial records, NO corrupt data
-    throw error;
-  }
-}
-```
-
-**Result**: Either all data is created successfully, or nothing is created. No partial state possible.
-
-## The Fail-Fast Guarantee
-
-### What It Means
-
-**When any error occurs during parsing, mapping, or validation, the GraphQL mutation is NEVER sent to Fluent Commerce.**
-
-This means:
-- ✅ No partial data created
-- ✅ No orphaned records
-- ✅ No data integrity violations
-- ✅ No manual cleanup required
-- ✅ Predictable error states
-
-### When Errors Are Caught
-
-```
-┌─────────────────────────────────────────────────────┐
-│ VALIDATION PHASE (No data sent to Fluent)          │
-├─────────────────────────────────────────────────────┤
-│                                                     │
-│  Parse XML/JSON/CSV                                │
-│    ↓ (throws FileParsingError if invalid)          │
-│                                                     │
-│  Resolve Field Paths                               │
-│    ↓ (throws PathResolutionError if path missing)  │
-│                                                     │
-│  Map Fields to Mutation                            │
-│    ↓ (throws MappingError if required field empty) │
-│                                                     │
-│  Validate Data Rules                               │
-│    ↓ (throws ValidationError if rules fail)        │
-│                                                     │
-└─────────────────────────────────────────────────────┘
-         │
-         │ ✅ All validations passed
-         ↓
-┌─────────────────────────────────────────────────────┐
-│ EXECUTION PHASE (Data sent to Fluent)              │
-├─────────────────────────────────────────────────────┤
-│                                                     │
-│  Execute GraphQL Mutation                          │
-│    ↓                                               │
-│                                                     │
-│  ✅ ALL DATA COMMITTED or ❌ FLUENT REJECTS ALL    │
-│                                                     │
-└─────────────────────────────────────────────────────┘
-```
-
-## Core Principles
-
-### 1. One Error Stops Everything
-
-A single failure at any validation stage prevents the entire mutation from executing:
-
-```typescript
-// Even if 99 fields are valid...
-const payload = {
-  field1: "valid",
-  field2: "valid",
-  // ... 97 more valid fields
-  field100: undefined  // ❌ This ONE missing required field
-};
-
-// The ENTIRE mutation is blocked
-// Result: NO data sent to Fluent
-```
-
-### 2. No Partial Data
-
-The SDK ensures atomic operations - all data succeeds or all data fails:
-
-```typescript
-// Creating order with 100 line items
-const mutation = `
-  mutation CreateOrder($input: CreateOrderInput!) {
-    createOrder(input: $input) {
-      id
-      items { id }  # 100 items
-    }
-  }
-`;
-
-// If ANY of the 100 items fails validation:
-// - Mutation is NOT sent
-// - Order is NOT created
-// - NO items are created
-// Result: Clean failure, no cleanup needed
-```
-
-### 3. Clear Error Context
-
-Every error includes detailed information about what went wrong and where:
-
-```typescript
-catch (error) {
-  if (error instanceof MappingError) {
-    console.log(error.field);       // "customerEmail"
-    console.log(error.sourcePath);  // "order.customer.email"
-    console.log(error.message);     // "Required field 'customerEmail' is missing or empty"
-
-    // You know EXACTLY what failed and why
-  }
-}
-```
-
-## Error Propagation Chain
-
-### How Errors Flow Through the SDK
-
-```typescript
-try {
-  // 1️⃣ PARSING
-  const parsed = await parser.parse(xmlContent);
-  // Throws: FileParsingError if XML/JSON/CSV is malformed
-
-} catch (error) {
-  // ❌ Stops here - mutation never attempted
-  throw error;
-}
-
-try {
-  // 2️⃣ PATH RESOLUTION
-  const mapper = new GraphQLMutationMapper(config, logger, { fluentClient: client });
-  // Validates all source paths exist in parsed data
-  // Throws: PathResolutionError if path doesn't exist
-
-} catch (error) {
-  // ❌ Stops here - mutation never attempted
-  throw error;
-}
-
-try {
-  // 3️⃣ FIELD MAPPING
-  const payload = await mapper.map(parsed);
-  // Validates required fields, array constraints, etc.
-  // Throws: MappingError if validation fails
-
-} catch (error) {
-  // ❌ Stops here - mutation never attempted
-  throw error;
-}
-
-try {
-  // 4️⃣ EXECUTION (only reached if all above succeed)
-  // Throws GraphQLExecutionError if Fluent returns errors
-  const result = await client.graphql(payload);
-
-  // ✅ SUCCESS - All data created
-  return result.data;
-
-} catch (error) {
-  // Either network error, or Fluent rejected the entire mutation
-  throw error;
-}
-```
-
-### Sequential Validation
-
-Each stage must pass before the next begins:
-
-| Stage | Validates | Throws On Failure | Mutation Sent? |
-|-------|-----------|------------------|----------------|
-| 1. Parsing | File format, syntax | `FileParsingError` | ❌ No |
-| 2. Path Resolution | Source paths exist | `PathResolutionError` | ❌ No |
-| 3. Field Mapping | Required fields, types | `MappingError` | ❌ No |
-| 4. Data Validation | Business rules | `ValidationError` | ❌ No |
-| 5. Execution | Network, API | `IngestionError` (NETWORK_ERROR), GraphQL errors | ✅ Yes, but Fluent can still reject |
-
-## Why This Matters
-
-### Data Integrity
-
-```typescript
-// ❌ WITHOUT fail-fast
-// Scenario: Processing 1000 orders
-// Order 1-500: ✅ Created
-// Order 501: ❌ Fails (missing required field)
-// Order 502-1000: Never processed
-// Result: Partial import, data reconciliation nightmare
-
-// ✅ WITH fail-fast
-// Order 1: Validation fails on required field
-// Orders 1-1000: ❌ None created
-// Result: Clear error, fix issue, retry all - clean process
-```
-
-### Predictable Error States
-
-With fail-fast, you have only two possible states:
-
-1. ✅ **Complete Success** - All data created exactly as specified
-2. ❌ **Complete Failure** - No data created, clear error message
-
-**Never** a partial success state that requires manual investigation and cleanup.
-
-## Real-World Example
-
-### Scenario: SFCC Order Integration
-
-```typescript
-import { XMLParserService, GraphQLMutationMapper } from '@fluentcommerce/fc-connect-sdk';
-
-async function ingestSFCCOrder(xmlContent: string) {
-  const logger = console;
-
-  try {
-    // Parse SFCC XML
-    const parser = new XMLParserService();
-    const parsed = await parser.parse(xmlContent);
-
-    logger.info('✅ Parsing successful');
-
-    // Map to Fluent createOrder mutation
-    const mapper = new GraphQLMutationMapper(mappingConfig, logger, { fluentClient: client });
-    const payload = await mapper.map(parsed);
-
-    logger.info('✅ Mapping successful');
-
-    // Execute mutation
-    // Throws GraphQLExecutionError if Fluent returns errors
-    const result = await client.graphql(payload);
-
-    logger.info('✅ Order created successfully', { orderId: result.data.createOrder.id });
-
-    return result.data.createOrder;
-
-  } catch (error) {
-    logger.error('❌ Order ingestion failed - NO DATA CREATED', { error });
-
-    // Because of fail-fast:
-    // - If parsing failed: No mutation sent
-    // - If mapping failed: No mutation sent
-    // - If Fluent rejected: Entire order rejected, not partial
-
-    throw error;  // Re-throw for upstream handling
-  }
-}
-```
-
-### What Happens on Error
-
-**Parsing Error:**
-```typescript
-// Invalid XML: <order><customer>Missing closing tag
-// Result: FileParsingError thrown
-// Mutation sent? NO
-// Data in Fluent? NO
-// State: Clean - fix XML and retry
-```
-
-**Mapping Error:**
-```typescript
-// Required field missing: customer.email is undefined
-// Result: MappingError thrown
-// Mutation sent? NO
-// Data in Fluent? NO
-// State: Clean - fix data and retry
-```
-
-**GraphQL Error:**
-```typescript
-// Invalid field in mutation: unknownField
-// Result: GraphQL validation error from Fluent
-// Mutation sent? YES
-// Data in Fluent? NO (Fluent rejected entire mutation)
-// State: Clean - fix mapping config and retry
-```
-
-## Key Takeaways
-
-- 🎯 **Fail-fast prevents partial data** - Either all data succeeds or no data is created
-- 🎯 **Errors caught early** - Validation happens before any API calls
-- 🎯 **Sequential validation** - Each stage must pass before the next begins
-- 🎯 **Clear error states** - Only two outcomes: complete success or complete failure
-- 🎯 **No manual cleanup** - Failed operations leave no trace in Fluent Commerce
-
-## Practice Exercise
-
-Try to answer these questions:
-
-1. At what point in the pipeline is a GraphQL mutation sent to Fluent?
-2. If parsing succeeds but mapping fails, is any data created in Fluent?
-3. What are the two possible outcomes when using fail-fast error handling?
-
-<details>
-<summary>Click to see answers</summary>
-
-1. **After** parsing, path resolution, field mapping, and validation all succeed
-2. **No** - mapping errors prevent the mutation from being sent
-3. **Complete success** (all data created) or **complete failure** (no data created)
-
-</details>
-
-## Next Steps
-
-Continue to [Module 2: Error Types & Codes →](./error-handling-02-error-types.md) to learn about all the error classes and error codes available in the SDK.
+# Module 1: Foundations
+
+**Level:** Beginner
+**Estimated Time:** 15 minutes
+
+## Overview
+
+This module covers the fundamental principles of error handling in the Fluent Connect SDK, including the fail-fast philosophy that ensures data integrity by preventing partial or corrupt data from being created.
+
+## Learning Objectives
+
+By the end of this module, you will:
+- ✅ Understand the fail-fast error handling philosophy
+- ✅ Know why preventing partial data is critical
+- ✅ Understand the error propagation chain
+- ✅ Recognize the three core principles of SDK error handling
+
+## The Fail-Fast Philosophy
+
+### The Problem: Partial Data Corruption
+
+In traditional error handling, errors might occur after some data has already been written:
+
+```typescript
+// ❌ RISKY: Without fail-fast protection
+async function processOrder(data: any) {
+  const order = await createOrder(data.order);           // ✅ Created
+  const customer = await createCustomer(data.customer);  // ✅ Created
+  const items = await createItems(data.items);           // ❌ FAILS HERE!
+
+  // Now what? Order and customer exist, but items don't
+  // Partial data = corrupt state = data integrity violation
+}
+```
+
+**Result**: You have an order and customer in Fluent, but no items. Your data is now in an inconsistent state.
+
+### The Solution: Fail-Fast Guarantee
+
+The SDK prevents this by **validating everything before executing any mutations**:
+
+```typescript
+// ✅ SAFE: With fail-fast protection
+async function processOrder(xmlContent: string) {
+  try {
+    // Step 1: Parse XML (validate structure)
+    const parsed = await parser.parse(xmlContent);
+
+    // Step 2: Map to mutation variables (validate fields)
+    const payload = await mapper.map(parsed);
+
+    // Step 3: Execute mutation (ONLY if Steps 1 and 2 succeed)
+    const result = await client.graphql(payload);
+
+    return result.data;  // ✅ Complete data or nothing
+
+  } catch (error) {
+    // Error at ANY step = NO data sent to Fluent
+    // NO partial records, NO corrupt data
+    throw error;
+  }
+}
+```
+
+**Result**: Either all data is created successfully, or nothing is created. No partial state possible.
+
+## The Fail-Fast Guarantee
+
+### What It Means
+
+**When any error occurs during parsing, mapping, or validation, the GraphQL mutation is NEVER sent to Fluent Commerce.**
+
+This means:
+- ✅ No partial data created
+- ✅ No orphaned records
+- ✅ No data integrity violations
+- ✅ No manual cleanup required
+- ✅ Predictable error states
+
+### When Errors Are Caught
+
+```
+┌─────────────────────────────────────────────────────┐
+│ VALIDATION PHASE (No data sent to Fluent)          │
+├─────────────────────────────────────────────────────┤
+│                                                     │
+│  Parse XML/JSON/CSV                                │
+│    ↓ (throws FileParsingError if invalid)          │
+│                                                     │
+│  Resolve Field Paths                               │
+│    ↓ (throws PathResolutionError if path missing)  │
+│                                                     │
+│  Map Fields to Mutation                            │
+│    ↓ (throws MappingError if required field empty) │
+│                                                     │
+│  Validate Data Rules                               │
+│    ↓ (throws ValidationError if rules fail)        │
+│                                                     │
+└─────────────────────────────────────────────────────┘
+         │
+         │ ✅ All validations passed
+         ↓
+┌─────────────────────────────────────────────────────┐
+│ EXECUTION PHASE (Data sent to Fluent)              │
+├─────────────────────────────────────────────────────┤
+│                                                     │
+│  Execute GraphQL Mutation                          │
+│    ↓                                               │
+│                                                     │
+│  ✅ ALL DATA COMMITTED or ❌ FLUENT REJECTS ALL    │
+│                                                     │
+└─────────────────────────────────────────────────────┘
+```
+
+## Core Principles
+
+### 1. One Error Stops Everything
+
+A single failure at any validation stage prevents the entire mutation from executing:
+
+```typescript
+// Even if 99 fields are valid...
+const payload = {
+  field1: "valid",
+  field2: "valid",
+  // ... 97 more valid fields
+  field100: undefined  // ❌ This ONE missing required field
+};
+
+// The ENTIRE mutation is blocked
+// Result: NO data sent to Fluent
+```
+
+### 2. No Partial Data
+
+The SDK ensures atomic operations - all data succeeds or all data fails:
+
+```typescript
+// Creating order with 100 line items
+const mutation = `
+  mutation CreateOrder($input: CreateOrderInput!) {
+    createOrder(input: $input) {
+      id
+      items { id }  # 100 items
+    }
+  }
+`;
+
+// If ANY of the 100 items fails validation:
+// - Mutation is NOT sent
+// - Order is NOT created
+// - NO items are created
+// Result: Clean failure, no cleanup needed
+```
+
+### 3. Clear Error Context
+
+Every error includes detailed information about what went wrong and where:
+
+```typescript
+catch (error) {
+  if (error instanceof MappingError) {
+    console.log(error.field);       // "customerEmail"
+    console.log(error.sourcePath);  // "order.customer.email"
+    console.log(error.message);     // "Required field 'customerEmail' is missing or empty"
+
+    // You know EXACTLY what failed and why
+  }
+}
+```
+
+## Error Propagation Chain
+
+### How Errors Flow Through the SDK
+
+```typescript
+try {
+  // 1️⃣ PARSING
+  const parsed = await parser.parse(xmlContent);
+  // Throws: FileParsingError if XML/JSON/CSV is malformed
+
+} catch (error) {
+  // ❌ Stops here - mutation never attempted
+  throw error;
+}
+
+try {
+  // 2️⃣ PATH RESOLUTION
+  const mapper = new GraphQLMutationMapper(config, logger, { fluentClient: client });
+  // Validates all source paths exist in parsed data
+  // Throws: PathResolutionError if path doesn't exist
+
+} catch (error) {
+  // ❌ Stops here - mutation never attempted
+  throw error;
+}
+
+try {
+  // 3️⃣ FIELD MAPPING
+  const payload = await mapper.map(parsed);
+  // Validates required fields, array constraints, etc.
+  // Throws: MappingError if validation fails
+
+} catch (error) {
+  // ❌ Stops here - mutation never attempted
+  throw error;
+}
+
+try {
+  // 4️⃣ EXECUTION (only reached if all above succeed)
+  // Throws GraphQLExecutionError if Fluent returns errors
+  const result = await client.graphql(payload);
+
+  // ✅ SUCCESS - All data created
+  return result.data;
+
+} catch (error) {
+  // Either network error, or Fluent rejected the entire mutation
+  throw error;
+}
+```
+
+### Sequential Validation
+
+Each stage must pass before the next begins:
+
+| Stage | Validates | Throws On Failure | Mutation Sent? |
+|-------|-----------|------------------|----------------|
+| 1. Parsing | File format, syntax | `FileParsingError` | ❌ No |
+| 2. Path Resolution | Source paths exist | `PathResolutionError` | ❌ No |
+| 3. Field Mapping | Required fields, types | `MappingError` | ❌ No |
+| 4. Data Validation | Business rules | `ValidationError` | ❌ No |
+| 5. Execution | Network, API | `IngestionError` (NETWORK_ERROR), GraphQL errors | ✅ Yes, but Fluent can still reject |
+
+## Why This Matters
+
+### Data Integrity
+
+```typescript
+// ❌ WITHOUT fail-fast
+// Scenario: Processing 1000 orders
+// Order 1-500: ✅ Created
+// Order 501: ❌ Fails (missing required field)
+// Order 502-1000: Never processed
+// Result: Partial import, data reconciliation nightmare
+
+// ✅ WITH fail-fast
+// Order 1: Validation fails on required field
+// Orders 1-1000: ❌ None created
+// Result: Clear error, fix issue, retry all - clean process
+```
+
+### Predictable Error States
+
+With fail-fast, you have only two possible states:
+
+1. ✅ **Complete Success** - All data created exactly as specified
+2. ❌ **Complete Failure** - No data created, clear error message
+
+**Never** a partial success state that requires manual investigation and cleanup.
+
+## Real-World Example
+
+### Scenario: SFCC Order Integration
+
+```typescript
+import { XMLParserService, GraphQLMutationMapper } from '@fluentcommerce/fc-connect-sdk';
+
+async function ingestSFCCOrder(xmlContent: string) {
+  const logger = console;
+
+  try {
+    // Parse SFCC XML
+    const parser = new XMLParserService();
+    const parsed = await parser.parse(xmlContent);
+
+    logger.info('✅ Parsing successful');
+
+    // Map to Fluent createOrder mutation
+    const mapper = new GraphQLMutationMapper(mappingConfig, logger, { fluentClient: client });
+    const payload = await mapper.map(parsed);
+
+    logger.info('✅ Mapping successful');
+
+    // Execute mutation
+    // Throws GraphQLExecutionError if Fluent returns errors
+    const result = await client.graphql(payload);
+
+    logger.info('✅ Order created successfully', { orderId: result.data.createOrder.id });
+
+    return result.data.createOrder;
+
+  } catch (error) {
+    logger.error('❌ Order ingestion failed - NO DATA CREATED', { error });
+
+    // Because of fail-fast:
+    // - If parsing failed: No mutation sent
+    // - If mapping failed: No mutation sent
+    // - If Fluent rejected: Entire order rejected, not partial
+
+    throw error;  // Re-throw for upstream handling
+  }
+}
+```
+
+### What Happens on Error
+
+**Parsing Error:**
+```typescript
+// Invalid XML: <order><customer>Missing closing tag
+// Result: FileParsingError thrown
+// Mutation sent? NO
+// Data in Fluent? NO
+// State: Clean - fix XML and retry
+```
+
+**Mapping Error:**
+```typescript
+// Required field missing: customer.email is undefined
+// Result: MappingError thrown
+// Mutation sent? NO
+// Data in Fluent? NO
+// State: Clean - fix data and retry
+```
+
+**GraphQL Error:**
+```typescript
+// Invalid field in mutation: unknownField
+// Result: GraphQL validation error from Fluent
+// Mutation sent? YES
+// Data in Fluent? NO (Fluent rejected entire mutation)
+// State: Clean - fix mapping config and retry
+```
+
+## Key Takeaways
+
+- 🎯 **Fail-fast prevents partial data** - Either all data succeeds or no data is created
+- 🎯 **Errors caught early** - Validation happens before any API calls
+- 🎯 **Sequential validation** - Each stage must pass before the next begins
+- 🎯 **Clear error states** - Only two outcomes: complete success or complete failure
+- 🎯 **No manual cleanup** - Failed operations leave no trace in Fluent Commerce
+
+## Practice Exercise
+
+Try to answer these questions:
+
+1. At what point in the pipeline is a GraphQL mutation sent to Fluent?
+2. If parsing succeeds but mapping fails, is any data created in Fluent?
+3. What are the two possible outcomes when using fail-fast error handling?
+
+<details>
+<summary>Click to see answers</summary>
+
+1. **After** parsing, path resolution, field mapping, and validation all succeed
+2. **No** - mapping errors prevent the mutation from being sent
+3. **Complete success** (all data created) or **complete failure** (no data created)
+
+</details>
+
+## Next Steps
+
+Continue to [Module 2: Error Types & Codes →](./error-handling-02-error-types.md) to learn about all the error classes and error codes available in the SDK.