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/01-TEMPLATES/patterns/patterns-field-mapping-universal.md CHANGED Viewed

@@ -1,701 +1,701 @@
-# Pattern: Universal Field Mapping
-**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 UniversalMapper for transforming data between formats
-**Type**: Reusable Pattern
-**Complexity**: Low-Medium
-**Lines**: ~200 lines
-## When to Use This Pattern
-- Transforming CSV/JSON/XML to Fluent format
-- Extracting Fluent data for export
-- Data normalization and validation
-- Type conversions and formatting
-- Building GraphQL mutation inputs
-- Generating XML/JSON output structures
-## SDK Methods
-- `UniversalMapper(config, options)` - Create mapper instance
-- `mapper.map(sourceData)` - Transform single record
-- `mapper.registerResolver(name, fn)` - Add custom resolver
-- `mapper.registerResolvers(map)` - Add multiple custom resolvers
-- SDK Resolvers: `sdk.*` prefix (15 built-in)
-- Custom resolvers: Your own transformation functions
----
-## Basic Mapping
-### Simple Field Mapping
-```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';
-const config = {
-  fields: {
-    // Direct mapping - no transformation
-    customerEmail: {
-      source: 'email',
-    },
-    // Map with transformation
-    status: {
-      source: 'orderStatus',
-      resolver: 'sdk.uppercase',
-    },
-    // Required field with validation
-    productSku: {
-      source: 'sku',
-      required: true,
-    },
-  },
-};
-const mapper = new UniversalMapper(config);
-// Transform data
-const sourceData = { email: 'john@example.com', orderStatus: 'pending', sku: 'PROD-001' };
-const result = await mapper.map(sourceData);
-if (result.success) {
-  console.log(result.data);
-  // { customerEmail: 'john@example.com', status: 'PENDING', productSku: 'PROD-001' }
-}
-```
-### Static Values
-```typescript
-const config = {
-  fields: {
-    type: {
-      value: 'STANDARD', // Always returns "STANDARD"
-    },
-    retailerId: {
-      value: 1, // Static numeric value
-    },
-    version: {
-      value: '2.0',
-    },
-  },
-};
-```
-### Default Values
-```typescript
-const config = {
-  fields: {
-    status: {
-      source: 'orderStatus',
-      defaultValue: 'PENDING', // Used if source is missing/empty
-    },
-    quantity: {
-      source: 'qty',
-      resolver: 'sdk.parseInt',
-      defaultValue: 0, // Fallback for missing quantity
-    },
-  },
-};
-```
----
-## SDK Resolver Patterns
-### String Transformations
-```typescript
-const config = {
-  fields: {
-    // Convert to uppercase
-    countryCode: {
-      source: 'country',
-      resolver: 'sdk.uppercase', // "us" → "US"
-    },
-    // Convert to lowercase
-    email: {
-      source: 'customerEmail',
-      resolver: 'sdk.lowercase', // "JOHN@EXAMPLE.COM" → "john@example.com"
-    },
-    // Trim whitespace
-    sku: {
-      source: 'productSku',
-      resolver: 'sdk.trim', // "  SKU123  " → "SKU123"
-    },
-    // Convert to string
-    orderId: {
-      source: 'order_id',
-      resolver: 'sdk.toString', // 12345 → "12345"
-    },
-  },
-};
-```
-### Number Transformations
-```typescript
-const config = {
-  fields: {
-    // Parse as integer
-    quantity: {
-      source: 'qty',
-      resolver: 'sdk.parseInt', // "123" → 123, "123.99" → 123
-    },
-    // Parse as float
-    price: {
-      source: 'total',
-      resolver: 'sdk.parseFloat', // "99.99" → 99.99, "$45.50" → 45.5
-    },
-    // Generic number parser (alias for parseFloat)
-    weight: {
-      source: 'weight_kg',
-      resolver: 'sdk.number', // "3.14" → 3.14
-    },
-  },
-};
-```
-### Date Transformations
-```typescript
-const config = {
-  fields: {
-    // Format to ISO8601 (Fluent API standard)
-    expectedOn: {
-      source: 'delivery_date',
-      resolver: 'sdk.formatDate', // "2024-01-15" → "2024-01-15T00:00:00.000Z"
-    },
-    // Format to YYYY-MM-DD
-    orderDate: {
-      source: 'created_at',
-      resolver: 'sdk.formatDateShort', // "2024-01-15T10:30:00Z" → "2024-01-15"
-    },
-    // Parse date string
-    scheduledDate: {
-      source: 'schedule',
-      resolver: 'sdk.parseDate', // "01/15/2024" → Date object
-    },
-  },
-};
-```
-### Type Conversions
-```typescript
-const config = {
-  fields: {
-    // Convert to boolean
-    isActive: {
-      source: 'active',
-      resolver: 'sdk.boolean', // "true", "1", "yes", "y" → true
-    },
-    // Parse JSON string
-    metadata: {
-      source: 'json_data',
-      resolver: 'sdk.parseJson', // '{"key":"value"}' → { key: "value" }
-    },
-    // Stringify to JSON
-    customAttributes: {
-      source: 'attributes',
-      resolver: 'sdk.toJson', // { name: "John" } → '{"name":"John"}'
-    },
-  },
-};
-```
-### Utility Resolvers
-```typescript
-const config = {
-  fields: {
-    // Identity - no transformation
-    originalValue: {
-      source: 'rawData',
-      resolver: 'sdk.identity', // Pass through unchanged
-    },
-    // Coalesce - first non-null value
-    displayName: {
-      source: 'name',
-      resolver: 'sdk.coalesce',
-      defaultValue: 'Unknown', // Fallback if null/undefined
-    },
-  },
-};
-```
----
-## Complete SDK Resolver Reference
-### String Resolvers (4)
-- `sdk.uppercase` - Convert to UPPERCASE
-- `sdk.lowercase` - Convert to lowercase
-- `sdk.trim` - Remove leading/trailing whitespace
-- `sdk.toString` - Convert any value to string
-### Number Resolvers (3)
-- `sdk.parseInt` - Parse as integer (returns 0 for invalid)
-- `sdk.parseFloat` - Parse as float (returns 0 for invalid)
-- `sdk.number` - Alias for parseFloat
-### Date Resolvers (3)
-- `sdk.formatDate` - Format to ISO8601 (Fluent API standard)
-- `sdk.formatDateShort` - Format to YYYY-MM-DD
-- `sdk.parseDate` - Parse date string to Date object
-### Type Conversion Resolvers (3)
-- `sdk.boolean` - Convert to boolean (handles "true", "1", "yes", etc.)
-- `sdk.parseJson` - Parse JSON string to object
-- `sdk.toJson` - Stringify object to JSON
-### Utility Resolvers (2)
-- `sdk.identity` - Pass value through unchanged
-- `sdk.coalesce` - Return first non-null value
-**Total: 15 SDK Resolvers**
----
-## Custom Resolver Patterns
-### Basic Custom Resolver
-```typescript
-import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-const customResolvers = {
-  'custom.calculateTax': (value, sourceData, config, helpers) => {
-    const subtotal = helpers.parseFloatSafe(value, 0);
-    return subtotal * 0.1; // 10% tax
-  },
-  'custom.formatPhone': (value, sourceData, config, helpers) => {
-    // Remove non-digits
-    const digits = value.replace(/\D/g, '');
-    // Format as (XXX) XXX-XXXX
-    return `(${digits.slice(0, 3)}) ${digits.slice(3, 6)}-${digits.slice(6)}`;
-  },
-};
-const mapper = new UniversalMapper(config, { customResolvers });
-```
-### Using Helper Functions
-```typescript
-const customResolvers = {
-  'custom.cleanAndUpper': (value, sourceData, config, helpers) => {
-    // Use helpers for safe operations
-    const trimmed = helpers.normalizeWhitespace(value);
-    return trimmed.toUpperCase();
-  },
-  'custom.extractId': (value, sourceData, config, helpers) => {
-    // Safe nested property access
-    const product = helpers.get(sourceData, 'product.details') || {};
-    return product.id || 'UNKNOWN';
-  },
-};
-```
-### Context-Aware Resolvers
-> **⚠️ Important**: To use `helpers.fluentClient` or `helpers.context` in custom resolvers, you MUST pass them when creating the mapper. They are NOT available by default.
-```typescript
-const customResolvers = {
-  'custom.lookupCustomer': async (email, sourceData, config, helpers) => {
-    // Access fluentClient from helpers (passed via options)
-    if (!helpers.fluentClient) {
-      throw new Error('fluentClient not available');
-    }
-    const query = `query { customers(email: "${email}") { edges { node { id } } } }`;
-    const result = await helpers.fluentClient.graphql({ query });
-    return result.data.customers.edges[0]?.node.id;
-  },
-  'custom.addOrderContext': (value, sourceData, config, helpers) => {
-    // Access custom context
-    const orderId = helpers.context?.orderId;
-    return `${value}_${orderId}`;
-  },
-};
-// ✅ REQUIRED: Initialize mapper with fluentClient and context for async resolvers
-const mapper = new UniversalMapper(config, {
-  customResolvers,
-  fluentClient: fluentClient, // ← Required for API access in resolvers
-  logger: console, // ← Required for helpers.log
-  context: { orderId: '12345', userId: '999' }, // ← Required for helpers.context
-});
-```
----
-## Nested Field Patterns
-### Nested Objects
-```typescript
-const config = {
-  fields: {
-    // Simple nested field with dot notation
-    'customer.id': {
-      source: 'customerId',
-      resolver: 'sdk.parseInt',
-    },
-    'customer.email': {
-      source: 'email',
-      resolver: 'sdk.lowercase',
-    },
-    'customer.address.city': {
-      source: 'city',
-    },
-  },
-};
-// Output:
-// {
-//   customer: {
-//     id: 12345,
-//     email: "john@example.com",
-//     address: { city: "New York" }
-//   }
-// }
-```
-### Nested Object Structure
-```typescript
-const config = {
-  fields: {
-    customer: {
-      fields: {
-        id: { source: 'customerId' },
-        email: { source: 'email' },
-        address: {
-          fields: {
-            street: { source: 'street' },
-            city: { source: 'city' },
-            zip: { source: 'zipCode' },
-          },
-        },
-      },
-    },
-  },
-};
-```
----
-## Array Patterns
-### Array with Nested Mapping
-```typescript
-const config = {
-  fields: {
-    items: {
-      source: 'orderItems',
-      isArray: true, // Map each array element
-      fields: {
-        ref: { source: 'id' },
-        productRef: { source: 'sku' },
-        quantity: { source: 'qty', resolver: 'sdk.parseInt' },
-      },
-    },
-  },
-};
-// Source: { orderItems: [{ id: "1", sku: "SKU001", qty: "5" }] }
-// Output: { items: [{ ref: "1", productRef: "SKU001", quantity: 5 }] }
-```
-### GraphQL Edges/Nodes Pattern
-```typescript
-const config = {
-  fields: {
-    products: {
-      source: 'products.edges[*].node', // Wildcard extraction
-      isArray: true,
-      fields: {
-        id: { source: 'id' },
-        ref: { source: 'ref' },
-        name: { source: 'name' },
-      },
-    },
-  },
-};
-// Automatically extracts nodes from GraphQL pagination structure
-```
-### Conditional Array Item Processing
-```typescript
-const customResolvers = {
-  'custom.filterActive': (items, sourceData, config, helpers) => {
-    // Filter array items based on condition
-    return helpers.ensureArray(items).filter(item => item.status === 'ACTIVE');
-  },
-};
-const config = {
-  fields: {
-    activeItems: {
-      source: 'items',
-      resolver: 'custom.filterActive',
-      isArray: true,
-      fields: {
-        id: { source: 'id' },
-        name: { source: 'name' },
-      },
-    },
-  },
-};
-```
----
-## Error Handling Patterns
-### Required Field Validation
-```typescript
-const config = {
-  fields: {
-    skuRef: {
-      source: 'sku',
-      required: true, // Fails entire mapping if missing
-    },
-    locationRef: {
-      source: 'location',
-      required: true,
-    },
-    qty: {
-      source: 'quantity',
-      resolver: 'sdk.parseInt',
-      defaultValue: 0, // Optional field with default
-    },
-  },
-};
-const result = await mapper.map(sourceData);
-if (!result.success) {
-  console.error('Mapping failed:', result.errors);
-  // ["Required field 'skuRef' is missing or empty (source: sku)"]
-}
-```
-### Checking Mapping Results
-```typescript
-const result = await mapper.map(sourceData);
-if (result.success) {
-  // All fields mapped successfully
-  console.log('Mapped data:', result.data);
-  batchEntities.push(result.data);
-} else {
-  // One or more errors occurred
-  console.error('Mapping errors:', result.errors);
-  failedRecords.push({ sourceData, errors: result.errors });
-}
-// Partial success - some optional fields failed
-if (result.success && result.errors) {
-  console.warn('Mapping succeeded with warnings:', result.errors);
-}
-```
-### Safe Resolver with Error Handling
-```typescript
-const customResolvers = {
-  'custom.safeCalculate': (value, sourceData, config, helpers) => {
-    try {
-      const num = helpers.parseFloatSafe(value, 0);
-      if (num < 0) {
-        helpers.log.warn('Negative value found, using 0', { value });
-        return 0;
-      }
-      return num * 1.1; // Add 10%
-    } catch (error) {
-      helpers.log.error('Calculation failed', error);
-      return 0; // Safe fallback
-    }
-  },
-};
-```
----
-## Common Use Case Patterns
-### CSV to Batch API
-```typescript
-const config = {
-  fields: {
-    skuRef: { source: 'sku', required: true },
-    locationRef: { source: 'location', required: true },
-    qty: { source: 'quantity', resolver: 'sdk.parseInt', required: true },
-    status: { source: 'status', resolver: 'sdk.uppercase', defaultValue: 'ACTIVE' },
-  },
-};
-const mapper = new UniversalMapper(config);
-for (const row of csvRows) {
-  const result = await mapper.map(row);
-  if (result.success) {
-    batchEntities.push(result.data);
-  } else {
-    console.error(`Row failed: ${JSON.stringify(row)}, errors: ${result.errors}`);
-  }
-}
-await client.sendBatch(jobId, { entities: batchEntities });
-```
-### XML to GraphQL Structure
-```typescript
-const config = {
-  fields: {
-    ref: { source: 'order@id', required: true }, // XML attribute
-    'customer.email': { source: 'order.customer@email', resolver: 'sdk.lowercase' },
-    totalPrice: { source: 'order.total', resolver: 'sdk.parseFloat' },
-    items: {
-      source: 'order.items.item',
-      isArray: true,
-      fields: {
-        productRef: { source: 'sku' },
-        quantity: { source: 'qty', resolver: 'sdk.parseInt' },
-      },
-    },
-  },
-};
-```
-### Fluent to JSON Export
-```typescript
-const config = {
-  fields: {
-    position_id: { source: 'id' },
-    sku: { source: 'productRef' },
-    available_qty: { source: 'quantity', resolver: 'sdk.parseInt' },
-    last_updated: { source: 'updatedOn', resolver: 'sdk.formatDate' },
-  },
-};
-const mapper = new UniversalMapper(config);
-for (const edge of data.inventoryPositions.edges) {
-  const result = await mapper.map(edge.node);
-  if (result.success) {
-    extractedRecords.push(result.data);
-  }
-}
-await writeJsonFile(extractedRecords);
-```
----
-## When NOT to Use This Pattern
-### 1. Complex Multi-Step Transformations
-If your transformation requires multiple passes or complex state management, use:
-- Intermediate data structures to separate concerns
-- Multiple mapper instances for each transformation step
-- Custom service classes for domain-specific business logic
-### 2. Performance-Critical Async Operations
-For high-volume batch processing with async resolvers:
-- Pre-fetch lookup data before mapping
-- Use memoization for repeated lookups
-- Consider batch API calls instead of individual resolver calls
-### 3. Schema-Driven Code Generation
-When you need type-safe generated code:
-- Use GraphQLMutationMapper for XML/JSON to GraphQL mutations
-- Use introspection tools to generate TypeScript types
-- Consider schema-first development approaches
-### 4. Real-Time Streaming
-For streaming data transformations:
-- Use data source streaming APIs (CSVParserService streaming mode)
-- Consider event-driven architectures
-- Use transform streams for pipeline processing
----
-## Best Practices
-1. **Use SDK Resolvers First** - Try built-in resolvers before creating custom ones
-2. **Keep Resolvers Pure** - Same input should always produce same output
-3. **Mark Critical Fields Required** - Fail fast for data integrity
-4. **Provide Defaults for Optional Fields** - Prevent null/undefined in output
-5. **Use Helper Functions** - Leverage parseIntSafe, parseFloatSafe for safety
-6. **Document Custom Resolvers** - Add comments explaining transformation logic
-7. **Test Edge Cases** - Null, undefined, empty string, invalid formats
-8. **Handle Arrays Consistently** - Use isArray: true for uniform processing
-9. **Single Resolver Per Field** - The `resolver` property accepts a single resolver name (string). If you need multiple steps (e.g., toString + trim), create one custom resolver (for example, `custom.toStringTrim`) and use that.
-10. **Identifiers That Look Numeric** - For fields like SKU/GTIN/UPC that must remain strings, use `sdk.toString`. When parsing XML, set parser options to avoid numeric coercion (for example, `parseNumbers: false`) so leading zeros are preserved.
----
-## Related Patterns
-- **GraphQL Mutation Mapping** - XML/JSON to GraphQL mutations with GraphQLMutationMapper
-- **XML Parser** - Detailed XML path syntax and parsing patterns
-- **Batch Processing** - High-volume data ingestion patterns
-- **State Management** - Preventing duplicate processing with StateService
----
-**Remember**: UniversalMapper is the ONE mapping engine for ALL SDK transformations. Learn this pattern once, use it everywhere.
+# Pattern: Universal Field Mapping
+**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 UniversalMapper for transforming data between formats
+**Type**: Reusable Pattern
+**Complexity**: Low-Medium
+**Lines**: ~200 lines
+## When to Use This Pattern
+- Transforming CSV/JSON/XML to Fluent format
+- Extracting Fluent data for export
+- Data normalization and validation
+- Type conversions and formatting
+- Building GraphQL mutation inputs
+- Generating XML/JSON output structures
+## SDK Methods
+- `UniversalMapper(config, options)` - Create mapper instance
+- `mapper.map(sourceData)` - Transform single record
+- `mapper.registerResolver(name, fn)` - Add custom resolver
+- `mapper.registerResolvers(map)` - Add multiple custom resolvers
+- SDK Resolvers: `sdk.*` prefix (15 built-in)
+- Custom resolvers: Your own transformation functions
+---
+## Basic Mapping
+### Simple Field Mapping
+```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';
+const config = {
+  fields: {
+    // Direct mapping - no transformation
+    customerEmail: {
+      source: 'email',
+    },
+    // Map with transformation
+    status: {
+      source: 'orderStatus',
+      resolver: 'sdk.uppercase',
+    },
+    // Required field with validation
+    productSku: {
+      source: 'sku',
+      required: true,
+    },
+  },
+};
+const mapper = new UniversalMapper(config);
+// Transform data
+const sourceData = { email: 'john@example.com', orderStatus: 'pending', sku: 'PROD-001' };
+const result = await mapper.map(sourceData);
+if (result.success) {
+  console.log(result.data);
+  // { customerEmail: 'john@example.com', status: 'PENDING', productSku: 'PROD-001' }
+}
+```
+### Static Values
+```typescript
+const config = {
+  fields: {
+    type: {
+      value: 'STANDARD', // Always returns "STANDARD"
+    },
+    retailerId: {
+      value: 1, // Static numeric value
+    },
+    version: {
+      value: '2.0',
+    },
+  },
+};
+```
+### Default Values
+```typescript
+const config = {
+  fields: {
+    status: {
+      source: 'orderStatus',
+      defaultValue: 'PENDING', // Used if source is missing/empty
+    },
+    quantity: {
+      source: 'qty',
+      resolver: 'sdk.parseInt',
+      defaultValue: 0, // Fallback for missing quantity
+    },
+  },
+};
+```
+---
+## SDK Resolver Patterns
+### String Transformations
+```typescript
+const config = {
+  fields: {
+    // Convert to uppercase
+    countryCode: {
+      source: 'country',
+      resolver: 'sdk.uppercase', // "us" → "US"
+    },
+    // Convert to lowercase
+    email: {
+      source: 'customerEmail',
+      resolver: 'sdk.lowercase', // "JOHN@EXAMPLE.COM" → "john@example.com"
+    },
+    // Trim whitespace
+    sku: {
+      source: 'productSku',
+      resolver: 'sdk.trim', // "  SKU123  " → "SKU123"
+    },
+    // Convert to string
+    orderId: {
+      source: 'order_id',
+      resolver: 'sdk.toString', // 12345 → "12345"
+    },
+  },
+};
+```
+### Number Transformations
+```typescript
+const config = {
+  fields: {
+    // Parse as integer
+    quantity: {
+      source: 'qty',
+      resolver: 'sdk.parseInt', // "123" → 123, "123.99" → 123
+    },
+    // Parse as float
+    price: {
+      source: 'total',
+      resolver: 'sdk.parseFloat', // "99.99" → 99.99, "$45.50" → 45.5
+    },
+    // Generic number parser (alias for parseFloat)
+    weight: {
+      source: 'weight_kg',
+      resolver: 'sdk.number', // "3.14" → 3.14
+    },
+  },
+};
+```
+### Date Transformations
+```typescript
+const config = {
+  fields: {
+    // Format to ISO8601 (Fluent API standard)
+    expectedOn: {
+      source: 'delivery_date',
+      resolver: 'sdk.formatDate', // "2024-01-15" → "2024-01-15T00:00:00.000Z"
+    },
+    // Format to YYYY-MM-DD
+    orderDate: {
+      source: 'created_at',
+      resolver: 'sdk.formatDateShort', // "2024-01-15T10:30:00Z" → "2024-01-15"
+    },
+    // Parse date string
+    scheduledDate: {
+      source: 'schedule',
+      resolver: 'sdk.parseDate', // "01/15/2024" → Date object
+    },
+  },
+};
+```
+### Type Conversions
+```typescript
+const config = {
+  fields: {
+    // Convert to boolean
+    isActive: {
+      source: 'active',
+      resolver: 'sdk.boolean', // "true", "1", "yes", "y" → true
+    },
+    // Parse JSON string
+    metadata: {
+      source: 'json_data',
+      resolver: 'sdk.parseJson', // '{"key":"value"}' → { key: "value" }
+    },
+    // Stringify to JSON
+    customAttributes: {
+      source: 'attributes',
+      resolver: 'sdk.toJson', // { name: "John" } → '{"name":"John"}'
+    },
+  },
+};
+```
+### Utility Resolvers
+```typescript
+const config = {
+  fields: {
+    // Identity - no transformation
+    originalValue: {
+      source: 'rawData',
+      resolver: 'sdk.identity', // Pass through unchanged
+    },
+    // Coalesce - first non-null value
+    displayName: {
+      source: 'name',
+      resolver: 'sdk.coalesce',
+      defaultValue: 'Unknown', // Fallback if null/undefined
+    },
+  },
+};
+```
+---
+## Complete SDK Resolver Reference
+### String Resolvers (4)
+- `sdk.uppercase` - Convert to UPPERCASE
+- `sdk.lowercase` - Convert to lowercase
+- `sdk.trim` - Remove leading/trailing whitespace
+- `sdk.toString` - Convert any value to string
+### Number Resolvers (3)
+- `sdk.parseInt` - Parse as integer (returns 0 for invalid)
+- `sdk.parseFloat` - Parse as float (returns 0 for invalid)
+- `sdk.number` - Alias for parseFloat
+### Date Resolvers (3)
+- `sdk.formatDate` - Format to ISO8601 (Fluent API standard)
+- `sdk.formatDateShort` - Format to YYYY-MM-DD
+- `sdk.parseDate` - Parse date string to Date object
+### Type Conversion Resolvers (3)
+- `sdk.boolean` - Convert to boolean (handles "true", "1", "yes", etc.)
+- `sdk.parseJson` - Parse JSON string to object
+- `sdk.toJson` - Stringify object to JSON
+### Utility Resolvers (2)
+- `sdk.identity` - Pass value through unchanged
+- `sdk.coalesce` - Return first non-null value
+**Total: 15 SDK Resolvers**
+---
+## Custom Resolver Patterns
+### Basic Custom Resolver
+```typescript
+import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+const customResolvers = {
+  'custom.calculateTax': (value, sourceData, config, helpers) => {
+    const subtotal = helpers.parseFloatSafe(value, 0);
+    return subtotal * 0.1; // 10% tax
+  },
+  'custom.formatPhone': (value, sourceData, config, helpers) => {
+    // Remove non-digits
+    const digits = value.replace(/\D/g, '');
+    // Format as (XXX) XXX-XXXX
+    return `(${digits.slice(0, 3)}) ${digits.slice(3, 6)}-${digits.slice(6)}`;
+  },
+};
+const mapper = new UniversalMapper(config, { customResolvers });
+```
+### Using Helper Functions
+```typescript
+const customResolvers = {
+  'custom.cleanAndUpper': (value, sourceData, config, helpers) => {
+    // Use helpers for safe operations
+    const trimmed = helpers.normalizeWhitespace(value);
+    return trimmed.toUpperCase();
+  },
+  'custom.extractId': (value, sourceData, config, helpers) => {
+    // Safe nested property access
+    const product = helpers.get(sourceData, 'product.details') || {};
+    return product.id || 'UNKNOWN';
+  },
+};
+```
+### Context-Aware Resolvers
+> **⚠️ Important**: To use `helpers.fluentClient` or `helpers.context` in custom resolvers, you MUST pass them when creating the mapper. They are NOT available by default.
+```typescript
+const customResolvers = {
+  'custom.lookupCustomer': async (email, sourceData, config, helpers) => {
+    // Access fluentClient from helpers (passed via options)
+    if (!helpers.fluentClient) {
+      throw new Error('fluentClient not available');
+    }
+    const query = `query { customers(email: "${email}") { edges { node { id } } } }`;
+    const result = await helpers.fluentClient.graphql({ query });
+    return result.data.customers.edges[0]?.node.id;
+  },
+  'custom.addOrderContext': (value, sourceData, config, helpers) => {
+    // Access custom context
+    const orderId = helpers.context?.orderId;
+    return `${value}_${orderId}`;
+  },
+};
+// ✅ REQUIRED: Initialize mapper with fluentClient and context for async resolvers
+const mapper = new UniversalMapper(config, {
+  customResolvers,
+  fluentClient: fluentClient, // ← Required for API access in resolvers
+  logger: console, // ← Required for helpers.log
+  context: { orderId: '12345', userId: '999' }, // ← Required for helpers.context
+});
+```
+---
+## Nested Field Patterns
+### Nested Objects
+```typescript
+const config = {
+  fields: {
+    // Simple nested field with dot notation
+    'customer.id': {
+      source: 'customerId',
+      resolver: 'sdk.parseInt',
+    },
+    'customer.email': {
+      source: 'email',
+      resolver: 'sdk.lowercase',
+    },
+    'customer.address.city': {
+      source: 'city',
+    },
+  },
+};
+// Output:
+// {
+//   customer: {
+//     id: 12345,
+//     email: "john@example.com",
+//     address: { city: "New York" }
+//   }
+// }
+```
+### Nested Object Structure
+```typescript
+const config = {
+  fields: {
+    customer: {
+      fields: {
+        id: { source: 'customerId' },
+        email: { source: 'email' },
+        address: {
+          fields: {
+            street: { source: 'street' },
+            city: { source: 'city' },
+            zip: { source: 'zipCode' },
+          },
+        },
+      },
+    },
+  },
+};
+```
+---
+## Array Patterns
+### Array with Nested Mapping
+```typescript
+const config = {
+  fields: {
+    items: {
+      source: 'orderItems',
+      isArray: true, // Map each array element
+      fields: {
+        ref: { source: 'id' },
+        productRef: { source: 'sku' },
+        quantity: { source: 'qty', resolver: 'sdk.parseInt' },
+      },
+    },
+  },
+};
+// Source: { orderItems: [{ id: "1", sku: "SKU001", qty: "5" }] }
+// Output: { items: [{ ref: "1", productRef: "SKU001", quantity: 5 }] }
+```
+### GraphQL Edges/Nodes Pattern
+```typescript
+const config = {
+  fields: {
+    products: {
+      source: 'products.edges[*].node', // Wildcard extraction
+      isArray: true,
+      fields: {
+        id: { source: 'id' },
+        ref: { source: 'ref' },
+        name: { source: 'name' },
+      },
+    },
+  },
+};
+// Automatically extracts nodes from GraphQL pagination structure
+```
+### Conditional Array Item Processing
+```typescript
+const customResolvers = {
+  'custom.filterActive': (items, sourceData, config, helpers) => {
+    // Filter array items based on condition
+    return helpers.ensureArray(items).filter(item => item.status === 'ACTIVE');
+  },
+};
+const config = {
+  fields: {
+    activeItems: {
+      source: 'items',
+      resolver: 'custom.filterActive',
+      isArray: true,
+      fields: {
+        id: { source: 'id' },
+        name: { source: 'name' },
+      },
+    },
+  },
+};
+```
+---
+## Error Handling Patterns
+### Required Field Validation
+```typescript
+const config = {
+  fields: {
+    skuRef: {
+      source: 'sku',
+      required: true, // Fails entire mapping if missing
+    },
+    locationRef: {
+      source: 'location',
+      required: true,
+    },
+    qty: {
+      source: 'quantity',
+      resolver: 'sdk.parseInt',
+      defaultValue: 0, // Optional field with default
+    },
+  },
+};
+const result = await mapper.map(sourceData);
+if (!result.success) {
+  console.error('Mapping failed:', result.errors);
+  // ["Required field 'skuRef' is missing or empty (source: sku)"]
+}
+```
+### Checking Mapping Results
+```typescript
+const result = await mapper.map(sourceData);
+if (result.success) {
+  // All fields mapped successfully
+  console.log('Mapped data:', result.data);
+  batchEntities.push(result.data);
+} else {
+  // One or more errors occurred
+  console.error('Mapping errors:', result.errors);
+  failedRecords.push({ sourceData, errors: result.errors });
+}
+// Partial success - some optional fields failed
+if (result.success && result.errors) {
+  console.warn('Mapping succeeded with warnings:', result.errors);
+}
+```
+### Safe Resolver with Error Handling
+```typescript
+const customResolvers = {
+  'custom.safeCalculate': (value, sourceData, config, helpers) => {
+    try {
+      const num = helpers.parseFloatSafe(value, 0);
+      if (num < 0) {
+        helpers.log.warn('Negative value found, using 0', { value });
+        return 0;
+      }
+      return num * 1.1; // Add 10%
+    } catch (error) {
+      helpers.log.error('Calculation failed', error);
+      return 0; // Safe fallback
+    }
+  },
+};
+```
+---
+## Common Use Case Patterns
+### CSV to Batch API
+```typescript
+const config = {
+  fields: {
+    skuRef: { source: 'sku', required: true },
+    locationRef: { source: 'location', required: true },
+    qty: { source: 'quantity', resolver: 'sdk.parseInt', required: true },
+    status: { source: 'status', resolver: 'sdk.uppercase', defaultValue: 'ACTIVE' },
+  },
+};
+const mapper = new UniversalMapper(config);
+for (const row of csvRows) {
+  const result = await mapper.map(row);
+  if (result.success) {
+    batchEntities.push(result.data);
+  } else {
+    console.error(`Row failed: ${JSON.stringify(row)}, errors: ${result.errors}`);
+  }
+}
+await client.sendBatch(jobId, { entities: batchEntities });
+```
+### XML to GraphQL Structure
+```typescript
+const config = {
+  fields: {
+    ref: { source: 'order@id', required: true }, // XML attribute
+    'customer.email': { source: 'order.customer@email', resolver: 'sdk.lowercase' },
+    totalPrice: { source: 'order.total', resolver: 'sdk.parseFloat' },
+    items: {
+      source: 'order.items.item',
+      isArray: true,
+      fields: {
+        productRef: { source: 'sku' },
+        quantity: { source: 'qty', resolver: 'sdk.parseInt' },
+      },
+    },
+  },
+};
+```
+### Fluent to JSON Export
+```typescript
+const config = {
+  fields: {
+    position_id: { source: 'id' },
+    sku: { source: 'productRef' },
+    available_qty: { source: 'quantity', resolver: 'sdk.parseInt' },
+    last_updated: { source: 'updatedOn', resolver: 'sdk.formatDate' },
+  },
+};
+const mapper = new UniversalMapper(config);
+for (const edge of data.inventoryPositions.edges) {
+  const result = await mapper.map(edge.node);
+  if (result.success) {
+    extractedRecords.push(result.data);
+  }
+}
+await writeJsonFile(extractedRecords);
+```
+---
+## When NOT to Use This Pattern
+### 1. Complex Multi-Step Transformations
+If your transformation requires multiple passes or complex state management, use:
+- Intermediate data structures to separate concerns
+- Multiple mapper instances for each transformation step
+- Custom service classes for domain-specific business logic
+### 2. Performance-Critical Async Operations
+For high-volume batch processing with async resolvers:
+- Pre-fetch lookup data before mapping
+- Use memoization for repeated lookups
+- Consider batch API calls instead of individual resolver calls
+### 3. Schema-Driven Code Generation
+When you need type-safe generated code:
+- Use GraphQLMutationMapper for XML/JSON to GraphQL mutations
+- Use introspection tools to generate TypeScript types
+- Consider schema-first development approaches
+### 4. Real-Time Streaming
+For streaming data transformations:
+- Use data source streaming APIs (CSVParserService streaming mode)
+- Consider event-driven architectures
+- Use transform streams for pipeline processing
+---
+## Best Practices
+1. **Use SDK Resolvers First** - Try built-in resolvers before creating custom ones
+2. **Keep Resolvers Pure** - Same input should always produce same output
+3. **Mark Critical Fields Required** - Fail fast for data integrity
+4. **Provide Defaults for Optional Fields** - Prevent null/undefined in output
+5. **Use Helper Functions** - Leverage parseIntSafe, parseFloatSafe for safety
+6. **Document Custom Resolvers** - Add comments explaining transformation logic
+7. **Test Edge Cases** - Null, undefined, empty string, invalid formats
+8. **Handle Arrays Consistently** - Use isArray: true for uniform processing
+9. **Single Resolver Per Field** - The `resolver` property accepts a single resolver name (string). If you need multiple steps (e.g., toString + trim), create one custom resolver (for example, `custom.toStringTrim`) and use that.
+10. **Identifiers That Look Numeric** - For fields like SKU/GTIN/UPC that must remain strings, use `sdk.toString`. When parsing XML, set parser options to avoid numeric coercion (for example, `parseNumbers: false`) so leading zeros are preserved.
+---
+## Related Patterns
+- **GraphQL Mutation Mapping** - XML/JSON to GraphQL mutations with GraphQLMutationMapper
+- **XML Parser** - Detailed XML path syntax and parsing patterns
+- **Batch Processing** - High-volume data ingestion patterns
+- **State Management** - Preventing duplicate processing with StateService
+---
+**Remember**: UniversalMapper is the ONE mapping engine for ALL SDK transformations. Learn this pattern once, use it everywhere.