npm - @fluentcommerce/fc-connect-sdk - Versions diffs - 0.1.54 → 0.1.56 - Mend

@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (476) hide show

package/docs/02-CORE-GUIDES/ingestion/modules/02-core-guides-ingestion-04-field-mapping.md CHANGED Viewed

@@ -1,763 +1,763 @@
-# Module 4: Field Mapping
-**Level:** Intermediate
-**Estimated Time:** 25 minutes
-## Overview
-This module teaches you how to transform source data (CSV, Parquet, JSON) into the exact format required by Fluent Commerce's Batch API using the UniversalMapper service with schema-validated field mappings.
-## Learning Objectives
-By the end of this module, you will:
-- ✅ Understand InventoryPositionInput schema requirements
-- ✅ Configure UniversalMapper with field mappings
-- ✅ Use SDK resolvers for data transformation
-- ✅ Create custom resolvers for business logic
-- ✅ Validate mappings against GraphQL schema
-- ✅ Handle mapping errors gracefully
-## Inventory Position Schema
-### Required Fields
-The Batch API requires specific fields for `InventoryPositionInput`:
-```typescript
-{
-  "ref": "SKU-WM-001",         // String! - Position reference (required)
-  "productRef": "SKU-WM-001",  // String! - Product SKU (required)
-  "locationRef": "WH-001",     // String! - Warehouse code (required)
-  "qty": 500                   // Int! - Available quantity (required)
-}
-```
-### Optional Fields
-```typescript
-{
-  "status": "AVAILABLE",       // String - Position status
-  "type": "ADJUSTMENT"         // String - Position type
-}
-```
-### Valid Status Values
-| Status | Description |
-|--------|-------------|
-| `AVAILABLE` | Stock available for sale |
-| `RESERVED` | Stock reserved for orders |
-| `ON_HOLD` | Stock on hold (damaged, quarantine, etc.) |
-| `DISCONTINUED` | Product no longer carried |
-## UniversalMapper Basics
-### Simple Mapping
-```typescript
-import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-const mapper = new UniversalMapper({
-  fields: {
-    // Map source field to target field
-    ref: {
-      source: 'sku',           // Source CSV column
-      required: true           // Must be present
-    },
-    productRef: {
-      source: 'sku',
-      required: true
-    },
-    locationRef: {
-      source: 'warehouse',
-      required: true
-    },
-    qty: {
-      source: 'quantity',
-      resolver: 'sdk.parseInt',  // Convert to integer
-      required: true
-    }
-  }
-});
-// Transform CSV data
-const csvData = [
-  { sku: 'SKU-001', warehouse: 'WH-001', quantity: '500' }
-];
-const result = await mapper.map(csvData);
-if (result.success) {
-  console.log(result.data);
-  // [{
-  //   ref: 'SKU-001',
-  //   productRef: 'SKU-001',
-  //   locationRef: 'WH-001',
-  //   qty: 500
-  // }]
-}
-```
-### Mapping Result
-```typescript
-interface MappingResult {
-  success: boolean;
-  data: any[];            // Mapped records (if success)
-  errors?: string[];      // Validation errors (if failed)
-  skippedFields?: string[];  // Fields that were skipped because they were undefined (field names only)
-}
-```
-## SDK Resolvers
-The SDK provides built-in resolvers for common transformations:
-### String Resolvers
-```typescript
-const mapping = {
-  fields: {
-    ref: {
-      source: 'sku',
-      resolver: 'sdk.uppercase'    // Convert to UPPERCASE
-    },
-    status: {
-      source: 'status',
-      resolver: 'sdk.lowercase'    // Convert to lowercase
-    },
-    locationRef: {
-      source: ' warehouse ',
-      resolver: 'sdk.trim'         // Remove whitespace
-    }
-  }
-};
-```
-### Number Resolvers
-```typescript
-const mapping = {
-  fields: {
-    qty: {
-      source: 'quantity',
-      resolver: 'sdk.parseInt'     // String → Int
-    },
-    price: {
-      source: 'cost',
-      resolver: 'sdk.parseFloat'   // String → Float
-    },
-    count: {
-      source: 'total',
-      resolver: 'sdk.number'       // Force to number
-    }
-  }
-};
-```
-### Date Resolvers
-```typescript
-const mapping = {
-  fields: {
-    expectedOn: {
-      source: 'ship_date',
-      resolver: 'sdk.formatDate'       // Format as ISO date
-    },
-    lastUpdated: {
-      source: 'updated',
-      resolver: 'sdk.formatDateShort'  // Format as YYYY-MM-DD
-    },
-    createdAt: {
-      source: 'created_timestamp',
-      resolver: 'sdk.parseDate'        // Parse various date formats
-    }
-  }
-};
-```
-### Utility Resolvers
-```typescript
-const mapping = {
-  fields: {
-    isActive: {
-      source: 'active',
-      resolver: 'sdk.boolean'      // Convert to boolean
-    },
-    metadata: {
-      source: 'meta_json',
-      resolver: 'sdk.parseJson'    // Parse JSON string
-    },
-    config: {
-      source: 'settings',
-      resolver: 'sdk.toJson'       // Convert to JSON string
-    },
-    value: {
-      source: 'original',
-      resolver: 'sdk.identity'     // Pass through unchanged
-    }
-  }
-};
-```
-## Custom Resolvers
-### Basic Custom Resolver
-```typescript
-const mapper = new UniversalMapper(mappingConfig, {
-  customResolvers: {
-    'custom.mapStatus': (value, sourceData, config, helpers) => {
-      const statusMap = {
-        'in_stock': 'AVAILABLE',
-        'out_of_stock': 'ON_HOLD',
-        'discontinued': 'DISCONTINUED',
-        'reserved': 'RESERVED'
-      };
-      const mapped = statusMap[String(value).toLowerCase()];
-      if (!mapped) {
-        throw new Error(`Unknown status: ${value}`);
-      }
-      return mapped;
-    }
-  }
-});
-```
-### Resolver with Helper Functions
-```typescript
-const customResolvers = {
-  'custom.calculateQty': (value, sourceData, config, helpers) => {
-    // Use helper functions for safe conversions
-    const onHand = helpers.parseIntSafe(sourceData.on_hand, 0);
-    const reserved = helpers.parseIntSafe(sourceData.reserved, 0);
-    return onHand - reserved;
-  },
-  'custom.formatLocation': (value, sourceData, config, helpers) => {
-    // Combine multiple source fields
-    const region = helpers.toString(sourceData.region);
-    const warehouse = helpers.toString(sourceData.warehouse);
-    return `${region}-${warehouse}`;
-  }
-};
-```
-### Validation Resolver
-```typescript
-const customResolvers = {
-  'custom.validateSKU': (value, sourceData, config, helpers) => {
-    const sku = helpers.toString(value).trim();
-    // Must be alphanumeric and at least 3 characters
-    if (!/^[A-Z0-9-]{3,}$/i.test(sku)) {
-      throw new Error(`Invalid SKU format: ${sku}`);
-    }
-    return sku.toUpperCase();
-  },
-  'custom.ensurePositiveQty': (value, sourceData, config, helpers) => {
-    const qty = helpers.parseIntSafe(value, 0);
-    if (qty < 0) {
-      throw new Error(`Negative quantity not allowed: ${qty}`);
-    }
-    return qty;
-  }
-};
-```
-## Required Fields with Resolvers
-When using `required: true` with resolvers, understand how validation timing works:
-**Fields with `source`**: Validation happens **before** resolver execution
-```json
-{
-  "qty": {
-    "source": "quantity",
-    "resolver": "sdk.parseInt",
-    "required": true
-  }
-}
-```
-- ✅ Checks if `quantity` exists in source data first
-- ✅ If missing → mapping fails immediately (resolver never runs)
-- ✅ If present → resolver runs to transform the value
-**Resolver-only fields** (no `source`): Validation happens **after** resolver execution
-```json
-{
-  "metadata.uuid": {
-    "resolver": "custom.generateUUID",
-    "required": true
-  }
-}
-```
-- ✅ Resolver runs first to generate value
-- ✅ Then validates that resolver produced a value
-- ✅ If resolver returns `null`, `undefined`, or empty string → mapping fails
-**Important:** Resolvers can return empty values. `required: true` ensures validation happens **after** the resolver runs to catch these cases. If your resolver has conditional logic that might return `undefined`, use `required: true` to ensure the field always has a value.
-**Example: Conditional Resolver**
-```typescript
-const customResolvers = {
-  'custom.calculateDiscount': (value, sourceData, config, helpers) => {
-    const customerTier = helpers.get(sourceData, 'customer.tier');
-    // ⚠️ Can return undefined for BASIC tier!
-    if (customerTier === 'PREMIUM') {
-      return helpers.parseFloatSafe(value, 0) * 0.2;
-    } else if (customerTier === 'STANDARD') {
-      return helpers.parseFloatSafe(value, 0) * 0.1;
-    }
-    return undefined; // ❌ Returns undefined
-  }
-};
-// Mapping config
-{
-  "fields": {
-    "discount": {
-      "source": "order.subtotal",
-      "resolver": "custom.calculateDiscount",
-      "required": true  // ✅ Ensures discount is always calculated
-    }
-  }
-}
-```
-Without `required: true`:
-- Resolver returns `undefined` for BASIC tier → mapping succeeds → API call fails
-With `required: true`:
-- Resolver returns `undefined` → mapping fails immediately → No API call (saves quota)
-## Complete Mapping Example
-```typescript
-import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-// Schema-validated mapping configuration
-const mappingConfig = {
-  fields: {
-    // Required fields
-    ref: {
-      source: 'sku',
-      resolver: 'custom.validateSKU',
-      required: true,
-      comment: '✅ InventoryPositionInput.ref (String! required)'
-    },
-    productRef: {
-      source: 'sku',
-      resolver: 'custom.validateSKU',
-      required: true,
-      comment: '✅ InventoryPositionInput.productRef (String! required)'
-    },
-    locationRef: {
-      source: 'warehouse',
-      resolver: 'sdk.trim',
-      required: true,
-      comment: '✅ InventoryPositionInput.locationRef (String! required)'
-    },
-    qty: {
-      source: 'quantity',
-      resolver: 'custom.ensurePositiveQty',
-      required: true,
-      comment: '✅ InventoryPositionInput.qty (Int! required)'
-    },
-    // Optional fields with defaults
-    status: {
-      source: 'status',
-      resolver: 'custom.mapStatus',
-      defaultValue: 'AVAILABLE',
-      comment: '✅ InventoryPositionInput.status (String optional)'
-    },
-    type: {
-      value: 'ADJUSTMENT',      // Static value for all records
-      comment: '✅ InventoryPositionInput.type (String optional)'
-    }
-  }
-};
-// Custom resolvers for business logic
-const customResolvers = {
-  'custom.validateSKU': (value, sourceData, config, helpers) => {
-    const sku = helpers.toString(value).trim().toUpperCase();
-    if (!/^[A-Z0-9-]{3,}$/.test(sku)) {
-      throw new Error(`Invalid SKU: ${sku}`);
-    }
-    return sku;
-  },
-  'custom.ensurePositiveQty': (value, sourceData, config, helpers) => {
-    const qty = helpers.parseIntSafe(value, 0);
-    if (qty < 0) {
-      throw new Error(`Negative quantity: ${qty}`);
-    }
-    return qty;
-  },
-  'custom.mapStatus': (value, sourceData, config, helpers) => {
-    const statusMap = {
-      'in_stock': 'AVAILABLE',
-      'out_of_stock': 'ON_HOLD',
-      'discontinued': 'DISCONTINUED',
-      'reserved': 'RESERVED'
-    };
-    const status = helpers.toString(value).toLowerCase();
-    const mapped = statusMap[status];
-    if (!mapped) {
-      throw new Error(`Unknown status: ${value}`);
-    }
-    return mapped;
-  }
-};
-// Create mapper with custom resolvers
-const mapper = new UniversalMapper(mappingConfig, { customResolvers });
-// Map CSV data
-const csvData = [
-  { sku: 'sku-wm-001', warehouse: 'WH-001', quantity: '500', status: 'in_stock' },
-  { sku: 'sku-wm-002', warehouse: 'WH-001', quantity: '150', status: 'reserved' }
-];
-const result = await mapper.map(csvData);
-if (!result.success) {
-  console.error('Mapping errors:', result.errors);
-  process.exit(1);
-}
-console.log('Mapped records:', result.data);
-// [
-//   { ref: 'SKU-WM-001', productRef: 'SKU-WM-001', locationRef: 'WH-001', qty: 500, status: 'AVAILABLE', type: 'ADJUSTMENT' },
-//   { ref: 'SKU-WM-002', productRef: 'SKU-WM-002', locationRef: 'WH-001', qty: 150, status: 'RESERVED', type: 'ADJUSTMENT' }
-// ]
-```
-## Schema Validation
-### Validate Before Deployment
-```bash
-# Step 1: Introspect your Fluent Commerce schema
-npx @fluentcommerce/fc-connect-sdk introspect-schema \
-  --url https://YOUR_ACCOUNT.api.fluentcommerce.com/graphql \
-  --output schema.json
-# Step 2: Save your mapping configuration
-cat > field-mappings.json << 'EOF'
-{
-  "fields": {
-    "ref": { "source": "sku", "required": true },
-    "productRef": { "source": "sku", "required": true },
-    "locationRef": { "source": "warehouse", "required": true },
-    "qty": { "source": "quantity", "resolver": "sdk.parseInt", "required": true },
-    "status": { "source": "status", "resolver": "custom.mapStatus", "defaultValue": "AVAILABLE" }
-  }
-}
-EOF
-# Step 3: Validate mapping against schema
-npx @fluentcommerce/fc-connect-sdk validate-schema \
-  --mapping field-mappings.json \
-  --schema schema.json
-```
-### Expected Output
-```
-✅ Mapping validation successful
-✅ All required fields present: ref, productRef, locationRef, qty
-✅ All field types compatible with InventoryPositionInput schema
-✅ No unknown fields detected
-Validation Summary:
-  Required fields: 4/4 ✓
-  Optional fields: 1
-  Custom resolvers: 1 (custom.mapStatus)
-  SDK resolvers: 1 (sdk.parseInt)
-```
-## Error Handling
-### Mapping Errors
-```typescript
-const result = await mapper.map(csvData);
-if (!result.success) {
-  // Log all errors
-  console.error('Mapping failed with errors:');
-  result.errors.forEach((error, index) => {
-    console.error(`  ${index + 1}. ${error}`);
-  });
-  // Optionally: Write failed records to error file
-  const errorReport = {
-    timestamp: new Date().toISOString(),
-    totalRecords: csvData.length,
-    errors: result.errors,
-    failedRecords: csvData.filter((_, i) => result.errors.some(e => e.includes(`Row ${i}`)))
-  };
-  await fs.writeFile('mapping-errors.json', JSON.stringify(errorReport, null, 2));
-  throw new Error(`Mapping failed: ${result.errors.length} errors`);
-}
-```
-### Partial Success Handling
-```typescript
-async function mapWithPartialSuccess(mapper: UniversalMapper, records: any[]) {
-  const successful = [];
-  const failed = [];
-  for (const [index, record] of records.entries()) {
-    try {
-      const result = await mapper.map([record]);
-      if (result.success) {
-        successful.push(result.data[0]);
-      } else {
-        failed.push({ record, errors: result.errors });
-      }
-    } catch (error) {
-      failed.push({ record, error: error.message });
-    }
-  }
-  return {
-    successful,
-    failed,
-    successRate: successful.length / records.length
-  };
-}
-```
-## Advanced Patterns
-### Conditional Mapping
-```typescript
-const conditionalMapper = {
-  'custom.conditionalStatus': (value, sourceData, config, helpers) => {
-    const qty = helpers.parseIntSafe(sourceData.quantity, 0);
-    const status = helpers.toString(value).toLowerCase();
-    // Override status based on quantity
-    if (qty === 0) {
-      return 'ON_HOLD';
-    }
-    if (qty > 1000) {
-      return 'AVAILABLE';
-    }
-    // Use source status
-    return status === 'available' ? 'AVAILABLE' : 'RESERVED';
-  }
-};
-```
-### Multi-Field Transformation
-```typescript
-const multiFieldMapper = {
-  'custom.generateRef': (value, sourceData, config, helpers) => {
-    const sku = helpers.toString(sourceData.sku).trim();
-    const location = helpers.toString(sourceData.warehouse).trim();
-    const date = new Date().toISOString().split('T')[0];
-    return `${sku}-${location}-${date}`;
-  }
-};
-```
-### Lookup Table Resolver
-```typescript
-const lookupTables = {
-  warehouseCodes: {
-    'California DC': 'CA-001',
-    'Texas DC': 'TX-001',
-    'New York DC': 'NY-001'
-  }
-};
-const lookupResolver = {
-  'custom.lookupWarehouse': (value, sourceData, config, helpers) => {
-    const warehouseName = helpers.toString(value);
-    const code = lookupTables.warehouseCodes[warehouseName];
-    if (!code) {
-      throw new Error(`Unknown warehouse: ${warehouseName}`);
-    }
-    return code;
-  }
-};
-```
-## Practice Exercise
-Create a field mapping that:
-1. Validates SKU format (alphanumeric, min 3 chars)
-2. Maps status from custom values to Fluent values
-3. Calculates available quantity (on_hand - reserved)
-4. Generates a unique position reference
-<details>
-<summary>Click to see solution</summary>
-```typescript
-import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-const mappingConfig = {
-  fields: {
-    ref: {
-      source: 'sku',
-      resolver: 'custom.generatePositionRef',
-      required: true
-    },
-    productRef: {
-      source: 'sku',
-      resolver: 'custom.validateSKU',
-      required: true
-    },
-    locationRef: {
-      source: 'warehouse',
-      required: true
-    },
-    qty: {
-      source: 'on_hand',
-      resolver: 'custom.calculateAvailable',
-      required: true
-    },
-    status: {
-      source: 'stock_status',
-      resolver: 'custom.mapStockStatus',
-      defaultValue: 'AVAILABLE'
-    }
-  }
-};
-const customResolvers = {
-  'custom.validateSKU': (value, sourceData, config, helpers) => {
-    const sku = helpers.toString(value).trim().toUpperCase();
-    if (!/^[A-Z0-9]{3,}$/.test(sku)) {
-      throw new Error(`Invalid SKU format: ${value}`);
-    }
-    return sku;
-  },
-  'custom.generatePositionRef': (value, sourceData, config, helpers) => {
-    const sku = helpers.toString(value).trim().toUpperCase();
-    const warehouse = helpers.toString(sourceData.warehouse).trim();
-    return `${sku}-${warehouse}`;
-  },
-  'custom.calculateAvailable': (value, sourceData, config, helpers) => {
-    const onHand = helpers.parseIntSafe(value, 0);
-    const reserved = helpers.parseIntSafe(sourceData.reserved, 0);
-    return Math.max(0, onHand - reserved);
-  },
-  'custom.mapStockStatus': (value, sourceData, config, helpers) => {
-    const statusMap = {
-      'active': 'AVAILABLE',
-      'low': 'RESERVED',
-      'out': 'ON_HOLD',
-      'discontinued': 'DISCONTINUED'
-    };
-    const status = helpers.toString(value).toLowerCase();
-    return statusMap[status] || 'AVAILABLE';
-  }
-};
-const mapper = new UniversalMapper(mappingConfig, { customResolvers });
-// Test data
-const csvData = [
-  { sku: 'abc123', warehouse: 'WH-001', on_hand: '100', reserved: '20', stock_status: 'active' }
-];
-const result = await mapper.map(csvData);
-console.log(result);
-// {
-//   success: true,
-//   data: [{
-//     ref: 'ABC123-WH-001',
-//     productRef: 'ABC123',
-//     locationRef: 'WH-001',
-//     qty: 80,
-//     status: 'AVAILABLE'
-//   }]
-// }
-```
-</details>
-## Key Takeaways
-- 🎯 **UniversalMapper** transforms source data to Fluent schema
-- 🎯 **SDK resolvers** provide common transformations (uppercase, parseInt, etc.)
-- 🎯 **Custom resolvers** implement business logic and validation
-- 🎯 **Schema validation** ensures compatibility before deployment
-- 🎯 **Error handling** provides clear feedback for mapping failures
-- 🎯 **Resolver helpers** simplify safe type conversions
-## Next Steps
-Continue to [Module 5: Advanced Parsers →](./02-core-guides-ingestion-05-advanced-parsers.md) to learn about Parquet, XML, and JSON parsing with streaming support.
----
-**Related Documentation:**
-- [Universal Mapping Guide](../../mapping/mapping-readme.md) - Complete field mapping reference
-- [Resolver Development Guide](../../mapping/resolvers/mapping-resolvers-readme.md) - Advanced custom resolver patterns
-- [Schema Validation CLI](../../../../bin/readme.md#validate-04-REFERENCE/schema) - CLI tool documentation
+# Module 4: Field Mapping
+**Level:** Intermediate
+**Estimated Time:** 25 minutes
+## Overview
+This module teaches you how to transform source data (CSV, Parquet, JSON) into the exact format required by Fluent Commerce's Batch API using the UniversalMapper service with schema-validated field mappings.
+## Learning Objectives
+By the end of this module, you will:
+- ✅ Understand InventoryPositionInput schema requirements
+- ✅ Configure UniversalMapper with field mappings
+- ✅ Use SDK resolvers for data transformation
+- ✅ Create custom resolvers for business logic
+- ✅ Validate mappings against GraphQL schema
+- ✅ Handle mapping errors gracefully
+## Inventory Position Schema
+### Required Fields
+The Batch API requires specific fields for `InventoryPositionInput`:
+```typescript
+{
+  "ref": "SKU-WM-001",         // String! - Position reference (required)
+  "productRef": "SKU-WM-001",  // String! - Product SKU (required)
+  "locationRef": "WH-001",     // String! - Warehouse code (required)
+  "qty": 500                   // Int! - Available quantity (required)
+}
+```
+### Optional Fields
+```typescript
+{
+  "status": "AVAILABLE",       // String - Position status
+  "type": "ADJUSTMENT"         // String - Position type
+}
+```
+### Valid Status Values
+| Status | Description |
+|--------|-------------|
+| `AVAILABLE` | Stock available for sale |
+| `RESERVED` | Stock reserved for orders |
+| `ON_HOLD` | Stock on hold (damaged, quarantine, etc.) |
+| `DISCONTINUED` | Product no longer carried |
+## UniversalMapper Basics
+### Simple Mapping
+```typescript
+import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+const mapper = new UniversalMapper({
+  fields: {
+    // Map source field to target field
+    ref: {
+      source: 'sku',           // Source CSV column
+      required: true           // Must be present
+    },
+    productRef: {
+      source: 'sku',
+      required: true
+    },
+    locationRef: {
+      source: 'warehouse',
+      required: true
+    },
+    qty: {
+      source: 'quantity',
+      resolver: 'sdk.parseInt',  // Convert to integer
+      required: true
+    }
+  }
+});
+// Transform CSV data
+const csvData = [
+  { sku: 'SKU-001', warehouse: 'WH-001', quantity: '500' }
+];
+const result = await mapper.map(csvData);
+if (result.success) {
+  console.log(result.data);
+  // [{
+  //   ref: 'SKU-001',
+  //   productRef: 'SKU-001',
+  //   locationRef: 'WH-001',
+  //   qty: 500
+  // }]
+}
+```
+### Mapping Result
+```typescript
+interface MappingResult {
+  success: boolean;
+  data: any[];            // Mapped records (if success)
+  errors?: string[];      // Validation errors (if failed)
+  skippedFields?: string[];  // Fields that were skipped because they were undefined (field names only)
+}
+```
+## SDK Resolvers
+The SDK provides built-in resolvers for common transformations:
+### String Resolvers
+```typescript
+const mapping = {
+  fields: {
+    ref: {
+      source: 'sku',
+      resolver: 'sdk.uppercase'    // Convert to UPPERCASE
+    },
+    status: {
+      source: 'status',
+      resolver: 'sdk.lowercase'    // Convert to lowercase
+    },
+    locationRef: {
+      source: ' warehouse ',
+      resolver: 'sdk.trim'         // Remove whitespace
+    }
+  }
+};
+```
+### Number Resolvers
+```typescript
+const mapping = {
+  fields: {
+    qty: {
+      source: 'quantity',
+      resolver: 'sdk.parseInt'     // String → Int
+    },
+    price: {
+      source: 'cost',
+      resolver: 'sdk.parseFloat'   // String → Float
+    },
+    count: {
+      source: 'total',
+      resolver: 'sdk.number'       // Force to number
+    }
+  }
+};
+```
+### Date Resolvers
+```typescript
+const mapping = {
+  fields: {
+    expectedOn: {
+      source: 'ship_date',
+      resolver: 'sdk.formatDate'       // Format as ISO date
+    },
+    lastUpdated: {
+      source: 'updated',
+      resolver: 'sdk.formatDateShort'  // Format as YYYY-MM-DD
+    },
+    createdAt: {
+      source: 'created_timestamp',
+      resolver: 'sdk.parseDate'        // Parse various date formats
+    }
+  }
+};
+```
+### Utility Resolvers
+```typescript
+const mapping = {
+  fields: {
+    isActive: {
+      source: 'active',
+      resolver: 'sdk.boolean'      // Convert to boolean
+    },
+    metadata: {
+      source: 'meta_json',
+      resolver: 'sdk.parseJson'    // Parse JSON string
+    },
+    config: {
+      source: 'settings',
+      resolver: 'sdk.toJson'       // Convert to JSON string
+    },
+    value: {
+      source: 'original',
+      resolver: 'sdk.identity'     // Pass through unchanged
+    }
+  }
+};
+```
+## Custom Resolvers
+### Basic Custom Resolver
+```typescript
+const mapper = new UniversalMapper(mappingConfig, {
+  customResolvers: {
+    'custom.mapStatus': (value, sourceData, config, helpers) => {
+      const statusMap = {
+        'in_stock': 'AVAILABLE',
+        'out_of_stock': 'ON_HOLD',
+        'discontinued': 'DISCONTINUED',
+        'reserved': 'RESERVED'
+      };
+      const mapped = statusMap[String(value).toLowerCase()];
+      if (!mapped) {
+        throw new Error(`Unknown status: ${value}`);
+      }
+      return mapped;
+    }
+  }
+});
+```
+### Resolver with Helper Functions
+```typescript
+const customResolvers = {
+  'custom.calculateQty': (value, sourceData, config, helpers) => {
+    // Use helper functions for safe conversions
+    const onHand = helpers.parseIntSafe(sourceData.on_hand, 0);
+    const reserved = helpers.parseIntSafe(sourceData.reserved, 0);
+    return onHand - reserved;
+  },
+  'custom.formatLocation': (value, sourceData, config, helpers) => {
+    // Combine multiple source fields
+    const region = helpers.toString(sourceData.region);
+    const warehouse = helpers.toString(sourceData.warehouse);
+    return `${region}-${warehouse}`;
+  }
+};
+```
+### Validation Resolver
+```typescript
+const customResolvers = {
+  'custom.validateSKU': (value, sourceData, config, helpers) => {
+    const sku = helpers.toString(value).trim();
+    // Must be alphanumeric and at least 3 characters
+    if (!/^[A-Z0-9-]{3,}$/i.test(sku)) {
+      throw new Error(`Invalid SKU format: ${sku}`);
+    }
+    return sku.toUpperCase();
+  },
+  'custom.ensurePositiveQty': (value, sourceData, config, helpers) => {
+    const qty = helpers.parseIntSafe(value, 0);
+    if (qty < 0) {
+      throw new Error(`Negative quantity not allowed: ${qty}`);
+    }
+    return qty;
+  }
+};
+```
+## Required Fields with Resolvers
+When using `required: true` with resolvers, understand how validation timing works:
+**Fields with `source`**: Validation happens **before** resolver execution
+```json
+{
+  "qty": {
+    "source": "quantity",
+    "resolver": "sdk.parseInt",
+    "required": true
+  }
+}
+```
+- ✅ Checks if `quantity` exists in source data first
+- ✅ If missing → mapping fails immediately (resolver never runs)
+- ✅ If present → resolver runs to transform the value
+**Resolver-only fields** (no `source`): Validation happens **after** resolver execution
+```json
+{
+  "metadata.uuid": {
+    "resolver": "custom.generateUUID",
+    "required": true
+  }
+}
+```
+- ✅ Resolver runs first to generate value
+- ✅ Then validates that resolver produced a value
+- ✅ If resolver returns `null`, `undefined`, or empty string → mapping fails
+**Important:** Resolvers can return empty values. `required: true` ensures validation happens **after** the resolver runs to catch these cases. If your resolver has conditional logic that might return `undefined`, use `required: true` to ensure the field always has a value.
+**Example: Conditional Resolver**
+```typescript
+const customResolvers = {
+  'custom.calculateDiscount': (value, sourceData, config, helpers) => {
+    const customerTier = helpers.get(sourceData, 'customer.tier');
+    // ⚠️ Can return undefined for BASIC tier!
+    if (customerTier === 'PREMIUM') {
+      return helpers.parseFloatSafe(value, 0) * 0.2;
+    } else if (customerTier === 'STANDARD') {
+      return helpers.parseFloatSafe(value, 0) * 0.1;
+    }
+    return undefined; // ❌ Returns undefined
+  }
+};
+// Mapping config
+{
+  "fields": {
+    "discount": {
+      "source": "order.subtotal",
+      "resolver": "custom.calculateDiscount",
+      "required": true  // ✅ Ensures discount is always calculated
+    }
+  }
+}
+```
+Without `required: true`:
+- Resolver returns `undefined` for BASIC tier → mapping succeeds → API call fails
+With `required: true`:
+- Resolver returns `undefined` → mapping fails immediately → No API call (saves quota)
+## Complete Mapping Example
+```typescript
+import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+// Schema-validated mapping configuration
+const mappingConfig = {
+  fields: {
+    // Required fields
+    ref: {
+      source: 'sku',
+      resolver: 'custom.validateSKU',
+      required: true,
+      comment: '✅ InventoryPositionInput.ref (String! required)'
+    },
+    productRef: {
+      source: 'sku',
+      resolver: 'custom.validateSKU',
+      required: true,
+      comment: '✅ InventoryPositionInput.productRef (String! required)'
+    },
+    locationRef: {
+      source: 'warehouse',
+      resolver: 'sdk.trim',
+      required: true,
+      comment: '✅ InventoryPositionInput.locationRef (String! required)'
+    },
+    qty: {
+      source: 'quantity',
+      resolver: 'custom.ensurePositiveQty',
+      required: true,
+      comment: '✅ InventoryPositionInput.qty (Int! required)'
+    },
+    // Optional fields with defaults
+    status: {
+      source: 'status',
+      resolver: 'custom.mapStatus',
+      defaultValue: 'AVAILABLE',
+      comment: '✅ InventoryPositionInput.status (String optional)'
+    },
+    type: {
+      value: 'ADJUSTMENT',      // Static value for all records
+      comment: '✅ InventoryPositionInput.type (String optional)'
+    }
+  }
+};
+// Custom resolvers for business logic
+const customResolvers = {
+  'custom.validateSKU': (value, sourceData, config, helpers) => {
+    const sku = helpers.toString(value).trim().toUpperCase();
+    if (!/^[A-Z0-9-]{3,}$/.test(sku)) {
+      throw new Error(`Invalid SKU: ${sku}`);
+    }
+    return sku;
+  },
+  'custom.ensurePositiveQty': (value, sourceData, config, helpers) => {
+    const qty = helpers.parseIntSafe(value, 0);
+    if (qty < 0) {
+      throw new Error(`Negative quantity: ${qty}`);
+    }
+    return qty;
+  },
+  'custom.mapStatus': (value, sourceData, config, helpers) => {
+    const statusMap = {
+      'in_stock': 'AVAILABLE',
+      'out_of_stock': 'ON_HOLD',
+      'discontinued': 'DISCONTINUED',
+      'reserved': 'RESERVED'
+    };
+    const status = helpers.toString(value).toLowerCase();
+    const mapped = statusMap[status];
+    if (!mapped) {
+      throw new Error(`Unknown status: ${value}`);
+    }
+    return mapped;
+  }
+};
+// Create mapper with custom resolvers
+const mapper = new UniversalMapper(mappingConfig, { customResolvers });
+// Map CSV data
+const csvData = [
+  { sku: 'sku-wm-001', warehouse: 'WH-001', quantity: '500', status: 'in_stock' },
+  { sku: 'sku-wm-002', warehouse: 'WH-001', quantity: '150', status: 'reserved' }
+];
+const result = await mapper.map(csvData);
+if (!result.success) {
+  console.error('Mapping errors:', result.errors);
+  process.exit(1);
+}
+console.log('Mapped records:', result.data);
+// [
+//   { ref: 'SKU-WM-001', productRef: 'SKU-WM-001', locationRef: 'WH-001', qty: 500, status: 'AVAILABLE', type: 'ADJUSTMENT' },
+//   { ref: 'SKU-WM-002', productRef: 'SKU-WM-002', locationRef: 'WH-001', qty: 150, status: 'RESERVED', type: 'ADJUSTMENT' }
+// ]
+```
+## Schema Validation
+### Validate Before Deployment
+```bash
+# Step 1: Introspect your Fluent Commerce schema
+npx @fluentcommerce/fc-connect-sdk introspect-schema \
+  --url https://YOUR_ACCOUNT.api.fluentcommerce.com/graphql \
+  --output schema.json
+# Step 2: Save your mapping configuration
+cat > field-mappings.json << 'EOF'
+{
+  "fields": {
+    "ref": { "source": "sku", "required": true },
+    "productRef": { "source": "sku", "required": true },
+    "locationRef": { "source": "warehouse", "required": true },
+    "qty": { "source": "quantity", "resolver": "sdk.parseInt", "required": true },
+    "status": { "source": "status", "resolver": "custom.mapStatus", "defaultValue": "AVAILABLE" }
+  }
+}
+EOF
+# Step 3: Validate mapping against schema
+npx @fluentcommerce/fc-connect-sdk validate-schema \
+  --mapping field-mappings.json \
+  --schema schema.json
+```
+### Expected Output
+```
+✅ Mapping validation successful
+✅ All required fields present: ref, productRef, locationRef, qty
+✅ All field types compatible with InventoryPositionInput schema
+✅ No unknown fields detected
+Validation Summary:
+  Required fields: 4/4 ✓
+  Optional fields: 1
+  Custom resolvers: 1 (custom.mapStatus)
+  SDK resolvers: 1 (sdk.parseInt)
+```
+## Error Handling
+### Mapping Errors
+```typescript
+const result = await mapper.map(csvData);
+if (!result.success) {
+  // Log all errors
+  console.error('Mapping failed with errors:');
+  result.errors.forEach((error, index) => {
+    console.error(`  ${index + 1}. ${error}`);
+  });
+  // Optionally: Write failed records to error file
+  const errorReport = {
+    timestamp: new Date().toISOString(),
+    totalRecords: csvData.length,
+    errors: result.errors,
+    failedRecords: csvData.filter((_, i) => result.errors.some(e => e.includes(`Row ${i}`)))
+  };
+  await fs.writeFile('mapping-errors.json', JSON.stringify(errorReport, null, 2));
+  throw new Error(`Mapping failed: ${result.errors.length} errors`);
+}
+```
+### Partial Success Handling
+```typescript
+async function mapWithPartialSuccess(mapper: UniversalMapper, records: any[]) {
+  const successful = [];
+  const failed = [];
+  for (const [index, record] of records.entries()) {
+    try {
+      const result = await mapper.map([record]);
+      if (result.success) {
+        successful.push(result.data[0]);
+      } else {
+        failed.push({ record, errors: result.errors });
+      }
+    } catch (error) {
+      failed.push({ record, error: error.message });
+    }
+  }
+  return {
+    successful,
+    failed,
+    successRate: successful.length / records.length
+  };
+}
+```
+## Advanced Patterns
+### Conditional Mapping
+```typescript
+const conditionalMapper = {
+  'custom.conditionalStatus': (value, sourceData, config, helpers) => {
+    const qty = helpers.parseIntSafe(sourceData.quantity, 0);
+    const status = helpers.toString(value).toLowerCase();
+    // Override status based on quantity
+    if (qty === 0) {
+      return 'ON_HOLD';
+    }
+    if (qty > 1000) {
+      return 'AVAILABLE';
+    }
+    // Use source status
+    return status === 'available' ? 'AVAILABLE' : 'RESERVED';
+  }
+};
+```
+### Multi-Field Transformation
+```typescript
+const multiFieldMapper = {
+  'custom.generateRef': (value, sourceData, config, helpers) => {
+    const sku = helpers.toString(sourceData.sku).trim();
+    const location = helpers.toString(sourceData.warehouse).trim();
+    const date = new Date().toISOString().split('T')[0];
+    return `${sku}-${location}-${date}`;
+  }
+};
+```
+### Lookup Table Resolver
+```typescript
+const lookupTables = {
+  warehouseCodes: {
+    'California DC': 'CA-001',
+    'Texas DC': 'TX-001',
+    'New York DC': 'NY-001'
+  }
+};
+const lookupResolver = {
+  'custom.lookupWarehouse': (value, sourceData, config, helpers) => {
+    const warehouseName = helpers.toString(value);
+    const code = lookupTables.warehouseCodes[warehouseName];
+    if (!code) {
+      throw new Error(`Unknown warehouse: ${warehouseName}`);
+    }
+    return code;
+  }
+};
+```
+## Practice Exercise
+Create a field mapping that:
+1. Validates SKU format (alphanumeric, min 3 chars)
+2. Maps status from custom values to Fluent values
+3. Calculates available quantity (on_hand - reserved)
+4. Generates a unique position reference
+<details>
+<summary>Click to see solution</summary>
+```typescript
+import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+const mappingConfig = {
+  fields: {
+    ref: {
+      source: 'sku',
+      resolver: 'custom.generatePositionRef',
+      required: true
+    },
+    productRef: {
+      source: 'sku',
+      resolver: 'custom.validateSKU',
+      required: true
+    },
+    locationRef: {
+      source: 'warehouse',
+      required: true
+    },
+    qty: {
+      source: 'on_hand',
+      resolver: 'custom.calculateAvailable',
+      required: true
+    },
+    status: {
+      source: 'stock_status',
+      resolver: 'custom.mapStockStatus',
+      defaultValue: 'AVAILABLE'
+    }
+  }
+};
+const customResolvers = {
+  'custom.validateSKU': (value, sourceData, config, helpers) => {
+    const sku = helpers.toString(value).trim().toUpperCase();
+    if (!/^[A-Z0-9]{3,}$/.test(sku)) {
+      throw new Error(`Invalid SKU format: ${value}`);
+    }
+    return sku;
+  },
+  'custom.generatePositionRef': (value, sourceData, config, helpers) => {
+    const sku = helpers.toString(value).trim().toUpperCase();
+    const warehouse = helpers.toString(sourceData.warehouse).trim();
+    return `${sku}-${warehouse}`;
+  },
+  'custom.calculateAvailable': (value, sourceData, config, helpers) => {
+    const onHand = helpers.parseIntSafe(value, 0);
+    const reserved = helpers.parseIntSafe(sourceData.reserved, 0);
+    return Math.max(0, onHand - reserved);
+  },
+  'custom.mapStockStatus': (value, sourceData, config, helpers) => {
+    const statusMap = {
+      'active': 'AVAILABLE',
+      'low': 'RESERVED',
+      'out': 'ON_HOLD',
+      'discontinued': 'DISCONTINUED'
+    };
+    const status = helpers.toString(value).toLowerCase();
+    return statusMap[status] || 'AVAILABLE';
+  }
+};
+const mapper = new UniversalMapper(mappingConfig, { customResolvers });
+// Test data
+const csvData = [
+  { sku: 'abc123', warehouse: 'WH-001', on_hand: '100', reserved: '20', stock_status: 'active' }
+];
+const result = await mapper.map(csvData);
+console.log(result);
+// {
+//   success: true,
+//   data: [{
+//     ref: 'ABC123-WH-001',
+//     productRef: 'ABC123',
+//     locationRef: 'WH-001',
+//     qty: 80,
+//     status: 'AVAILABLE'
+//   }]
+// }
+```
+</details>
+## Key Takeaways
+- 🎯 **UniversalMapper** transforms source data to Fluent schema
+- 🎯 **SDK resolvers** provide common transformations (uppercase, parseInt, etc.)
+- 🎯 **Custom resolvers** implement business logic and validation
+- 🎯 **Schema validation** ensures compatibility before deployment
+- 🎯 **Error handling** provides clear feedback for mapping failures
+- 🎯 **Resolver helpers** simplify safe type conversions
+## Next Steps
+Continue to [Module 5: Advanced Parsers →](./02-core-guides-ingestion-05-advanced-parsers.md) to learn about Parquet, XML, and JSON parsing with streaming support.
+---
+**Related Documentation:**
+- [Universal Mapping Guide](../../mapping/mapping-readme.md) - Complete field mapping reference
+- [Resolver Development Guide](../../mapping/resolvers/mapping-resolvers-readme.md) - Advanced custom resolver patterns
+- [Schema Validation CLI](../../../../bin/readme.md#validate-04-REFERENCE/schema) - CLI tool documentation