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

@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

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

Files changed (475) hide show

package/docs/02-CORE-GUIDES/mapping/resolvers/mapping-resolvers-resolver-api-reference.md CHANGED Viewed

@@ -1,679 +1,679 @@
-# Resolver Builder API Reference
-**Complete API documentation for `ResolverBuilder`**
-Version: 2.0.0
-Last Updated: 2025-01-14
----
-## Table of Contents
-1. [Overview](#overview)
-2. [Factory Function](#factory-function)
-3. [Builder Methods](#builder-methods)
-4. [Method Chaining](#method-chaining)
-5. [TypeScript Types](#typescript-types)
----
-## Overview
-The `ResolverBuilder` provides a fluent API for creating resolver functions without boilerplate code. All methods return `this` for chaining, except `.build()` which returns the final resolver map.
-### SDK Resolver Helpers (NEW)
-Access built-in SDK resolvers and test resolver identifiers programmatically.
-```typescript
-import { sdkResolvers, getSdkResolver, isSdkResolver } from '@fluentcommerce/fc-connect-sdk';
-// Lookup a resolver by name
-const parseIntFn = getSdkResolver('sdk.parseInt');
-const ok = isSdkResolver('sdk.parseInt'); // true
-// Call resolvers directly
-const qty = sdkResolvers.parseInt('42'); // 42
-```
-### Quick Example
-```typescript
-import { createResolverBuilder } from '@fluentcommerce/fc-connect-sdk';
-const builder = createResolverBuilder();
-const resolvers = builder
-  .from('input.ref', 'order.orderNo')
-  .from('input.totalPrice', 'order.total', val => parseFloat(val))
-  .withDefault('input.currency', 'order.currency', 'USD')
-  .build();
-```
----
-## Factory Function
-### `createResolverBuilder()`
-Creates a new `ResolverBuilder` instance.
-**Signature:**
-```typescript
-function createResolverBuilder(): ResolverBuilder;
-```
-**Returns:** New `ResolverBuilder` instance
-**Example:**
-```typescript
-import { createResolverBuilder } from '@fluentcommerce/fc-connect-sdk';
-const builder = createResolverBuilder();
-```
----
-## Builder Methods
-### `.field(path, fn)`
-Add a custom resolver function with full control.
-**Signature:**
-```typescript
-field(path: string, fn: ResolverFunction): this
-```
-**Parameters:**
-- `path: string` - Target field path (e.g., `'input.ref'`, `'input.customer.email'`)
-- `fn: ResolverFunction` - Custom function `(data, config, helpers) => any`
-**Returns:** `this` (chainable)
-**Example:**
-```typescript
-builder.field('input.orderType', (data, config, helpers) => {
-  const channel = helpers.get(data, 'order.channel');
-  return channel === 'web' ? 'HD' : 'STORE';
-});
-```
-**Use when:** You need full control over the transformation logic.
----
-### `.from(targetPath, sourcePath, transform?)`
-Map from source path to target path with optional transformation.
-**Signature:**
-```typescript
-from(
-  targetPath: string,
-  sourcePath: string,
-  transform?: (value: any) => any
-): this
-```
-**Parameters:**
-- `targetPath: string` - Target field path
-- `sourcePath: string` - Source data path (dot notation)
-- `transform?: (value: any) => any` - Optional transformation function
-**Returns:** `this` (chainable)
-**Examples:**
-```typescript
-// Simple mapping
-builder.from('input.ref', 'order.orderNo');
-// With transformation
-builder.from('input.totalPrice', 'order.total', val => parseFloat(val));
-// With complex transformation
-builder.from('input.createdOn', 'order.date', val => {
-  return new Date(val).toISOString();
-});
-```
-**Use when:** Simple field-to-field mapping with optional transformation.
----
-### `.withDefault(path, sourcePath, defaultValue)`
-Extract from source with fallback default value.
-**Signature:**
-```typescript
-withDefault(
-  path: string,
-  sourcePath: string,
-  defaultValue: any
-): this
-```
-**Parameters:**
-- `path: string` - Target field path
-- `sourcePath: string` - Source data path
-- `defaultValue: any` - Default value if source is null/undefined
-**Returns:** `this` (chainable)
-**Example:**
-```typescript
-builder.withDefault('input.status', 'order.status', 'PENDING');
-builder.withDefault('input.currency', 'order.currency', 'USD');
-```
-**Use when:** You need a static fallback value.
----
-### `.withConfigFallback(path, sourcePath, configKey)`
-Extract from source with config fallback.
-**Signature:**
-```typescript
-withConfigFallback(
-  path: string,
-  sourcePath: string,
-  configKey: string
-): this
-```
-**Parameters:**
-- `path: string` - Target field path
-- `sourcePath: string` - Source data path
-- `configKey: string` - Key in config object for fallback
-**Returns:** `this` (chainable)
-**Example:**
-```typescript
-const config = {
-  defaultRetailerId: '1',
-  defaultCurrency: 'USD',
-};
-builder
-  .withConfigFallback('input.retailer.id', 'order.retailerId', 'defaultRetailerId')
-  .withConfigFallback('input.currency', 'order.currency', 'defaultCurrency');
-```
-**Use when:** You need environment-specific fallback values.
----
-### `.calculate(path, fn)`
-Add a calculated resolver (no automatic path extraction).
-**Signature:**
-```typescript
-calculate(
-  path: string,
-  fn: (data: any, helpers: any) => any
-): this
-```
-**Parameters:**
-- `path: string` - Target field path
-- `fn: (data: any, helpers: any) => any` - Calculation function
-**Returns:** `this` (chainable)
-**Example:**
-```typescript
-builder.calculate('input.totalPrice', (data, helpers) => {
-  const items = helpers.get(data, 'order.items', []);
-  return items.reduce((sum, item) => {
-    return sum + helpers.parseFloatSafe(item.price, 0);
-  }, 0);
-});
-```
-**Use when:** Calculating values from multiple sources or complex logic.
----
-### `.mapArray(path, sourcePath, itemMapper)`
-Transform array of items.
-**Signature:**
-```typescript
-mapArray(
-  path: string,
-  sourcePath: string,
-  itemMapper: (item, index, config, helpers) => any
-): this
-```
-**Parameters:**
-- `path: string` - Target field path
-- `sourcePath: string` - Source array path
-- `itemMapper: (item, index, config, helpers) => any` - Item transformation function
-**Returns:** `this` (chainable)
-**Example:**
-```typescript
-builder.mapArray('input.items', 'order.lineItems', (item, index, config, helpers) => ({
-  ref: `ITEM-${index + 1}`,
-  productRef: item.sku,
-  quantity: helpers.parseIntSafe(item.qty, 1),
-  price: helpers.parseFloatSafe(item.price, 0),
-}));
-```
-**Auto-wrapping:** If source is a single object (not array), it's automatically wrapped in an array.
-**Use when:** Transforming arrays of objects (line items, addresses, etc.).
----
-### `.when(path, condition, thenFn, elseFn?)`
-Conditional resolver (if-then-else).
-**Signature:**
-```typescript
-when(
-  path: string,
-  condition: (data: any) => boolean,
-  thenFn: ResolverFunction,
-  elseFn?: ResolverFunction
-): this
-```
-**Parameters:**
-- `path: string` - Target field path
-- `condition: (data: any) => boolean` - Condition function
-- `thenFn: ResolverFunction` - Function to call if condition is true
-- `elseFn?: ResolverFunction` - Optional function if condition is false (default: returns null)
-**Returns:** `this` (chainable)
-**Example:**
-```typescript
-builder.when(
-  'input.orderType',
-  data => helpers.get(data, 'order.isPrimeOrder') === true,
-  (data, config, helpers) => 'PRIME_HD',
-  (data, config, helpers) => 'STANDARD_HD'
-);
-```
-**Use when:** You need if-then-else logic based on data conditions.
----
-### `.aggregate(path, sources, aggregator)`
-Aggregate values from multiple source paths.
-**Signature:**
-```typescript
-aggregate(
-  path: string,
-  sources: string[],
-  aggregator: (values: any[]) => any
-): this
-```
-**Parameters:**
-- `path: string` - Target field path
-- `sources: string[]` - Array of source paths
-- `aggregator: (values: any[]) => any` - Function to aggregate values
-**Returns:** `this` (chainable)
-**Example:**
-```typescript
-builder.aggregate('input.totalPrice', ['order.subtotal', 'order.tax', 'order.shipping'], values =>
-  values.reduce((sum, val) => sum + (val || 0), 0)
-);
-```
-**Use when:** Combining values from multiple paths.
----
-### `.validate(path, fn, validator)`
-Add resolver with validation.
-**Signature:**
-```typescript
-validate(
-  path: string,
-  fn: ResolverFunction,
-  validator: (value: any) => boolean | string
-): this
-```
-**Parameters:**
-- `path: string` - Target field path
-- `fn: ResolverFunction` - Resolver function
-- `validator: (value: any) => boolean | string` - Validation function
-  - Return `true` to pass
-  - Return `false` or error string to fail
-**Returns:** `this` (chainable)
-**Examples:**
-```typescript
-// Boolean validation
-builder.validate(
-  'input.email',
-  (data, config, helpers) => helpers.get(data, 'customer.email'),
-  value => helpers.isValidEmail(value)
-);
-// String validation (custom error message)
-builder.validate(
-  'input.totalPrice',
-  (data, config, helpers) => helpers.parseFloatSafe(helpers.get(data, 'order.total'), 0),
-  value => value > 0 || 'Total price must be positive'
-);
-```
-**Use when:** You need to enforce validation rules.
----
-### `.build()`
-Build and return the resolver map.
-**Signature:**
-```typescript
-build(): ResolverMap
-```
-**Returns:** `ResolverMap` - Object with field paths as keys and resolver functions as values
-**Example:**
-```typescript
-const resolvers = builder
-  .from('input.ref', 'order.orderNo')
-  .calculate('input.total', (data, helpers) => calculateTotal(data))
-  .build();
-// Returns:
-// {
-//   'input.ref': (data, config, helpers) => { ... },
-//   'input.total': (data, config, helpers) => { ... }
-// }
-```
-**Use when:** You're done building and ready to use the resolvers.
----
-## Method Chaining
-All builder methods (except `.build()`) return `this`, allowing fluent chaining:
-```typescript
-const resolvers = builder
-  .from('input.ref', 'order.orderNo')
-  .from('input.totalPrice', 'order.total', parseFloat)
-  .withDefault('input.currency', 'order.currency', 'USD')
-  .withConfigFallback('input.retailer.id', 'order.retailerId', 'defaultRetailerId')
-  .calculate('input.discount', calculateDiscount)
-  .mapArray('input.items', 'order.items', transformItem)
-  .validate('input.email', extractEmail, isValidEmail)
-  .build();
-```
-**Execution Order:**
-Resolvers are executed in the order they're added to the builder.
----
-## TypeScript Types
-### Core Types
-```typescript
-/**
- * Resolver function signature
- */
-type ResolverFunction = (
-  data: unknown, // Full source data with named nodes
-  config: unknown, // Configuration object
-  helpers: Helpers // Helper utilities
-) => unknown | Promise<unknown>;
-/**
- * Resolver map (output of .build())
- */
-type ResolverMap = {
-  [path: string]: ResolverFunction;
-};
-/**
- * Helper functions available in resolvers
- */
-interface Helpers {
-  // Data access
-  get: (obj: any, path: string, defaultValue?: any) => any;
-  ensureArray: <T>(val: T | T[] | null | undefined) => T[];
-  // Parsing
-  parseFloatSafe: (value: any, defaultValue?: number) => number;
-  parseIntSafe: (value: any, defaultValue?: number) => number;
-  safeJsonParse: <T = any>(jsonString: string, defaultValue?: T) => T;
-  // Formatting
-  formatDate: (date: Date | string) => string;
-  formatCurrency: (amount: number, scale?: number) => string;
-  // Validation
-  isValidEmail: (email: string) => boolean;
-  requireField: (value: any, fieldName: string) => void;
-  // Mapping
-  mapValue: <T>(value: any, mapping: Record<string, T>, defaultValue?: T) => T;
-  // String utilities
-  fullName: (firstName?: string, lastName?: string) => string;
-  truncate: (str: string, maxLength: number) => string;
-  normalizeWhitespace: (str: string) => string;
-  toCamelCase: (str: string) => string;
-  toSnakeCase: (str: string) => string;
-  // Object utilities
-  isEmpty: (value: any) => boolean;
-  pick: <T extends object, K extends keyof T>(obj: T, keys: K[]) => Pick<T, K>;
-  omit: <T extends object, K extends keyof T>(obj: T, keys: K[]) => Omit<T, K>;
-  deepClone: <T>(obj: T) => T;
-  deepMerge: <T extends object>(target: T, source: Partial<T>) => T;
-  // Performance
-  memoize: <T extends (...args: any[]) => any>(fn: T) => T;
-  retry: <T>(fn: () => Promise<T>, maxRetries?: number, delayMs?: number) => Promise<T>;
-  batchProcess: <T, R>(
-    items: T[],
-    processor: (item: T, index: number) => Promise<R>,
-    batchSize?: number
-  ) => Promise<R[]>;
-  // Logging (if provided)
-  log?: Logger;
-  // Fluent API client (if provided)
-  fluentClient?: FluentClient;
-}
-/**
- * Logger interface
- */
-interface Logger {
-  info: (message: string, meta?: any) => void;
-  warn: (message: string, meta?: any) => void;
-  error: (message: string, meta?: any) => void;
-  debug: (message: string, meta?: any) => void;
-}
-```
-### Usage with TypeScript
-```typescript
-import type { ResolverFunction, ResolverMap, Helpers } from '@fluentcommerce/fc-connect-sdk';
-// Typed resolver function
-const orderRefResolver: ResolverFunction = (data, config, helpers) => {
-  return helpers.get(data, 'orders.order@order-no');
-};
-// Typed resolver map
-const resolvers: ResolverMap = {
-  'input.ref': orderRefResolver,
-};
-// Typed config
-interface MyConfig {
-  defaultRetailerId: string;
-  defaultCurrency: string;
-}
-const config: MyConfig = {
-  defaultRetailerId: '1',
-  defaultCurrency: 'USD',
-};
-```
----
-## Complete Example
-Here's a complete example showing all builder methods:
-```typescript
-import { createResolverBuilder, ResolverHelpers } from '@fluentcommerce/fc-connect-sdk';
-const builder = createResolverBuilder();
-const resolvers = builder
-  // Simple field mapping
-  .from('input.ref', 'orders.order@order-no')
-  // With transformation
-  .from('input.totalPrice', 'orders.order.totals.order-total.gross-price', val => parseFloat(val))
-  // With default value
-  .withDefault('input.currency', 'orders.order.currency', 'USD')
-  // With config fallback
-  .withConfigFallback('input.retailer.id', 'orders.order.retailerId', 'defaultRetailerId')
-  // Custom field resolver
-  .field('input.orderType', (data, config, helpers) => {
-    const channel = helpers.get(data, 'orders.order.channel-type');
-    const mapping = { Storefront: 'HD', CallCenter: 'CC' };
-    return helpers.mapValue(channel, mapping, 'HD');
-  })
-  // Calculated field
-  .calculate('input.totalDiscount', (data, helpers) => {
-    const adjustment = helpers.get(data, 'orders.order.totals.adjustment-total.gross-price');
-    return Math.abs(helpers.parseFloatSafe(adjustment, 0));
-  })
-  // Array mapping
-  .mapArray(
-    'input.items',
-    'orders.order.product-lineitems.product-lineitem',
-    (item, index, config, helpers) => ({
-      ref: item['@lineitem-id'],
-      productRef: item['product-id'],
-      quantity: helpers.parseIntSafe(item.quantity, 1),
-      price: helpers.parseFloatSafe(item['base-price'], 0),
-    })
-  )
-  // Conditional resolver
-  .when(
-    'input.priority',
-    data => helpers.get(data, 'orders.order.express-shipping') === 'true',
-    () => 'HIGH',
-    () => 'NORMAL'
-  )
-  // Aggregation
-  .aggregate(
-    'input.totalTax',
-    ['orders.order.totals.merchandize-total.tax', 'orders.order.totals.shipping-total.tax'],
-    values => values.reduce((sum, val) => sum + (parseFloat(val) || 0), 0)
-  )
-  // With validation
-  .validate(
-    'input.customer.email',
-    (data, config, helpers) => helpers.get(data, 'orders.order.customer.customer-email'),
-    value => helpers.isValidEmail(value) || 'Invalid email format'
-  )
-  // Build the resolver map
-  .build();
-// Use the resolvers
-export default resolvers;
-```
----
-## See Also
-- [Main Resolver Guide](./mapping-resolvers-resolver-guide.md) - Getting started and examples
-- [Helper Functions Reference](./mapping-resolvers-resolver-helpers-reference.md) - All 54 helper functions
-- [Parameters Reference](./mapping-resolvers-resolver-parameters-reference.md) - Understanding value, data, config, helpers
-- [Troubleshooting](./mapping-resolvers-resolver-troubleshooting.md) - Common issues and solutions
-- [Cookbook](./mapping-resolvers-resolver-cookbook.md) - Advanced patterns and recipes
----
-**Document Version:** 2.0.0
-**SDK Version:** 1.5.0+
-**Last Updated:** 2025-01-14
----
-**License:** MIT
-**Copyright:** © 2025 Fluent Commerce
+# Resolver Builder API Reference
+**Complete API documentation for `ResolverBuilder`**
+Version: 2.0.0
+Last Updated: 2025-01-14
+---
+## Table of Contents
+1. [Overview](#overview)
+2. [Factory Function](#factory-function)
+3. [Builder Methods](#builder-methods)
+4. [Method Chaining](#method-chaining)
+5. [TypeScript Types](#typescript-types)
+---
+## Overview
+The `ResolverBuilder` provides a fluent API for creating resolver functions without boilerplate code. All methods return `this` for chaining, except `.build()` which returns the final resolver map.
+### SDK Resolver Helpers (NEW)
+Access built-in SDK resolvers and test resolver identifiers programmatically.
+```typescript
+import { sdkResolvers, getSdkResolver, isSdkResolver } from '@fluentcommerce/fc-connect-sdk';
+// Lookup a resolver by name
+const parseIntFn = getSdkResolver('sdk.parseInt');
+const ok = isSdkResolver('sdk.parseInt'); // true
+// Call resolvers directly
+const qty = sdkResolvers.parseInt('42'); // 42
+```
+### Quick Example
+```typescript
+import { createResolverBuilder } from '@fluentcommerce/fc-connect-sdk';
+const builder = createResolverBuilder();
+const resolvers = builder
+  .from('input.ref', 'order.orderNo')
+  .from('input.totalPrice', 'order.total', val => parseFloat(val))
+  .withDefault('input.currency', 'order.currency', 'USD')
+  .build();
+```
+---
+## Factory Function
+### `createResolverBuilder()`
+Creates a new `ResolverBuilder` instance.
+**Signature:**
+```typescript
+function createResolverBuilder(): ResolverBuilder;
+```
+**Returns:** New `ResolverBuilder` instance
+**Example:**
+```typescript
+import { createResolverBuilder } from '@fluentcommerce/fc-connect-sdk';
+const builder = createResolverBuilder();
+```
+---
+## Builder Methods
+### `.field(path, fn)`
+Add a custom resolver function with full control.
+**Signature:**
+```typescript
+field(path: string, fn: ResolverFunction): this
+```
+**Parameters:**
+- `path: string` - Target field path (e.g., `'input.ref'`, `'input.customer.email'`)
+- `fn: ResolverFunction` - Custom function `(data, config, helpers) => any`
+**Returns:** `this` (chainable)
+**Example:**
+```typescript
+builder.field('input.orderType', (data, config, helpers) => {
+  const channel = helpers.get(data, 'order.channel');
+  return channel === 'web' ? 'HD' : 'STORE';
+});
+```
+**Use when:** You need full control over the transformation logic.
+---
+### `.from(targetPath, sourcePath, transform?)`
+Map from source path to target path with optional transformation.
+**Signature:**
+```typescript
+from(
+  targetPath: string,
+  sourcePath: string,
+  transform?: (value: any) => any
+): this
+```
+**Parameters:**
+- `targetPath: string` - Target field path
+- `sourcePath: string` - Source data path (dot notation)
+- `transform?: (value: any) => any` - Optional transformation function
+**Returns:** `this` (chainable)
+**Examples:**
+```typescript
+// Simple mapping
+builder.from('input.ref', 'order.orderNo');
+// With transformation
+builder.from('input.totalPrice', 'order.total', val => parseFloat(val));
+// With complex transformation
+builder.from('input.createdOn', 'order.date', val => {
+  return new Date(val).toISOString();
+});
+```
+**Use when:** Simple field-to-field mapping with optional transformation.
+---
+### `.withDefault(path, sourcePath, defaultValue)`
+Extract from source with fallback default value.
+**Signature:**
+```typescript
+withDefault(
+  path: string,
+  sourcePath: string,
+  defaultValue: any
+): this
+```
+**Parameters:**
+- `path: string` - Target field path
+- `sourcePath: string` - Source data path
+- `defaultValue: any` - Default value if source is null/undefined
+**Returns:** `this` (chainable)
+**Example:**
+```typescript
+builder.withDefault('input.status', 'order.status', 'PENDING');
+builder.withDefault('input.currency', 'order.currency', 'USD');
+```
+**Use when:** You need a static fallback value.
+---
+### `.withConfigFallback(path, sourcePath, configKey)`
+Extract from source with config fallback.
+**Signature:**
+```typescript
+withConfigFallback(
+  path: string,
+  sourcePath: string,
+  configKey: string
+): this
+```
+**Parameters:**
+- `path: string` - Target field path
+- `sourcePath: string` - Source data path
+- `configKey: string` - Key in config object for fallback
+**Returns:** `this` (chainable)
+**Example:**
+```typescript
+const config = {
+  defaultRetailerId: '1',
+  defaultCurrency: 'USD',
+};
+builder
+  .withConfigFallback('input.retailer.id', 'order.retailerId', 'defaultRetailerId')
+  .withConfigFallback('input.currency', 'order.currency', 'defaultCurrency');
+```
+**Use when:** You need environment-specific fallback values.
+---
+### `.calculate(path, fn)`
+Add a calculated resolver (no automatic path extraction).
+**Signature:**
+```typescript
+calculate(
+  path: string,
+  fn: (data: any, helpers: any) => any
+): this
+```
+**Parameters:**
+- `path: string` - Target field path
+- `fn: (data: any, helpers: any) => any` - Calculation function
+**Returns:** `this` (chainable)
+**Example:**
+```typescript
+builder.calculate('input.totalPrice', (data, helpers) => {
+  const items = helpers.get(data, 'order.items', []);
+  return items.reduce((sum, item) => {
+    return sum + helpers.parseFloatSafe(item.price, 0);
+  }, 0);
+});
+```
+**Use when:** Calculating values from multiple sources or complex logic.
+---
+### `.mapArray(path, sourcePath, itemMapper)`
+Transform array of items.
+**Signature:**
+```typescript
+mapArray(
+  path: string,
+  sourcePath: string,
+  itemMapper: (item, index, config, helpers) => any
+): this
+```
+**Parameters:**
+- `path: string` - Target field path
+- `sourcePath: string` - Source array path
+- `itemMapper: (item, index, config, helpers) => any` - Item transformation function
+**Returns:** `this` (chainable)
+**Example:**
+```typescript
+builder.mapArray('input.items', 'order.lineItems', (item, index, config, helpers) => ({
+  ref: `ITEM-${index + 1}`,
+  productRef: item.sku,
+  quantity: helpers.parseIntSafe(item.qty, 1),
+  price: helpers.parseFloatSafe(item.price, 0),
+}));
+```
+**Auto-wrapping:** If source is a single object (not array), it's automatically wrapped in an array.
+**Use when:** Transforming arrays of objects (line items, addresses, etc.).
+---
+### `.when(path, condition, thenFn, elseFn?)`
+Conditional resolver (if-then-else).
+**Signature:**
+```typescript
+when(
+  path: string,
+  condition: (data: any) => boolean,
+  thenFn: ResolverFunction,
+  elseFn?: ResolverFunction
+): this
+```
+**Parameters:**
+- `path: string` - Target field path
+- `condition: (data: any) => boolean` - Condition function
+- `thenFn: ResolverFunction` - Function to call if condition is true
+- `elseFn?: ResolverFunction` - Optional function if condition is false (default: returns null)
+**Returns:** `this` (chainable)
+**Example:**
+```typescript
+builder.when(
+  'input.orderType',
+  data => helpers.get(data, 'order.isPrimeOrder') === true,
+  (data, config, helpers) => 'PRIME_HD',
+  (data, config, helpers) => 'STANDARD_HD'
+);
+```
+**Use when:** You need if-then-else logic based on data conditions.
+---
+### `.aggregate(path, sources, aggregator)`
+Aggregate values from multiple source paths.
+**Signature:**
+```typescript
+aggregate(
+  path: string,
+  sources: string[],
+  aggregator: (values: any[]) => any
+): this
+```
+**Parameters:**
+- `path: string` - Target field path
+- `sources: string[]` - Array of source paths
+- `aggregator: (values: any[]) => any` - Function to aggregate values
+**Returns:** `this` (chainable)
+**Example:**
+```typescript
+builder.aggregate('input.totalPrice', ['order.subtotal', 'order.tax', 'order.shipping'], values =>
+  values.reduce((sum, val) => sum + (val || 0), 0)
+);
+```
+**Use when:** Combining values from multiple paths.
+---
+### `.validate(path, fn, validator)`
+Add resolver with validation.
+**Signature:**
+```typescript
+validate(
+  path: string,
+  fn: ResolverFunction,
+  validator: (value: any) => boolean | string
+): this
+```
+**Parameters:**
+- `path: string` - Target field path
+- `fn: ResolverFunction` - Resolver function
+- `validator: (value: any) => boolean | string` - Validation function
+  - Return `true` to pass
+  - Return `false` or error string to fail
+**Returns:** `this` (chainable)
+**Examples:**
+```typescript
+// Boolean validation
+builder.validate(
+  'input.email',
+  (data, config, helpers) => helpers.get(data, 'customer.email'),
+  value => helpers.isValidEmail(value)
+);
+// String validation (custom error message)
+builder.validate(
+  'input.totalPrice',
+  (data, config, helpers) => helpers.parseFloatSafe(helpers.get(data, 'order.total'), 0),
+  value => value > 0 || 'Total price must be positive'
+);
+```
+**Use when:** You need to enforce validation rules.
+---
+### `.build()`
+Build and return the resolver map.
+**Signature:**
+```typescript
+build(): ResolverMap
+```
+**Returns:** `ResolverMap` - Object with field paths as keys and resolver functions as values
+**Example:**
+```typescript
+const resolvers = builder
+  .from('input.ref', 'order.orderNo')
+  .calculate('input.total', (data, helpers) => calculateTotal(data))
+  .build();
+// Returns:
+// {
+//   'input.ref': (data, config, helpers) => { ... },
+//   'input.total': (data, config, helpers) => { ... }
+// }
+```
+**Use when:** You're done building and ready to use the resolvers.
+---
+## Method Chaining
+All builder methods (except `.build()`) return `this`, allowing fluent chaining:
+```typescript
+const resolvers = builder
+  .from('input.ref', 'order.orderNo')
+  .from('input.totalPrice', 'order.total', parseFloat)
+  .withDefault('input.currency', 'order.currency', 'USD')
+  .withConfigFallback('input.retailer.id', 'order.retailerId', 'defaultRetailerId')
+  .calculate('input.discount', calculateDiscount)
+  .mapArray('input.items', 'order.items', transformItem)
+  .validate('input.email', extractEmail, isValidEmail)
+  .build();
+```
+**Execution Order:**
+Resolvers are executed in the order they're added to the builder.
+---
+## TypeScript Types
+### Core Types
+```typescript
+/**
+ * Resolver function signature
+ */
+type ResolverFunction = (
+  data: unknown, // Full source data with named nodes
+  config: unknown, // Configuration object
+  helpers: Helpers // Helper utilities
+) => unknown | Promise<unknown>;
+/**
+ * Resolver map (output of .build())
+ */
+type ResolverMap = {
+  [path: string]: ResolverFunction;
+};
+/**
+ * Helper functions available in resolvers
+ */
+interface Helpers {
+  // Data access
+  get: (obj: any, path: string, defaultValue?: any) => any;
+  ensureArray: <T>(val: T | T[] | null | undefined) => T[];
+  // Parsing
+  parseFloatSafe: (value: any, defaultValue?: number) => number;
+  parseIntSafe: (value: any, defaultValue?: number) => number;
+  safeJsonParse: <T = any>(jsonString: string, defaultValue?: T) => T;
+  // Formatting
+  formatDate: (date: Date | string) => string;
+  formatCurrency: (amount: number, scale?: number) => string;
+  // Validation
+  isValidEmail: (email: string) => boolean;
+  requireField: (value: any, fieldName: string) => void;
+  // Mapping
+  mapValue: <T>(value: any, mapping: Record<string, T>, defaultValue?: T) => T;
+  // String utilities
+  fullName: (firstName?: string, lastName?: string) => string;
+  truncate: (str: string, maxLength: number) => string;
+  normalizeWhitespace: (str: string) => string;
+  toCamelCase: (str: string) => string;
+  toSnakeCase: (str: string) => string;
+  // Object utilities
+  isEmpty: (value: any) => boolean;
+  pick: <T extends object, K extends keyof T>(obj: T, keys: K[]) => Pick<T, K>;
+  omit: <T extends object, K extends keyof T>(obj: T, keys: K[]) => Omit<T, K>;
+  deepClone: <T>(obj: T) => T;
+  deepMerge: <T extends object>(target: T, source: Partial<T>) => T;
+  // Performance
+  memoize: <T extends (...args: any[]) => any>(fn: T) => T;
+  retry: <T>(fn: () => Promise<T>, maxRetries?: number, delayMs?: number) => Promise<T>;
+  batchProcess: <T, R>(
+    items: T[],
+    processor: (item: T, index: number) => Promise<R>,
+    batchSize?: number
+  ) => Promise<R[]>;
+  // Logging (if provided)
+  log?: Logger;
+  // Fluent API client (if provided)
+  fluentClient?: FluentClient;
+}
+/**
+ * Logger interface
+ */
+interface Logger {
+  info: (message: string, meta?: any) => void;
+  warn: (message: string, meta?: any) => void;
+  error: (message: string, meta?: any) => void;
+  debug: (message: string, meta?: any) => void;
+}
+```
+### Usage with TypeScript
+```typescript
+import type { ResolverFunction, ResolverMap, Helpers } from '@fluentcommerce/fc-connect-sdk';
+// Typed resolver function
+const orderRefResolver: ResolverFunction = (data, config, helpers) => {
+  return helpers.get(data, 'orders.order@order-no');
+};
+// Typed resolver map
+const resolvers: ResolverMap = {
+  'input.ref': orderRefResolver,
+};
+// Typed config
+interface MyConfig {
+  defaultRetailerId: string;
+  defaultCurrency: string;
+}
+const config: MyConfig = {
+  defaultRetailerId: '1',
+  defaultCurrency: 'USD',
+};
+```
+---
+## Complete Example
+Here's a complete example showing all builder methods:
+```typescript
+import { createResolverBuilder, ResolverHelpers } from '@fluentcommerce/fc-connect-sdk';
+const builder = createResolverBuilder();
+const resolvers = builder
+  // Simple field mapping
+  .from('input.ref', 'orders.order@order-no')
+  // With transformation
+  .from('input.totalPrice', 'orders.order.totals.order-total.gross-price', val => parseFloat(val))
+  // With default value
+  .withDefault('input.currency', 'orders.order.currency', 'USD')
+  // With config fallback
+  .withConfigFallback('input.retailer.id', 'orders.order.retailerId', 'defaultRetailerId')
+  // Custom field resolver
+  .field('input.orderType', (data, config, helpers) => {
+    const channel = helpers.get(data, 'orders.order.channel-type');
+    const mapping = { Storefront: 'HD', CallCenter: 'CC' };
+    return helpers.mapValue(channel, mapping, 'HD');
+  })
+  // Calculated field
+  .calculate('input.totalDiscount', (data, helpers) => {
+    const adjustment = helpers.get(data, 'orders.order.totals.adjustment-total.gross-price');
+    return Math.abs(helpers.parseFloatSafe(adjustment, 0));
+  })
+  // Array mapping
+  .mapArray(
+    'input.items',
+    'orders.order.product-lineitems.product-lineitem',
+    (item, index, config, helpers) => ({
+      ref: item['@lineitem-id'],
+      productRef: item['product-id'],
+      quantity: helpers.parseIntSafe(item.quantity, 1),
+      price: helpers.parseFloatSafe(item['base-price'], 0),
+    })
+  )
+  // Conditional resolver
+  .when(
+    'input.priority',
+    data => helpers.get(data, 'orders.order.express-shipping') === 'true',
+    () => 'HIGH',
+    () => 'NORMAL'
+  )
+  // Aggregation
+  .aggregate(
+    'input.totalTax',
+    ['orders.order.totals.merchandize-total.tax', 'orders.order.totals.shipping-total.tax'],
+    values => values.reduce((sum, val) => sum + (parseFloat(val) || 0), 0)
+  )
+  // With validation
+  .validate(
+    'input.customer.email',
+    (data, config, helpers) => helpers.get(data, 'orders.order.customer.customer-email'),
+    value => helpers.isValidEmail(value) || 'Invalid email format'
+  )
+  // Build the resolver map
+  .build();
+// Use the resolvers
+export default resolvers;
+```
+---
+## See Also
+- [Main Resolver Guide](./mapping-resolvers-resolver-guide.md) - Getting started and examples
+- [Helper Functions Reference](./mapping-resolvers-resolver-helpers-reference.md) - All 54 helper functions
+- [Parameters Reference](./mapping-resolvers-resolver-parameters-reference.md) - Understanding value, data, config, helpers
+- [Troubleshooting](./mapping-resolvers-resolver-troubleshooting.md) - Common issues and solutions
+- [Cookbook](./mapping-resolvers-resolver-cookbook.md) - Advanced patterns and recipes
+---
+**Document Version:** 2.0.0
+**SDK Version:** 1.5.0+
+**Last Updated:** 2025-01-14
+---
+**License:** MIT
+**Copyright:** © 2025 Fluent Commerce