@fluentcommerce/fc-connect-sdk 0.1.48 → 0.1.52

package/docs/02-CORE-GUIDES/mapping/modules/mapping-01-foundations.md

@@ -1,448 +1,450 @@
-# Module 1: Foundations
-
-**Learn the fundamental concepts of universal mapping**
-
-**Level:** Beginner
-
-**Estimated Time:** 30 minutes
-
----
-
-## What You'll Learn
-
-By the end of this module, you'll understand:
-
-- ✅ What universal mapping is and why it's powerful
-- ✅ How mapping works with JavaScript objects (not file formats)
-- ✅ The core concepts: fields, sources, resolvers, and validation
-- ✅ How to read and write mapping configurations
-- ✅ When to use UniversalMapper vs other mapping approaches
-
----
-
-## What is Universal Mapping?
-
-Universal mapping is a **single, unified pattern** for transforming data from any source format (CSV, JSON, XML, Parquet) into any target format (Fluent Commerce Batch API, GraphQL mutations, Parquet, JSON, XML).
-
-### The Problem It Solves
-
-Before universal mapping, you needed different tools for different transformations:
-
-```typescript
-// ❌ OLD WAY: Different tools for different formats
-import { CSVMapper } from './csv-mapper';
-import { XMLMapper } from './xml-mapper';
-import { JSONMapper } from './json-mapper';
-
-const csvMapper = new CSVMapper(csvConfig);
-const xmlMapper = new XMLMapper(xmlConfig);
-const jsonMapper = new JSONMapper(jsonConfig);
-
-// Different APIs, different patterns, different learning curves
-```
-
-```typescript
-// ✅ NEW WAY: One mapper for everything
-import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-
-const mapper = new UniversalMapper({
-  fields: {
-    sku: { source: 'productRef', required: true },
-    quantity: { source: 'qty', resolver: 'sdk.parseInt' },
-    warehouse: { source: 'locationRef' }
-  }
-});
-
-// Same API, same pattern, works with CSV, JSON, XML, Parquet, GraphQL
-const result = await mapper.map(data);
-```
-
-### Key Benefits
-
-1. **One Pattern for All Formats** - Learn once, use everywhere
-2. **Consistent API** - Same methods, same error handling, same validation
-3. **Reusable Configurations** - Write once, use with CSV, JSON, XML, Parquet
-4. **Type Safety** - Full TypeScript support with type inference
-5. **Built-in Resolvers** - Common transformations (trim, parseInt, formatDate) included
-6. **Custom Resolvers** - Extend with your own transformation logic
-
----
-
-## Core Concepts
-
-### 1. Fields
-
-A **field** is a target property in your output data. Each field defines:
-- **Source**: Where to get the data from (JavaScript object path)
-- **Resolver**: How to transform it (optional)
-- **Required**: Whether it must be present (optional)
-- **Default**: Fallback value if missing (optional)
-
-```typescript
-{
-  fields: {
-    sku: {                          // ← Field name (target)
-      source: 'productRef',          // ← Source path
-      required: true,                // ← Validation rule
-      resolver: 'sdk.trim'           // ← Transformation
-    }
-  }
-}
-```
-
-### 2. Source Paths
-
-Source paths use **JavaScript object notation** (dot notation), not JSONPath or XPath:
-
-```typescript
-// ✅ CORRECT: JavaScript object paths
-source: 'productRef'              // Simple property
-source: 'order.items[0].sku'      // Array access
-source: 'customer.address.city'   // Nested object
-
-// ❌ WRONG: JSONPath syntax
-source: '$.productRef'           // Don't use $ prefix
-source: '$..items[*].sku'         // Don't use JSONPath wildcards
-```
-
-**Important:** Source paths work on **parsed JavaScript objects**, not raw file formats. The SDK parsers (CSVParserService, XMLParserService, etc.) convert files to JavaScript objects first.
-
-### 3. Resolvers
-
-Resolvers transform source values before mapping:
-
-```typescript
-{
-  fields: {
-    quantity: {
-      source: 'qty',
-      resolver: 'sdk.parseInt'  // ← Converts string "100" to number 100
-    },
-    status: {
-      source: 'status',
-      resolver: 'sdk.uppercase'  // ← Converts "available" to "AVAILABLE"
-    }
-  }
-}
-```
-
-**Built-in SDK Resolvers:**
-- **String**: `sdk.trim`, `sdk.uppercase`, `sdk.lowercase`, `sdk.toString`
-- **Number**: `sdk.parseInt`, `sdk.parseFloat`, `sdk.number`
-- **Date**: `sdk.formatDate`, `sdk.parseDate`
-- **Boolean**: `sdk.boolean`
-- **Utility**: `sdk.identity`, `sdk.default`, `sdk.coalesce`
-
-**Custom Resolvers:** You can also create your own (see [Module 6: Custom Resolvers](./mapping-06-helpers-resolvers.md)).
-
-### 4. Validation
-
-UniversalMapper validates data automatically:
-
-```typescript
-const result = await mapper.map(data);
-
-if (!result.success) {
-  // Validation failed
-  console.error('Errors:', result.errors);
-  // [
-  //   { field: 'sku', error: 'Required field missing' },
-  //   { field: 'quantity', error: 'Invalid number format' }
-  // ]
-} else {
-  // Validation passed
-  console.log('Mapped data:', result.data);
-}
-```
-
----
-
-## How Mapping Works
-
-### Step-by-Step Process
-
-```mermaid
-graph LR
-    A[Source Data] --> B[Parser]
-    B --> C[JavaScript Object]
-    C --> D[UniversalMapper]
-    D --> E[Field Mapping]
-    E --> F[Resolver Transform]
-    F --> G[Validation]
-    G --> H[Output Data]
-```
-
-**Example Flow:**
-
-1. **Source**: CSV file with columns `sku`, `qty`, `warehouse`
-2. **Parser**: `CSVParserService` converts CSV → JavaScript array:
-   ```javascript
-   [
-     { sku: 'SKU-001', qty: '100', warehouse: 'WH-001' },
-     { sku: 'SKU-002', qty: '200', warehouse: 'WH-002' }
-   ]
-   ```
-3. **Mapper**: `UniversalMapper` transforms using config:
-   ```typescript
-   {
-     fields: {
-       productRef: { source: 'sku' },
-       quantity: { source: 'qty', resolver: 'sdk.parseInt' },
-       locationRef: { source: 'warehouse' }
-     }
-   }
-   ```
-4. **Output**: Transformed data:
-   ```javascript
-   [
-     { productRef: 'SKU-001', quantity: 100, locationRef: 'WH-001' },
-     { productRef: 'SKU-002', quantity: 200, locationRef: 'WH-002' }
-   ]
-   ```
-
----
-
-## Mapping Configuration Format
-
-### Basic Structure
-
-```typescript
-{
-  fields: {
-    targetField1: {
-      source: 'sourcePath1',
-      resolver: 'sdk.resolverName',  // Optional
-      required: true,                 // Optional
-      defaultValue: 'default'         // Optional
-    },
-    targetField2: {
-      source: 'sourcePath2'
-    }
-  }
-}
-```
-
-### External JSON Configuration (Recommended)
-
-For production, store mapping configs in external JSON files:
-
-```json
-// config/inventory-mapping.json
-{
-  "fields": {
-    "ref": {
-      "source": "sku",
-      "required": true
-    },
-    "productRef": {
-      "source": "sku",
-      "required": true
-    },
-    "locationRef": {
-      "source": "warehouse",
-      "required": true
-    },
-    "qty": {
-      "source": "quantity",
-      "resolver": "sdk.parseInt",
-      "required": true
-    }
-  }
-}
-```
-
-```typescript
-// Load and use
-import mappingConfig from './config/inventory-mapping.json' with { type: 'json' };
-const mapper = new UniversalMapper(mappingConfig);
-```
-
-**Benefits of External JSON:**
-- ✅ Environment-specific configurations
-- ✅ No code changes for field updates
-- ✅ Easier testing and validation
-- ✅ Better separation of concerns
-
----
-
-## When to Use UniversalMapper
-
-### ✅ Use UniversalMapper For:
-
-- **CSV → Batch API** - Inventory ingestion from CSV files
-- **JSON → Batch API** - API responses to Fluent Commerce
-- **GraphQL → Parquet** - Data extraction and export
-- **XML → JSON** - Format conversion
-- **Any data transformation** - When you need field mapping
-
-### ❌ Don't Use UniversalMapper For:
-
-- **XML → GraphQL Mutations** - Use `GraphQLMutationMapper` instead (specialized tool)
-- **Simple field copying** - If no transformation needed, direct assignment might be simpler
-- **Complex business logic** - Use custom resolvers or separate transformation functions
-
-**See:** [Mapper Comparison Guide](../mapping-mapper-comparison-guide.md) for detailed decision matrix.
-
----
-
-## Quick Example
-
-Here's a complete, working example:
-
-```typescript
-import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-
-// Define mapping configuration
-const mappingConfig = {
-  fields: {
-    sku: {
-      source: 'productRef',
-      required: true
-    },
-    quantity: {
-      source: 'qty',
-      resolver: 'sdk.parseInt',
-      required: true
-    },
-    warehouse: {
-      source: 'locationRef',
-      defaultValue: 'DEFAULT-WH'
-    },
-    status: {
-      source: 'status',
-      resolver: 'sdk.uppercase',
-      defaultValue: 'AVAILABLE'
-    }
-  }
-};
-
-// Create mapper
-const mapper = new UniversalMapper(mappingConfig);
-
-// Source data (could be from CSV, JSON, XML, etc.)
-const sourceData = [
-  { productRef: 'SKU-001', qty: '100', locationRef: 'WH-001', status: 'available' },
-  { productRef: 'SKU-002', qty: '200', status: 'in_stock' }  // Missing locationRef
-];
-
-// Map data
-const result = await mapper.map(sourceData);
-
-if (result.success) {
-  console.log('Mapped data:', result.data);
-  // [
-  //   { sku: 'SKU-001', quantity: 100, warehouse: 'WH-001', status: 'AVAILABLE' },
-  //   { sku: 'SKU-002', quantity: 200, warehouse: 'DEFAULT-WH', status: 'IN_STOCK' }
-  // ]
-} else {
-  console.error('Mapping errors:', result.errors);
-}
-```
-
----
-
-## Common Patterns
-
-### Pattern 1: Simple Field Mapping
-
-```typescript
-{
-  fields: {
-    targetField: { source: 'sourceField' }
-  }
-}
-```
-
-### Pattern 2: With Type Conversion
-
-```typescript
-{
-  fields: {
-    quantity: {
-      source: 'qty',
-      resolver: 'sdk.parseInt'  // String → Number
-    }
-  }
-}
-```
-
-### Pattern 3: With Default Value
-
-```typescript
-{
-  fields: {
-    status: {
-      source: 'status',
-      defaultValue: 'AVAILABLE'  // Use if source is missing
-    }
-  }
-}
-```
-
-### Pattern 4: Required Field
-
-```typescript
-{
-  fields: {
-    sku: {
-      source: 'productRef',
-      required: true  // Validation: must be present
-    }
-  }
-}
-```
-
-### Pattern 5: Nested Object Access
-
-```typescript
-{
-  fields: {
-    city: {
-      source: 'address.city'  // Access nested property
-    }
-  }
-}
-```
-
----
-
-## Next Steps
-
-Now that you understand the foundations:
-
-1. **Module 2: Quick Start** - Build your first mapping workflow
-2. **Module 3: Schema Validation** - Validate mappings against Fluent Commerce schema
-3. **Module 4: Use Cases** - Real-world mapping scenarios
-4. **Module 5: Advanced Patterns** - Arrays, nested objects, conditional mapping
-
----
-
-## Key Takeaways
-
-✅ **Universal mapping** = One pattern for all data transformations
-
-✅ **Source paths** = JavaScript object notation (not JSONPath/XPath)
-
-✅ **Resolvers** = Transform values before mapping (built-in + custom)
-
-✅ **Validation** = Automatic validation of required fields and types
-
-✅ **External JSON** = Recommended for production configurations
-
-✅ **Works with any format** = CSV, JSON, XML, Parquet, GraphQL
-
----
-
-**Ready to build your first mapping?** → [Module 2: Quick Start](./mapping-02-quick-start.md)
-
-
-
-
-
-
-
-
-
-
-
-
+# Module 1: Foundations
+
+**Learn the fundamental concepts of universal mapping**
+
+**Level:** Beginner
+
+**Estimated Time:** 30 minutes
+
+---
+
+## What You'll Learn
+
+By the end of this module, you'll understand:
+
+- ✅ What universal mapping is and why it's powerful
+- ✅ How mapping works with JavaScript objects (not file formats)
+- ✅ The core concepts: fields, sources, resolvers, and validation
+- ✅ How to read and write mapping configurations
+- ✅ When to use UniversalMapper vs other mapping approaches
+
+---
+
+## What is Universal Mapping?
+
+Universal mapping is a **single, unified pattern** for transforming data from any source format (CSV, JSON, XML, Parquet) into any target format (Fluent Commerce Batch API, GraphQL mutations, Parquet, JSON, XML).
+
+### The Problem It Solves
+
+Before universal mapping, you needed different tools for different transformations:
+
+```typescript
+// ❌ OLD WAY: Different tools for different formats
+import { CSVMapper } from './csv-mapper';
+import { XMLMapper } from './xml-mapper';
+import { JSONMapper } from './json-mapper';
+
+const csvMapper = new CSVMapper(csvConfig);
+const xmlMapper = new XMLMapper(xmlConfig);
+const jsonMapper = new JSONMapper(jsonConfig);
+
+// Different APIs, different patterns, different learning curves
+```
+
+```typescript
+// ✅ NEW WAY: One mapper for everything
+import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+
+const mapper = new UniversalMapper({
+  fields: {
+    sku: { source: 'productRef', required: true },
+    quantity: { source: 'qty', resolver: 'sdk.parseInt' },
+    warehouse: { source: 'locationRef' }
+  }
+});
+
+// Same API, same pattern, works with CSV, JSON, XML, Parquet, GraphQL
+const result = await mapper.map(data);
+```
+
+### Key Benefits
+
+1. **One Pattern for All Formats** - Learn once, use everywhere
+2. **Consistent API** - Same methods, same error handling, same validation
+3. **Reusable Configurations** - Write once, use with CSV, JSON, XML, Parquet
+4. **Type Safety** - Full TypeScript support with type inference
+5. **Built-in Resolvers** - Common transformations (trim, parseInt, formatDate) included
+6. **Custom Resolvers** - Extend with your own transformation logic
+
+---
+
+## Core Concepts
+
+### 1. Fields
+
+A **field** is a target property in your output data. Each field defines:
+- **Source**: Where to get the data from (JavaScript object path)
+- **Resolver**: How to transform it (optional)
+- **Required**: Whether it must be present (optional)
+- **Default**: Fallback value if missing (optional)
+
+```typescript
+{
+  fields: {
+    sku: {                          // ← Field name (target)
+      source: 'productRef',          // ← Source path
+      required: true,                // ← Validation rule
+      resolver: 'sdk.trim'           // ← Transformation
+    }
+  }
+}
+```
+
+### 2. Source Paths
+
+Source paths use **JavaScript object notation** (dot notation), not JSONPath or XPath:
+
+```typescript
+// ✅ CORRECT: JavaScript object paths
+source: 'productRef'              // Simple property
+source: 'order.items[0].sku'      // Array access
+source: 'customer.address.city'   // Nested object
+
+// ❌ WRONG: JSONPath syntax
+source: '$.productRef'           // Don't use $ prefix
+source: '$..items[*].sku'         // Don't use JSONPath wildcards
+```
+
+**Important:** Source paths work on **parsed JavaScript objects**, not raw file formats. The SDK parsers (CSVParserService, XMLParserService, etc.) convert files to JavaScript objects first.
+
+### 3. Resolvers
+
+Resolvers transform source values before mapping:
+
+```typescript
+{
+  fields: {
+    quantity: {
+      source: 'qty',
+      resolver: 'sdk.parseInt'  // ← Converts string "100" to number 100
+    },
+    status: {
+      source: 'status',
+      resolver: 'sdk.uppercase'  // ← Converts "available" to "AVAILABLE"
+    }
+  }
+}
+```
+
+**Built-in SDK Resolvers:**
+- **String**: `sdk.trim`, `sdk.uppercase`, `sdk.lowercase`, `sdk.toString`
+- **Number**: `sdk.parseInt`, `sdk.parseFloat`, `sdk.number`
+- **Date**: `sdk.formatDate`, `sdk.parseDate`
+- **Boolean**: `sdk.boolean`
+- **Utility**: `sdk.identity`, `sdk.default`, `sdk.coalesce`
+
+**Custom Resolvers:** You can also create your own (see [Module 6: Custom Resolvers](./mapping-06-helpers-resolvers.md)).
+
+### 4. Validation
+
+UniversalMapper validates data automatically:
+
+```typescript
+const result = await mapper.map(data);
+
+if (!result.success) {
+  // Validation failed
+  console.error('Errors:', result.errors);
+  // [
+  //   { field: 'sku', error: 'Required field missing' },
+  //   { field: 'quantity', error: 'Invalid number format' }
+  // ]
+} else {
+  // Validation passed
+  console.log('Mapped data:', result.data);
+}
+```
+
+---
+
+## How Mapping Works
+
+### Step-by-Step Process
+
+```mermaid
+graph LR
+    A[Source Data] --> B[Parser]
+    B --> C[JavaScript Object]
+    C --> D[UniversalMapper]
+    D --> E[Field Mapping]
+    E --> F[Resolver Transform]
+    F --> G[Validation]
+    G --> H[Output Data]
+```
+
+**Example Flow:**
+
+1. **Source**: CSV file with columns `sku`, `qty`, `warehouse`
+2. **Parser**: `CSVParserService` converts CSV → JavaScript array:
+   ```javascript
+   [
+     { sku: 'SKU-001', qty: '100', warehouse: 'WH-001' },
+     { sku: 'SKU-002', qty: '200', warehouse: 'WH-002' }
+   ]
+   ```
+3. **Mapper**: `UniversalMapper` transforms using config:
+   ```typescript
+   {
+     fields: {
+       productRef: { source: 'sku' },
+       quantity: { source: 'qty', resolver: 'sdk.parseInt' },
+       locationRef: { source: 'warehouse' }
+     }
+   }
+   ```
+4. **Output**: Transformed data:
+   ```javascript
+   [
+     { productRef: 'SKU-001', quantity: 100, locationRef: 'WH-001' },
+     { productRef: 'SKU-002', quantity: 200, locationRef: 'WH-002' }
+   ]
+   ```
+
+---
+
+## Mapping Configuration Format
+
+### Basic Structure
+
+```typescript
+{
+  fields: {
+    targetField1: {
+      source: 'sourcePath1',
+      resolver: 'sdk.resolverName',  // Optional
+      required: true,                 // Optional
+      defaultValue: 'default'         // Optional
+    },
+    targetField2: {
+      source: 'sourcePath2'
+    }
+  }
+}
+```
+
+### External JSON Configuration (Recommended)
+
+For production, store mapping configs in external JSON files:
+
+```json
+// config/inventory-mapping.json
+{
+  "fields": {
+    "ref": {
+      "source": "sku",
+      "required": true
+    },
+    "productRef": {
+      "source": "sku",
+      "required": true
+    },
+    "locationRef": {
+      "source": "warehouse",
+      "required": true
+    },
+    "qty": {
+      "source": "quantity",
+      "resolver": "sdk.parseInt",
+      "required": true
+    }
+  }
+}
+```
+
+```typescript
+// Load and use
+import mappingConfig from './config/inventory-mapping.json' with { type: 'json' };
+const mapper = new UniversalMapper(mappingConfig);
+```
+
+**Benefits of External JSON:**
+- ✅ Environment-specific configurations
+- ✅ No code changes for field updates
+- ✅ Easier testing and validation
+- ✅ Better separation of concerns
+
+---
+
+## When to Use UniversalMapper
+
+### ✅ Use UniversalMapper For:
+
+- **CSV → Batch API** - Inventory ingestion from CSV files
+- **JSON → Batch API** - API responses to Fluent Commerce
+- **GraphQL → Parquet** - Data extraction and export
+- **XML → JSON** - Format conversion
+- **Any data transformation** - When you need field mapping
+
+### ❌ Don't Use UniversalMapper For:
+
+- **XML → GraphQL Mutations** - Use `GraphQLMutationMapper` instead (specialized tool)
+- **Simple field copying** - If no transformation needed, direct assignment might be simpler
+- **Complex business logic** - Use custom resolvers or separate transformation functions
+
+**See:** [Mapper Comparison Guide](../mapping-mapper-comparison-guide.md) for detailed decision matrix.
+
+---
+
+## Quick Example
+
+Here's a complete, working example:
+
+```typescript
+import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+
+// Define mapping configuration
+const mappingConfig = {
+  fields: {
+    sku: {
+      source: 'productRef',
+      required: true
+    },
+    quantity: {
+      source: 'qty',
+      resolver: 'sdk.parseInt',
+      required: true
+    },
+    warehouse: {
+      source: 'locationRef',
+      defaultValue: 'DEFAULT-WH'
+    },
+    status: {
+      source: 'status',
+      resolver: 'sdk.uppercase',
+      defaultValue: 'AVAILABLE'
+    }
+  }
+};
+
+// Create mapper
+const mapper = new UniversalMapper(mappingConfig);
+
+// Source data (could be from CSV, JSON, XML, etc.)
+const sourceData = [
+  { productRef: 'SKU-001', qty: '100', locationRef: 'WH-001', status: 'available' },
+  { productRef: 'SKU-002', qty: '200', status: 'in_stock' }  // Missing locationRef
+];
+
+// Map data
+const result = await mapper.map(sourceData);
+
+if (result.success) {
+  console.log('Mapped data:', result.data);
+  // [
+  //   { sku: 'SKU-001', quantity: 100, warehouse: 'WH-001', status: 'AVAILABLE' },
+  //   { sku: 'SKU-002', quantity: 200, warehouse: 'DEFAULT-WH', status: 'IN_STOCK' }
+  // ]
+} else {
+  console.error('Mapping errors:', result.errors);
+}
+```
+
+---
+
+## Common Patterns
+
+### Pattern 1: Simple Field Mapping
+
+```typescript
+{
+  fields: {
+    targetField: { source: 'sourceField' }
+  }
+}
+```
+
+### Pattern 2: With Type Conversion
+
+```typescript
+{
+  fields: {
+    quantity: {
+      source: 'qty',
+      resolver: 'sdk.parseInt'  // String → Number
+    }
+  }
+}
+```
+
+### Pattern 3: With Default Value
+
+```typescript
+{
+  fields: {
+    status: {
+      source: 'status',
+      defaultValue: 'AVAILABLE'  // Use if source is missing
+    }
+  }
+}
+```
+
+### Pattern 4: Required Field
+
+```typescript
+{
+  fields: {
+    sku: {
+      source: 'productRef',
+      required: true  // Validation: must be present
+    }
+  }
+}
+```
+
+### Pattern 5: Nested Object Access
+
+```typescript
+{
+  fields: {
+    city: {
+      source: 'address.city'  // Access nested property
+    }
+  }
+}
+```
+
+---
+
+## Next Steps
+
+Now that you understand the foundations:
+
+1. **Module 2: Quick Start** - Build your first mapping workflow
+2. **Module 3: Schema Validation** - Validate mappings against Fluent Commerce schema
+3. **Module 4: Use Cases** - Real-world mapping scenarios
+4. **Module 5: Advanced Patterns** - Arrays, nested objects, conditional mapping
+
+---
+
+## Key Takeaways
+
+✅ **Universal mapping** = One pattern for all data transformations
+
+✅ **Source paths** = JavaScript object notation (not JSONPath/XPath)
+
+✅ **Resolvers** = Transform values before mapping (built-in + custom)
+
+✅ **Validation** = Automatic validation of required fields and types
+
+✅ **External JSON** = Recommended for production configurations
+
+✅ **Works with any format** = CSV, JSON, XML, Parquet, GraphQL
+
+---
+
+**Ready to build your first mapping?** → [Module 2: Quick Start](./mapping-02-quick-start.md)
+
+
+
+
+
+
+
+
+
+
+
+
+
+