@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/02-CORE-GUIDES/mapping/resolvers/mapping-resolvers-resolver-guide.md

@@ -1,1330 +1,1330 @@
-# Resolver Pattern Guide
-
-**FC Connect SDK - Transform Data with Custom Logic**
-
-Version: 2.0.0
-Last Updated: 2025-01-14
-
----
-
-## 📚 Table of Contents
-
-1. [Quick Start (5 Minutes)](#quick-start-5-minutes)
-2. [Core Concepts](#core-concepts)
-3. [Real-World Examples](#real-world-examples)
-4. [Advanced Topics](#advanced-topics)
-   - [Async Operations & API Calls](#async-operations--api-calls)
-   - [Error Handling Patterns](#error-handling-patterns)
-   - [Performance Optimization](#performance-optimization)
-   - [Resolver-Only Fields & Required Validation](#resolver-only-fields--required-validation) ← NEW
-5. [Reference Documentation](#reference-documentation)
-
----
-
-## 🎯 What You'll Learn
-
-By the end of this guide, you'll be able to:
-
-✅ Write custom resolver functions for complex transformations
-✅ Use the ResolverBuilder API for clean, maintainable code
-✅ Handle order management and inventory data transformations
-✅ Work with async operations (API calls, database lookups)
-✅ Apply best practices for production-ready resolvers
-
-**Time to Complete:** 30 minutes to 2 hours (depending on depth)
-
----
-
-## Quick Start (5 Minutes)
-
-### What are Resolvers?
-
-**Resolvers** are custom JavaScript functions that transform source data into the format required by Fluent Commerce. They're your solution when JSON mapping isn't enough.
-
-**Use resolvers when you need:**
-
-- 🧮 Complex calculations (totals, aggregations, formulas)
-- 🔀 Conditional logic (if-then-else transformations)
-- 🌐 External API calls (customer lookup, price checks)
-- 🔄 Cross-referencing data (resolve IDs to full objects)
-- ♻️ Reusable transformation logic
-
----
-
-### Your First Resolver
-
-Let's transform an order from our e-commerce system to Fluent Commerce.
-
-**Step 1: Install the SDK**
-
-```bash
-npm install @fluentcommerce/fc-connect-sdk
-```
-
-**Step 2: Create Your First Resolver**
-
-```typescript
-import { createResolverBuilder, ResolverHelpers } from '@fluentcommerce/fc-connect-sdk';
-
-// Create a builder instance
-const builder = createResolverBuilder();
-
-// Define your resolvers
-const resolvers = builder
-  // Simple field mapping: Extract order reference
-  .from('input.ref', 'orders.order@order-no')
-
-  // With transformation: Parse price to number
-  .from('input.totalPrice', 'orders.order.totals.order-total.gross-price', value =>
-    parseFloat(value)
-  )
-
-  // Build the resolver map
-  .build();
-
-export default resolvers;
-```
-
-**Step 3: Use in Your Workflow**
-
-```typescript
-import { http } from '@versori/run';
-import { createClient, XMLParserService, ResolverHelpers } from '@fluentcommerce/fc-connect-sdk';
-import resolvers from './resolvers';
-
-// Versori workflow - ctx comes from workflow parameter
-export default http('processOrder', async (ctx) => {  // ← ctx defined here!
-  const { log, activation, fetch } = ctx;
-
-  // 1. Parse input XML
-  const parser = new XMLParserService(log);
-  const orderData = await parser.parseFromString(activation.body);
-
-  // 2. Apply resolvers
-  const config = {
-    defaultRetailerId: activation.getVariable('RETAILER_ID'),
-    apiToken: activation.getVariable('API_TOKEN')
-  };
-
-  const transformedData = {};
-  for (const [path, resolver] of Object.entries(resolvers)) {
-    const value = await resolver(orderData, config, ResolverHelpers, ctx);
-    setNestedValue(transformedData, path, value);
-  }
-
-  // 3. Send to Fluent Commerce
-  const client = await createClient({ ...ctx, log });
-
-  const result = await client.graphql({
-    query: `mutation CreateOrder($input: CreateOrderInput!) {
-      createOrder(input: $input) { id ref }
-    }`,
-    variables: { input: transformedData },
-  });
-
-  return { success: true, data: result };
-});
-
-function setNestedValue(obj: any, path: string, value: any) {
-  const keys = path.split('.');
-  let current = obj;
-  for (let i = 0; i < keys.length - 1; i++) {
-    current[keys[i]] = current[keys[i]] || {};
-    current = current[keys[i]];
-  }
-  current[keys[keys.length - 1]] = value;
-}
-```
-
-**🎉 That's it!** You've created and executed your first resolver.
-
----
-
-### Test Your Resolver
-
-Use our canonical test data to verify your resolver works:
-
-```typescript
-import { canonicalOrder } from '../../../03-PATTERN-GUIDES/examples/test-data/canonical-order.json';
-import { ResolverHelpers } from '@fluentcommerce/fc-connect-sdk';
-
-// Test the resolver
-const result = resolvers\['input.ref'](canonicalOrder, {}, ResolverHelpers);
-console.log(result); // Expected: "ORD-2025-001"
-```
-
-✅ **Expected Output:** `"ORD-2025-001"`
-
-📖 **See:** [Complete test data structure](../../../03-PATTERN-GUIDES/examples/test-data/) for resolver testing examples
-
----
-
-## Core Concepts
-
-### JSON Mapping vs Resolvers
-
-**Use JSON Mapping when:**
-
-- Simple field-to-field mapping
-- Standard transformations (toString, toNumber)
-- Static data structures
-
-```json
-{
-  "ref": { "source": "order.orderNo" },
-  "totalPrice": { "source": "order.total", "resolver": "sdk.number" }
-}
-```
-
-**Use Resolvers when:**
-
-- Complex calculations or business logic
-- Conditional transformations
-- External API calls
-- Multiple source aggregation
-
-```typescript
-builder.field('input.totalDiscount', (data, config, helpers) => {
-  // Calculate from multiple sources
-  const itemDiscounts = helpers.sum(data.order.items, 'discount');
-  const couponValue = helpers.get(data, 'order.coupon.value', 0);
-  return itemDiscounts + couponValue;
-});
-```
-
----
-
-### The Four Resolver Parameters
-
-Every resolver receives four parameters:
-
-```typescript
-type ResolverFunction = (
-  value: unknown, // Extracted value from 'source' path
-  data: unknown, // Full data context (includes named nodes)
-  config: unknown, // Configuration object
-  helpers: Helpers // Utility functions
-) => unknown | Promise<unknown>;
-```
-
-**You don't have to use all four** - just what you need!
-
----
-
-#### 1. `value` - The Extracted Value
-
-**What:** The value extracted from the `source` path in your mapping.
-
-**When defined:** When your field has a `source` property
-**When undefined:** When your field only has a `resolver` (resolver-only field)
-
-**Example: Using `value` from source**
-
-```typescript
-// Mapping config
-{
-  "ref": {
-    "source": "orders.order@order-no",
-    "resolver": "custom.addPrefix"
-  }
-}
-
-// Resolver
-'custom.addPrefix': (value, data, config, helpers) => {
-  // value = "ORD-2025-001" (extracted from source)
-  return `ORDER-${value}`;
-  // Returns: "ORDER-ORD-2025-001"
-}
-```
-
-**Example: Resolver-only (no source)**
-
-```typescript
-// Mapping config (NO source!)
-{
-  "totalDiscount": {
-    "resolver": "custom.calculateTotalDiscount"
-  }
-}
-
-// Resolver
-'custom.calculateTotalDiscount': (value, data, config, helpers) => {
-  // value = undefined (no source specified)
-  // Use 'data' to access full context
-  const items = helpers.get(data, 'orders.order.product-lineitems.product-lineitem', []);
-  return helpers.sum(helpers.ensureArray(items), item =>
-    helpers.parseFloatSafe(item['base-price'], 0) - helpers.parseFloatSafe(item['net-price'], 0)
-  );
-}
-```
-
-**Important: Required Fields with Resolvers**
-
-When using `required: true` with resolvers, validation timing depends on whether the field has a `source`:
-
-**Fields with `source`**: Validation happens **before** resolver execution
-```json
-{
-  "discount": {
-    "source": "order.subtotal",
-    "resolver": "custom.calculateDiscount",
-    "required": true
-  }
-}
-```
-- ✅ Checks if `order.subtotal` 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
-{
-  "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
-
-**Why this matters:** 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.
-
-📖 **Learn more:** [Resolver Parameters Deep Dive](./mapping-resolvers-resolver-parameters-reference.md)
-
----
-
-#### 2. `data` - Full Data Context
-
-**What:** The complete data object, including all named nodes from your mapping config.
-
-**When to use:** When you need to access data from different parts of your payload or from named nodes.
-
-**Example: Accessing order data**
-
-```typescript
-builder.field('input.customer.email', (data, config, helpers) => {
-  // Access nested data safely
-  return helpers.get(data, 'orders.order.customer.customer-email');
-});
-```
-
-**Example: Using named nodes**
-
-Named nodes let you parse embedded XML/JSON within your payload:
-
-```json
-{
-  "nodes": {
-    "radialXml": {
-      "extract": "orders.order.custom-attributes.custom-attribute[attribute-id=RadialData]",
-      "parse": "xml"
-    }
-  }
-}
-```
-
-```typescript
-builder.field('input.specialInstructions', (data, config, helpers) => {
-  // 'data' now contains both original data AND parsed nodes
-  // data = {
-  //   orders: { ... original data ... },
-  //   radialXml: { ... parsed XML ... }
-  // }
-
-  const radialData = data.radialXml;
-  return helpers.get(radialData, 'Order.SpecialInstructions.Text');
-});
-```
-
----
-
-#### 3. `config` - Configuration Object
-
-**What:** Settings and defaults passed when executing resolvers.
-
-**When to use:** For environment-specific values, defaults, or API credentials.
-
-**Example: Config with fallbacks**
-
-```typescript
-// Standalone Pattern
-const config = {
-  defaultRetailerId: '1',
-  defaultCurrency: 'USD',
-  apiToken: process.env.EXTERNAL_API_TOKEN,
-};
-
-// Versori Platform Pattern
-const config = {
-  defaultRetailerId: activation.getVariable('FLUENT_RETAILER_ID'),
-  defaultCurrency: activation.getVariable('DEFAULT_CURRENCY') || 'USD',
-  // Credentials accessed via ctx.credentials() in resolver
-};
-
-builder.withConfigFallback(
-  'input.retailer.id',
-  'orders.order.retailerId',
-  'defaultRetailerId' // Fallback key in config
-);
-```
-
-**Versori Credential Access in Resolvers:**
-
-```typescript
-// Use in async resolver for external API calls
-builder.field('input.enrichedData', async (data, config, helpers, ctx) => {
-  // Option 1: Get from activation variables
-  const apiToken = ctx.activation.getVariable('EXTERNAL_API_TOKEN');
-
-  // Option 2: Get from connection credentials
-  const apiCreds = await ctx.credentials().getAccessToken('external_api');
-
-  const response = await ctx.fetch('https://api.example.com/enrich', {
-    method: 'POST',
-    headers: {
-      'Authorization': `Bearer ${apiCreds?.accessToken || apiToken}`,
-      'Content-Type': 'application/json'
-    },
-    body: JSON.stringify(data)
-  });
-
-  return response.json();
-});
-```
-
----
-
-#### 4. `helpers` - Utility Functions
-
-**What:** Collection of 54 helper functions for common transformations.
-
-**Available helpers:**
-
-- **Data access:** `get()`, `ensureArray()`
-- **Parsing:** `parseFloatSafe()`, `parseIntSafe()`, `safeJsonParse()`
-- **Formatting:** `formatDate()`, `formatCurrency()`
-- **Arrays:** `sum()`, `avg()`, `groupBy()`, `chunk()`, `flatten()`
-- **Strings:** `slugify()`, `template()`, `truncate()`
-- **Validation:** `isValidEmail()`, `requireField()`
-- **Async:** `retry()`, `batchProcess()`
-
-**Example: Using helpers**
-
-```typescript
-builder.field('input.items', (data, config, helpers) => {
-  // Safe path access
-  const items = helpers.get(data, 'orders.order.product-lineitems.product-lineitem');
-
-  // Handle XML single vs array
-  const itemsArray = helpers.ensureArray(items);
-
-  // Transform with safe parsing
-  return itemsArray.map(item => ({
-    ref: item['@lineitem-id'],
-    quantity: helpers.parseIntSafe(item.quantity, 1),
-    price: helpers.parseFloatSafe(item['base-price'], 0),
-  }));
-});
-```
-
-📖 **See all helpers:** [Resolver Helpers Reference](./mapping-resolvers-resolver-helpers-reference.md)
-
----
-
-## Real-World Examples
-
-All examples use our **canonical datasets** for consistency. You can test every example!
-
-📁 **Test Data:**
-
-- [canonical-order.json](../../../03-PATTERN-GUIDES/examples/test-data/canonical-order.json) - Order management
-- [canonical-inventory.json](../../../03-PATTERN-GUIDES/examples/test-data/canonical-inventory.json) - Inventory management
-
----
-
-### Example 1: Order Management - Simple Transformation
-
-**Scenario:** Extract basic order fields from SFCC-style XML.
-
-**Source Data:** See [canonical-order.json](../../../03-PATTERN-GUIDES/examples/test-data/canonical-order.json)
-
-**Goal:** Create Fluent Commerce order input with ref, totalPrice, and customer.
-
-```typescript
-import { createResolverBuilder } from '@fluentcommerce/fc-connect-sdk';
-
-const builder = createResolverBuilder();
-
-export const orderResolvers = builder
-  // Extract order reference (required field)
-  .validate(
-    'input.ref',
-    (data, config, helpers) => helpers.get(data, 'orders.order@order-no'),
-    value => !!value || 'Order reference is required'
-  )
-
-  // Parse total price to number
-  .from('input.totalPrice', 'orders.order.totals.order-total.gross-price', value =>
-    parseFloat(value)
-  )
-
-  // Extract customer email
-  .from('input.customer.email', 'orders.order.customer.customer-email')
-
-  .build();
-```
-
-**Test it:**
-
-```typescript
-import { canonicalOrder } from '../../../03-PATTERN-GUIDES/examples/test-data/canonical-order.json';
-import { ResolverHelpers } from '@fluentcommerce/fc-connect-sdk';
-
-const result = {
-  ref: orderResolvers\['input.ref'](canonicalOrder, {}, ResolverHelpers),
-  totalPrice: orderResolvers\['input.totalPrice'](canonicalOrder, {}, ResolverHelpers),
-  customer: {
-    email: orderResolvers\['input.customer.email'](canonicalOrder, {}, ResolverHelpers),
-  },
-};
-
-console.log(result);
-// Expected:
-// {
-//   ref: "ORD-2025-001",
-//   totalPrice: 151.17,
-//   customer: { email: "john.doe@example.com" }
-// }
-```
-
-✅ **Expected Output:**
-
-```json
-{
-  "ref": "ORD-2025-001",
-  "totalPrice": 151.17,
-  "customer": { "email": "john.doe@example.com" }
-}
-```
-
----
-
-### Example 2: Order Management - Array Mapping
-
-**Scenario:** Transform line items array with quantity and price calculations.
-
-```typescript
-export const itemResolvers = builder
-  .mapArray(
-    'input.items',
-    'orders.order.product-lineitems.product-lineitem',
-    (item, index, config, helpers) => ({
-      ref: item['@lineitem-id'] || `ITEM-${index + 1}`,
-      productRef: item['product-id'],
-      quantity: helpers.parseIntSafe(item.quantity, 1),
-      price: helpers.parseFloatSafe(item['base-price'], 0),
-      totalPrice: helpers.parseFloatSafe(item['gross-price'], 0),
-
-      attributes: {
-        productName: item['product-name'],
-        position: helpers.parseIntSafe(item.position, index + 1),
-        taxAmount: helpers.parseFloatSafe(item.tax, 0),
-      },
-    })
-  )
-  .build();
-```
-
-**Test it:**
-
-```typescript
-const items = itemResolvers\['input.items'](canonicalOrder, {}, ResolverHelpers);
-console.log(items);
-```
-
-✅ **Expected Output:**
-
-```json
-[
-  {
-    "ref": "ITEM-001",
-    "productRef": "SKU-WM-001",
-    "quantity": 2,
-    "price": 29.99,
-    "totalPrice": 64.78,
-    "attributes": {
-      "productName": "Wireless Mouse",
-      "position": 1,
-      "taxAmount": 4.8
-    }
-  },
-  {
-    "ref": "ITEM-002",
-    "productRef": "SKU-KB-001",
-    "quantity": 1,
-    "price": 79.99,
-    "totalPrice": 86.39,
-    "attributes": {
-      "productName": "Mechanical Keyboard",
-      "position": 2,
-      "taxAmount": 6.4
-    }
-  }
-]
-```
-
----
-
-### Example 3: Inventory Management - Batch Ingestion
-
-**Scenario:** Transform WMS inventory data to Fluent Commerce batch format.
-
-**Source Data:** See [canonical-inventory.json](../../../03-PATTERN-GUIDES/examples/test-data/canonical-inventory.json)
-
-```typescript
-export const inventoryResolvers = builder
-  // Extract location ID
-  .from('input.locationId', 'inventory.header.location-id')
-
-  // Transform inventory items array
-  .mapArray('input.entities', 'inventory.items', (item, index, config, helpers) => ({
-    skuRef: item.sku,
-    locationRef: item.location.id,
-    qty: helpers.parseIntSafe(item.quantity['on-hand'], 0),
-
-    // Optional: Add expected delivery date
-    expectedOn: helpers.get(item, 'dates.next-expected-receipt')
-      ? new Date(item['dates']['next-expected-receipt']).toISOString()
-      : null,
-
-    attributes: {
-      available: helpers.parseIntSafe(item.quantity.available, 0),
-      reserved: helpers.parseIntSafe(item.quantity.reserved, 0),
-      inTransit: helpers.parseIntSafe(item.quantity['in-transit'], 0),
-      binLocation: item.attributes['bin-location'],
-      lotNumber: item.attributes['lot-number'],
-    },
-  }))
-
-  .build();
-```
-
-**Test it:**
-
-```typescript
-import { canonicalInventory } from '../../../03-PATTERN-GUIDES/examples/test-data/canonical-inventory.json';
-
-const result = {
-  locationId: inventoryResolvers\['input.locationId'](canonicalInventory, {}, ResolverHelpers),
-  entities: inventoryResolvers\['input.entities'](canonicalInventory, {}, ResolverHelpers),
-};
-
-console.log(result.entities[0]);
-```
-
-✅ **Expected Output:**
-
-```json
-{
-  "skuRef": "SKU-WM-001",
-  "locationRef": "WH-001",
-  "qty": 250,
-  "expectedOn": "2025-01-20T00:00:00.000Z",
-  "attributes": {
-    "available": 200,
-    "reserved": 50,
-    "inTransit": 100,
-    "binLocation": "A-12-03",
-    "lotNumber": "LOT-2025-001"
-  }
-}
-```
-
----
-
-### Example 4: Complex Calculation - Total Discount
-
-**Scenario:** Calculate total discount from multiple sources (item discounts + promotions).
-
-```typescript
-builder.calculate('input.totalDiscount', (data, helpers) => {
-  // Get line items
-  const items = helpers.ensureArray(
-    helpers.get(data, 'orders.order.product-lineitems.product-lineitem', [])
-  );
-
-  // Calculate item-level discounts
-  const itemDiscounts = items.reduce((sum, item) => {
-    const basePrice = helpers.parseFloatSafe(item['base-price'], 0);
-    const netPrice = helpers.parseFloatSafe(item['net-price'], 0);
-    const quantity = helpers.parseIntSafe(item.quantity, 1);
-    return sum + (basePrice - netPrice) * quantity;
-  }, 0);
-
-  // Add order-level adjustment (if negative, it's a discount)
-  const adjustment = helpers.parseFloatSafe(
-    helpers.get(data, 'orders.order.totals.adjustment-total.gross-price'),
-    0
-  );
-
-  const orderDiscount = adjustment < 0 ? Math.abs(adjustment) : 0;
-
-  const totalDiscount = itemDiscounts + orderDiscount;
-
-  helpers.log?.info('Calculated total discount', {
-    itemDiscounts,
-    orderDiscount,
-    totalDiscount,
-  });
-
-  return helpers.formatCurrency(totalDiscount, 2);
-});
-```
-
-**Test it:**
-
-```typescript
-const discount = resolvers\['input.totalDiscount'](canonicalOrder, {}, ResolverHelpers);
-console.log(discount); // Expected: "14.00" (from adjustment-total in canonical data)
-```
-
----
-
-### Example 5: Conditional Mapping - Order Type
-
-**Scenario:** Map channel type to Fluent order type with business rules.
-
-```typescript
-builder.field('input.type', (data, config, helpers) => {
-  const channelType = helpers.get(data, 'orders.order.channel-type');
-  const isGift = helpers.get(data, 'orders.order.shipments.shipment.gift') === 'true';
-
-  // Channel to order type mapping
-  const channelMapping = {
-    Storefront: 'HD',
-    CallCenter: 'CC',
-    Mobile: 'MOBILE',
-    POS: 'STORE',
-  };
-
-  let orderType = helpers.mapValue(channelType, channelMapping, config.defaultOrderType || 'HD');
-
-  // Business rule: Gift orders get special type
-  if (isGift && orderType === 'HD') {
-    orderType = 'GIFT_HD';
-  }
-
-  helpers.log?.debug('Mapped order type', { channelType, isGift, orderType });
-
-  return orderType;
-});
-```
-
-**Test it:**
-
-```typescript
-const orderType = resolvers`'input.type'`;
-console.log(orderType); // Expected: "HD" (Storefront channel)
-```
-
----
-
-## Advanced Topics
-
-### Async Operations & API Calls
-
-Resolvers can be async to call external APIs or perform lookups.
-
-**Example: Customer Lookup**
-
-```typescript
-builder.field('input.customer.id', async (data, config, helpers) => {
-  const customerId = helpers.get(data, 'orders.order.customer.customer-no');
-
-  if (!helpers.fluentClient) {
-    throw new Error('FluentClient is required for customer lookup');
-  }
-
-  // Use retry helper for resilience
-  return await helpers.retry(
-    async () => {
-      // Query for existing customer
-      const result = await helpers.fluentClient.graphql({
-        query: `
-          query GetCustomer($username: [String]) {
-            customers(username: $username, first: 1) {
-              edges {
-                node { id username }
-              }
-            }
-          }
-        `,
-        variables: { username: [customerId] },
-      });
-
-      const existing = result.data?.customers?.edges?.[0]?.node;
-
-      if (existing) {
-        helpers.log?.info('Found existing customer', { id: existing.id });
-        return existing.id;
-      }
-
-      // Create new customer if not found
-      helpers.log?.info('Creating new customer', { customerId });
-      const createResult = await helpers.fluentClient.graphql({
-        query: `
-          mutation CreateCustomer($input: CreateCustomerInput!) {
-            createCustomer(input: $input) { id }
-          }
-        `,
-        variables: {
-          input: {
-            username: customerId,
-            retailer: { id: config.defaultRetailerId },
-          },
-        },
-      });
-
-      return createResult.data?.createCustomer?.id;
-    },
-    3, // Retry 3 times
-    500 // 500ms delay
-  );
-});
-```
-
-**Best Practices for Async Resolvers:**
-
-1. ✅ **Always use error handling**
-2. ✅ **Use `helpers.retry()` for transient failures**
-3. ✅ **Add timeout protection**
-4. ✅ **Log API calls for debugging**
-5. ✅ **Cache results when possible**
-
-📖 **Learn more:** [Async Patterns Cookbook](./mapping-resolvers-resolver-cookbook.md#async-patterns)
-
----
-
-### Error Handling Patterns
-
-**Pattern 1: Validation with Custom Errors**
-
-```typescript
-builder.validate(
-  'input.totalPrice',
-  (data, config, helpers) => {
-    const price = helpers.get(data, 'orders.order.totals.order-total.gross-price');
-    return helpers.parseFloatSafe(price, 0);
-  },
-  value => value > 0 || 'Total price must be greater than zero'
-);
-```
-
-**Pattern 2: Try-Catch with Fallbacks**
-
-```typescript
-builder.field('input.customAttribute', (data, config, helpers) => {
-  try {
-    const attrs = helpers.get(data, 'orders.order.custom-attributes.custom-attribute');
-    return helpers.extractCustomAttribute(attrs, 'specialValue');
-  } catch (error) {
-    helpers.log?.warn('Failed to extract custom attribute', { error });
-    return config.defaultSpecialValue || null;
-  }
-});
-```
-
-📖 **Learn more:** [Error Handling Guide](./mapping-resolvers-resolver-troubleshooting.md#error-patterns)
-
----
-
-### Performance Optimization
-
-**1. Memoize Expensive Calculations**
-
-```typescript
-import { ResolverHelpers } from '@fluentcommerce/fc-connect-sdk';
-
-const calculateComplexDiscount = ResolverHelpers.memoize((items, discountRules) => {
-  // Expensive calculation cached by input
-  return items.reduce((total, item) => {
-    return total + applyDiscountRules(item, discountRules);
-  }, 0);
-});
-
-builder.field('input.discount', (data, config, helpers) => {
-  const items = helpers.get(data, 'orders.order.product-lineitems.product-lineitem', []);
-  return calculateComplexDiscount(items, config.discountRules);
-});
-```
-
-**2. Parallel Async Operations**
-
-```typescript
-// ❌ Sequential (slow)
-const customer = await lookupCustomer(customerId);
-const inventory = await checkInventory(sku);
-const pricing = await getPricing(sku);
-
-// ✅ Parallel (fast)
-const [customer, inventory, pricing] = await Promise.all([
-  lookupCustomer(customerId),
-  checkInventory(sku),
-  getPricing(sku),
-]);
-```
-
-**3. Batch Processing**
-
-```typescript
-builder.field('input.enrichedItems', async (data, config, helpers) => {
-  const items = helpers.get(data, 'orders.order.product-lineitems.product-lineitem', []);
-
-  // Process in batches of 10
-  return await helpers.batchProcess(
-    items,
-    async item => {
-      // Enrich each item with external data
-      const details = await fetchProductDetails(item['product-id']);
-      return { ...item, ...details };
-    },
-    10 // Batch size
-  );
-});
-```
-
-📖 **Learn more:** [Performance Best Practices](./mapping-resolvers-resolver-cookbook.md#performance-optimization)
-
----
-
-### Resolver-Only Fields & Required Validation
-
-**New in SDK v0.1.37:** Required validation for resolver-only fields (fields without a source).
-
-**What are resolver-only fields?**
-
-Resolver-only fields are fields that don't extract data from a source path, but instead generate values programmatically using a resolver function.
-
-**Use cases:**
-
-1. **Generate unique IDs** - Create UUIDs or composite keys
-2. **Derive values** - Calculate from other fields in the data
-3. **Enrich with external data** - Look up values from APIs without a source field
-4. **Apply business logic** - Determine values based on complex rules
-
----
-
-#### UniversalMapper Configuration
-
-**Example: Generate ID without source**
-
-```json
-{
-  "fields": {
-    "id": {
-      "resolver": "custom.generateProductId",
-      "required": true
-    },
-    "name": {
-      "source": "productName",
-      "required": true
-    },
-    "enrichedData": {
-      "resolver": "custom.enrichFromAPI",
-      "required": false
-    }
-  }
-}
-```
-
-**Resolver implementation:**
-
-```typescript
-import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-import { v4 as uuid } from 'uuid';
-
-const customResolvers = {
-  // Generate UUID for each product (no source needed)
-  'custom.generateProductId': (value, sourceData, config, helpers) => {
-    // value is undefined (no source)
-    // Generate unique ID based on business logic
-    const sku = helpers.get(sourceData, 'sku');
-    const prefix = config.idPrefix || 'PROD';
-    return `${prefix}-${sku}-${uuid()}`;
-  },
-
-  // Enrich with external API data
-  'custom.enrichFromAPI': async (value, sourceData, config, helpers) => {
-    const sku = helpers.get(sourceData, 'sku');
-
-    try {
-      const response = await helpers.retry(async () => {
-        return await fetch(`https://api.example.com/products/${sku}`);
-      }, 3);
-
-      return await response.json();
-    } catch (error) {
-      helpers.log?.warn('Failed to enrich product', { sku, error });
-      return null; // Optional field, return null on failure
-    }
-  },
-};
-
-const mapper = new UniversalMapper(mappingConfig, { customResolvers });
-```
-
----
-
-#### Validation Behavior
-
-**For resolver-only fields (`resolver` without `source`):**
-
-1. ✅ **No source extraction** - Value starts as `undefined`
-2. ✅ **Skip pre-validation** - Required validation does NOT run before resolver
-3. ✅ **Execute resolver** - Resolver generates the value
-4. ✅ **Post-validation** - Required validation runs AFTER resolver execution
-
-**For fields with source (`source` + `resolver`):**
-
-1. ✅ **Extract from source** - Value extracted from data
-2. ✅ **Validate required** - Required validation runs immediately
-3. ✅ **Execute resolver** - Resolver transforms the extracted value
-4. ✅ **No post-validation** - Required already validated before resolver
-
----
-
-#### When to Use Resolver-Only Required
-
-**✅ Good use cases:**
-
-```json
-{
-  "fields": {
-    // Generate unique transaction ID
-    "transactionId": {
-      "resolver": "custom.generateTransactionId",
-      "required": true
-    },
-
-    // Look up customer ID by email from source
-    "customerId": {
-      "resolver": "custom.lookupCustomerByEmail",
-      "required": true
-    },
-
-    // Calculate value from multiple source fields
-    "totalWeight": {
-      "resolver": "custom.calculateTotalWeight",
-      "required": true
-    },
-
-    // Apply complex business rules
-    "fulfillmentType": {
-      "resolver": "custom.determineFulfillmentType",
-      "required": true
-    }
-  }
-}
-```
-
-**❌ Avoid for simple transformations:**
-
-```json
-{
-  "fields": {
-    // ❌ BAD - Use source + resolver instead
-    "uppercaseStatus": {
-      "resolver": "custom.getAndUppercaseStatus",
-      "required": true
-    },
-
-    // ✅ GOOD - Extract then transform
-    "status": {
-      "source": "orderStatus",
-      "resolver": "sdk.uppercase",
-      "required": true
-    }
-  }
-}
-```
-
----
-
-#### Complete Example: Product Ingestion
-
-```typescript
-import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-import { v4 as uuid } from 'uuid';
-
-// Mapping configuration
-const productMappingConfig = {
-  fields: {
-    // Resolver-only: Generate unique product ID
-    id: {
-      resolver: 'custom.generateProductId',
-      required: true,
-    },
-
-    // Source + resolver: Extract and transform
-    name: {
-      source: 'productName',
-      resolver: 'sdk.trim',
-      required: true,
-    },
-
-    sku: {
-      source: 'sku',
-      required: true,
-    },
-
-    // Resolver-only: Enrich with category data
-    category: {
-      resolver: 'custom.resolveCategoryFromSku',
-      required: false,
-    },
-
-    // Static value
-    type: {
-      value: 'STANDARD',
-      required: true,
-    },
-  },
-};
-
-// Custom resolvers
-const customResolvers = {
-  'custom.generateProductId': (value, sourceData, config, helpers) => {
-    const sku = helpers.get(sourceData, 'sku');
-    const retailerId = config.retailerId;
-    return `${retailerId}-${sku}-${uuid()}`;
-  },
-
-  'custom.resolveCategoryFromSku': async (value, sourceData, config, helpers) => {
-    const sku = helpers.get(sourceData, 'sku');
-
-    // Lookup category from SKU prefix
-    const prefix = sku.substring(0, 3);
-    const categoryMap = {
-      'ELE': 'Electronics',
-      'CLO': 'Clothing',
-      'FOO': 'Food',
-    };
-
-    return categoryMap[prefix] || 'General';
-  },
-};
-
-// Create mapper with custom resolvers
-const mapper = new UniversalMapper(
-  productMappingConfig,
-  {
-    customResolvers,
-    context: { retailerId: '1' },
-    logger: console,
-  }
-);
-
-// Map product data
-const sourceData = {
-  sku: 'ELE-12345',
-  productName: '  Wireless Mouse  ',
-};
-
-const result = await mapper.map(sourceData);
-
-console.log(result);
-// {
-//   success: true,
-//   data: {
-//     id: '1-ELE-12345-a1b2c3d4-...',
-//     name: 'Wireless Mouse',
-//     sku: 'ELE-12345',
-//     category: 'Electronics',
-//     type: 'STANDARD'
-//   }
-// }
-```
-
----
-
-#### Required Validation Error Messages
-
-**Resolver-only field returns empty:**
-
-```typescript
-// If resolver returns null/undefined/''
-{
-  success: false,
-  data: null,
-  errors: [
-    "Failed to map field 'id': Required field 'id' is missing or empty after resolver 'custom.generateId' execution"
-  ]
-}
-```
-
-**Source-based required field missing:**
-
-```typescript
-// If source field is missing
-{
-  success: false,
-  data: null,
-  errors: [
-    "Failed to map field 'sku': Required field 'sku' is missing or empty (source: sku)"
-  ]
-}
-```
-
----
-
-#### Testing Resolver-Only Required Fields
-
-```typescript
-import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-
-describe('Resolver-only required fields', () => {
-  it('should pass validation when resolver returns value', async () => {
-    const mapper = new UniversalMapper(
-      {
-        fields: {
-          id: {
-            resolver: 'custom.generateId',
-            required: true,
-          },
-        },
-      },
-      {
-        customResolvers: {
-          'custom.generateId': () => 'generated-id-123',
-        },
-      }
-    );
-
-    const result = await mapper.map({});
-
-    expect(result.success).toBe(true);
-    expect(result.data.id).toBe('generated-id-123');
-  });
-
-  it('should fail validation when resolver returns empty', async () => {
-    const mapper = new UniversalMapper(
-      {
-        fields: {
-          id: {
-            resolver: 'custom.generateId',
-            required: true,
-          },
-        },
-      },
-      {
-        customResolvers: {
-          'custom.generateId': () => null, // Returns empty
-        },
-      }
-    );
-
-    const result = await mapper.map({});
-
-    expect(result.success).toBe(false);
-    expect(result.errors[0]).toContain('Required field');
-  });
-});
-```
-
----
-
-📖 **Learn more:** [Performance Best Practices](./mapping-resolvers-resolver-cookbook.md#performance-optimization)
-
----
-
-## Reference Documentation
-
-### 📘 Detailed References
-
-| Document                                                      | Description                                          |
-| ------------------------------------------------------------- | ---------------------------------------------------- |
-| [Resolver API Reference](./mapping-resolvers-resolver-api-reference.md)         | Complete ResolverBuilder API documentation           |
-| [Helper Functions Reference](./mapping-resolvers-resolver-helpers-reference.md) | All 54 helper functions with examples                |
-| [Parameters Deep Dive](./mapping-resolvers-resolver-parameters-reference.md)    | Detailed explanation of value, data, config, helpers |
-| [Troubleshooting Guide](./mapping-resolvers-resolver-troubleshooting.md)        | Common issues and solutions                          |
-| [Cookbook](./mapping-resolvers-resolver-cookbook.md)                            | Advanced patterns and recipes                        |
-
-### 🧪 Test Examples
-
-All examples are validated with automated tests:
-
-```bash
-cd fc-connect-sdk
-npm test -- examples/__tests__/resolver-guide-examples.test.ts
-```
-
-📁 **Example Files:**
-
-- [Resolver Examples](../examples/)
-- [Order Test Data](../../../03-PATTERN-GUIDES/examples/test-data/canonical-order.json)
-- [Inventory Test Data](../../../03-PATTERN-GUIDES/examples/test-data/canonical-inventory.json)
-
----
-
-## Best Practices Summary
-
-### ✅ Do's
-
-1. **Organize by domain** - Group related resolvers (order, customer, inventory)
-2. **Use config for defaults** - Never hardcode environment-specific values
-3. **Validate critical fields** - Use `.validate()` for required fields
-4. **Use helper functions** - Don't reinvent the wheel
-5. **Handle arrays gracefully** - Use `ensureArray()` and `mapArray()`
-6. **Log important decisions** - Help with debugging
-7. **Test in isolation** - Write unit tests for resolvers
-8. **Use TypeScript types** - Leverage type safety
-
-### ❌ Don'ts
-
-1. **Don't hardcode values** - Use config instead
-2. **Don't skip validation** - Validate required fields
-3. **Don't ignore errors** - Handle async failures gracefully
-4. **Don't forget to await** - Async resolvers must be awaited
-5. **Don't assume array structure** - XML can return object for single item
-6. **Don't skip logging** - Log for production debugging
-7. **Don't write untested code** - Test with canonical data
-
----
-
-## Next Steps
-
-### 🎓 Continue Learning
-
-1. **Beginner (30 min):**
-   - ✅ Completed Quick Start
-   - 📖 Read [Resolver Parameters](./mapping-resolvers-resolver-parameters-reference.md)
-   - 🧪 Test examples with canonical data
-
-2. **Intermediate (2 hours):**
-   - 📖 Read [API Reference](./mapping-resolvers-resolver-api-reference.md)
-   - 💻 Build resolvers for your use case
-   - 🧪 Write tests for your resolvers
-
-3. **Advanced (4 hours):**
-   - 📖 Read [Cookbook](./mapping-resolvers-resolver-cookbook.md)
-   - 🌐 Add async API calls
-   - 🚀 Deploy to production
-
-### 🆘 Get Help
-
-- **GitHub Issues:** https://github.com/fluentcommerce/fc-connect-sdk/issues
-- **Documentation:** https://docs.fluentcommerce.com
-- **Email:** support@fluentcommerce.com
-
----
-
-**Document Version:** 2.0.0
-**SDK Version:** 1.5.0+
-**Last Updated:** 2025-01-14
-
----
-
-**License:** MIT
-**Copyright:** © 2025 Fluent Commerce
+# Resolver Pattern Guide
+
+**FC Connect SDK - Transform Data with Custom Logic**
+
+Version: 2.0.0
+Last Updated: 2025-01-14
+
+---
+
+## 📚 Table of Contents
+
+1. [Quick Start (5 Minutes)](#quick-start-5-minutes)
+2. [Core Concepts](#core-concepts)
+3. [Real-World Examples](#real-world-examples)
+4. [Advanced Topics](#advanced-topics)
+   - [Async Operations & API Calls](#async-operations--api-calls)
+   - [Error Handling Patterns](#error-handling-patterns)
+   - [Performance Optimization](#performance-optimization)
+   - [Resolver-Only Fields & Required Validation](#resolver-only-fields--required-validation) ← NEW
+5. [Reference Documentation](#reference-documentation)
+
+---
+
+## 🎯 What You'll Learn
+
+By the end of this guide, you'll be able to:
+
+✅ Write custom resolver functions for complex transformations
+✅ Use the ResolverBuilder API for clean, maintainable code
+✅ Handle order management and inventory data transformations
+✅ Work with async operations (API calls, database lookups)
+✅ Apply best practices for production-ready resolvers
+
+**Time to Complete:** 30 minutes to 2 hours (depending on depth)
+
+---
+
+## Quick Start (5 Minutes)
+
+### What are Resolvers?
+
+**Resolvers** are custom JavaScript functions that transform source data into the format required by Fluent Commerce. They're your solution when JSON mapping isn't enough.
+
+**Use resolvers when you need:**
+
+- 🧮 Complex calculations (totals, aggregations, formulas)
+- 🔀 Conditional logic (if-then-else transformations)
+- 🌐 External API calls (customer lookup, price checks)
+- 🔄 Cross-referencing data (resolve IDs to full objects)
+- ♻️ Reusable transformation logic
+
+---
+
+### Your First Resolver
+
+Let's transform an order from our e-commerce system to Fluent Commerce.
+
+**Step 1: Install the SDK**
+
+```bash
+npm install @fluentcommerce/fc-connect-sdk
+```
+
+**Step 2: Create Your First Resolver**
+
+```typescript
+import { createResolverBuilder, ResolverHelpers } from '@fluentcommerce/fc-connect-sdk';
+
+// Create a builder instance
+const builder = createResolverBuilder();
+
+// Define your resolvers
+const resolvers = builder
+  // Simple field mapping: Extract order reference
+  .from('input.ref', 'orders.order@order-no')
+
+  // With transformation: Parse price to number
+  .from('input.totalPrice', 'orders.order.totals.order-total.gross-price', value =>
+    parseFloat(value)
+  )
+
+  // Build the resolver map
+  .build();
+
+export default resolvers;
+```
+
+**Step 3: Use in Your Workflow**
+
+```typescript
+import { http } from '@versori/run';
+import { createClient, XMLParserService, ResolverHelpers } from '@fluentcommerce/fc-connect-sdk';
+import resolvers from './resolvers';
+
+// Versori workflow - ctx comes from workflow parameter
+export default http('processOrder', async (ctx) => {  // ← ctx defined here!
+  const { log, activation, fetch } = ctx;
+
+  // 1. Parse input XML
+  const parser = new XMLParserService(log);
+  const orderData = await parser.parseFromString(activation.body);
+
+  // 2. Apply resolvers
+  const config = {
+    defaultRetailerId: activation.getVariable('RETAILER_ID'),
+    apiToken: activation.getVariable('API_TOKEN')
+  };
+
+  const transformedData = {};
+  for (const [path, resolver] of Object.entries(resolvers)) {
+    const value = await resolver(orderData, config, ResolverHelpers, ctx);
+    setNestedValue(transformedData, path, value);
+  }
+
+  // 3. Send to Fluent Commerce
+  const client = await createClient({ ...ctx, log });
+
+  const result = await client.graphql({
+    query: `mutation CreateOrder($input: CreateOrderInput!) {
+      createOrder(input: $input) { id ref }
+    }`,
+    variables: { input: transformedData },
+  });
+
+  return { success: true, data: result };
+});
+
+function setNestedValue(obj: any, path: string, value: any) {
+  const keys = path.split('.');
+  let current = obj;
+  for (let i = 0; i < keys.length - 1; i++) {
+    current[keys[i]] = current[keys[i]] || {};
+    current = current[keys[i]];
+  }
+  current[keys[keys.length - 1]] = value;
+}
+```
+
+**🎉 That's it!** You've created and executed your first resolver.
+
+---
+
+### Test Your Resolver
+
+Use our canonical test data to verify your resolver works:
+
+```typescript
+import { canonicalOrder } from '../../../03-PATTERN-GUIDES/examples/test-data/canonical-order.json';
+import { ResolverHelpers } from '@fluentcommerce/fc-connect-sdk';
+
+// Test the resolver
+const result = resolvers\['input.ref'](canonicalOrder, {}, ResolverHelpers);
+console.log(result); // Expected: "ORD-2025-001"
+```
+
+✅ **Expected Output:** `"ORD-2025-001"`
+
+📖 **See:** [Complete test data structure](../../../03-PATTERN-GUIDES/examples/test-data/) for resolver testing examples
+
+---
+
+## Core Concepts
+
+### JSON Mapping vs Resolvers
+
+**Use JSON Mapping when:**
+
+- Simple field-to-field mapping
+- Standard transformations (toString, toNumber)
+- Static data structures
+
+```json
+{
+  "ref": { "source": "order.orderNo" },
+  "totalPrice": { "source": "order.total", "resolver": "sdk.number" }
+}
+```
+
+**Use Resolvers when:**
+
+- Complex calculations or business logic
+- Conditional transformations
+- External API calls
+- Multiple source aggregation
+
+```typescript
+builder.field('input.totalDiscount', (data, config, helpers) => {
+  // Calculate from multiple sources
+  const itemDiscounts = helpers.sum(data.order.items, 'discount');
+  const couponValue = helpers.get(data, 'order.coupon.value', 0);
+  return itemDiscounts + couponValue;
+});
+```
+
+---
+
+### The Four Resolver Parameters
+
+Every resolver receives four parameters:
+
+```typescript
+type ResolverFunction = (
+  value: unknown, // Extracted value from 'source' path
+  data: unknown, // Full data context (includes named nodes)
+  config: unknown, // Configuration object
+  helpers: Helpers // Utility functions
+) => unknown | Promise<unknown>;
+```
+
+**You don't have to use all four** - just what you need!
+
+---
+
+#### 1. `value` - The Extracted Value
+
+**What:** The value extracted from the `source` path in your mapping.
+
+**When defined:** When your field has a `source` property
+**When undefined:** When your field only has a `resolver` (resolver-only field)
+
+**Example: Using `value` from source**
+
+```typescript
+// Mapping config
+{
+  "ref": {
+    "source": "orders.order@order-no",
+    "resolver": "custom.addPrefix"
+  }
+}
+
+// Resolver
+'custom.addPrefix': (value, data, config, helpers) => {
+  // value = "ORD-2025-001" (extracted from source)
+  return `ORDER-${value}`;
+  // Returns: "ORDER-ORD-2025-001"
+}
+```
+
+**Example: Resolver-only (no source)**
+
+```typescript
+// Mapping config (NO source!)
+{
+  "totalDiscount": {
+    "resolver": "custom.calculateTotalDiscount"
+  }
+}
+
+// Resolver
+'custom.calculateTotalDiscount': (value, data, config, helpers) => {
+  // value = undefined (no source specified)
+  // Use 'data' to access full context
+  const items = helpers.get(data, 'orders.order.product-lineitems.product-lineitem', []);
+  return helpers.sum(helpers.ensureArray(items), item =>
+    helpers.parseFloatSafe(item['base-price'], 0) - helpers.parseFloatSafe(item['net-price'], 0)
+  );
+}
+```
+
+**Important: Required Fields with Resolvers**
+
+When using `required: true` with resolvers, validation timing depends on whether the field has a `source`:
+
+**Fields with `source`**: Validation happens **before** resolver execution
+```json
+{
+  "discount": {
+    "source": "order.subtotal",
+    "resolver": "custom.calculateDiscount",
+    "required": true
+  }
+}
+```
+- ✅ Checks if `order.subtotal` 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
+{
+  "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
+
+**Why this matters:** 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.
+
+📖 **Learn more:** [Resolver Parameters Deep Dive](./mapping-resolvers-resolver-parameters-reference.md)
+
+---
+
+#### 2. `data` - Full Data Context
+
+**What:** The complete data object, including all named nodes from your mapping config.
+
+**When to use:** When you need to access data from different parts of your payload or from named nodes.
+
+**Example: Accessing order data**
+
+```typescript
+builder.field('input.customer.email', (data, config, helpers) => {
+  // Access nested data safely
+  return helpers.get(data, 'orders.order.customer.customer-email');
+});
+```
+
+**Example: Using named nodes**
+
+Named nodes let you parse embedded XML/JSON within your payload:
+
+```json
+{
+  "nodes": {
+    "radialXml": {
+      "extract": "orders.order.custom-attributes.custom-attribute[attribute-id=RadialData]",
+      "parse": "xml"
+    }
+  }
+}
+```
+
+```typescript
+builder.field('input.specialInstructions', (data, config, helpers) => {
+  // 'data' now contains both original data AND parsed nodes
+  // data = {
+  //   orders: { ... original data ... },
+  //   radialXml: { ... parsed XML ... }
+  // }
+
+  const radialData = data.radialXml;
+  return helpers.get(radialData, 'Order.SpecialInstructions.Text');
+});
+```
+
+---
+
+#### 3. `config` - Configuration Object
+
+**What:** Settings and defaults passed when executing resolvers.
+
+**When to use:** For environment-specific values, defaults, or API credentials.
+
+**Example: Config with fallbacks**
+
+```typescript
+// Standalone Pattern
+const config = {
+  defaultRetailerId: '1',
+  defaultCurrency: 'USD',
+  apiToken: process.env.EXTERNAL_API_TOKEN,
+};
+
+// Versori Platform Pattern
+const config = {
+  defaultRetailerId: activation.getVariable('FLUENT_RETAILER_ID'),
+  defaultCurrency: activation.getVariable('DEFAULT_CURRENCY') || 'USD',
+  // Credentials accessed via ctx.credentials() in resolver
+};
+
+builder.withConfigFallback(
+  'input.retailer.id',
+  'orders.order.retailerId',
+  'defaultRetailerId' // Fallback key in config
+);
+```
+
+**Versori Credential Access in Resolvers:**
+
+```typescript
+// Use in async resolver for external API calls
+builder.field('input.enrichedData', async (data, config, helpers, ctx) => {
+  // Option 1: Get from activation variables
+  const apiToken = ctx.activation.getVariable('EXTERNAL_API_TOKEN');
+
+  // Option 2: Get from connection credentials
+  const apiCreds = await ctx.credentials().getAccessToken('external_api');
+
+  const response = await ctx.fetch('https://api.example.com/enrich', {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${apiCreds?.accessToken || apiToken}`,
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify(data)
+  });
+
+  return response.json();
+});
+```
+
+---
+
+#### 4. `helpers` - Utility Functions
+
+**What:** Collection of 54 helper functions for common transformations.
+
+**Available helpers:**
+
+- **Data access:** `get()`, `ensureArray()`
+- **Parsing:** `parseFloatSafe()`, `parseIntSafe()`, `safeJsonParse()`
+- **Formatting:** `formatDate()`, `formatCurrency()`
+- **Arrays:** `sum()`, `avg()`, `groupBy()`, `chunk()`, `flatten()`
+- **Strings:** `slugify()`, `template()`, `truncate()`
+- **Validation:** `isValidEmail()`, `requireField()`
+- **Async:** `retry()`, `batchProcess()`
+
+**Example: Using helpers**
+
+```typescript
+builder.field('input.items', (data, config, helpers) => {
+  // Safe path access
+  const items = helpers.get(data, 'orders.order.product-lineitems.product-lineitem');
+
+  // Handle XML single vs array
+  const itemsArray = helpers.ensureArray(items);
+
+  // Transform with safe parsing
+  return itemsArray.map(item => ({
+    ref: item['@lineitem-id'],
+    quantity: helpers.parseIntSafe(item.quantity, 1),
+    price: helpers.parseFloatSafe(item['base-price'], 0),
+  }));
+});
+```
+
+📖 **See all helpers:** [Resolver Helpers Reference](./mapping-resolvers-resolver-helpers-reference.md)
+
+---
+
+## Real-World Examples
+
+All examples use our **canonical datasets** for consistency. You can test every example!
+
+📁 **Test Data:**
+
+- [canonical-order.json](../../../03-PATTERN-GUIDES/examples/test-data/canonical-order.json) - Order management
+- [canonical-inventory.json](../../../03-PATTERN-GUIDES/examples/test-data/canonical-inventory.json) - Inventory management
+
+---
+
+### Example 1: Order Management - Simple Transformation
+
+**Scenario:** Extract basic order fields from SFCC-style XML.
+
+**Source Data:** See [canonical-order.json](../../../03-PATTERN-GUIDES/examples/test-data/canonical-order.json)
+
+**Goal:** Create Fluent Commerce order input with ref, totalPrice, and customer.
+
+```typescript
+import { createResolverBuilder } from '@fluentcommerce/fc-connect-sdk';
+
+const builder = createResolverBuilder();
+
+export const orderResolvers = builder
+  // Extract order reference (required field)
+  .validate(
+    'input.ref',
+    (data, config, helpers) => helpers.get(data, 'orders.order@order-no'),
+    value => !!value || 'Order reference is required'
+  )
+
+  // Parse total price to number
+  .from('input.totalPrice', 'orders.order.totals.order-total.gross-price', value =>
+    parseFloat(value)
+  )
+
+  // Extract customer email
+  .from('input.customer.email', 'orders.order.customer.customer-email')
+
+  .build();
+```
+
+**Test it:**
+
+```typescript
+import { canonicalOrder } from '../../../03-PATTERN-GUIDES/examples/test-data/canonical-order.json';
+import { ResolverHelpers } from '@fluentcommerce/fc-connect-sdk';
+
+const result = {
+  ref: orderResolvers\['input.ref'](canonicalOrder, {}, ResolverHelpers),
+  totalPrice: orderResolvers\['input.totalPrice'](canonicalOrder, {}, ResolverHelpers),
+  customer: {
+    email: orderResolvers\['input.customer.email'](canonicalOrder, {}, ResolverHelpers),
+  },
+};
+
+console.log(result);
+// Expected:
+// {
+//   ref: "ORD-2025-001",
+//   totalPrice: 151.17,
+//   customer: { email: "john.doe@example.com" }
+// }
+```
+
+✅ **Expected Output:**
+
+```json
+{
+  "ref": "ORD-2025-001",
+  "totalPrice": 151.17,
+  "customer": { "email": "john.doe@example.com" }
+}
+```
+
+---
+
+### Example 2: Order Management - Array Mapping
+
+**Scenario:** Transform line items array with quantity and price calculations.
+
+```typescript
+export const itemResolvers = builder
+  .mapArray(
+    'input.items',
+    'orders.order.product-lineitems.product-lineitem',
+    (item, index, config, helpers) => ({
+      ref: item['@lineitem-id'] || `ITEM-${index + 1}`,
+      productRef: item['product-id'],
+      quantity: helpers.parseIntSafe(item.quantity, 1),
+      price: helpers.parseFloatSafe(item['base-price'], 0),
+      totalPrice: helpers.parseFloatSafe(item['gross-price'], 0),
+
+      attributes: {
+        productName: item['product-name'],
+        position: helpers.parseIntSafe(item.position, index + 1),
+        taxAmount: helpers.parseFloatSafe(item.tax, 0),
+      },
+    })
+  )
+  .build();
+```
+
+**Test it:**
+
+```typescript
+const items = itemResolvers\['input.items'](canonicalOrder, {}, ResolverHelpers);
+console.log(items);
+```
+
+✅ **Expected Output:**
+
+```json
+[
+  {
+    "ref": "ITEM-001",
+    "productRef": "SKU-WM-001",
+    "quantity": 2,
+    "price": 29.99,
+    "totalPrice": 64.78,
+    "attributes": {
+      "productName": "Wireless Mouse",
+      "position": 1,
+      "taxAmount": 4.8
+    }
+  },
+  {
+    "ref": "ITEM-002",
+    "productRef": "SKU-KB-001",
+    "quantity": 1,
+    "price": 79.99,
+    "totalPrice": 86.39,
+    "attributes": {
+      "productName": "Mechanical Keyboard",
+      "position": 2,
+      "taxAmount": 6.4
+    }
+  }
+]
+```
+
+---
+
+### Example 3: Inventory Management - Batch Ingestion
+
+**Scenario:** Transform WMS inventory data to Fluent Commerce batch format.
+
+**Source Data:** See [canonical-inventory.json](../../../03-PATTERN-GUIDES/examples/test-data/canonical-inventory.json)
+
+```typescript
+export const inventoryResolvers = builder
+  // Extract location ID
+  .from('input.locationId', 'inventory.header.location-id')
+
+  // Transform inventory items array
+  .mapArray('input.entities', 'inventory.items', (item, index, config, helpers) => ({
+    skuRef: item.sku,
+    locationRef: item.location.id,
+    qty: helpers.parseIntSafe(item.quantity['on-hand'], 0),
+
+    // Optional: Add expected delivery date
+    expectedOn: helpers.get(item, 'dates.next-expected-receipt')
+      ? new Date(item['dates']['next-expected-receipt']).toISOString()
+      : null,
+
+    attributes: {
+      available: helpers.parseIntSafe(item.quantity.available, 0),
+      reserved: helpers.parseIntSafe(item.quantity.reserved, 0),
+      inTransit: helpers.parseIntSafe(item.quantity['in-transit'], 0),
+      binLocation: item.attributes['bin-location'],
+      lotNumber: item.attributes['lot-number'],
+    },
+  }))
+
+  .build();
+```
+
+**Test it:**
+
+```typescript
+import { canonicalInventory } from '../../../03-PATTERN-GUIDES/examples/test-data/canonical-inventory.json';
+
+const result = {
+  locationId: inventoryResolvers\['input.locationId'](canonicalInventory, {}, ResolverHelpers),
+  entities: inventoryResolvers\['input.entities'](canonicalInventory, {}, ResolverHelpers),
+};
+
+console.log(result.entities[0]);
+```
+
+✅ **Expected Output:**
+
+```json
+{
+  "skuRef": "SKU-WM-001",
+  "locationRef": "WH-001",
+  "qty": 250,
+  "expectedOn": "2025-01-20T00:00:00.000Z",
+  "attributes": {
+    "available": 200,
+    "reserved": 50,
+    "inTransit": 100,
+    "binLocation": "A-12-03",
+    "lotNumber": "LOT-2025-001"
+  }
+}
+```
+
+---
+
+### Example 4: Complex Calculation - Total Discount
+
+**Scenario:** Calculate total discount from multiple sources (item discounts + promotions).
+
+```typescript
+builder.calculate('input.totalDiscount', (data, helpers) => {
+  // Get line items
+  const items = helpers.ensureArray(
+    helpers.get(data, 'orders.order.product-lineitems.product-lineitem', [])
+  );
+
+  // Calculate item-level discounts
+  const itemDiscounts = items.reduce((sum, item) => {
+    const basePrice = helpers.parseFloatSafe(item['base-price'], 0);
+    const netPrice = helpers.parseFloatSafe(item['net-price'], 0);
+    const quantity = helpers.parseIntSafe(item.quantity, 1);
+    return sum + (basePrice - netPrice) * quantity;
+  }, 0);
+
+  // Add order-level adjustment (if negative, it's a discount)
+  const adjustment = helpers.parseFloatSafe(
+    helpers.get(data, 'orders.order.totals.adjustment-total.gross-price'),
+    0
+  );
+
+  const orderDiscount = adjustment < 0 ? Math.abs(adjustment) : 0;
+
+  const totalDiscount = itemDiscounts + orderDiscount;
+
+  helpers.log?.info('Calculated total discount', {
+    itemDiscounts,
+    orderDiscount,
+    totalDiscount,
+  });
+
+  return helpers.formatCurrency(totalDiscount, 2);
+});
+```
+
+**Test it:**
+
+```typescript
+const discount = resolvers\['input.totalDiscount'](canonicalOrder, {}, ResolverHelpers);
+console.log(discount); // Expected: "14.00" (from adjustment-total in canonical data)
+```
+
+---
+
+### Example 5: Conditional Mapping - Order Type
+
+**Scenario:** Map channel type to Fluent order type with business rules.
+
+```typescript
+builder.field('input.type', (data, config, helpers) => {
+  const channelType = helpers.get(data, 'orders.order.channel-type');
+  const isGift = helpers.get(data, 'orders.order.shipments.shipment.gift') === 'true';
+
+  // Channel to order type mapping
+  const channelMapping = {
+    Storefront: 'HD',
+    CallCenter: 'CC',
+    Mobile: 'MOBILE',
+    POS: 'STORE',
+  };
+
+  let orderType = helpers.mapValue(channelType, channelMapping, config.defaultOrderType || 'HD');
+
+  // Business rule: Gift orders get special type
+  if (isGift && orderType === 'HD') {
+    orderType = 'GIFT_HD';
+  }
+
+  helpers.log?.debug('Mapped order type', { channelType, isGift, orderType });
+
+  return orderType;
+});
+```
+
+**Test it:**
+
+```typescript
+const orderType = resolvers`'input.type'`;
+console.log(orderType); // Expected: "HD" (Storefront channel)
+```
+
+---
+
+## Advanced Topics
+
+### Async Operations & API Calls
+
+Resolvers can be async to call external APIs or perform lookups.
+
+**Example: Customer Lookup**
+
+```typescript
+builder.field('input.customer.id', async (data, config, helpers) => {
+  const customerId = helpers.get(data, 'orders.order.customer.customer-no');
+
+  if (!helpers.fluentClient) {
+    throw new Error('FluentClient is required for customer lookup');
+  }
+
+  // Use retry helper for resilience
+  return await helpers.retry(
+    async () => {
+      // Query for existing customer
+      const result = await helpers.fluentClient.graphql({
+        query: `
+          query GetCustomer($username: [String]) {
+            customers(username: $username, first: 1) {
+              edges {
+                node { id username }
+              }
+            }
+          }
+        `,
+        variables: { username: [customerId] },
+      });
+
+      const existing = result.data?.customers?.edges?.[0]?.node;
+
+      if (existing) {
+        helpers.log?.info('Found existing customer', { id: existing.id });
+        return existing.id;
+      }
+
+      // Create new customer if not found
+      helpers.log?.info('Creating new customer', { customerId });
+      const createResult = await helpers.fluentClient.graphql({
+        query: `
+          mutation CreateCustomer($input: CreateCustomerInput!) {
+            createCustomer(input: $input) { id }
+          }
+        `,
+        variables: {
+          input: {
+            username: customerId,
+            retailer: { id: config.defaultRetailerId },
+          },
+        },
+      });
+
+      return createResult.data?.createCustomer?.id;
+    },
+    3, // Retry 3 times
+    500 // 500ms delay
+  );
+});
+```
+
+**Best Practices for Async Resolvers:**
+
+1. ✅ **Always use error handling**
+2. ✅ **Use `helpers.retry()` for transient failures**
+3. ✅ **Add timeout protection**
+4. ✅ **Log API calls for debugging**
+5. ✅ **Cache results when possible**
+
+📖 **Learn more:** [Async Patterns Cookbook](./mapping-resolvers-resolver-cookbook.md#async-patterns)
+
+---
+
+### Error Handling Patterns
+
+**Pattern 1: Validation with Custom Errors**
+
+```typescript
+builder.validate(
+  'input.totalPrice',
+  (data, config, helpers) => {
+    const price = helpers.get(data, 'orders.order.totals.order-total.gross-price');
+    return helpers.parseFloatSafe(price, 0);
+  },
+  value => value > 0 || 'Total price must be greater than zero'
+);
+```
+
+**Pattern 2: Try-Catch with Fallbacks**
+
+```typescript
+builder.field('input.customAttribute', (data, config, helpers) => {
+  try {
+    const attrs = helpers.get(data, 'orders.order.custom-attributes.custom-attribute');
+    return helpers.extractCustomAttribute(attrs, 'specialValue');
+  } catch (error) {
+    helpers.log?.warn('Failed to extract custom attribute', { error });
+    return config.defaultSpecialValue || null;
+  }
+});
+```
+
+📖 **Learn more:** [Error Handling Guide](./mapping-resolvers-resolver-troubleshooting.md#error-patterns)
+
+---
+
+### Performance Optimization
+
+**1. Memoize Expensive Calculations**
+
+```typescript
+import { ResolverHelpers } from '@fluentcommerce/fc-connect-sdk';
+
+const calculateComplexDiscount = ResolverHelpers.memoize((items, discountRules) => {
+  // Expensive calculation cached by input
+  return items.reduce((total, item) => {
+    return total + applyDiscountRules(item, discountRules);
+  }, 0);
+});
+
+builder.field('input.discount', (data, config, helpers) => {
+  const items = helpers.get(data, 'orders.order.product-lineitems.product-lineitem', []);
+  return calculateComplexDiscount(items, config.discountRules);
+});
+```
+
+**2. Parallel Async Operations**
+
+```typescript
+// ❌ Sequential (slow)
+const customer = await lookupCustomer(customerId);
+const inventory = await checkInventory(sku);
+const pricing = await getPricing(sku);
+
+// ✅ Parallel (fast)
+const [customer, inventory, pricing] = await Promise.all([
+  lookupCustomer(customerId),
+  checkInventory(sku),
+  getPricing(sku),
+]);
+```
+
+**3. Batch Processing**
+
+```typescript
+builder.field('input.enrichedItems', async (data, config, helpers) => {
+  const items = helpers.get(data, 'orders.order.product-lineitems.product-lineitem', []);
+
+  // Process in batches of 10
+  return await helpers.batchProcess(
+    items,
+    async item => {
+      // Enrich each item with external data
+      const details = await fetchProductDetails(item['product-id']);
+      return { ...item, ...details };
+    },
+    10 // Batch size
+  );
+});
+```
+
+📖 **Learn more:** [Performance Best Practices](./mapping-resolvers-resolver-cookbook.md#performance-optimization)
+
+---
+
+### Resolver-Only Fields & Required Validation
+
+**New in SDK v0.1.37:** Required validation for resolver-only fields (fields without a source).
+
+**What are resolver-only fields?**
+
+Resolver-only fields are fields that don't extract data from a source path, but instead generate values programmatically using a resolver function.
+
+**Use cases:**
+
+1. **Generate unique IDs** - Create UUIDs or composite keys
+2. **Derive values** - Calculate from other fields in the data
+3. **Enrich with external data** - Look up values from APIs without a source field
+4. **Apply business logic** - Determine values based on complex rules
+
+---
+
+#### UniversalMapper Configuration
+
+**Example: Generate ID without source**
+
+```json
+{
+  "fields": {
+    "id": {
+      "resolver": "custom.generateProductId",
+      "required": true
+    },
+    "name": {
+      "source": "productName",
+      "required": true
+    },
+    "enrichedData": {
+      "resolver": "custom.enrichFromAPI",
+      "required": false
+    }
+  }
+}
+```
+
+**Resolver implementation:**
+
+```typescript
+import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+import { v4 as uuid } from 'uuid';
+
+const customResolvers = {
+  // Generate UUID for each product (no source needed)
+  'custom.generateProductId': (value, sourceData, config, helpers) => {
+    // value is undefined (no source)
+    // Generate unique ID based on business logic
+    const sku = helpers.get(sourceData, 'sku');
+    const prefix = config.idPrefix || 'PROD';
+    return `${prefix}-${sku}-${uuid()}`;
+  },
+
+  // Enrich with external API data
+  'custom.enrichFromAPI': async (value, sourceData, config, helpers) => {
+    const sku = helpers.get(sourceData, 'sku');
+
+    try {
+      const response = await helpers.retry(async () => {
+        return await fetch(`https://api.example.com/products/${sku}`);
+      }, 3);
+
+      return await response.json();
+    } catch (error) {
+      helpers.log?.warn('Failed to enrich product', { sku, error });
+      return null; // Optional field, return null on failure
+    }
+  },
+};
+
+const mapper = new UniversalMapper(mappingConfig, { customResolvers });
+```
+
+---
+
+#### Validation Behavior
+
+**For resolver-only fields (`resolver` without `source`):**
+
+1. ✅ **No source extraction** - Value starts as `undefined`
+2. ✅ **Skip pre-validation** - Required validation does NOT run before resolver
+3. ✅ **Execute resolver** - Resolver generates the value
+4. ✅ **Post-validation** - Required validation runs AFTER resolver execution
+
+**For fields with source (`source` + `resolver`):**
+
+1. ✅ **Extract from source** - Value extracted from data
+2. ✅ **Validate required** - Required validation runs immediately
+3. ✅ **Execute resolver** - Resolver transforms the extracted value
+4. ✅ **No post-validation** - Required already validated before resolver
+
+---
+
+#### When to Use Resolver-Only Required
+
+**✅ Good use cases:**
+
+```json
+{
+  "fields": {
+    // Generate unique transaction ID
+    "transactionId": {
+      "resolver": "custom.generateTransactionId",
+      "required": true
+    },
+
+    // Look up customer ID by email from source
+    "customerId": {
+      "resolver": "custom.lookupCustomerByEmail",
+      "required": true
+    },
+
+    // Calculate value from multiple source fields
+    "totalWeight": {
+      "resolver": "custom.calculateTotalWeight",
+      "required": true
+    },
+
+    // Apply complex business rules
+    "fulfillmentType": {
+      "resolver": "custom.determineFulfillmentType",
+      "required": true
+    }
+  }
+}
+```
+
+**❌ Avoid for simple transformations:**
+
+```json
+{
+  "fields": {
+    // ❌ BAD - Use source + resolver instead
+    "uppercaseStatus": {
+      "resolver": "custom.getAndUppercaseStatus",
+      "required": true
+    },
+
+    // ✅ GOOD - Extract then transform
+    "status": {
+      "source": "orderStatus",
+      "resolver": "sdk.uppercase",
+      "required": true
+    }
+  }
+}
+```
+
+---
+
+#### Complete Example: Product Ingestion
+
+```typescript
+import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+import { v4 as uuid } from 'uuid';
+
+// Mapping configuration
+const productMappingConfig = {
+  fields: {
+    // Resolver-only: Generate unique product ID
+    id: {
+      resolver: 'custom.generateProductId',
+      required: true,
+    },
+
+    // Source + resolver: Extract and transform
+    name: {
+      source: 'productName',
+      resolver: 'sdk.trim',
+      required: true,
+    },
+
+    sku: {
+      source: 'sku',
+      required: true,
+    },
+
+    // Resolver-only: Enrich with category data
+    category: {
+      resolver: 'custom.resolveCategoryFromSku',
+      required: false,
+    },
+
+    // Static value
+    type: {
+      value: 'STANDARD',
+      required: true,
+    },
+  },
+};
+
+// Custom resolvers
+const customResolvers = {
+  'custom.generateProductId': (value, sourceData, config, helpers) => {
+    const sku = helpers.get(sourceData, 'sku');
+    const retailerId = config.retailerId;
+    return `${retailerId}-${sku}-${uuid()}`;
+  },
+
+  'custom.resolveCategoryFromSku': async (value, sourceData, config, helpers) => {
+    const sku = helpers.get(sourceData, 'sku');
+
+    // Lookup category from SKU prefix
+    const prefix = sku.substring(0, 3);
+    const categoryMap = {
+      'ELE': 'Electronics',
+      'CLO': 'Clothing',
+      'FOO': 'Food',
+    };
+
+    return categoryMap[prefix] || 'General';
+  },
+};
+
+// Create mapper with custom resolvers
+const mapper = new UniversalMapper(
+  productMappingConfig,
+  {
+    customResolvers,
+    context: { retailerId: '1' },
+    logger: console,
+  }
+);
+
+// Map product data
+const sourceData = {
+  sku: 'ELE-12345',
+  productName: '  Wireless Mouse  ',
+};
+
+const result = await mapper.map(sourceData);
+
+console.log(result);
+// {
+//   success: true,
+//   data: {
+//     id: '1-ELE-12345-a1b2c3d4-...',
+//     name: 'Wireless Mouse',
+//     sku: 'ELE-12345',
+//     category: 'Electronics',
+//     type: 'STANDARD'
+//   }
+// }
+```
+
+---
+
+#### Required Validation Error Messages
+
+**Resolver-only field returns empty:**
+
+```typescript
+// If resolver returns null/undefined/''
+{
+  success: false,
+  data: null,
+  errors: [
+    "Failed to map field 'id': Required field 'id' is missing or empty after resolver 'custom.generateId' execution"
+  ]
+}
+```
+
+**Source-based required field missing:**
+
+```typescript
+// If source field is missing
+{
+  success: false,
+  data: null,
+  errors: [
+    "Failed to map field 'sku': Required field 'sku' is missing or empty (source: sku)"
+  ]
+}
+```
+
+---
+
+#### Testing Resolver-Only Required Fields
+
+```typescript
+import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+
+describe('Resolver-only required fields', () => {
+  it('should pass validation when resolver returns value', async () => {
+    const mapper = new UniversalMapper(
+      {
+        fields: {
+          id: {
+            resolver: 'custom.generateId',
+            required: true,
+          },
+        },
+      },
+      {
+        customResolvers: {
+          'custom.generateId': () => 'generated-id-123',
+        },
+      }
+    );
+
+    const result = await mapper.map({});
+
+    expect(result.success).toBe(true);
+    expect(result.data.id).toBe('generated-id-123');
+  });
+
+  it('should fail validation when resolver returns empty', async () => {
+    const mapper = new UniversalMapper(
+      {
+        fields: {
+          id: {
+            resolver: 'custom.generateId',
+            required: true,
+          },
+        },
+      },
+      {
+        customResolvers: {
+          'custom.generateId': () => null, // Returns empty
+        },
+      }
+    );
+
+    const result = await mapper.map({});
+
+    expect(result.success).toBe(false);
+    expect(result.errors[0]).toContain('Required field');
+  });
+});
+```
+
+---
+
+📖 **Learn more:** [Performance Best Practices](./mapping-resolvers-resolver-cookbook.md#performance-optimization)
+
+---
+
+## Reference Documentation
+
+### 📘 Detailed References
+
+| Document                                                      | Description                                          |
+| ------------------------------------------------------------- | ---------------------------------------------------- |
+| [Resolver API Reference](./mapping-resolvers-resolver-api-reference.md)         | Complete ResolverBuilder API documentation           |
+| [Helper Functions Reference](./mapping-resolvers-resolver-helpers-reference.md) | All 54 helper functions with examples                |
+| [Parameters Deep Dive](./mapping-resolvers-resolver-parameters-reference.md)    | Detailed explanation of value, data, config, helpers |
+| [Troubleshooting Guide](./mapping-resolvers-resolver-troubleshooting.md)        | Common issues and solutions                          |
+| [Cookbook](./mapping-resolvers-resolver-cookbook.md)                            | Advanced patterns and recipes                        |
+
+### 🧪 Test Examples
+
+All examples are validated with automated tests:
+
+```bash
+cd fc-connect-sdk
+npm test -- examples/__tests__/resolver-guide-examples.test.ts
+```
+
+📁 **Example Files:**
+
+- [Resolver Examples](../examples/)
+- [Order Test Data](../../../03-PATTERN-GUIDES/examples/test-data/canonical-order.json)
+- [Inventory Test Data](../../../03-PATTERN-GUIDES/examples/test-data/canonical-inventory.json)
+
+---
+
+## Best Practices Summary
+
+### ✅ Do's
+
+1. **Organize by domain** - Group related resolvers (order, customer, inventory)
+2. **Use config for defaults** - Never hardcode environment-specific values
+3. **Validate critical fields** - Use `.validate()` for required fields
+4. **Use helper functions** - Don't reinvent the wheel
+5. **Handle arrays gracefully** - Use `ensureArray()` and `mapArray()`
+6. **Log important decisions** - Help with debugging
+7. **Test in isolation** - Write unit tests for resolvers
+8. **Use TypeScript types** - Leverage type safety
+
+### ❌ Don'ts
+
+1. **Don't hardcode values** - Use config instead
+2. **Don't skip validation** - Validate required fields
+3. **Don't ignore errors** - Handle async failures gracefully
+4. **Don't forget to await** - Async resolvers must be awaited
+5. **Don't assume array structure** - XML can return object for single item
+6. **Don't skip logging** - Log for production debugging
+7. **Don't write untested code** - Test with canonical data
+
+---
+
+## Next Steps
+
+### 🎓 Continue Learning
+
+1. **Beginner (30 min):**
+   - ✅ Completed Quick Start
+   - 📖 Read [Resolver Parameters](./mapping-resolvers-resolver-parameters-reference.md)
+   - 🧪 Test examples with canonical data
+
+2. **Intermediate (2 hours):**
+   - 📖 Read [API Reference](./mapping-resolvers-resolver-api-reference.md)
+   - 💻 Build resolvers for your use case
+   - 🧪 Write tests for your resolvers
+
+3. **Advanced (4 hours):**
+   - 📖 Read [Cookbook](./mapping-resolvers-resolver-cookbook.md)
+   - 🌐 Add async API calls
+   - 🚀 Deploy to production
+
+### 🆘 Get Help
+
+- **GitHub Issues:** https://github.com/fluentcommerce/fc-connect-sdk/issues
+- **Documentation:** https://docs.fluentcommerce.com
+- **Email:** support@fluentcommerce.com
+
+---
+
+**Document Version:** 2.0.0
+**SDK Version:** 1.5.0+
+**Last Updated:** 2025-01-14
+
+---
+
+**License:** MIT
+**Copyright:** © 2025 Fluent Commerce