@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

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

@@ -1,826 +1,826 @@
-# Resolver Cookbook
-
-**Advanced patterns and recipes for production resolvers**
-
-Version: 2.0.0
-Last Updated: 2025-01-14
-
----
-
-## Table of Contents
-
-1. [Async Patterns](#async-patterns)
-2. [Order Management Recipes](#order-management-recipes)
-3. [Inventory Management Recipes](#inventory-management-recipes)
-4. [Performance Optimization](#performance-optimization)
-5. [Error Handling](#error-handling)
-6. [Testing Patterns](#testing-patterns)
-
----
-
-## Async Patterns
-
-### Pattern 1: Lookup-or-Create Customer
-
-**Use Case:** Ensure customer exists before creating order.
-
-```typescript
-builder.field('input.customer.id', async (data, config, helpers) => {
-  const customerId = helpers.get(data, 'orders.order.customer.customer-no');
-  const email = helpers.get(data, 'orders.order.customer.customer-email');
-
-  if (!helpers.fluentClient) {
-    throw new Error('FluentClient is required for customer lookup');
-  }
-
-  return await helpers.retry(async () => {
-    // Step 1: Try to find existing customer
-    const queryResult = await helpers.fluentClient.graphql({
-      query: `
-        query GetCustomer($username: [String]) {
-          customers(username: $username, first: 1) {
-            edges {
-              node {
-                id
-                username
-                primaryEmail
-              }
-            }
-          }
-        }
-      `,
-      variables: { username: [customerId] }
-    });
-
-    const existing = queryResult.data?.customers?.edges?.[0]?.node;
-
-    if (existing) {
-      helpers.log?.info('Found existing customer', { id: existing.id });
-      return existing.id;
-    }
-
-    // Step 2: Create if not found
-    helpers.log?.info('Creating new customer', { customerId, email });
-
-    const createResult = await helpers.fluentClient.graphql({
-      query: `
-        mutation CreateCustomer($input: CreateCustomerInput!) {
-          createCustomer(input: $input) {
-            id
-            username
-          }
-        }
-      `,
-      variables: {
-        input: {
-          username: customerId,
-          primaryEmail: email,
-          retailer: { id: config.defaultRetailerId }
-        }
-      }
-    });
-
-    if (createResult.errors) {
-      throw new Error(`Failed to create customer: ${createResult.errors[0].message}`);
-    }
-
-    return createResult.data?.createCustomer?.id;
-  }, 3, 500);  // Retry 3 times, 500ms delay
-});
-```
-
----
-
-### Pattern 2: Parallel API Enrichment
-
-**Use Case:** Enrich order items with external data efficiently.
-
-```typescript
-builder.field('input.items', async (data, config, helpers) => {
-  const items = helpers.ensureArray(
-    helpers.get(data, 'orders.order.product-lineitems.product-lineitem')
-  );
-
-  // Fetch all product details in parallel
-  const enrichedItems = await Promise.all(
-    items.map(async (item) => {
-      // Run multiple lookups in parallel for each item
-      const [productDetails, inventory, pricing] = await Promise.all([
-        fetchProductDetails(item['product-id']),
-        checkInventory(item['product-id'], config.defaultLocationId),
-        getPricing(item['product-id'], config.priceTier)
-      ]);
-
-      return {
-        ref: item['@lineitem-id'],
-        productRef: item['product-id'],
-        quantity: helpers.parseIntSafe(item.quantity, 1),
-        price: helpers.parseFloatSafe(item['base-price'], 0),
-
-        // Enriched data
-        attributes: {
-          productName: productDetails.name,
-          category: productDetails.category,
-          availableQty: inventory.available,
-          currentPrice: pricing.currentPrice,
-          priceWas: pricing.previousPrice
-        }
-      };
-    })
-  );
-
-  return enrichedItems;
-});
-```
-
----
-
-### Pattern 3: Rate-Limited API Calls with Batch Processing
-
-**Use Case:** Process large item lists without overwhelming external APIs.
-
-```typescript
-builder.field('input.enrichedItems', async (data, config, helpers) => {
-  const items = helpers.ensureArray(
-    helpers.get(data, 'orders.order.product-lineitems.product-lineitem')
-  );
-
-  // Process in batches of 5 to respect API rate limits
-  const enrichedItems = await helpers.batchProcess(
-    items,
-    async (item, index) => {
-      try {
-        // Add delay to respect rate limits
-        await new Promise(resolve => setTimeout(resolve, 200));  // 5 req/sec
-
-        const productData = await helpers.retry(
-          async () => {
-            const response = await fetch(
-              `https://api.product-service.com/products/${item['product-id']}`,
-              {
-                headers: {
-                  'Authorization': `Bearer ${config.productApiToken}`
-                }
-              }
-            );
-
-            if (!response.ok) {
-              throw new Error(`API error: ${response.status}`);
-            }
-
-            return await response.json();
-          },
-          3,   // Max 3 retries
-          1000 // 1 second delay between retries
-        );
-
-        return {
-          ref: item['@lineitem-id'],
-          productRef: item['product-id'],
-          quantity: helpers.parseIntSafe(item.quantity, 1),
-          price: helpers.parseFloatSafe(item['base-price'], 0),
-          attributes: {
-            ...productData
-          }
-        };
-
-      } catch (error) {
-        helpers.log?.error(`Failed to enrich item ${item['@lineitem-id']}`, { error });
-
-        // Return basic item without enrichment
-        return {
-          ref: item['@lineitem-id'],
-          productRef: item['product-id'],
-          quantity: helpers.parseIntSafe(item.quantity, 1),
-          price: helpers.parseFloatSafe(item['base-price'], 0)
-        };
-      }
-    },
-    5  // Process 5 items at a time
-  );
-
-  return enrichedItems;
-});
-```
-
----
-
-## Order Management Recipes
-
-### Recipe 1: Multi-Source Total Calculation
-
-**Use Case:** Calculate order total from various sources with validation.
-
-```typescript
-builder.calculate('input.totalPrice', (data, helpers) => {
-  // Get line items
-  const items = helpers.ensureArray(
-    helpers.get(data, 'orders.order.product-lineitems.product-lineitem', [])
-  );
-
-  // Calculate merchandise total
-  const merchandiseTotal = helpers.sum(items, item =>
-    helpers.parseFloatSafe(item['gross-price'], 0)
-  );
-
-  // Get shipping total
-  const shippingTotal = helpers.parseFloatSafe(
-    helpers.get(data, 'orders.order.totals.shipping-total.gross-price'),
-    0
-  );
-
-  // Get tax total
-  const taxTotal = helpers.parseFloatSafe(
-    helpers.get(data, 'orders.order.totals.order-total.tax'),
-    0
-  );
-
-  // Get adjustments (discounts/fees)
-  const adjustment = helpers.parseFloatSafe(
-    helpers.get(data, 'orders.order.totals.adjustment-total.gross-price'),
-    0
-  );
-
-  // Calculate final total
-  const total = merchandiseTotal + shippingTotal + taxTotal + adjustment;
-
-  // Validation
-  if (total < 0) {
-    helpers.log?.warn('Negative order total detected', {
-      merchandiseTotal,
-      shippingTotal,
-      taxTotal,
-      adjustment,
-      total
-    });
-    return 0;
-  }
-
-  helpers.log?.debug('Calculated order total', {
-    merchandiseTotal,
-    shippingTotal,
-    taxTotal,
-    adjustment,
-    total: helpers.formatCurrency(total, 2)
-  });
-
-  return helpers.formatCurrency(total, 2);
-});
-```
-
----
-
-### Recipe 2: Order Type Decision Tree
-
-**Use Case:** Determine order type based on multiple 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';
-  const isExpress = helpers.get(data, 'orders.order.shipping-method')?.includes('Express');
-  const customAttributes = helpers.get(data, 'orders.order.custom-attributes.custom-attribute', []);
-  const isPrime = helpers.extractCustomAttribute(customAttributes, 'isPrime') === 'true';
-
-  // Decision tree
-  let orderType = 'HD';  // Default: Home Delivery
-
-  // Channel-based mapping
-  const channelMapping = {
-    'Storefront': 'HD',
-    'CallCenter': 'CC',
-    'Mobile': 'MOBILE',
-    'POS': 'STORE'
-  };
-
-  orderType = helpers.mapValue(channelType, channelMapping, orderType);
-
-  // Business rules override
-  if (isPrime && orderType === 'HD') {
-    orderType = 'PRIME_HD';
-  } else if (isGift && orderType === 'HD') {
-    orderType = 'GIFT_HD';
-  } else if (isExpress) {
-    orderType = `EXPRESS_${orderType}`;
-  }
-
-  helpers.log?.info('Determined order type', {
-    channelType,
-    isGift,
-    isExpress,
-    isPrime,
-    orderType
-  });
-
-  return orderType;
-});
-```
-
----
-
-### Recipe 3: Payment Method Transformation
-
-**Use Case:** Transform payment data with sensitive data masking.
-
-```typescript
-builder.mapArray(
-  'input.financialTransactions',
-  'orders.order.payments.payment',
-  (payment, index, config, helpers) => {
-    const creditCard = payment['credit-card'];
-    const cardType = creditCard?.['card-type'] || 'UNKNOWN';
-    const cardNumber = creditCard?.['card-number'] || '';
-
-    // Map card type
-    const paymentTypeMapping = {
-      'Visa': 'CREDIT_CARD',
-      'MasterCard': 'CREDIT_CARD',
-      'American Express': 'CREDIT_CARD',
-      'Discover': 'CREDIT_CARD',
-      'PayPal': 'PAYPAL',
-      'Apple Pay': 'DIGITAL_WALLET',
-      'Google Pay': 'DIGITAL_WALLET'
-    };
-
-    const paymentType = helpers.mapValue(cardType, paymentTypeMapping, 'CREDIT_CARD');
-
-    // Mask sensitive data
-    const last4 = cardNumber.slice(-4);
-    const maskedNumber = `************${last4}`;
-
-    return {
-      ref: payment['@payment-id'] || `PAY-${index + 1}`,
-      type: paymentType,
-      amount: helpers.parseFloatSafe(payment.amount, 0),
-
-      attributes: {
-        cardType: cardType,
-        cardNumber: maskedNumber,  // Masked
-        expirationMonth: creditCard?.['expiration-month'],
-        expirationYear: creditCard?.['expiration-year'],
-        processorId: payment['processor-id'],
-        transactionId: payment['transaction-id'],
-        authorizationCode: payment['authorization-code']
-      }
-    };
-  }
-);
-```
-
----
-
-## Inventory Management Recipes
-
-### Recipe 1: Multi-Location Inventory Aggregation
-
-**Use Case:** Aggregate inventory across multiple locations.
-
-```typescript
-builder.field('input.totalAvailableInventory', (data, helpers) => {
-  const items = helpers.ensureArray(
-    helpers.get(data, 'inventory.items', [])
-  );
-
-  // Group by SKU
-  const inventoryBySku = helpers.groupBy(items, 'sku');
-
-  // Calculate totals for each SKU
-  const aggregated = Object.entries(inventoryBySku).map(([sku, locations]) => {
-    const totalOnHand = helpers.sum(locations, item =>
-      helpers.parseIntSafe(item.quantity['on-hand'], 0)
-    );
-
-    const totalAvailable = helpers.sum(locations, item =>
-      helpers.parseIntSafe(item.quantity.available, 0)
-    );
-
-    const totalReserved = helpers.sum(locations, item =>
-      helpers.parseIntSafe(item.quantity.reserved, 0)
-    );
-
-    const locationCount = locations.length;
-
-    return {
-      sku,
-      totalOnHand,
-      totalAvailable,
-      totalReserved,
-      locationCount,
-      locations: locations.map(loc => ({
-        locationId: loc.location.id,
-        locationName: loc.location.name,
-        onHand: helpers.parseIntSafe(loc.quantity['on-hand'], 0),
-        available: helpers.parseIntSafe(loc.quantity.available, 0)
-      }))
-    };
-  });
-
-  return aggregated;
-});
-```
-
----
-
-### Recipe 2: Inventory Delta Calculation
-
-**Use Case:** Calculate inventory changes for incremental updates.
-
-```typescript
-builder.mapArray(
-  'input.entities',
-  'inventory.items',
-  (item, index, config, helpers) => {
-    const sku = item.sku;
-    const newQuantity = helpers.parseIntSafe(item.quantity['on-hand'], 0);
-
-    // Get previous quantity from cache/state
-    const previousQuantity = config.previousInventory?.[sku] || 0;
-
-    // Calculate delta
-    const delta = newQuantity - previousQuantity;
-    const changePercent = previousQuantity > 0
-      ? ((delta / previousQuantity) * 100).toFixed(2)
-      : 0;
-
-    // Determine if significant change
-    const isSignificantChange = Math.abs(delta) > config.significantChangeThreshold || 10;
-
-    return {
-      skuRef: sku,
-      locationRef: item.location.id,
-      qty: newQuantity,
-
-      attributes: {
-        available: helpers.parseIntSafe(item.quantity.available, 0),
-        reserved: helpers.parseIntSafe(item.quantity.reserved, 0),
-
-        // Delta information
-        previousQty: previousQuantity,
-        delta: delta,
-        changePercent: changePercent,
-        isSignificantChange: isSignificantChange,
-
-        // Metadata
-        lastUpdated: item.dates['last-updated'],
-        binLocation: item.attributes['bin-location'],
-        lotNumber: item.attributes['lot-number']
-      }
-    };
-  }
-);
-```
-
----
-
-### Recipe 3: Low Stock Alerts
-
-**Use Case:** Generate alerts for items below reorder point.
-
-```typescript
-builder.field('input.lowStockAlerts', (data, helpers) => {
-  const items = helpers.ensureArray(
-    helpers.get(data, 'inventory.items', [])
-  );
-
-  const reorderPoints = config.reorderPoints || {};  // SKU → reorder point
-
-  const lowStockItems = items
-    .map(item => {
-      const sku = item.sku;
-      const available = helpers.parseIntSafe(item.quantity.available, 0);
-      const reserved = helpers.parseIntSafe(item.quantity.reserved, 0);
-      const inTransit = helpers.parseIntSafe(item.quantity['in-transit'], 0);
-      const reorderPoint = reorderPoints[sku] || 20;  // Default: 20 units
-
-      // Calculate effective available (available + in-transit - reserved)
-      const effectiveAvailable = available + inTransit - reserved;
-
-      // Determine alert severity
-      let severity = 'none';
-      if (effectiveAvailable <= 0) {
-        severity = 'critical';  // Out of stock
-      } else if (effectiveAvailable < reorderPoint * 0.25) {
-        severity = 'high';
-      } else if (effectiveAvailable < reorderPoint * 0.5) {
-        severity = 'medium';
-      } else if (effectiveAvailable < reorderPoint) {
-        severity = 'low';
-      }
-
-      return {
-        sku,
-        productName: item['product-name'],
-        locationId: item.location.id,
-        locationName: item.location.name,
-        available,
-        reserved,
-        inTransit,
-        effectiveAvailable,
-        reorderPoint,
-        severity,
-        needsReorder: effectiveAvailable < reorderPoint
-      };
-    })
-    .filter(item => item.needsReorder)  // Only include items needing reorder
-    .sort((a, b) => {
-      // Sort by severity
-      const severityOrder = { critical: 0, high: 1, medium: 2, low: 3 };
-      return severityOrder[a.severity] - severityOrder[b.severity];
-    });
-
-  helpers.log?.info('Low stock alerts generated', {
-    totalItems: items.length,
-    lowStockCount: lowStockItems.length,
-    criticalCount: lowStockItems.filter(i => i.severity === 'critical').length
-  });
-
-  return lowStockItems;
-});
-```
-
----
-
-## Performance Optimization
-
-### Pattern 1: Memoized Complex Calculations
-
-**Use Case:** Cache expensive calculations that are called multiple times.
-
-```typescript
-// Create memoized functions outside resolver
-const calculateComplexDiscount = helpers.memoize((items, discountRules) => {
-  // Expensive calculation
-  return items.reduce((total, item) => {
-    const basePrice = parseFloat(item['base-price'] || 0);
-    const quantity = parseInt(item.quantity || 1);
-
-    // Apply complex discount rules
-    let discount = 0;
-    for (const rule of discountRules) {
-      if (item.category === rule.category && quantity >= rule.minQuantity) {
-        discount += basePrice * quantity * rule.discountPercent;
-      }
-    }
-
-    return total + discount;
-  }, 0);
-});
-
-builder.field('input.totalDiscount', (data, config, helpers) => {
-  const items = helpers.ensureArray(
-    helpers.get(data, 'orders.order.product-lineitems.product-lineitem')
-  );
-
-  // Cached result
-  return calculateComplexDiscount(items, config.discountRules);
-});
-```
-
----
-
-### Pattern 2: Lazy Evaluation
-
-**Use Case:** Only perform expensive operations when actually needed.
-
-```typescript
-builder.field('input.enrichedData', async (data, config, helpers) => {
-  const requiresEnrichment = helpers.get(data, 'orders.order.enrichment-required') === 'true';
-
-  if (!requiresEnrichment) {
-    helpers.log?.debug('Skipping enrichment (not required)');
-    return null;
-  }
-
-  // Only fetch if needed
-  helpers.log?.debug('Fetching enrichment data...');
-  const enrichmentData = await fetchEnrichmentData(data, config);
-
-  return enrichmentData;
-});
-```
-
----
-
-### Pattern 3: Result Caching with TTL
-
-**Use Case:** Cache API responses with time-to-live.
-
-```typescript
-const cache = new Map();
-
-function getCachedOrFetch(key, fetcher, ttlMs = 300000) {  // 5 min default
-  const cached = cache.get(key);
-
-  if (cached && Date.now() - cached.timestamp < ttlMs) {
-    return Promise.resolve(cached.data);
-  }
-
-  return fetcher().then(data => {
-    cache.set(key, {
-      data,
-      timestamp: Date.now()
-    });
-    return data;
-  });
-}
-
-builder.field('input.productCategory', async (data, config, helpers) => {
-  const sku = helpers.get(data, 'item.sku');
-
-  // Cache product data for 5 minutes
-  const productData = await getCachedOrFetch(
-    `product:${sku}`,
-    () => fetchProductData(sku),
-    300000  // 5 minutes
-  );
-
-  return productData.category;
-});
-```
-
----
-
-## Error Handling
-
-### Pattern 1: Graceful Degradation
-
-**Use Case:** Provide fallback when optional services fail.
-
-```typescript
-builder.field('input.customer.loyaltyTier', async (data, config, helpers) => {
-  const customerId = helpers.get(data, 'orders.order.customer.customer-no');
-
-  try {
-    const loyaltyData = await helpers.retry(
-      async () => {
-        const response = await fetch(
-          `https://api.loyalty.com/customers/${customerId}/tier`,
-          {
-            headers: { 'Authorization': `Bearer ${config.loyaltyApiToken}` },
-            timeout: 5000  // 5 second timeout
-          }
-        );
-
-        if (!response.ok) {
-          throw new Error(`Loyalty API error: ${response.status}`);
-        }
-
-        return await response.json();
-      },
-      2,  // Only retry twice for optional service
-      500
-    );
-
-    return loyaltyData.tier;
-
-  } catch (error) {
-    helpers.log?.warn('Failed to fetch loyalty tier, using default', {
-      customerId,
-      error: error.message
-    });
-
-    // Graceful degradation - use default tier
-    return config.defaultLoyaltyTier || 'STANDARD';
-  }
-});
-```
-
----
-
-### Pattern 2: Validation with Custom Errors
-
-**Use Case:** Provide clear, actionable error messages.
-
-```typescript
-builder.validate(
-  'input.totalPrice',
-  (data, config, helpers) => {
-    const grossPrice = helpers.get(data, 'orders.order.totals.order-total.gross-price');
-
-    if (!grossPrice) {
-      throw new Error(
-        'Missing required field: orders.order.totals.order-total.gross-price. ' +
-        'Ensure the order data includes total pricing information.'
-      );
-    }
-
-    const parsed = helpers.parseFloatSafe(grossPrice, -1);
-
-    if (parsed < 0) {
-      throw new Error(
-        `Invalid price value: "${grossPrice}". ` +
-        'Price must be a positive number.'
-      );
-    }
-
-    return parsed;
-  },
-  (value) => {
-    if (value <= 0) {
-      return `Order total must be greater than zero. Received: ${value}`;
-    }
-
-    if (value > 1000000) {
-      return `Order total exceeds maximum allowed value. Received: ${value}`;
-    }
-
-    return true;  // Validation passed
-  }
-);
-```
-
----
-
-## Testing Patterns
-
-### Pattern 1: Test with Canonical Data
-
-```typescript
-import { canonicalOrder } from '../../../03-PATTERN-GUIDES/examples/test-data/canonical-order.json';
-import { ResolverHelpers } from '@fluentcommerce/fc-connect-sdk';
-
-describe('Order Resolvers', () => {
-  const config = {
-    defaultRetailerId: '1',
-    defaultCurrency: 'USD'
-  };
-
-  it('should extract order reference', () => {
-    const result = resolvers\['input.ref'](canonicalOrder, config, ResolverHelpers);
-    expect(result).toBe('ORD-2025-001');
-  });
-
-  it('should calculate total price', () => {
-    const result = resolvers\['input.totalPrice'](canonicalOrder, config, ResolverHelpers);
-    expect(result).toBe('151.17');
-  });
-
-  it('should extract customer email', () => {
-    const result = resolvers\['input.customer.email'](canonicalOrder, config, ResolverHelpers);
-    expect(result).toBe('john.doe@example.com');
-  });
-});
-```
-
----
-
-### Pattern 2: Mock External Dependencies
-
-```typescript
-describe('Customer Lookup Resolver', () => {
-  it('should use existing customer when found', async () => {
-    const mockFluentClient = {
-      graphql: jest.fn().mockResolvedValue({
-        data: {
-          customers: {
-            edges: [{
-              node: { id: '123', username: 'CUST-001' }
-            }]
-          }
-        }
-      })
-    };
-
-    const mockHelpers = {
-      ...ResolverHelpers,
-      fluentClient: mockFluentClient,
-      retry: (fn) => fn(),  // Skip retry logic in tests
-      log: {
-        info: jest.fn(),
-        warn: jest.fn(),
-        error: jest.fn()
-      }
-    };
-
-    const result = await resolvers`'input.customer.id'`;
-
-    expect(result).toBe('123');
-    expect(mockFluentClient.graphql).toHaveBeenCalledTimes(1);
-    expect(mockHelpers.log.info).toHaveBeenCalledWith(
-      'Found existing customer',
-      { id: '123' }
-    );
-  });
-});
-```
-
----
-
-## See Also
-
-- [Main Resolver Guide](./mapping-resolvers-resolver-guide.md)
-- [API Reference](./mapping-resolvers-resolver-api-reference.md)
-- [Helper Functions Reference](./mapping-resolvers-resolver-helpers-reference.md)
-- [Parameters Reference](./mapping-resolvers-resolver-parameters-reference.md)
-- [Troubleshooting](./mapping-resolvers-resolver-troubleshooting.md)
-
----
-
-**Document Version:** 2.0.0
-**SDK Version:** 1.5.0+
-**Last Updated:** 2025-01-14
-
----
-
-**License:** MIT
-**Copyright:** © 2025 Fluent Commerce
+# Resolver Cookbook
+
+**Advanced patterns and recipes for production resolvers**
+
+Version: 2.0.0
+Last Updated: 2025-01-14
+
+---
+
+## Table of Contents
+
+1. [Async Patterns](#async-patterns)
+2. [Order Management Recipes](#order-management-recipes)
+3. [Inventory Management Recipes](#inventory-management-recipes)
+4. [Performance Optimization](#performance-optimization)
+5. [Error Handling](#error-handling)
+6. [Testing Patterns](#testing-patterns)
+
+---
+
+## Async Patterns
+
+### Pattern 1: Lookup-or-Create Customer
+
+**Use Case:** Ensure customer exists before creating order.
+
+```typescript
+builder.field('input.customer.id', async (data, config, helpers) => {
+  const customerId = helpers.get(data, 'orders.order.customer.customer-no');
+  const email = helpers.get(data, 'orders.order.customer.customer-email');
+
+  if (!helpers.fluentClient) {
+    throw new Error('FluentClient is required for customer lookup');
+  }
+
+  return await helpers.retry(async () => {
+    // Step 1: Try to find existing customer
+    const queryResult = await helpers.fluentClient.graphql({
+      query: `
+        query GetCustomer($username: [String]) {
+          customers(username: $username, first: 1) {
+            edges {
+              node {
+                id
+                username
+                primaryEmail
+              }
+            }
+          }
+        }
+      `,
+      variables: { username: [customerId] }
+    });
+
+    const existing = queryResult.data?.customers?.edges?.[0]?.node;
+
+    if (existing) {
+      helpers.log?.info('Found existing customer', { id: existing.id });
+      return existing.id;
+    }
+
+    // Step 2: Create if not found
+    helpers.log?.info('Creating new customer', { customerId, email });
+
+    const createResult = await helpers.fluentClient.graphql({
+      query: `
+        mutation CreateCustomer($input: CreateCustomerInput!) {
+          createCustomer(input: $input) {
+            id
+            username
+          }
+        }
+      `,
+      variables: {
+        input: {
+          username: customerId,
+          primaryEmail: email,
+          retailer: { id: config.defaultRetailerId }
+        }
+      }
+    });
+
+    if (createResult.errors) {
+      throw new Error(`Failed to create customer: ${createResult.errors[0].message}`);
+    }
+
+    return createResult.data?.createCustomer?.id;
+  }, 3, 500);  // Retry 3 times, 500ms delay
+});
+```
+
+---
+
+### Pattern 2: Parallel API Enrichment
+
+**Use Case:** Enrich order items with external data efficiently.
+
+```typescript
+builder.field('input.items', async (data, config, helpers) => {
+  const items = helpers.ensureArray(
+    helpers.get(data, 'orders.order.product-lineitems.product-lineitem')
+  );
+
+  // Fetch all product details in parallel
+  const enrichedItems = await Promise.all(
+    items.map(async (item) => {
+      // Run multiple lookups in parallel for each item
+      const [productDetails, inventory, pricing] = await Promise.all([
+        fetchProductDetails(item['product-id']),
+        checkInventory(item['product-id'], config.defaultLocationId),
+        getPricing(item['product-id'], config.priceTier)
+      ]);
+
+      return {
+        ref: item['@lineitem-id'],
+        productRef: item['product-id'],
+        quantity: helpers.parseIntSafe(item.quantity, 1),
+        price: helpers.parseFloatSafe(item['base-price'], 0),
+
+        // Enriched data
+        attributes: {
+          productName: productDetails.name,
+          category: productDetails.category,
+          availableQty: inventory.available,
+          currentPrice: pricing.currentPrice,
+          priceWas: pricing.previousPrice
+        }
+      };
+    })
+  );
+
+  return enrichedItems;
+});
+```
+
+---
+
+### Pattern 3: Rate-Limited API Calls with Batch Processing
+
+**Use Case:** Process large item lists without overwhelming external APIs.
+
+```typescript
+builder.field('input.enrichedItems', async (data, config, helpers) => {
+  const items = helpers.ensureArray(
+    helpers.get(data, 'orders.order.product-lineitems.product-lineitem')
+  );
+
+  // Process in batches of 5 to respect API rate limits
+  const enrichedItems = await helpers.batchProcess(
+    items,
+    async (item, index) => {
+      try {
+        // Add delay to respect rate limits
+        await new Promise(resolve => setTimeout(resolve, 200));  // 5 req/sec
+
+        const productData = await helpers.retry(
+          async () => {
+            const response = await fetch(
+              `https://api.product-service.com/products/${item['product-id']}`,
+              {
+                headers: {
+                  'Authorization': `Bearer ${config.productApiToken}`
+                }
+              }
+            );
+
+            if (!response.ok) {
+              throw new Error(`API error: ${response.status}`);
+            }
+
+            return await response.json();
+          },
+          3,   // Max 3 retries
+          1000 // 1 second delay between retries
+        );
+
+        return {
+          ref: item['@lineitem-id'],
+          productRef: item['product-id'],
+          quantity: helpers.parseIntSafe(item.quantity, 1),
+          price: helpers.parseFloatSafe(item['base-price'], 0),
+          attributes: {
+            ...productData
+          }
+        };
+
+      } catch (error) {
+        helpers.log?.error(`Failed to enrich item ${item['@lineitem-id']}`, { error });
+
+        // Return basic item without enrichment
+        return {
+          ref: item['@lineitem-id'],
+          productRef: item['product-id'],
+          quantity: helpers.parseIntSafe(item.quantity, 1),
+          price: helpers.parseFloatSafe(item['base-price'], 0)
+        };
+      }
+    },
+    5  // Process 5 items at a time
+  );
+
+  return enrichedItems;
+});
+```
+
+---
+
+## Order Management Recipes
+
+### Recipe 1: Multi-Source Total Calculation
+
+**Use Case:** Calculate order total from various sources with validation.
+
+```typescript
+builder.calculate('input.totalPrice', (data, helpers) => {
+  // Get line items
+  const items = helpers.ensureArray(
+    helpers.get(data, 'orders.order.product-lineitems.product-lineitem', [])
+  );
+
+  // Calculate merchandise total
+  const merchandiseTotal = helpers.sum(items, item =>
+    helpers.parseFloatSafe(item['gross-price'], 0)
+  );
+
+  // Get shipping total
+  const shippingTotal = helpers.parseFloatSafe(
+    helpers.get(data, 'orders.order.totals.shipping-total.gross-price'),
+    0
+  );
+
+  // Get tax total
+  const taxTotal = helpers.parseFloatSafe(
+    helpers.get(data, 'orders.order.totals.order-total.tax'),
+    0
+  );
+
+  // Get adjustments (discounts/fees)
+  const adjustment = helpers.parseFloatSafe(
+    helpers.get(data, 'orders.order.totals.adjustment-total.gross-price'),
+    0
+  );
+
+  // Calculate final total
+  const total = merchandiseTotal + shippingTotal + taxTotal + adjustment;
+
+  // Validation
+  if (total < 0) {
+    helpers.log?.warn('Negative order total detected', {
+      merchandiseTotal,
+      shippingTotal,
+      taxTotal,
+      adjustment,
+      total
+    });
+    return 0;
+  }
+
+  helpers.log?.debug('Calculated order total', {
+    merchandiseTotal,
+    shippingTotal,
+    taxTotal,
+    adjustment,
+    total: helpers.formatCurrency(total, 2)
+  });
+
+  return helpers.formatCurrency(total, 2);
+});
+```
+
+---
+
+### Recipe 2: Order Type Decision Tree
+
+**Use Case:** Determine order type based on multiple 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';
+  const isExpress = helpers.get(data, 'orders.order.shipping-method')?.includes('Express');
+  const customAttributes = helpers.get(data, 'orders.order.custom-attributes.custom-attribute', []);
+  const isPrime = helpers.extractCustomAttribute(customAttributes, 'isPrime') === 'true';
+
+  // Decision tree
+  let orderType = 'HD';  // Default: Home Delivery
+
+  // Channel-based mapping
+  const channelMapping = {
+    'Storefront': 'HD',
+    'CallCenter': 'CC',
+    'Mobile': 'MOBILE',
+    'POS': 'STORE'
+  };
+
+  orderType = helpers.mapValue(channelType, channelMapping, orderType);
+
+  // Business rules override
+  if (isPrime && orderType === 'HD') {
+    orderType = 'PRIME_HD';
+  } else if (isGift && orderType === 'HD') {
+    orderType = 'GIFT_HD';
+  } else if (isExpress) {
+    orderType = `EXPRESS_${orderType}`;
+  }
+
+  helpers.log?.info('Determined order type', {
+    channelType,
+    isGift,
+    isExpress,
+    isPrime,
+    orderType
+  });
+
+  return orderType;
+});
+```
+
+---
+
+### Recipe 3: Payment Method Transformation
+
+**Use Case:** Transform payment data with sensitive data masking.
+
+```typescript
+builder.mapArray(
+  'input.financialTransactions',
+  'orders.order.payments.payment',
+  (payment, index, config, helpers) => {
+    const creditCard = payment['credit-card'];
+    const cardType = creditCard?.['card-type'] || 'UNKNOWN';
+    const cardNumber = creditCard?.['card-number'] || '';
+
+    // Map card type
+    const paymentTypeMapping = {
+      'Visa': 'CREDIT_CARD',
+      'MasterCard': 'CREDIT_CARD',
+      'American Express': 'CREDIT_CARD',
+      'Discover': 'CREDIT_CARD',
+      'PayPal': 'PAYPAL',
+      'Apple Pay': 'DIGITAL_WALLET',
+      'Google Pay': 'DIGITAL_WALLET'
+    };
+
+    const paymentType = helpers.mapValue(cardType, paymentTypeMapping, 'CREDIT_CARD');
+
+    // Mask sensitive data
+    const last4 = cardNumber.slice(-4);
+    const maskedNumber = `************${last4}`;
+
+    return {
+      ref: payment['@payment-id'] || `PAY-${index + 1}`,
+      type: paymentType,
+      amount: helpers.parseFloatSafe(payment.amount, 0),
+
+      attributes: {
+        cardType: cardType,
+        cardNumber: maskedNumber,  // Masked
+        expirationMonth: creditCard?.['expiration-month'],
+        expirationYear: creditCard?.['expiration-year'],
+        processorId: payment['processor-id'],
+        transactionId: payment['transaction-id'],
+        authorizationCode: payment['authorization-code']
+      }
+    };
+  }
+);
+```
+
+---
+
+## Inventory Management Recipes
+
+### Recipe 1: Multi-Location Inventory Aggregation
+
+**Use Case:** Aggregate inventory across multiple locations.
+
+```typescript
+builder.field('input.totalAvailableInventory', (data, helpers) => {
+  const items = helpers.ensureArray(
+    helpers.get(data, 'inventory.items', [])
+  );
+
+  // Group by SKU
+  const inventoryBySku = helpers.groupBy(items, 'sku');
+
+  // Calculate totals for each SKU
+  const aggregated = Object.entries(inventoryBySku).map(([sku, locations]) => {
+    const totalOnHand = helpers.sum(locations, item =>
+      helpers.parseIntSafe(item.quantity['on-hand'], 0)
+    );
+
+    const totalAvailable = helpers.sum(locations, item =>
+      helpers.parseIntSafe(item.quantity.available, 0)
+    );
+
+    const totalReserved = helpers.sum(locations, item =>
+      helpers.parseIntSafe(item.quantity.reserved, 0)
+    );
+
+    const locationCount = locations.length;
+
+    return {
+      sku,
+      totalOnHand,
+      totalAvailable,
+      totalReserved,
+      locationCount,
+      locations: locations.map(loc => ({
+        locationId: loc.location.id,
+        locationName: loc.location.name,
+        onHand: helpers.parseIntSafe(loc.quantity['on-hand'], 0),
+        available: helpers.parseIntSafe(loc.quantity.available, 0)
+      }))
+    };
+  });
+
+  return aggregated;
+});
+```
+
+---
+
+### Recipe 2: Inventory Delta Calculation
+
+**Use Case:** Calculate inventory changes for incremental updates.
+
+```typescript
+builder.mapArray(
+  'input.entities',
+  'inventory.items',
+  (item, index, config, helpers) => {
+    const sku = item.sku;
+    const newQuantity = helpers.parseIntSafe(item.quantity['on-hand'], 0);
+
+    // Get previous quantity from cache/state
+    const previousQuantity = config.previousInventory?.[sku] || 0;
+
+    // Calculate delta
+    const delta = newQuantity - previousQuantity;
+    const changePercent = previousQuantity > 0
+      ? ((delta / previousQuantity) * 100).toFixed(2)
+      : 0;
+
+    // Determine if significant change
+    const isSignificantChange = Math.abs(delta) > config.significantChangeThreshold || 10;
+
+    return {
+      skuRef: sku,
+      locationRef: item.location.id,
+      qty: newQuantity,
+
+      attributes: {
+        available: helpers.parseIntSafe(item.quantity.available, 0),
+        reserved: helpers.parseIntSafe(item.quantity.reserved, 0),
+
+        // Delta information
+        previousQty: previousQuantity,
+        delta: delta,
+        changePercent: changePercent,
+        isSignificantChange: isSignificantChange,
+
+        // Metadata
+        lastUpdated: item.dates['last-updated'],
+        binLocation: item.attributes['bin-location'],
+        lotNumber: item.attributes['lot-number']
+      }
+    };
+  }
+);
+```
+
+---
+
+### Recipe 3: Low Stock Alerts
+
+**Use Case:** Generate alerts for items below reorder point.
+
+```typescript
+builder.field('input.lowStockAlerts', (data, helpers) => {
+  const items = helpers.ensureArray(
+    helpers.get(data, 'inventory.items', [])
+  );
+
+  const reorderPoints = config.reorderPoints || {};  // SKU → reorder point
+
+  const lowStockItems = items
+    .map(item => {
+      const sku = item.sku;
+      const available = helpers.parseIntSafe(item.quantity.available, 0);
+      const reserved = helpers.parseIntSafe(item.quantity.reserved, 0);
+      const inTransit = helpers.parseIntSafe(item.quantity['in-transit'], 0);
+      const reorderPoint = reorderPoints[sku] || 20;  // Default: 20 units
+
+      // Calculate effective available (available + in-transit - reserved)
+      const effectiveAvailable = available + inTransit - reserved;
+
+      // Determine alert severity
+      let severity = 'none';
+      if (effectiveAvailable <= 0) {
+        severity = 'critical';  // Out of stock
+      } else if (effectiveAvailable < reorderPoint * 0.25) {
+        severity = 'high';
+      } else if (effectiveAvailable < reorderPoint * 0.5) {
+        severity = 'medium';
+      } else if (effectiveAvailable < reorderPoint) {
+        severity = 'low';
+      }
+
+      return {
+        sku,
+        productName: item['product-name'],
+        locationId: item.location.id,
+        locationName: item.location.name,
+        available,
+        reserved,
+        inTransit,
+        effectiveAvailable,
+        reorderPoint,
+        severity,
+        needsReorder: effectiveAvailable < reorderPoint
+      };
+    })
+    .filter(item => item.needsReorder)  // Only include items needing reorder
+    .sort((a, b) => {
+      // Sort by severity
+      const severityOrder = { critical: 0, high: 1, medium: 2, low: 3 };
+      return severityOrder[a.severity] - severityOrder[b.severity];
+    });
+
+  helpers.log?.info('Low stock alerts generated', {
+    totalItems: items.length,
+    lowStockCount: lowStockItems.length,
+    criticalCount: lowStockItems.filter(i => i.severity === 'critical').length
+  });
+
+  return lowStockItems;
+});
+```
+
+---
+
+## Performance Optimization
+
+### Pattern 1: Memoized Complex Calculations
+
+**Use Case:** Cache expensive calculations that are called multiple times.
+
+```typescript
+// Create memoized functions outside resolver
+const calculateComplexDiscount = helpers.memoize((items, discountRules) => {
+  // Expensive calculation
+  return items.reduce((total, item) => {
+    const basePrice = parseFloat(item['base-price'] || 0);
+    const quantity = parseInt(item.quantity || 1);
+
+    // Apply complex discount rules
+    let discount = 0;
+    for (const rule of discountRules) {
+      if (item.category === rule.category && quantity >= rule.minQuantity) {
+        discount += basePrice * quantity * rule.discountPercent;
+      }
+    }
+
+    return total + discount;
+  }, 0);
+});
+
+builder.field('input.totalDiscount', (data, config, helpers) => {
+  const items = helpers.ensureArray(
+    helpers.get(data, 'orders.order.product-lineitems.product-lineitem')
+  );
+
+  // Cached result
+  return calculateComplexDiscount(items, config.discountRules);
+});
+```
+
+---
+
+### Pattern 2: Lazy Evaluation
+
+**Use Case:** Only perform expensive operations when actually needed.
+
+```typescript
+builder.field('input.enrichedData', async (data, config, helpers) => {
+  const requiresEnrichment = helpers.get(data, 'orders.order.enrichment-required') === 'true';
+
+  if (!requiresEnrichment) {
+    helpers.log?.debug('Skipping enrichment (not required)');
+    return null;
+  }
+
+  // Only fetch if needed
+  helpers.log?.debug('Fetching enrichment data...');
+  const enrichmentData = await fetchEnrichmentData(data, config);
+
+  return enrichmentData;
+});
+```
+
+---
+
+### Pattern 3: Result Caching with TTL
+
+**Use Case:** Cache API responses with time-to-live.
+
+```typescript
+const cache = new Map();
+
+function getCachedOrFetch(key, fetcher, ttlMs = 300000) {  // 5 min default
+  const cached = cache.get(key);
+
+  if (cached && Date.now() - cached.timestamp < ttlMs) {
+    return Promise.resolve(cached.data);
+  }
+
+  return fetcher().then(data => {
+    cache.set(key, {
+      data,
+      timestamp: Date.now()
+    });
+    return data;
+  });
+}
+
+builder.field('input.productCategory', async (data, config, helpers) => {
+  const sku = helpers.get(data, 'item.sku');
+
+  // Cache product data for 5 minutes
+  const productData = await getCachedOrFetch(
+    `product:${sku}`,
+    () => fetchProductData(sku),
+    300000  // 5 minutes
+  );
+
+  return productData.category;
+});
+```
+
+---
+
+## Error Handling
+
+### Pattern 1: Graceful Degradation
+
+**Use Case:** Provide fallback when optional services fail.
+
+```typescript
+builder.field('input.customer.loyaltyTier', async (data, config, helpers) => {
+  const customerId = helpers.get(data, 'orders.order.customer.customer-no');
+
+  try {
+    const loyaltyData = await helpers.retry(
+      async () => {
+        const response = await fetch(
+          `https://api.loyalty.com/customers/${customerId}/tier`,
+          {
+            headers: { 'Authorization': `Bearer ${config.loyaltyApiToken}` },
+            timeout: 5000  // 5 second timeout
+          }
+        );
+
+        if (!response.ok) {
+          throw new Error(`Loyalty API error: ${response.status}`);
+        }
+
+        return await response.json();
+      },
+      2,  // Only retry twice for optional service
+      500
+    );
+
+    return loyaltyData.tier;
+
+  } catch (error) {
+    helpers.log?.warn('Failed to fetch loyalty tier, using default', {
+      customerId,
+      error: error.message
+    });
+
+    // Graceful degradation - use default tier
+    return config.defaultLoyaltyTier || 'STANDARD';
+  }
+});
+```
+
+---
+
+### Pattern 2: Validation with Custom Errors
+
+**Use Case:** Provide clear, actionable error messages.
+
+```typescript
+builder.validate(
+  'input.totalPrice',
+  (data, config, helpers) => {
+    const grossPrice = helpers.get(data, 'orders.order.totals.order-total.gross-price');
+
+    if (!grossPrice) {
+      throw new Error(
+        'Missing required field: orders.order.totals.order-total.gross-price. ' +
+        'Ensure the order data includes total pricing information.'
+      );
+    }
+
+    const parsed = helpers.parseFloatSafe(grossPrice, -1);
+
+    if (parsed < 0) {
+      throw new Error(
+        `Invalid price value: "${grossPrice}". ` +
+        'Price must be a positive number.'
+      );
+    }
+
+    return parsed;
+  },
+  (value) => {
+    if (value <= 0) {
+      return `Order total must be greater than zero. Received: ${value}`;
+    }
+
+    if (value > 1000000) {
+      return `Order total exceeds maximum allowed value. Received: ${value}`;
+    }
+
+    return true;  // Validation passed
+  }
+);
+```
+
+---
+
+## Testing Patterns
+
+### Pattern 1: Test with Canonical Data
+
+```typescript
+import { canonicalOrder } from '../../../03-PATTERN-GUIDES/examples/test-data/canonical-order.json';
+import { ResolverHelpers } from '@fluentcommerce/fc-connect-sdk';
+
+describe('Order Resolvers', () => {
+  const config = {
+    defaultRetailerId: '1',
+    defaultCurrency: 'USD'
+  };
+
+  it('should extract order reference', () => {
+    const result = resolvers\['input.ref'](canonicalOrder, config, ResolverHelpers);
+    expect(result).toBe('ORD-2025-001');
+  });
+
+  it('should calculate total price', () => {
+    const result = resolvers\['input.totalPrice'](canonicalOrder, config, ResolverHelpers);
+    expect(result).toBe('151.17');
+  });
+
+  it('should extract customer email', () => {
+    const result = resolvers\['input.customer.email'](canonicalOrder, config, ResolverHelpers);
+    expect(result).toBe('john.doe@example.com');
+  });
+});
+```
+
+---
+
+### Pattern 2: Mock External Dependencies
+
+```typescript
+describe('Customer Lookup Resolver', () => {
+  it('should use existing customer when found', async () => {
+    const mockFluentClient = {
+      graphql: jest.fn().mockResolvedValue({
+        data: {
+          customers: {
+            edges: [{
+              node: { id: '123', username: 'CUST-001' }
+            }]
+          }
+        }
+      })
+    };
+
+    const mockHelpers = {
+      ...ResolverHelpers,
+      fluentClient: mockFluentClient,
+      retry: (fn) => fn(),  // Skip retry logic in tests
+      log: {
+        info: jest.fn(),
+        warn: jest.fn(),
+        error: jest.fn()
+      }
+    };
+
+    const result = await resolvers`'input.customer.id'`;
+
+    expect(result).toBe('123');
+    expect(mockFluentClient.graphql).toHaveBeenCalledTimes(1);
+    expect(mockHelpers.log.info).toHaveBeenCalledWith(
+      'Found existing customer',
+      { id: '123' }
+    );
+  });
+});
+```
+
+---
+
+## See Also
+
+- [Main Resolver Guide](./mapping-resolvers-resolver-guide.md)
+- [API Reference](./mapping-resolvers-resolver-api-reference.md)
+- [Helper Functions Reference](./mapping-resolvers-resolver-helpers-reference.md)
+- [Parameters Reference](./mapping-resolvers-resolver-parameters-reference.md)
+- [Troubleshooting](./mapping-resolvers-resolver-troubleshooting.md)
+
+---
+
+**Document Version:** 2.0.0
+**SDK Version:** 1.5.0+
+**Last Updated:** 2025-01-14
+
+---
+
+**License:** MIT
+**Copyright:** © 2025 Fluent Commerce