@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

package/docs/01-TEMPLATES/patterns/patterns-custom-resolvers.md

@@ -1,407 +1,407 @@
-# Pattern: Custom Resolvers
-
-**FC Connect SDK Use Case Guide**
-
-> **SDK**: [@fluentcommerce/fc-connect-sdk](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk)
-> **Version**: Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
-
-**Context**: Focused guide on writing custom transformation resolvers
-
-**Type**: Reusable Pattern
-
-**Complexity**: Low-Medium
-
-**Lines**: ~140 lines
-
-## When to Use This Pattern
-
-- Complex data transformations beyond SDK resolvers
-- API lookups during mapping (enrichment)
-- Conditional logic based on multiple fields
-- Data enrichment from external systems
-- Custom validation and business rules
-- Multi-field calculations
-
-## Resolver Signature
-
-All resolvers across ALL mappers use a consistent 4-parameter signature:
-
-```typescript
-type ResolverFunction = (
-  value: any, // Source field value being transformed
-  sourceData: any, // Complete source record for context
-  config: any, // Resolver configuration (from mapper context)
-  helpers: ResolverHelpers // SDK helper functions (48+ utilities)
-) => any | Promise<any>;
-```
-
-**Parameter Breakdown:**
-
-1. **value**: The extracted field value (from `source` path or `value` literal)
-2. **sourceData**: Full source object - access sibling fields via `helpers.get()`
-3. **config**: User-provided context passed to mapper constructor via `options.context` (business rules, settings)
-4. **helpers**: SDK utilities + fluentClient + logger + context
-
-> **💡 Note**: The `config` parameter and `helpers.context` both reference the same object you passed to the mapper constructor. Use whichever is more convenient.
->
-> **Resolver usage notes**:
->
-> - UniversalMapper accepts a single resolver name per field (string). To compose multiple steps, create one custom resolver that performs them in order.
-> - If a resolver derives its value from the full record, you may omit `source` in the field config; the resolver receives `sourceData` and can access any fields via `helpers.get()`.
-
-## Pattern Examples
-
-### 1. Simple String Transformation
-
-```typescript
-export const customResolvers = {
-  'custom.formatSKU': (value, sourceData, config, helpers) => {
-    const prefix = config.skuPrefix || 'SKU';
-    return `${prefix}-${helpers.toString(value).toUpperCase()}`;
-  },
-};
-
-// Usage
-const mapper = new UniversalMapper(mapping, {
-  customResolvers,
-  context: { skuPrefix: 'PROD' },
-});
-```
-
-### 2. Context-Aware Resolver (Use sourceData)
-
-```typescript
-export const customResolvers = {
-  'custom.calculatePrice': (basePrice, sourceData, config, helpers) => {
-    // Access sibling fields from sourceData
-    const quantity = helpers.get(sourceData, 'quantity') || 1;
-    const discount = helpers.get(sourceData, 'discountPercent') || 0;
-
-    // Use config for business rules
-    const taxRate = config.taxRate || 0;
-
-    // Calculate final price
-    const subtotal = basePrice * quantity;
-    const afterDiscount = subtotal * (1 - discount / 100);
-    const withTax = afterDiscount * (1 + taxRate);
-
-    return helpers.parseFloatSafe(withTax, 0);
-  },
-};
-```
-
-### 3. Async Resolver (API Call)
-
-```typescript
-export const customResolvers = {
-  'custom.enrichWithCustomer': async (customerId, sourceData, config, helpers) => {
-    if (!helpers.fluentClient) {
-      helpers.log.warn('FluentClient not available');
-      return customerId;
-    }
-
-    try {
-      const result = await helpers.fluentClient.graphql({
-        query: `query { customer(id: "${customerId}") { id name email } }`,
-      });
-
-      return {
-        id: customerId,
-        ...result.data.customer,
-      };
-    } catch (error) {
-      helpers.log.error('Failed to fetch customer', error);
-      return customerId; // Safe fallback
-    }
-  },
-};
-```
-
-### 4. Conditional Resolver (If/Else Logic)
-
-```typescript
-export const customResolvers = {
-  'custom.formatRadialDate': (value, sourceData, config, helpers) => {
-    if (!value) return '';
-
-    try {
-      const date = new Date(value);
-      return date.toISOString().replace(/\.\d{3}Z$/, '+00:00');
-    } catch {
-      return value; // Return original on error
-    }
-  },
-};
-```
-
-### 5. Array Processing (Extract from Attributes)
-
-```typescript
-export const customResolvers = {
-  'custom.extractColorId': (value, sourceData, config, helpers) => {
-    const item = value || sourceData;
-    const product = helpers.get(item, 'product') || {};
-    const attributes = product.attributes || [];
-
-    const colorAttr = attributes.find(
-      (a: any) => a.name?.toLowerCase().includes('color') || a.name === 'COLOR_CODE'
-    );
-
-    return colorAttr?.value || '';
-  },
-};
-```
-
-### 6. Multi-Field Aggregation
-
-```typescript
-export const customResolvers = {
-  'custom.extractDestinations': (value, sourceData, config, helpers) => {
-    const destinations = [];
-
-    // Extract delivery address
-    const deliveryAddress = helpers.get(sourceData, 'fulfilmentChoice.deliveryAddress');
-    if (deliveryAddress) {
-      destinations.push({
-        id: `s-${deliveryAddress.id || 'delivery'}`,
-        firstName: deliveryAddress.firstName || '',
-        lastName: deliveryAddress.lastName || deliveryAddress.name || '',
-        street: deliveryAddress.street || deliveryAddress.line1 || '',
-        city: deliveryAddress.city || '',
-        state: deliveryAddress.state || '',
-        country: deliveryAddress.country || 'US',
-      });
-    }
-
-    // Extract billing address (if different)
-    const billingAddress = helpers.get(sourceData, 'billingAddress');
-    if (billingAddress && billingAddress.id !== deliveryAddress?.id) {
-      destinations.push({
-        id: `b-${billingAddress.id || 'billing'}`,
-        // ... similar mapping
-      });
-    }
-
-    return destinations;
-  },
-};
-```
-
-### 7. Helper Function Usage
-
-```typescript
-export const customResolvers = {
-  'custom.complexTransform': (value, sourceData, config, helpers) => {
-    // Null-safe parsing
-    const numericValue = helpers.parseFloatSafe(value, 0);
-
-    // Coalesce multiple values
-    const category = helpers.coalesce(
-      helpers.get(sourceData, 'product.category'),
-      config.defaultCategory,
-      'UNKNOWN'
-    );
-
-    // Config-based business rules
-    const multiplier = config.multipliers?.[category] || 1;
-
-    // Safe calculation
-    const result = numericValue * multiplier;
-    return helpers.parseFloatSafe(result, 0);
-  },
-};
-```
-
-### 8. Error Handling Pattern
-
-```typescript
-export const customResolvers = {
-  'custom.safeTransform': (value, sourceData, config, helpers) => {
-    try {
-      // Complex transformation logic
-      const processed = performComplexOperation(value);
-
-      // Validate result
-      if (!processed || helpers.isEmpty(processed)) {
-        helpers.log.warn('Transformation produced empty result', { value });
-        return config.defaultValue || null;
-      }
-
-      return processed;
-    } catch (error) {
-      helpers.log.error('Transformation failed', error, { value, sourceData });
-      return config.defaultValue || null;
-    }
-  },
-};
-```
-
-## Available Helper Functions
-
-**Path Access:**
-
-- `get(obj, 'path.to.field[0]', defaultValue)` - Multi-format path access
-- `set(obj, 'path.to.field', value)` - Set nested value
-
-**Type Coercion:**
-
-- `parseFloatSafe(value, 0)` - Safe float parsing with fallback
-- `parseIntSafe(value, 0)` - Safe integer parsing
-- `toString(value)` - Safe string conversion
-- `defaultTo(value, fallback)` - Return fallback if null/undefined
-
-**Date Operations:**
-
-- `formatDate(date)` - ISO8601 format
-- `parseDate(str)` - Parse date string
-- `addDays(date, days)` - Add days to date
-- `subtractDays(date, days)` - Subtract days
-- `dateDiff(date1, date2)` - Days between dates
-
-**Array Operations:**
-
-- `ensureArray(value)` - Convert to array
-- `coalesce(...values)` - First non-null value
-- `groupBy(array, key)` - Group by field
-- `keyBy(array, key)` - Index by field
-- `chunk(array, size)` - Split into chunks
-- `flatten(array, depth)` - Flatten nested arrays
-- `unique(array, key?)` - Remove duplicates
-- `sortBy(array, key, desc?)` - Sort by field
-- `compact(array)` - Remove falsy values
-
-**String Operations:**
-
-- `toCamelCase(str)` - Convert to camelCase
-- `toSnakeCase(str)` - Convert to snake_case
-- `template(str, vars)` - Replace {{placeholders}}
-- `slugify(str)` - URL-safe slug
-- `truncate(str, maxLen)` - Limit length
-- `normalizeWhitespace(str)` - Clean whitespace
-
-**Object Operations:**
-
-- `deepClone(obj)` - Deep copy object
-- `deepMerge(target, source)` - Merge objects
-- `pick(obj, keys)` - Select fields
-- `omit(obj, keys)` - Exclude fields
-- `isEmpty(value)` - Check if empty
-
-**Math Operations:**
-
-- `sum(array, key?)` - Sum values
-- `avg(array, key?)` - Average
-- `min(array, key?)` - Minimum value
-- `max(array, key?)` - Maximum value
-- `clamp(num, min, max)` - Constrain range
-
-**Validation:**
-
-- `isValidEmail(email)` - Email validation
-- `requireField(value, name)` - Throw if missing
-- `isString(value)` - Type check
-- `isNumber(value)` - Type check
-- `isArray(value)` - Type check
-- `isObject(value)` - Type check
-- `isDate(value)` - Type check
-
-**Additional Context:**
-
-- `helpers.log` - Logger instance (info, error, warn, debug)
-- `helpers.fluentClient` - Fluent API client (for queries)
-- `helpers.context` - User-provided shared config
-
-## Best Practices
-
-1. **Always Use 4 Parameters** - Even if unused, include all for consistency
-2. **Use Helpers for Safety** - `helpers.parseFloatSafe()` instead of `parseFloat()`
-3. **Never Throw Errors** - Return safe fallbacks instead
-4. **Log Errors** - Use `helpers.log.error()` for debugging
-5. **Access Config via 3rd Param** - Use the `config` parameter instead of `helpers.context`
-6. **Null-Safety** - Check for null/undefined before operations
-7. **Document Resolvers** - Add JSDoc comments explaining logic
-8. **Test Edge Cases** - Handle empty arrays, null values, missing fields
-
-## Common Patterns
-
-**Pattern 1: Fallback Chain**
-
-```typescript
-const value = helpers.coalesce(
-  helpers.get(sourceData, 'primary.field'),
-  helpers.get(sourceData, 'secondary.field'),
-  config.defaultValue,
-  'UNKNOWN'
-);
-```
-
-**Pattern 2: Attribute Extraction**
-
-```typescript
-const attributes = helpers.get(sourceData, 'attributes') || [];
-const targetAttr = attributes.find(a => a.name === 'TargetName');
-return targetAttr?.value || '';
-```
-
-**Pattern 3: Conditional Format**
-
-```typescript
-if (!value) return '';
-
-try {
-  return formatValue(value);
-} catch {
-  return value; // Return original on error
-}
-```
-
-**Pattern 4: Multi-Source Calculation**
-
-```typescript
-const base = helpers.parseFloatSafe(value, 0);
-const multiplier = helpers.get(sourceData, 'multiplier') || 1;
-const adjustment = config.adjustments?.[sourceData.type] || 0;
-return base * multiplier + adjustment;
-```
-
-## Usage Example
-
-```typescript
-// FC Connect SDK (latest)
-// Install: npm install @fluentcommerce/fc-connect-sdk@latest
-// Docs: https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk
-// GitHub: https://github.com/fluentcommerce/fc-connect-sdk
-
-import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-import { customResolvers } from './resolvers';
-
-const mapper = new UniversalMapper(
-  {
-    fields: {
-      skuRef: { source: 'sku_id', resolver: 'custom.formatSKU' },
-      price: { source: 'base_price', resolver: 'custom.calculatePrice' },
-    },
-  },
-  {
-    customResolvers, // Your custom resolvers
-    fluentClient: myClient, // Available as helpers.fluentClient
-    logger: myLogger, // Available as helpers.log
-    context: {
-      // Available as config parameter
-      skuPrefix: 'PROD',
-      taxRate: 0.1,
-      multipliers: { electronics: 1.5 },
-    },
-  }
-);
-
-const result = await mapper.map(sourceData);
-```
-
----
-
-**See Also:**
-
-- [Resolver Signature Guide](../../02-CORE-GUIDES/mapping/resolvers/mapping-resolvers-resolver-guide.md)
-- [Universal Mapping Guide](../../02-CORE-GUIDES/advanced-services/advanced-services-readme.md)
-- [SFCC Connector Resolvers](../../02-CORE-GUIDES/advanced-services/advanced-services-readme.md)
+# Pattern: Custom Resolvers
+
+**FC Connect SDK Use Case Guide**
+
+> **SDK**: [@fluentcommerce/fc-connect-sdk](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk)
+> **Version**: Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
+
+**Context**: Focused guide on writing custom transformation resolvers
+
+**Type**: Reusable Pattern
+
+**Complexity**: Low-Medium
+
+**Lines**: ~140 lines
+
+## When to Use This Pattern
+
+- Complex data transformations beyond SDK resolvers
+- API lookups during mapping (enrichment)
+- Conditional logic based on multiple fields
+- Data enrichment from external systems
+- Custom validation and business rules
+- Multi-field calculations
+
+## Resolver Signature
+
+All resolvers across ALL mappers use a consistent 4-parameter signature:
+
+```typescript
+type ResolverFunction = (
+  value: any, // Source field value being transformed
+  sourceData: any, // Complete source record for context
+  config: any, // Resolver configuration (from mapper context)
+  helpers: ResolverHelpers // SDK helper functions (48+ utilities)
+) => any | Promise<any>;
+```
+
+**Parameter Breakdown:**
+
+1. **value**: The extracted field value (from `source` path or `value` literal)
+2. **sourceData**: Full source object - access sibling fields via `helpers.get()`
+3. **config**: User-provided context passed to mapper constructor via `options.context` (business rules, settings)
+4. **helpers**: SDK utilities + fluentClient + logger + context
+
+> **💡 Note**: The `config` parameter and `helpers.context` both reference the same object you passed to the mapper constructor. Use whichever is more convenient.
+>
+> **Resolver usage notes**:
+>
+> - UniversalMapper accepts a single resolver name per field (string). To compose multiple steps, create one custom resolver that performs them in order.
+> - If a resolver derives its value from the full record, you may omit `source` in the field config; the resolver receives `sourceData` and can access any fields via `helpers.get()`.
+
+## Pattern Examples
+
+### 1. Simple String Transformation
+
+```typescript
+export const customResolvers = {
+  'custom.formatSKU': (value, sourceData, config, helpers) => {
+    const prefix = config.skuPrefix || 'SKU';
+    return `${prefix}-${helpers.toString(value).toUpperCase()}`;
+  },
+};
+
+// Usage
+const mapper = new UniversalMapper(mapping, {
+  customResolvers,
+  context: { skuPrefix: 'PROD' },
+});
+```
+
+### 2. Context-Aware Resolver (Use sourceData)
+
+```typescript
+export const customResolvers = {
+  'custom.calculatePrice': (basePrice, sourceData, config, helpers) => {
+    // Access sibling fields from sourceData
+    const quantity = helpers.get(sourceData, 'quantity') || 1;
+    const discount = helpers.get(sourceData, 'discountPercent') || 0;
+
+    // Use config for business rules
+    const taxRate = config.taxRate || 0;
+
+    // Calculate final price
+    const subtotal = basePrice * quantity;
+    const afterDiscount = subtotal * (1 - discount / 100);
+    const withTax = afterDiscount * (1 + taxRate);
+
+    return helpers.parseFloatSafe(withTax, 0);
+  },
+};
+```
+
+### 3. Async Resolver (API Call)
+
+```typescript
+export const customResolvers = {
+  'custom.enrichWithCustomer': async (customerId, sourceData, config, helpers) => {
+    if (!helpers.fluentClient) {
+      helpers.log.warn('FluentClient not available');
+      return customerId;
+    }
+
+    try {
+      const result = await helpers.fluentClient.graphql({
+        query: `query { customer(id: "${customerId}") { id name email } }`,
+      });
+
+      return {
+        id: customerId,
+        ...result.data.customer,
+      };
+    } catch (error) {
+      helpers.log.error('Failed to fetch customer', error);
+      return customerId; // Safe fallback
+    }
+  },
+};
+```
+
+### 4. Conditional Resolver (If/Else Logic)
+
+```typescript
+export const customResolvers = {
+  'custom.formatRadialDate': (value, sourceData, config, helpers) => {
+    if (!value) return '';
+
+    try {
+      const date = new Date(value);
+      return date.toISOString().replace(/\.\d{3}Z$/, '+00:00');
+    } catch {
+      return value; // Return original on error
+    }
+  },
+};
+```
+
+### 5. Array Processing (Extract from Attributes)
+
+```typescript
+export const customResolvers = {
+  'custom.extractColorId': (value, sourceData, config, helpers) => {
+    const item = value || sourceData;
+    const product = helpers.get(item, 'product') || {};
+    const attributes = product.attributes || [];
+
+    const colorAttr = attributes.find(
+      (a: any) => a.name?.toLowerCase().includes('color') || a.name === 'COLOR_CODE'
+    );
+
+    return colorAttr?.value || '';
+  },
+};
+```
+
+### 6. Multi-Field Aggregation
+
+```typescript
+export const customResolvers = {
+  'custom.extractDestinations': (value, sourceData, config, helpers) => {
+    const destinations = [];
+
+    // Extract delivery address
+    const deliveryAddress = helpers.get(sourceData, 'fulfilmentChoice.deliveryAddress');
+    if (deliveryAddress) {
+      destinations.push({
+        id: `s-${deliveryAddress.id || 'delivery'}`,
+        firstName: deliveryAddress.firstName || '',
+        lastName: deliveryAddress.lastName || deliveryAddress.name || '',
+        street: deliveryAddress.street || deliveryAddress.line1 || '',
+        city: deliveryAddress.city || '',
+        state: deliveryAddress.state || '',
+        country: deliveryAddress.country || 'US',
+      });
+    }
+
+    // Extract billing address (if different)
+    const billingAddress = helpers.get(sourceData, 'billingAddress');
+    if (billingAddress && billingAddress.id !== deliveryAddress?.id) {
+      destinations.push({
+        id: `b-${billingAddress.id || 'billing'}`,
+        // ... similar mapping
+      });
+    }
+
+    return destinations;
+  },
+};
+```
+
+### 7. Helper Function Usage
+
+```typescript
+export const customResolvers = {
+  'custom.complexTransform': (value, sourceData, config, helpers) => {
+    // Null-safe parsing
+    const numericValue = helpers.parseFloatSafe(value, 0);
+
+    // Coalesce multiple values
+    const category = helpers.coalesce(
+      helpers.get(sourceData, 'product.category'),
+      config.defaultCategory,
+      'UNKNOWN'
+    );
+
+    // Config-based business rules
+    const multiplier = config.multipliers?.[category] || 1;
+
+    // Safe calculation
+    const result = numericValue * multiplier;
+    return helpers.parseFloatSafe(result, 0);
+  },
+};
+```
+
+### 8. Error Handling Pattern
+
+```typescript
+export const customResolvers = {
+  'custom.safeTransform': (value, sourceData, config, helpers) => {
+    try {
+      // Complex transformation logic
+      const processed = performComplexOperation(value);
+
+      // Validate result
+      if (!processed || helpers.isEmpty(processed)) {
+        helpers.log.warn('Transformation produced empty result', { value });
+        return config.defaultValue || null;
+      }
+
+      return processed;
+    } catch (error) {
+      helpers.log.error('Transformation failed', error, { value, sourceData });
+      return config.defaultValue || null;
+    }
+  },
+};
+```
+
+## Available Helper Functions
+
+**Path Access:**
+
+- `get(obj, 'path.to.field[0]', defaultValue)` - Multi-format path access
+- `set(obj, 'path.to.field', value)` - Set nested value
+
+**Type Coercion:**
+
+- `parseFloatSafe(value, 0)` - Safe float parsing with fallback
+- `parseIntSafe(value, 0)` - Safe integer parsing
+- `toString(value)` - Safe string conversion
+- `defaultTo(value, fallback)` - Return fallback if null/undefined
+
+**Date Operations:**
+
+- `formatDate(date)` - ISO8601 format
+- `parseDate(str)` - Parse date string
+- `addDays(date, days)` - Add days to date
+- `subtractDays(date, days)` - Subtract days
+- `dateDiff(date1, date2)` - Days between dates
+
+**Array Operations:**
+
+- `ensureArray(value)` - Convert to array
+- `coalesce(...values)` - First non-null value
+- `groupBy(array, key)` - Group by field
+- `keyBy(array, key)` - Index by field
+- `chunk(array, size)` - Split into chunks
+- `flatten(array, depth)` - Flatten nested arrays
+- `unique(array, key?)` - Remove duplicates
+- `sortBy(array, key, desc?)` - Sort by field
+- `compact(array)` - Remove falsy values
+
+**String Operations:**
+
+- `toCamelCase(str)` - Convert to camelCase
+- `toSnakeCase(str)` - Convert to snake_case
+- `template(str, vars)` - Replace {{placeholders}}
+- `slugify(str)` - URL-safe slug
+- `truncate(str, maxLen)` - Limit length
+- `normalizeWhitespace(str)` - Clean whitespace
+
+**Object Operations:**
+
+- `deepClone(obj)` - Deep copy object
+- `deepMerge(target, source)` - Merge objects
+- `pick(obj, keys)` - Select fields
+- `omit(obj, keys)` - Exclude fields
+- `isEmpty(value)` - Check if empty
+
+**Math Operations:**
+
+- `sum(array, key?)` - Sum values
+- `avg(array, key?)` - Average
+- `min(array, key?)` - Minimum value
+- `max(array, key?)` - Maximum value
+- `clamp(num, min, max)` - Constrain range
+
+**Validation:**
+
+- `isValidEmail(email)` - Email validation
+- `requireField(value, name)` - Throw if missing
+- `isString(value)` - Type check
+- `isNumber(value)` - Type check
+- `isArray(value)` - Type check
+- `isObject(value)` - Type check
+- `isDate(value)` - Type check
+
+**Additional Context:**
+
+- `helpers.log` - Logger instance (info, error, warn, debug)
+- `helpers.fluentClient` - Fluent API client (for queries)
+- `helpers.context` - User-provided shared config
+
+## Best Practices
+
+1. **Always Use 4 Parameters** - Even if unused, include all for consistency
+2. **Use Helpers for Safety** - `helpers.parseFloatSafe()` instead of `parseFloat()`
+3. **Never Throw Errors** - Return safe fallbacks instead
+4. **Log Errors** - Use `helpers.log.error()` for debugging
+5. **Access Config via 3rd Param** - Use the `config` parameter instead of `helpers.context`
+6. **Null-Safety** - Check for null/undefined before operations
+7. **Document Resolvers** - Add JSDoc comments explaining logic
+8. **Test Edge Cases** - Handle empty arrays, null values, missing fields
+
+## Common Patterns
+
+**Pattern 1: Fallback Chain**
+
+```typescript
+const value = helpers.coalesce(
+  helpers.get(sourceData, 'primary.field'),
+  helpers.get(sourceData, 'secondary.field'),
+  config.defaultValue,
+  'UNKNOWN'
+);
+```
+
+**Pattern 2: Attribute Extraction**
+
+```typescript
+const attributes = helpers.get(sourceData, 'attributes') || [];
+const targetAttr = attributes.find(a => a.name === 'TargetName');
+return targetAttr?.value || '';
+```
+
+**Pattern 3: Conditional Format**
+
+```typescript
+if (!value) return '';
+
+try {
+  return formatValue(value);
+} catch {
+  return value; // Return original on error
+}
+```
+
+**Pattern 4: Multi-Source Calculation**
+
+```typescript
+const base = helpers.parseFloatSafe(value, 0);
+const multiplier = helpers.get(sourceData, 'multiplier') || 1;
+const adjustment = config.adjustments?.[sourceData.type] || 0;
+return base * multiplier + adjustment;
+```
+
+## Usage Example
+
+```typescript
+// FC Connect SDK (latest)
+// Install: npm install @fluentcommerce/fc-connect-sdk@latest
+// Docs: https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk
+// GitHub: https://github.com/fluentcommerce/fc-connect-sdk
+
+import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+import { customResolvers } from './resolvers';
+
+const mapper = new UniversalMapper(
+  {
+    fields: {
+      skuRef: { source: 'sku_id', resolver: 'custom.formatSKU' },
+      price: { source: 'base_price', resolver: 'custom.calculatePrice' },
+    },
+  },
+  {
+    customResolvers, // Your custom resolvers
+    fluentClient: myClient, // Available as helpers.fluentClient
+    logger: myLogger, // Available as helpers.log
+    context: {
+      // Available as config parameter
+      skuPrefix: 'PROD',
+      taxRate: 0.1,
+      multipliers: { electronics: 1.5 },
+    },
+  }
+);
+
+const result = await mapper.map(sourceData);
+```
+
+---
+
+**See Also:**
+
+- [Resolver Signature Guide](../../02-CORE-GUIDES/mapping/resolvers/mapping-resolvers-resolver-guide.md)
+- [Universal Mapping Guide](../../02-CORE-GUIDES/advanced-services/advanced-services-readme.md)
+- [SFCC Connector Resolvers](../../02-CORE-GUIDES/advanced-services/advanced-services-readme.md)