@fluentcommerce/fc-connect-sdk 0.1.48 → 0.1.52

package/docs/02-CORE-GUIDES/mapping/modules/mapping-02-quick-start.md

@@ -1,474 +1,476 @@
-# Module 2: Quick Start
-
-**Get started with universal mapping in 15 minutes**
-
-**Level:** Beginner
-**Time:** 15 minutes
-**Prerequisites:** [Module 1: Foundations](./mapping-01-foundations.md)
-
----
-
-## Learning Objectives
-
-After completing this module, you will:
-
-- ✅ Create your first mapping configuration
-- ✅ Use basic SDK resolvers
-- ✅ Run a complete CSV ingestion example
-- ✅ Handle errors and validate results
-
----
-
-## Your First Mapping
-
-Let's create a simple CSV inventory ingestion mapping.
-
-### Step 1: Define the Mapping
-
-Create `inventory-mapping.json`:
-
-```json
-{
-  "fields": {
-    "ref": {
-      "source": "sku",
-      "required": true
-    },
-    "productRef": {
-      "source": "sku",
-      "required": true
-    },
-    "locationRef": {
-      "source": "location",
-      "required": true
-    },
-    "qty": {
-      "source": "quantity",
-      "resolver": "sdk.parseInt",
-      "required": true
-    },
-    "status": {
-      "source": "status",
-      "resolver": "sdk.uppercase",
-      "defaultValue": "AVAILABLE"
-    }
-  }
-}
-```
-
-### Step 2: Prepare Sample Data
-
-Create `inventory.csv`:
-
-```csv
-sku,location,quantity,status
-SKU-WM-001,WH-001,500,available
-SKU-WM-002,WH-001,150,available
-SKU-KB-001,WH-001,75,reserved
-```
-
-### Step 3: Implement the Workflow
-
-```typescript
-import { UniversalMapper, CSVParserService, createClient } from '@fluentcommerce/fc-connect-sdk';
-import * as fs from 'fs';
-
-// Load mapping configuration
-const mappingConfig = JSON.parse(fs.readFileSync('./inventory-mapping.json', 'utf-8'));
-
-// Load CSV data
-const csvContent = fs.readFileSync('./inventory.csv', 'utf-8');
-const parser = new CSVParserService();
-const records = await parser.parse(csvContent);
-
-// Create mapper
-const mapper = new UniversalMapper(mappingConfig);
-
-// Process each CSV row
-const batchEntities = [];
-for (const row of records) {
-  const result = await mapper.map(row);
-
-  if (result.success) {
-    batchEntities.push(result.data);
-  } else {
-    console.error('Mapping failed for row:', row);
-    console.error('Errors:', result.errors);
-  }
-}
-
-// Send to Fluent Commerce
-const client = await createClient({
-  config: {
-    baseUrl: process.env.FLUENT_BASE_URL!,
-    clientId: process.env.FLUENT_CLIENT_ID!,
-    clientSecret: process.env.FLUENT_CLIENT_SECRET!,
-    username: process.env.FLUENT_USERNAME!,
-    password: process.env.FLUENT_PASSWORD!,
-    retailerId: process.env.FLUENT_RETAILER_ID!,
-  },
-});
-
-// Create a batch job and send entities
-const job = await client.createJob({
-  name: `inventory-import-${Date.now()}`,
-  retailerId: process.env.FLUENT_RETAILER_ID!,
-});
-
-await client.sendBatch(job.id, {
-  action: 'UPSERT',
-  entityType: 'INVENTORY',
-  source: 'CSV_IMPORT',
-  event: 'INVENTORY_UPDATE',
-  entities: batchEntities,
-});
-
-console.log(`✅ Successfully processed ${batchEntities.length} records`);
-```
-
-### Step 4: Run and Validate
-
-```bash
-npm install @fluentcommerce/fc-connect-sdk
-node inventory-import.js
-```
-
-**Expected Output:**
-
-```
-✅ Successfully processed 3 records
-```
-
----
-
-## Understanding the Mapping
-
-Let's break down what each field does:
-
-### Field: `ref`
-
-```json
-"ref": {
-  "source": "sku",
-  "required": true
-}
-```
-
-- **source:** Read from `sku` column in CSV
-- **required:** Must have a value (fails if missing)
-- **Result:** Direct copy of SKU value
-
-### Field: `qty`
-
-```json
-"qty": {
-  "source": "quantity",
-  "resolver": "sdk.parseInt",
-  "required": true
-}
-```
-
-- **source:** Read from `quantity` column
-- **resolver:** Convert string "500" to integer 500
-- **required:** Must have a value
-- **Result:** Parsed integer
-
-### Field: `status`
-
-```json
-"status": {
-  "source": "status",
-  "resolver": "sdk.uppercase",
-  "defaultValue": "AVAILABLE"
-}
-```
-
-- **source:** Read from `status` column
-- **resolver:** Convert "available" to "AVAILABLE"
-- **defaultValue:** Use "AVAILABLE" if missing
-- **Result:** Uppercased string or default
-
----
-
-## Common SDK Resolvers
-
-Here are the most commonly used SDK resolvers:
-
-### String Transformations
-
-```json
-// Uppercase
-"status": { "source": "status", "resolver": "sdk.uppercase" }
-// "active" → "ACTIVE"
-
-// Lowercase
-"email": { "source": "email", "resolver": "sdk.lowercase" }
-// "USER@EXAMPLE.COM" → "user@example.com"
-
-// Trim whitespace
-"name": { "source": "name", "resolver": "sdk.trim" }
-// "  Product  " → "Product"
-```
-
-### Number Transformations
-
-```json
-// Parse integer
-"quantity": { "source": "qty", "resolver": "sdk.parseInt" }
-// "100" → 100
-
-// Parse float
-"price": { "source": "price", "resolver": "sdk.parseFloat" }
-// "19.99" → 19.99
-```
-
-### Date Transformations
-
-```json
-// ISO8601 format
-"createdAt": { "source": "date", "resolver": "sdk.formatDate" }
-// "2024-01-15" → "2024-01-15T00:00:00.000Z"
-
-// Short format (YYYY-MM-DD)
-"expectedOn": { "source": "date", "resolver": "sdk.formatDateShort" }
-// "01/15/2024" → "2024-01-15"
-```
-
----
-
-## Error Handling
-
-Always check mapping results:
-
-```typescript
-const result = await mapper.map(sourceData);
-
-if (result.success) {
-  // ✅ Mapping succeeded
-  console.log('Mapped data:', result.data);
-  batchEntities.push(result.data);
-} else {
-  // ❌ Mapping failed
-  console.error('Mapping failed');
-  console.error('Errors:', result.errors);
-  console.error('Source data:', sourceData);
-
-  // Log each error
-  result.errors.forEach(error => {
-    console.error(`- Field: ${error.field}`);
-    console.error(`  Message: ${error.message}`);
-  });
-}
-```
-
-### Common Errors
-
-**Missing Required Field:**
-
-```
-Error: Required field 'productRef' is missing
-Source: { sku: '', location: 'WH-001', quantity: '100' }
-```
-
-**Invalid Number:**
-
-```
-Error: Failed to parse 'qty' as integer
-Source: { quantity: 'invalid' }
-```
-
-**Resolver Error:**
-
-```
-Error: Resolver 'sdk.parseInt' failed
-Message: Cannot parse 'abc' as integer
-```
-
----
-
-## Static Values
-
-Sometimes you need constant values:
-
-```json
-{
-  "fields": {
-    "type": {
-      "value": "STANDARD"
-    },
-    "retailerId": {
-      "value": 1
-    },
-    "source": {
-      "value": "CSV_IMPORT"
-    }
-  }
-}
-```
-
-**Result:**
-
-```json
-{
-  "type": "STANDARD",
-  "retailerId": 1,
-  "source": "CSV_IMPORT"
-}
-```
-
----
-
-## Default Values
-
-Provide fallbacks for optional fields:
-
-```json
-{
-  "fields": {
-    "status": {
-      "source": "orderStatus",
-      "defaultValue": "PENDING"
-    },
-    "shippingMethod": {
-      "source": "shipping",
-      "defaultValue": "STANDARD"
-    }
-  }
-}
-```
-
-**Behavior:**
-
-- If `orderStatus` exists → use its value
-- If `orderStatus` is missing/empty → use "PENDING"
-
----
-
-## Combining Resolvers and Defaults
-
-```json
-{
-  "fields": {
-    "quantity": {
-      "source": "qty",
-      "resolver": "sdk.parseInt",
-      "defaultValue": 0
-    }
-  }
-}
-```
-
-**Processing order:**
-
-1. Read from `qty` field
-2. If missing → use default value `0`
-3. Apply resolver `sdk.parseInt`
-4. Return result
-
----
-
-## Practice Exercise
-
-**Task:** Create a mapping for this customer CSV:
-
-```csv
-email,first_name,last_name,phone,status
-john@example.com,John,Doe,555-1234,active
-jane@example.com,Jane,Smith,555-5678,
-```
-
-**Requirements:**
-
-1. Map `email` to lowercase
-2. Combine `first_name` and `last_name` into `fullName`
-3. Format `phone` (you'll need a custom resolver)
-4. Map `status` to uppercase with default "ACTIVE"
-5. Mark `email` as required
-
-<details>
-<summary>Click to see solution</summary>
-
-```json
-{
-  "fields": {
-    "email": {
-      "source": "email",
-      "resolver": "sdk.lowercase",
-      "required": true
-    },
-    "firstName": {
-      "source": "first_name",
-      "required": true
-    },
-    "lastName": {
-      "source": "last_name",
-      "required": true
-    },
-    "phone": {
-      "source": "phone",
-      "resolver": "custom.formatPhone"
-    },
-    "status": {
-      "source": "status",
-      "resolver": "sdk.uppercase",
-      "defaultValue": "ACTIVE"
-    }
-  }
-}
-```
-
-**Custom resolver for phone formatting:**
-
-```typescript
-const customResolvers = {
-  'custom.formatPhone': (value: any) => {
-    const digits = String(value).replace(/\D/g, '');
-    return `(${digits.slice(0, 3)}) ${digits.slice(3, 6)}-${digits.slice(6)}`;
-  },
-};
-
-const mapper = new UniversalMapper(config, { customResolvers });
-```
-
-**Note:** Combining `first_name` and `last_name` would also require a custom resolver. See [Module 6: Custom Resolvers](./mapping-06-helpers-resolvers.md) for advanced patterns.
-
-</details>
-
----
-
-## Key Takeaways
-
-1. **Start simple:** Basic mappings only need `source` and optional `resolver`
-2. **Mark required fields:** Use `required: true` to catch missing data early
-3. **Use SDK resolvers:** Built-in resolvers cover 90% of common transformations
-4. **Always check results:** Validate `result.success` before using data
-5. **Provide defaults:** Use `defaultValue` for optional fields
-
----
-
-## Next Steps
-
-Now that you can create basic mappings, you're ready to ensure they're correct:
-
-→ Continue to [Module 3: Schema Validation](./mapping-03-schema-validation.md)
-
-**Alternative paths:**
-
-- Jump to [Use Cases](./mapping-04-use-cases.md) to see real-world examples
-- Review [Advanced Patterns](./mapping-05-advanced-patterns.md) for nested objects and arrays
-
----
-
-[← Back to Foundations](./mapping-01-foundations.md) | [Next: Schema Validation →](./mapping-03-schema-validation.md)
-
-
-
-
-
-
-
-
-
-
-
-
+# Module 2: Quick Start
+
+**Get started with universal mapping in 15 minutes**
+
+**Level:** Beginner
+**Time:** 15 minutes
+**Prerequisites:** [Module 1: Foundations](./mapping-01-foundations.md)
+
+---
+
+## Learning Objectives
+
+After completing this module, you will:
+
+- ✅ Create your first mapping configuration
+- ✅ Use basic SDK resolvers
+- ✅ Run a complete CSV ingestion example
+- ✅ Handle errors and validate results
+
+---
+
+## Your First Mapping
+
+Let's create a simple CSV inventory ingestion mapping.
+
+### Step 1: Define the Mapping
+
+Create `inventory-mapping.json`:
+
+```json
+{
+  "fields": {
+    "ref": {
+      "source": "sku",
+      "required": true
+    },
+    "productRef": {
+      "source": "sku",
+      "required": true
+    },
+    "locationRef": {
+      "source": "location",
+      "required": true
+    },
+    "qty": {
+      "source": "quantity",
+      "resolver": "sdk.parseInt",
+      "required": true
+    },
+    "status": {
+      "source": "status",
+      "resolver": "sdk.uppercase",
+      "defaultValue": "AVAILABLE"
+    }
+  }
+}
+```
+
+### Step 2: Prepare Sample Data
+
+Create `inventory.csv`:
+
+```csv
+sku,location,quantity,status
+SKU-WM-001,WH-001,500,available
+SKU-WM-002,WH-001,150,available
+SKU-KB-001,WH-001,75,reserved
+```
+
+### Step 3: Implement the Workflow
+
+```typescript
+import { UniversalMapper, CSVParserService, createClient } from '@fluentcommerce/fc-connect-sdk';
+import * as fs from 'fs';
+
+// Load mapping configuration
+const mappingConfig = JSON.parse(fs.readFileSync('./inventory-mapping.json', 'utf-8'));
+
+// Load CSV data
+const csvContent = fs.readFileSync('./inventory.csv', 'utf-8');
+const parser = new CSVParserService();
+const records = await parser.parse(csvContent);
+
+// Create mapper
+const mapper = new UniversalMapper(mappingConfig);
+
+// Process each CSV row
+const batchEntities = [];
+for (const row of records) {
+  const result = await mapper.map(row);
+
+  if (result.success) {
+    batchEntities.push(result.data);
+  } else {
+    console.error('Mapping failed for row:', row);
+    console.error('Errors:', result.errors);
+  }
+}
+
+// Send to Fluent Commerce
+const client = await createClient({
+  config: {
+    baseUrl: process.env.FLUENT_BASE_URL!,
+    clientId: process.env.FLUENT_CLIENT_ID!,
+    clientSecret: process.env.FLUENT_CLIENT_SECRET!,
+    username: process.env.FLUENT_USERNAME!,
+    password: process.env.FLUENT_PASSWORD!,
+    retailerId: process.env.FLUENT_RETAILER_ID!,
+  },
+});
+
+// Create a batch job and send entities
+const job = await client.createJob({
+  name: `inventory-import-${Date.now()}`,
+  retailerId: process.env.FLUENT_RETAILER_ID!,
+});
+
+await client.sendBatch(job.id, {
+  action: 'UPSERT',
+  entityType: 'INVENTORY',
+  source: 'CSV_IMPORT',
+  event: 'INVENTORY_UPDATE',
+  entities: batchEntities,
+});
+
+console.log(`✅ Successfully processed ${batchEntities.length} records`);
+```
+
+### Step 4: Run and Validate
+
+```bash
+npm install @fluentcommerce/fc-connect-sdk
+node inventory-import.js
+```
+
+**Expected Output:**
+
+```
+✅ Successfully processed 3 records
+```
+
+---
+
+## Understanding the Mapping
+
+Let's break down what each field does:
+
+### Field: `ref`
+
+```json
+"ref": {
+  "source": "sku",
+  "required": true
+}
+```
+
+- **source:** Read from `sku` column in CSV
+- **required:** Must have a value (fails if missing)
+- **Result:** Direct copy of SKU value
+
+### Field: `qty`
+
+```json
+"qty": {
+  "source": "quantity",
+  "resolver": "sdk.parseInt",
+  "required": true
+}
+```
+
+- **source:** Read from `quantity` column
+- **resolver:** Convert string "500" to integer 500
+- **required:** Must have a value
+- **Result:** Parsed integer
+
+### Field: `status`
+
+```json
+"status": {
+  "source": "status",
+  "resolver": "sdk.uppercase",
+  "defaultValue": "AVAILABLE"
+}
+```
+
+- **source:** Read from `status` column
+- **resolver:** Convert "available" to "AVAILABLE"
+- **defaultValue:** Use "AVAILABLE" if missing
+- **Result:** Uppercased string or default
+
+---
+
+## Common SDK Resolvers
+
+Here are the most commonly used SDK resolvers:
+
+### String Transformations
+
+```json
+// Uppercase
+"status": { "source": "status", "resolver": "sdk.uppercase" }
+// "active" → "ACTIVE"
+
+// Lowercase
+"email": { "source": "email", "resolver": "sdk.lowercase" }
+// "USER@EXAMPLE.COM" → "user@example.com"
+
+// Trim whitespace
+"name": { "source": "name", "resolver": "sdk.trim" }
+// "  Product  " → "Product"
+```
+
+### Number Transformations
+
+```json
+// Parse integer
+"quantity": { "source": "qty", "resolver": "sdk.parseInt" }
+// "100" → 100
+
+// Parse float
+"price": { "source": "price", "resolver": "sdk.parseFloat" }
+// "19.99" → 19.99
+```
+
+### Date Transformations
+
+```json
+// ISO8601 format
+"createdAt": { "source": "date", "resolver": "sdk.formatDate" }
+// "2024-01-15" → "2024-01-15T00:00:00.000Z"
+
+// Short format (YYYY-MM-DD)
+"expectedOn": { "source": "date", "resolver": "sdk.formatDateShort" }
+// "01/15/2024" → "2024-01-15"
+```
+
+---
+
+## Error Handling
+
+Always check mapping results:
+
+```typescript
+const result = await mapper.map(sourceData);
+
+if (result.success) {
+  // ✅ Mapping succeeded
+  console.log('Mapped data:', result.data);
+  batchEntities.push(result.data);
+} else {
+  // ❌ Mapping failed
+  console.error('Mapping failed');
+  console.error('Errors:', result.errors);
+  console.error('Source data:', sourceData);
+
+  // Log each error
+  result.errors.forEach(error => {
+    console.error(`- Field: ${error.field}`);
+    console.error(`  Message: ${error.message}`);
+  });
+}
+```
+
+### Common Errors
+
+**Missing Required Field:**
+
+```
+Error: Required field 'productRef' is missing
+Source: { sku: '', location: 'WH-001', quantity: '100' }
+```
+
+**Invalid Number:**
+
+```
+Error: Failed to parse 'qty' as integer
+Source: { quantity: 'invalid' }
+```
+
+**Resolver Error:**
+
+```
+Error: Resolver 'sdk.parseInt' failed
+Message: Cannot parse 'abc' as integer
+```
+
+---
+
+## Static Values
+
+Sometimes you need constant values:
+
+```json
+{
+  "fields": {
+    "type": {
+      "value": "STANDARD"
+    },
+    "retailerId": {
+      "value": 1
+    },
+    "source": {
+      "value": "CSV_IMPORT"
+    }
+  }
+}
+```
+
+**Result:**
+
+```json
+{
+  "type": "STANDARD",
+  "retailerId": 1,
+  "source": "CSV_IMPORT"
+}
+```
+
+---
+
+## Default Values
+
+Provide fallbacks for optional fields:
+
+```json
+{
+  "fields": {
+    "status": {
+      "source": "orderStatus",
+      "defaultValue": "PENDING"
+    },
+    "shippingMethod": {
+      "source": "shipping",
+      "defaultValue": "STANDARD"
+    }
+  }
+}
+```
+
+**Behavior:**
+
+- If `orderStatus` exists → use its value
+- If `orderStatus` is missing/empty → use "PENDING"
+
+---
+
+## Combining Resolvers and Defaults
+
+```json
+{
+  "fields": {
+    "quantity": {
+      "source": "qty",
+      "resolver": "sdk.parseInt",
+      "defaultValue": 0
+    }
+  }
+}
+```
+
+**Processing order:**
+
+1. Read from `qty` field
+2. If missing → use default value `0`
+3. Apply resolver `sdk.parseInt`
+4. Return result
+
+---
+
+## Practice Exercise
+
+**Task:** Create a mapping for this customer CSV:
+
+```csv
+email,first_name,last_name,phone,status
+john@example.com,John,Doe,555-1234,active
+jane@example.com,Jane,Smith,555-5678,
+```
+
+**Requirements:**
+
+1. Map `email` to lowercase
+2. Combine `first_name` and `last_name` into `fullName`
+3. Format `phone` (you'll need a custom resolver)
+4. Map `status` to uppercase with default "ACTIVE"
+5. Mark `email` as required
+
+<details>
+<summary>Click to see solution</summary>
+
+```json
+{
+  "fields": {
+    "email": {
+      "source": "email",
+      "resolver": "sdk.lowercase",
+      "required": true
+    },
+    "firstName": {
+      "source": "first_name",
+      "required": true
+    },
+    "lastName": {
+      "source": "last_name",
+      "required": true
+    },
+    "phone": {
+      "source": "phone",
+      "resolver": "custom.formatPhone"
+    },
+    "status": {
+      "source": "status",
+      "resolver": "sdk.uppercase",
+      "defaultValue": "ACTIVE"
+    }
+  }
+}
+```
+
+**Custom resolver for phone formatting:**
+
+```typescript
+const customResolvers = {
+  'custom.formatPhone': (value: any) => {
+    const digits = String(value).replace(/\D/g, '');
+    return `(${digits.slice(0, 3)}) ${digits.slice(3, 6)}-${digits.slice(6)}`;
+  },
+};
+
+const mapper = new UniversalMapper(config, { customResolvers });
+```
+
+**Note:** Combining `first_name` and `last_name` would also require a custom resolver. See [Module 6: Custom Resolvers](./mapping-06-helpers-resolvers.md) for advanced patterns.
+
+</details>
+
+---
+
+## Key Takeaways
+
+1. **Start simple:** Basic mappings only need `source` and optional `resolver`
+2. **Mark required fields:** Use `required: true` to catch missing data early
+3. **Use SDK resolvers:** Built-in resolvers cover 90% of common transformations
+4. **Always check results:** Validate `result.success` before using data
+5. **Provide defaults:** Use `defaultValue` for optional fields
+
+---
+
+## Next Steps
+
+Now that you can create basic mappings, you're ready to ensure they're correct:
+
+→ Continue to [Module 3: Schema Validation](./mapping-03-schema-validation.md)
+
+**Alternative paths:**
+
+- Jump to [Use Cases](./mapping-04-use-cases.md) to see real-world examples
+- Review [Advanced Patterns](./mapping-05-advanced-patterns.md) for nested objects and arrays
+
+---
+
+[← Back to Foundations](./mapping-01-foundations.md) | [Next: Schema Validation →](./mapping-03-schema-validation.md)
+
+
+
+
+
+
+
+
+
+
+
+
+
+