@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/02-CORE-GUIDES/api-reference/modules/api-reference-04-graphql-mapping.md

@@ -1,925 +1,925 @@
-# Module 4: GraphQL Mutation Mapping
-
-**Level:** Advanced
-**Category:** Data Transformation
-
-## Overview
-
-The GraphQL Mutation Mapping system provides schema-driven transformation of XML/JSON data into GraphQL mutation inputs with full validation and type safety.
-
-## Table of Contents
-
-- [GraphQLMutationMapper](#graphqlmutationmapper)
-- [Path Resolvers](#path-resolvers)
-- [GraphQL Introspection Service](#graphql-introspection-service)
-- [Mapping Configuration](#mapping-configuration)
-- [Complete Examples](#complete-examples)
-- [See Also](#see-also)
-
----
-
-## GraphQLMutationMapper
-
-Main class for mapping source data to GraphQL mutations.
-
-### Constructor
-
-```typescript
-import { GraphQLMutationMapper } from '@fluentcommerce/fc-connect-sdk';
-
-const mapper = new GraphQLMutationMapper(
-  config: MappingConfig,
-  logger?: StructuredLogger,
-  options?: MappingOptions
-);
-```
-
-**Parameters:**
-- `config: MappingConfig` - Mapping configuration object
-- `logger?: StructuredLogger` - Optional logger instance
-- `options?: MappingOptions` - Optional configuration (customResolvers, fluentClient, context)
-
-**MappingOptions Interface:**
-```typescript
-interface MappingOptions {
-  /** Custom resolver functions (stored and used by mapWithNodes) */
-  customResolvers?: ResolversMap;
-  
-  /** Custom transform functions (for map() method) */
-  customTransforms?: Record<string, TransformFunction>;
-  
-  /** Schema cache TTL in milliseconds (default: 3600000) */
-  schemaCacheTTL?: number;
-}
-```
-
-**Usage:** `customResolvers` should be passed in the constructor (consistent with `UniversalMapper`). Method call resolvers can override constructor resolvers for per-call customization. Constructor resolvers are merged with method call resolvers, with method call resolvers taking precedence.
-
-### map Method
-
-Transform source data into a GraphQL mutation payload.
-
-```typescript
-async map(
-  sourceData: unknown,
-  hooks?: MappingHooks
-): Promise<GraphQLPayload>
-```
-
-**Parameters:**
-- `sourceData: unknown` - XML or JSON source data (already parsed)
-- `hooks?: MappingHooks` - Optional lifecycle hooks
-
-**Returns:**
-- `GraphQLPayload` - Object with `query` and `variables` properties
-
-**Example:**
-```typescript
-import { GraphQLMutationMapper } from '@fluentcommerce/fc-connect-sdk';
-import mappingConfig from './mappings/sfcc-order-to-fluent.json';
-
-const mapper = new GraphQLMutationMapper(mappingConfig, logger);
-
-// Map XML data to createOrder mutation
-const payload = await mapper.map(parsedXmlData, {
-  beforeMapping: async (data, context) => {
-    // Preprocess data before mapping
-    return data;
-  },
-  afterMapping: async (variables, context) => {
-    // Post-process mapped variables
-    variables.input.totalPrice = calculateTotal(variables.input.items);
-    return variables;
-  }
-});
-
-// Execute mutation
-const result = await fluentClient.graphql(payload);
-```
-
-### mapWithNodes Method
-
-Transform source data with custom resolvers and XML node extraction support.
-
-```typescript
-async mapWithNodes(
-  rootData: unknown,
-  resolvers?: ResolversMap,
-  context?: ResolverContext
-): Promise<MapWithNodesResult>
-```
-
-**Parameters:**
-- `rootData: unknown` - Source data (XML/JSON, already parsed)
-- `resolvers?: ResolversMap` - Optional custom resolver functions (overrides constructor resolvers)
-- `context?: ResolverContext` - Optional context with fluentClient, config, helpers
-
-**Returns:**
-- `MapWithNodesResult` - Object with `success`, `data`, `variables`, `query`, `context`, and `errors`
-
-**MapWithNodesResult Interface:**
-```typescript
-interface MapWithNodesResult {
-  /** Whether mapping succeeded */
-  success: boolean;
-
-  /** Unwrapped mapped data (for direct field access: result.data.orderNo) */
-  data: Record<string, any>;
-
-  /** Wrapped variables for GraphQL execution (use this in client.graphql())
-   * - Fields pattern: { input: { ... } }
-   * - Arguments pattern: { ... } (unwrapped)
-   */
-  variables: Record<string, any>;
-
-  /** GraphQL mutation query string (auto-generated) */
-  query: string;
-
-  /** Extracted nodes context */
-  context: NodesContext;
-
-  /** Error messages (if any) */
-  errors: string[];
-}
-```
-
-**Example:**
-```typescript
-import { GraphQLMutationMapper } from '@fluentcommerce/fc-connect-sdk';
-
-const mapper = new GraphQLMutationMapper(mappingConfig, logger, {
-  customResolvers: baseResolvers,  // Constructor resolvers
-  fluentClient: fluentClient  // Available as helpers.fluentClient in resolvers
-});
-
-// Map with custom resolvers and XML nodes
-// Pass resolverContext - resolvers can access config via helpers.context.config
-const resolverContext = {
-  fluentClient,
-  config: { retailerId: '1', defaultOrderType: 'HD' },
-  helpers: { fluentClient }
-};
-const result = await mapper.mapWithNodes(xmlData, overrideResolvers, resolverContext);
-
-// In your resolver, access config:
-// const retailerId = helpers.context?.config?.retailerId;
-// OR use the config parameter directly:
-// const retailerId = config?.retailerId;
-
-// Check success (errors are returned, not thrown)
-if (!result.success) {
-  console.error('Mapping failed:', result.errors);
-  return;
-}
-
-// Execute mutation (use result.variables for GraphQL, result.data for field access)
-await fluentClient.graphql({
-  query: result.query,
-  variables: result.variables  // ✅ Use variables (wrapped if fields pattern)
-});
-
-// Access mapped fields directly (unwrapped)
-const orderRef = result.data.ref;  // ✅ Use data for direct field access
-```
-
-**Key Features:**
-- ✅ **Custom resolvers** - Full access to source data and helpers
-- ✅ **XML node extraction** - Extract nested/escaped XML segments
-- ✅ **Context passing** - FluentClient, config, helpers available to resolvers
-- ✅ **Auto-generated query** - No need to call `buildMutation()` separately
-- ✅ **Error handling** - Returns error result instead of throwing
-
-### GraphQLPayload Interface
-
-```typescript
-interface GraphQLPayload<T = Record<string, JsonValue>> {
-  query: string;          // GraphQL mutation string with operation name
-  variables?: T;          // Mutation variables (optional)
-  operationName?: string; // Optional operation name
-  pagination?: PaginationConfig; // Optional pagination configuration for queries
-}
-```
-
-**Example Output:**
-```typescript
-{
-  query: `
-    mutation CreateOrderFromSFCC($input: CreateOrderInput!) {
-      createOrder(input: $input) {
-        id
-        ref
-        status
-        createdOn
-      }
-    }
-  `,
-  variables: {
-    input: {
-      ref: '0017326966182',
-      type: 'STANDARD',
-      retailer: '1',
-      customer: 'CUST-001',
-      items: [
-        { ref: 'PROD-001', productRef: 'PROD-001', quantity: 2 }
-      ]
-    }
-  }
-}
-```
-
-## Path Resolvers
-
-Path resolvers extract data from XML or JSON structures using path expressions.
-
-### XMLPathResolver
-
-Resolves XML paths with attribute support and graceful null/undefined handling.
-
-```typescript
-import { XMLPathResolver } from '@fluentcommerce/fc-connect-sdk';
-
-const resolver = new XMLPathResolver();
-
-// Element access
-const orderNo = resolver.resolve(xmlData, 'order.order-no');
-
-// Attribute access (using @)
-const orderId = resolver.resolve(xmlData, 'order@order-no');
-
-// Array indexing
-const firstItem = resolver.resolve(xmlData, 'items.item[0].sku');
-
-// Wildcard iteration
-const allSkus = resolver.resolve(xmlData, 'items.item.*.sku');
-
-// Graceful handling of undefined/null data
-const value = resolver.resolve(undefined, 'any.path');  // Returns: undefined (no error)
-const value2 = resolver.resolve(null, 'any.path');      // Returns: undefined (no error)
-```
-
-**Path Syntax:**
-- `element.child` - Element traversal
-- `element@attribute` - Attribute access
-- `array[0]` - Array indexing
-- `array.*` - Wildcard (all array items)
-- `element[attr=value]` - Filter by attribute value
-
-**Input Formats Supported:**
-- Raw XML strings (auto-parsed using `parseSync()`)
-- Pre-parsed objects with @-prefix attributes: `{ order: { "@id": "123" } }`
-- Pre-parsed objects with $-object attributes: `{ order: { $: { id: "123" } } }`
-- `undefined` or `null` (returns `undefined` gracefully without errors)
-
-**Methods:**
-- `resolve(data: any, path: string): any` - Resolve path to value (returns undefined for null/undefined data)
-- `exists(data: any, path: string): boolean` - Check if path exists
-- `getType(data: any, path: string): string` - Get value type
-
-**Error Handling:**
-- Gracefully handles `undefined` and `null` input data (returns `undefined`)
-- Throws `PathResolutionError` only for invalid paths or data structure mismatches
-- Safe to use in optional chaining scenarios
-
-### JSONPathResolver
-
-Resolves JSON paths with property access.
-
-```typescript
-import { JSONPathResolver } from '@fluentcommerce/fc-connect-sdk';
-
-const resolver = new JSONPathResolver();
-
-// Property access
-const orderNo = resolver.resolve(jsonData, 'order.orderNo');
-
-// Nested properties
-const email = resolver.resolve(jsonData, 'customer.email');
-
-// Array indexing
-const firstItem = resolver.resolve(jsonData, 'items[0].sku');
-
-// Wildcard iteration
-const allSkus = resolver.resolve(jsonData, 'items.*.sku');
-```
-
-**Path Syntax:**
-- `property.nested` - Property traversal
-- `array[0]` - Array indexing
-- `array.*` - Wildcard (all array items)
-
-**Methods:**
-- `resolve(data: any, path: string): any` - Resolve path to value
-- `exists(data: any, path: string): boolean` - Check if path exists
-- `getType(data: any, path: string): string` - Get value type
-
-## GraphQL Introspection Service
-
-Fetches and caches GraphQL schema information for validation.
-
-```typescript
-import { GraphQLIntrospectionService } from '@fluentcommerce/fc-connect-sdk';
-
-const introspection = new GraphQLIntrospectionService(
-  client: FluentClient,
-  logger?: StructuredLogger,
-  cacheTTL?: number  // Default: 3600000ms (1 hour)
-);
-```
-
-### Methods
-
-#### getSchema
-
-Fetch complete GraphQL schema (cached).
-
-```typescript
-async getSchema(): Promise<GraphQLSchema>
-```
-
-**Returns:**
-- `GraphQLSchema` - Complete schema object with types and mutations
-
-#### getMutation
-
-Get specific mutation definition from schema.
-
-```typescript
-async getMutation(name: string): Promise<GraphQLMutation | null>
-```
-
-**Parameters:**
-- `name: string` - Mutation name (e.g., 'createOrder')
-
-**Returns:**
-- `GraphQLMutation` - Mutation definition with arguments and return type
-- `null` - If mutation not found
-
-**Example:**
-```typescript
-const mutation = await introspection.getMutation('createOrder');
-console.log('Arguments:', mutation.args);
-console.log('Return type:', mutation.type);
-```
-
-#### getInputType
-
-Get input type definition from schema.
-
-```typescript
-async getInputType(typeName: string): Promise<GraphQLInputType | null>
-```
-
-**Parameters:**
-- `typeName: string` - Input type name (e.g., 'CreateOrderInput')
-
-**Returns:**
-- `GraphQLInputType` - Input type definition with fields
-- `null` - If type not found
-
-**Example:**
-```typescript
-const inputType = await introspection.getInputType('CreateOrderInput');
-console.log('Fields:', inputType.inputFields);
-```
-
-#### clearCache
-
-Clear cached schema.
-
-```typescript
-clearCache(): void
-```
-
-## Mapping Configuration
-
-Mapping configurations define how source data maps to GraphQL mutation arguments.
-
-### MappingConfig Interface
-
-```typescript
-interface MappingConfig {
-  // Core Configuration
-  version: string;                    // Config version (e.g., '1.0')
-  name?: string;                      // Mapping name
-  description?: string;               // Description
-
-  // GraphQL Mutation Configuration
-  mutation: string;                   // GraphQL mutation name (e.g., 'createOrder')
-  operationName?: string;             // Operation name for debugging
-  sourceFormat: 'xml' | 'json' | 'jsonl';  // Source data format (determines path resolver)
-
-  // Validation & Processing
-  schemaValidation?: boolean;         // Enable validation (default: true)
-
-  // Field Mappings (choose one pattern)
-  arguments?: Record<string, FieldConfig>;  // Mutation arguments (Pattern 1 - older approach)
-  fields?: Record<string, FieldConfig>;     // Universal field mappings (Pattern 2 - preferred)
-
-  // Return Configuration
-  returnFields?: string[];            // Fields to return from mutation (defaults to ['id', 'ref'])
-
-  // Optional: Alias batching configuration
-  aliasBatching?: {
-    enabled?: boolean;
-    mutationsPerBatch?: number;
-    maxMutationsPerBatch?: number;
-  };
-}
-```
-
-**Key Fields:**
-
-- **`mutation`** (required): GraphQL mutation name (e.g., `'createOrder'`). Used by `buildMutationQuery()` to generate the GraphQL mutation string.
-
-- **`sourceFormat`** (required): Determines which path resolver to use:
-  - `'xml'` → Uses `XMLPathResolver` (handles XML paths like `order.order-no`, `order@id`)
-  - `'json'` → Uses `JSONPathResolver` (handles JSON paths like `order.orderNo`, `order.id`)
-  - `'jsonl'` → Uses `JSONPathResolver` (same as JSON)
-
-**Example Configuration:**
-```typescript
-const mappingConfig: MappingConfig = {
-  version: '1.0',
-  mutation: 'createOrder',
-  sourceFormat: 'xml',  // ← Determines XMLPathResolver vs JSONPathResolver
-  fields: {
-    ref: { source: 'order@order-no', required: true },  // ← XML attribute syntax
-    totalPrice: { source: 'order.total', resolver: 'sdk.parseFloat' }
-  }
-};
-```
-
-**Note:** `direction` is NOT part of `MappingConfig`. It's only used in `MappingTemplate` (for template generation metadata) and is not used by `GraphQLMutationMapper`.
-
-### FieldConfig Interface
-
-```typescript
-interface FieldConfig {
-  // Value source
-  source?: string;        // Path to source data (supports wildcards like "items[*].node")
-  value?: any;           // Static value
-
-  // Validation
-  required?: boolean;     // Field is required. See note below about validation timing with resolvers.
-  _type?: string;        // GraphQL type (for validation)
-
-  // Transformation
-  transform?: string;     // Transformation function name
-  resolver?: string;     // Resolver function (sdk.* or custom.*)
-  defaultValue?: any;    // Default value if missing
-
-  // Array handling
-  _array?: boolean;       // Field is array (GraphQL mutation mapper)
-  isArray?: boolean;      // Treat source as array and map each element (UniversalMapper)
-  _autoWrap?: boolean;    // Wrap single value in array
-  _validation?: {
-    minItems?: number;
-    maxItems?: number;
-  };
-
-  // Nested objects/arrays
-  _nested?: boolean;      // Field is nested object (GraphQL mutation mapper)
-  fields?: Record<string, FieldConfig>;  // Nested field mappings (UniversalMapper)
-
-  // Metadata
-  description?: string;   // Field description
-  _comment?: string;      // Comment for documentation
-
-  // Nested fields (for objects and arrays - GraphQL mutation mapper)
-  [key: string]: any;     // Child field configurations
-}
-```
-
-**Array Field Mapping (`isArray` option):**
-
-When `isArray: true` is set along with `fields`, the mapper treats the source as an array and maps each element using the nested field mappings:
-
-```json
-{
-  "items": {
-    "source": "orderItems",
-    "isArray": true,
-    "fields": {
-      "id": { "source": "id" },
-      "name": { "source": "name" },
-      "quantity": { "source": "qty", "resolver": "sdk.parseInt" }
-    }
-  }
-}
-```
-
-This configuration:
-1. Extracts array from `orderItems`
-2. Maps each array element using the nested `fields` configuration
-3. Uses each array item as the context for nested field mapping
-
-**GraphQL Pagination Pattern:**
-
-Handle GraphQL edges/nodes with three equivalent patterns:
-
-**Option 1: Wildcard (extracts nodes)**
-```json
-{
-  "products": {
-    "source": "products.edges[*].node",
-    "isArray": true,
-    "fields": {
-      "id": { "source": "id" },       // Direct access
-      "ref": { "source": "ref" }
-    }
-  }
-}
-```
-
-**Option 2: Direct (extracts edges)**
-```json
-{
-  "products": {
-    "source": "products.edges",
-    "isArray": true,
-    "fields": {
-      "id": { "source": "node.id" },  // Need "node." prefix
-      "ref": { "source": "node.ref" }
-    }
-  }
-}
-```
-
-**Option 3: Auto-detection**
-```json
-{
-  "products": {
-    "source": "products",             // SDK detects { edges: [...] }
-    "isArray": true,
-    "fields": {
-      "id": { "source": "id" },       // Nodes auto-extracted
-      "ref": { "source": "ref" }
-    }
-  }
-}
-```
-
-The `[*]` wildcard is **optional** - all three patterns produce the same result.
-
-### Complete Configuration Example
-
-```json
-{
-  "version": "1.0",
-  "name": "SFCC Order to Fluent",
-  "description": "Maps SFCC order XML to Fluent createOrder mutation",
-  "mutation": "createOrder",
-  "operationName": "CreateOrderFromSFCC",
-  "sourceFormat": "xml",
-  "schemaValidation": true,
-
-  "arguments": {
-    "input": {
-      "_type": "CreateOrderInput!",
-
-      "ref": {
-        "source": "orders.order@order-no",
-        "required": true,
-        "description": "Order reference from SFCC"
-      },
-
-      "type": {
-        "value": "STANDARD",
-        "required": true
-      },
-
-      "retailer": {
-        "value": "${FLUENT_RETAILER_ID}",
-        "required": true
-      },
-
-      "items": {
-        "_type": "[CreateOrderItemInput]!",
-        "_array": true,
-        "source": "orders.order.product-lineitems.product-lineitem",
-        "_validation": {
-          "minItems": 1,
-          "maxItems": 100
-        },
-
-        "ref": {
-          "source": "product-id",
-          "required": true
-        },
-
-        "quantity": {
-          "source": "quantity",
-          "transform": "parseInt",
-          "required": true,
-          "defaultValue": 1
-        },
-
-        "paidPrice": {
-          "source": "net-price",
-          "transform": "parseFloat"
-        }
-      },
-
-      "fulfilmentChoice": {
-        "_type": "CreateFulfilmentChoiceInput",
-        "_nested": true,
-
-        "deliveryAddress": {
-          "_type": "CreateCustomerAddressInput",
-          "_nested": true,
-          "source": "orders.order.shipments.shipment.shipping-address",
-
-          "city": {
-            "source": "city",
-            "required": true
-          },
-
-          "country": {
-            "source": "country-code",
-            "required": true,
-            "transform": "toUpperCase"
-          }
-        }
-      }
-    }
-  },
-
-  "returnFields": ["id", "ref", "status", "createdOn"]
-}
-```
-
-### MappingHooks Interface
-
-Lifecycle hooks for custom preprocessing and postprocessing.
-
-```typescript
-interface MappingHooks {
-  beforeMapping?: (
-    sourceData: any,
-    context: MappingContext
-  ) => Promise<any> | any;
-
-  afterMapping?: (
-    variables: Record<string, any>,
-    context: MappingContext
-  ) => Promise<Record<string, any>> | Record<string, any>;
-}
-```
-
-**MappingContext Interface:**
-```typescript
-interface MappingContext {
-  mutation: string;
-  sourceFormat: 'xml' | 'json';
-  logger?: StructuredLogger;
-  metadata?: Record<string, any>;
-}
-```
-
-**Example Hooks:**
-```typescript
-const hooks: MappingHooks = {
-  beforeMapping: async (sourceData, context) => {
-    // Parse custom attributes
-    if (sourceData.customAttributes) {
-      sourceData.parsed = parseCustomAttributes(sourceData.customAttributes);
-    }
-    return sourceData;
-  },
-
-  afterMapping: async (variables, context) => {
-    // Calculate order total
-    variables.input.totalPrice = variables.input.items.reduce(
-      (sum, item) => sum + (item.paidPrice * item.quantity),
-      0
-    );
-
-    // Add metadata
-    variables.input.attributes = variables.input.attributes || [];
-    variables.input.attributes.push({
-      name: 'integration_source',
-      type: 'STRING',
-      value: JSON.stringify('SFCC')
-    });
-
-    return variables;
-  }
-};
-
-const payload = await mapper.map(sourceData, hooks);
-```
-
-### Built-in Transformations
-
-The mapper supports these built-in transformation functions:
-
-| Transform | Description | Example |
-|-----------|-------------|---------|
-| `parseInt` | Parse integer | `"42"` → `42` |
-| `parseFloat` | Parse float | `"3.14"` → `3.14` |
-| `toString` | Convert to string | `42` → `"42"` |
-| `toUpperCase` | Uppercase string | `"usa"` → `"USA"` |
-| `toLowerCase` | Lowercase string | `"USA"` → `"usa"` |
-| `trim` | Trim whitespace | `" text "` → `"text"` |
-| `toBoolean` | Parse boolean | `"true"` → `true` |
-| `toISO8601` | Format date | `Date` → `"2025-01-01T00:00:00Z"` |
-| `toDate` | Parse date | `"2025-01-01"` → `Date` |
-
-**Usage in Configuration:**
-```json
-{
-  "quantity": {
-    "source": "qty",
-    "transform": "parseInt"
-  },
-  "country": {
-    "source": "country_code",
-    "transform": "toUpperCase"
-  },
-  "updatedAt": {
-    "source": "last_modified",
-    "transform": "toISO8601"
-  }
-}
-```
-
-### Custom Transformations
-
-Add custom transformation functions during mapper initialization.
-
-```typescript
-const mapper = new GraphQLMutationMapper(
-  mappingConfig,
-  logger,
-  {
-    fluentClient: client,
-    customTransforms: {
-      toPhoneNumber: (value: string) => {
-        return value.replace(/\D/g, '').slice(0, 10);
-      },
-
-      calculateTotal: (items: any[]) => {
-        return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
-      },
-
-      formatAddress: (address: any) => {
-        return `${address.street}, ${address.city}, ${address.state} ${address.zip}`;
-      }
-    }
-  }
-);
-```
-
-**Use in Configuration:**
-```json
-{
-  "phone": {
-    "source": "customer.phone",
-    "transform": "toPhoneNumber"
-  },
-  "total": {
-    "source": "orderItems",
-    "transform": "calculateTotal"
-  }
-}
-```
-
-## Complete Examples
-
-### Complete Mapping Example
-
-```typescript
-import {
-  createClient,
-  GraphQLMutationMapper,
-  XMLParserService,
-  MappingHooks
-} from '@fluentcommerce/fc-connect-sdk';
-import mappingConfig from './mappings/sfcc-order-to-fluent.json';
-import { readFileSync } from 'fs';
-
-// 1. Initialize client
-const client = await createClient({
-  config: {
-    baseUrl: 'https://api.fluentcommerce.com',
-    clientId: process.env.FLUENT_CLIENT_ID,
-    clientSecret: process.env.FLUENT_CLIENT_SECRET,
-    username: process.env.FLUENT_USERNAME,
-    password: process.env.FLUENT_PASSWORD,
-    retailerId: '1'
-  }
-});
-
-// 2. Parse XML
-const xmlParser = new XMLParserService();
-const xmlContent = readFileSync('order.xml', 'utf-8');
-const parsedXml = await xmlParser.parse(xmlContent, {
-  includeAttributes: true,
-  attributePrefix: '@'
-});
-
-// 3. Configure hooks
-const hooks: MappingHooks = {
-  beforeMapping: async (data, context) => {
-    context.logger?.info('Preprocessing order data');
-    return data;
-  },
-
-  afterMapping: async (variables, context) => {
-    // Calculate total
-    variables.input.totalPrice = variables.input.items.reduce(
-      (sum, item) => sum + (item.paidPrice * item.quantity),
-      0
-    );
-
-    // Add audit metadata
-    variables.input.attributes = variables.input.attributes || [];
-    variables.input.attributes.push({
-      name: 'integration_source',
-      type: 'STRING',
-      value: JSON.stringify('SFCC')
-    });
-
-    context.logger?.info('Order total calculated', {
-      total: variables.input.totalPrice
-    });
-
-    return variables;
-  }
-};
-
-// 4. Initialize mapper
-const mapper = new GraphQLMutationMapper(
-  mappingConfig as any,
-  console,
-  { fluentClient: client }
-);
-
-// 5. Map data
-const payload = await mapper.map(parsedXml, hooks);
-
-// 6. Execute mutation
-const result = await client.graphql(payload);
-
-console.log('Order created:', result.data.createOrder);
-```
-
-### Environment Variables in Mappings
-
-Use environment variables for dynamic values:
-
-```json
-{
-  "retailer": {
-    "value": "${FLUENT_RETAILER_ID}",
-    "required": true
-  },
-  "createdBy": {
-    "value": "${INTEGRATION_NAME}"
-  }
-}
-```
-
-**Runtime Resolution:**
-- `"${FLUENT_RETAILER_ID}"` resolves to `process.env.FLUENT_RETAILER_ID`
-- Non-env strings pass through unchanged
-
-### Error Handling
-
-The mapper throws `MappingError` for validation failures:
-
-```typescript
-import { MappingError } from '@fluentcommerce/fc-connect-sdk';
-
-try {
-  const payload = await mapper.map(sourceData);
-} catch (error) {
-  if (error instanceof MappingError) {
-    console.error('Mapping failed:', {
-      field: error.field,
-      sourcePath: error.sourcePath,
-      message: error.message,
-      expectedType: error.expectedType,
-      actualType: error.actualType
-    });
-  }
-}
-```
-
-**Common Errors:**
-- `Required field 'ref' is missing or empty`
-- `Expected array but got object at path 'items'`
-- `Type mismatch: expected Int! but got String`
-- `Cannot resolve path 'order.missing'`
-
-## See Also
-
-- [GraphQL Mutation Mapping Guide](../../mapping/graphql-mutation-mapping/graphql-mutation-mapping-readme.md) - Detailed guide
-- [Module 7: Parsers](./api-reference-07-parsers.md) - XML and JSON parsers
-- [Module 5: Services](./api-reference-05-services.md) - UniversalMapper service
-- [Module 9: Error Handling](./api-reference-09-error-handling.md) - Error types and handling
-- [Examples: GraphQL Operations](../examples/) - See examples directory
-
----
-
-**[← Previous: Authentication](./api-reference-03-authentication.md)** | **[API Reference Home](../api-reference-readme.md)** | **[Next: Services →](./api-reference-05-services.md)**
+# Module 4: GraphQL Mutation Mapping
+
+**Level:** Advanced
+**Category:** Data Transformation
+
+## Overview
+
+The GraphQL Mutation Mapping system provides schema-driven transformation of XML/JSON data into GraphQL mutation inputs with full validation and type safety.
+
+## Table of Contents
+
+- [GraphQLMutationMapper](#graphqlmutationmapper)
+- [Path Resolvers](#path-resolvers)
+- [GraphQL Introspection Service](#graphql-introspection-service)
+- [Mapping Configuration](#mapping-configuration)
+- [Complete Examples](#complete-examples)
+- [See Also](#see-also)
+
+---
+
+## GraphQLMutationMapper
+
+Main class for mapping source data to GraphQL mutations.
+
+### Constructor
+
+```typescript
+import { GraphQLMutationMapper } from '@fluentcommerce/fc-connect-sdk';
+
+const mapper = new GraphQLMutationMapper(
+  config: MappingConfig,
+  logger?: StructuredLogger,
+  options?: MappingOptions
+);
+```
+
+**Parameters:**
+- `config: MappingConfig` - Mapping configuration object
+- `logger?: StructuredLogger` - Optional logger instance
+- `options?: MappingOptions` - Optional configuration (customResolvers, fluentClient, context)
+
+**MappingOptions Interface:**
+```typescript
+interface MappingOptions {
+  /** Custom resolver functions (stored and used by mapWithNodes) */
+  customResolvers?: ResolversMap;
+  
+  /** Custom transform functions (for map() method) */
+  customTransforms?: Record<string, TransformFunction>;
+  
+  /** Schema cache TTL in milliseconds (default: 3600000) */
+  schemaCacheTTL?: number;
+}
+```
+
+**Usage:** `customResolvers` should be passed in the constructor (consistent with `UniversalMapper`). Method call resolvers can override constructor resolvers for per-call customization. Constructor resolvers are merged with method call resolvers, with method call resolvers taking precedence.
+
+### map Method
+
+Transform source data into a GraphQL mutation payload.
+
+```typescript
+async map(
+  sourceData: unknown,
+  hooks?: MappingHooks
+): Promise<GraphQLPayload>
+```
+
+**Parameters:**
+- `sourceData: unknown` - XML or JSON source data (already parsed)
+- `hooks?: MappingHooks` - Optional lifecycle hooks
+
+**Returns:**
+- `GraphQLPayload` - Object with `query` and `variables` properties
+
+**Example:**
+```typescript
+import { GraphQLMutationMapper } from '@fluentcommerce/fc-connect-sdk';
+import mappingConfig from './mappings/sfcc-order-to-fluent.json';
+
+const mapper = new GraphQLMutationMapper(mappingConfig, logger);
+
+// Map XML data to createOrder mutation
+const payload = await mapper.map(parsedXmlData, {
+  beforeMapping: async (data, context) => {
+    // Preprocess data before mapping
+    return data;
+  },
+  afterMapping: async (variables, context) => {
+    // Post-process mapped variables
+    variables.input.totalPrice = calculateTotal(variables.input.items);
+    return variables;
+  }
+});
+
+// Execute mutation
+const result = await fluentClient.graphql(payload);
+```
+
+### mapWithNodes Method
+
+Transform source data with custom resolvers and XML node extraction support.
+
+```typescript
+async mapWithNodes(
+  rootData: unknown,
+  resolvers?: ResolversMap,
+  context?: ResolverContext
+): Promise<MapWithNodesResult>
+```
+
+**Parameters:**
+- `rootData: unknown` - Source data (XML/JSON, already parsed)
+- `resolvers?: ResolversMap` - Optional custom resolver functions (overrides constructor resolvers)
+- `context?: ResolverContext` - Optional context with fluentClient, config, helpers
+
+**Returns:**
+- `MapWithNodesResult` - Object with `success`, `data`, `variables`, `query`, `context`, and `errors`
+
+**MapWithNodesResult Interface:**
+```typescript
+interface MapWithNodesResult {
+  /** Whether mapping succeeded */
+  success: boolean;
+
+  /** Unwrapped mapped data (for direct field access: result.data.orderNo) */
+  data: Record<string, any>;
+
+  /** Wrapped variables for GraphQL execution (use this in client.graphql())
+   * - Fields pattern: { input: { ... } }
+   * - Arguments pattern: { ... } (unwrapped)
+   */
+  variables: Record<string, any>;
+
+  /** GraphQL mutation query string (auto-generated) */
+  query: string;
+
+  /** Extracted nodes context */
+  context: NodesContext;
+
+  /** Error messages (if any) */
+  errors: string[];
+}
+```
+
+**Example:**
+```typescript
+import { GraphQLMutationMapper } from '@fluentcommerce/fc-connect-sdk';
+
+const mapper = new GraphQLMutationMapper(mappingConfig, logger, {
+  customResolvers: baseResolvers,  // Constructor resolvers
+  fluentClient: fluentClient  // Available as helpers.fluentClient in resolvers
+});
+
+// Map with custom resolvers and XML nodes
+// Pass resolverContext - resolvers can access config via helpers.context.config
+const resolverContext = {
+  fluentClient,
+  config: { retailerId: '1', defaultOrderType: 'HD' },
+  helpers: { fluentClient }
+};
+const result = await mapper.mapWithNodes(xmlData, overrideResolvers, resolverContext);
+
+// In your resolver, access config:
+// const retailerId = helpers.context?.config?.retailerId;
+// OR use the config parameter directly:
+// const retailerId = config?.retailerId;
+
+// Check success (errors are returned, not thrown)
+if (!result.success) {
+  console.error('Mapping failed:', result.errors);
+  return;
+}
+
+// Execute mutation (use result.variables for GraphQL, result.data for field access)
+await fluentClient.graphql({
+  query: result.query,
+  variables: result.variables  // ✅ Use variables (wrapped if fields pattern)
+});
+
+// Access mapped fields directly (unwrapped)
+const orderRef = result.data.ref;  // ✅ Use data for direct field access
+```
+
+**Key Features:**
+- ✅ **Custom resolvers** - Full access to source data and helpers
+- ✅ **XML node extraction** - Extract nested/escaped XML segments
+- ✅ **Context passing** - FluentClient, config, helpers available to resolvers
+- ✅ **Auto-generated query** - No need to call `buildMutation()` separately
+- ✅ **Error handling** - Returns error result instead of throwing
+
+### GraphQLPayload Interface
+
+```typescript
+interface GraphQLPayload<T = Record<string, JsonValue>> {
+  query: string;          // GraphQL mutation string with operation name
+  variables?: T;          // Mutation variables (optional)
+  operationName?: string; // Optional operation name
+  pagination?: PaginationConfig; // Optional pagination configuration for queries
+}
+```
+
+**Example Output:**
+```typescript
+{
+  query: `
+    mutation CreateOrderFromSFCC($input: CreateOrderInput!) {
+      createOrder(input: $input) {
+        id
+        ref
+        status
+        createdOn
+      }
+    }
+  `,
+  variables: {
+    input: {
+      ref: '0017326966182',
+      type: 'STANDARD',
+      retailer: '1',
+      customer: 'CUST-001',
+      items: [
+        { ref: 'PROD-001', productRef: 'PROD-001', quantity: 2 }
+      ]
+    }
+  }
+}
+```
+
+## Path Resolvers
+
+Path resolvers extract data from XML or JSON structures using path expressions.
+
+### XMLPathResolver
+
+Resolves XML paths with attribute support and graceful null/undefined handling.
+
+```typescript
+import { XMLPathResolver } from '@fluentcommerce/fc-connect-sdk';
+
+const resolver = new XMLPathResolver();
+
+// Element access
+const orderNo = resolver.resolve(xmlData, 'order.order-no');
+
+// Attribute access (using @)
+const orderId = resolver.resolve(xmlData, 'order@order-no');
+
+// Array indexing
+const firstItem = resolver.resolve(xmlData, 'items.item[0].sku');
+
+// Wildcard iteration
+const allSkus = resolver.resolve(xmlData, 'items.item.*.sku');
+
+// Graceful handling of undefined/null data
+const value = resolver.resolve(undefined, 'any.path');  // Returns: undefined (no error)
+const value2 = resolver.resolve(null, 'any.path');      // Returns: undefined (no error)
+```
+
+**Path Syntax:**
+- `element.child` - Element traversal
+- `element@attribute` - Attribute access
+- `array[0]` - Array indexing
+- `array.*` - Wildcard (all array items)
+- `element[attr=value]` - Filter by attribute value
+
+**Input Formats Supported:**
+- Raw XML strings (auto-parsed using `parseSync()`)
+- Pre-parsed objects with @-prefix attributes: `{ order: { "@id": "123" } }`
+- Pre-parsed objects with $-object attributes: `{ order: { $: { id: "123" } } }`
+- `undefined` or `null` (returns `undefined` gracefully without errors)
+
+**Methods:**
+- `resolve(data: any, path: string): any` - Resolve path to value (returns undefined for null/undefined data)
+- `exists(data: any, path: string): boolean` - Check if path exists
+- `getType(data: any, path: string): string` - Get value type
+
+**Error Handling:**
+- Gracefully handles `undefined` and `null` input data (returns `undefined`)
+- Throws `PathResolutionError` only for invalid paths or data structure mismatches
+- Safe to use in optional chaining scenarios
+
+### JSONPathResolver
+
+Resolves JSON paths with property access.
+
+```typescript
+import { JSONPathResolver } from '@fluentcommerce/fc-connect-sdk';
+
+const resolver = new JSONPathResolver();
+
+// Property access
+const orderNo = resolver.resolve(jsonData, 'order.orderNo');
+
+// Nested properties
+const email = resolver.resolve(jsonData, 'customer.email');
+
+// Array indexing
+const firstItem = resolver.resolve(jsonData, 'items[0].sku');
+
+// Wildcard iteration
+const allSkus = resolver.resolve(jsonData, 'items.*.sku');
+```
+
+**Path Syntax:**
+- `property.nested` - Property traversal
+- `array[0]` - Array indexing
+- `array.*` - Wildcard (all array items)
+
+**Methods:**
+- `resolve(data: any, path: string): any` - Resolve path to value
+- `exists(data: any, path: string): boolean` - Check if path exists
+- `getType(data: any, path: string): string` - Get value type
+
+## GraphQL Introspection Service
+
+Fetches and caches GraphQL schema information for validation.
+
+```typescript
+import { GraphQLIntrospectionService } from '@fluentcommerce/fc-connect-sdk';
+
+const introspection = new GraphQLIntrospectionService(
+  client: FluentClient,
+  logger?: StructuredLogger,
+  cacheTTL?: number  // Default: 3600000ms (1 hour)
+);
+```
+
+### Methods
+
+#### getSchema
+
+Fetch complete GraphQL schema (cached).
+
+```typescript
+async getSchema(): Promise<GraphQLSchema>
+```
+
+**Returns:**
+- `GraphQLSchema` - Complete schema object with types and mutations
+
+#### getMutation
+
+Get specific mutation definition from schema.
+
+```typescript
+async getMutation(name: string): Promise<GraphQLMutation | null>
+```
+
+**Parameters:**
+- `name: string` - Mutation name (e.g., 'createOrder')
+
+**Returns:**
+- `GraphQLMutation` - Mutation definition with arguments and return type
+- `null` - If mutation not found
+
+**Example:**
+```typescript
+const mutation = await introspection.getMutation('createOrder');
+console.log('Arguments:', mutation.args);
+console.log('Return type:', mutation.type);
+```
+
+#### getInputType
+
+Get input type definition from schema.
+
+```typescript
+async getInputType(typeName: string): Promise<GraphQLInputType | null>
+```
+
+**Parameters:**
+- `typeName: string` - Input type name (e.g., 'CreateOrderInput')
+
+**Returns:**
+- `GraphQLInputType` - Input type definition with fields
+- `null` - If type not found
+
+**Example:**
+```typescript
+const inputType = await introspection.getInputType('CreateOrderInput');
+console.log('Fields:', inputType.inputFields);
+```
+
+#### clearCache
+
+Clear cached schema.
+
+```typescript
+clearCache(): void
+```
+
+## Mapping Configuration
+
+Mapping configurations define how source data maps to GraphQL mutation arguments.
+
+### MappingConfig Interface
+
+```typescript
+interface MappingConfig {
+  // Core Configuration
+  version: string;                    // Config version (e.g., '1.0')
+  name?: string;                      // Mapping name
+  description?: string;               // Description
+
+  // GraphQL Mutation Configuration
+  mutation: string;                   // GraphQL mutation name (e.g., 'createOrder')
+  operationName?: string;             // Operation name for debugging
+  sourceFormat: 'xml' | 'json' | 'jsonl';  // Source data format (determines path resolver)
+
+  // Validation & Processing
+  schemaValidation?: boolean;         // Enable validation (default: true)
+
+  // Field Mappings (choose one pattern)
+  arguments?: Record<string, FieldConfig>;  // Mutation arguments (Pattern 1 - older approach)
+  fields?: Record<string, FieldConfig>;     // Universal field mappings (Pattern 2 - preferred)
+
+  // Return Configuration
+  returnFields?: string[];            // Fields to return from mutation (defaults to ['id', 'ref'])
+
+  // Optional: Alias batching configuration
+  aliasBatching?: {
+    enabled?: boolean;
+    mutationsPerBatch?: number;
+    maxMutationsPerBatch?: number;
+  };
+}
+```
+
+**Key Fields:**
+
+- **`mutation`** (required): GraphQL mutation name (e.g., `'createOrder'`). Used by `buildMutationQuery()` to generate the GraphQL mutation string.
+
+- **`sourceFormat`** (required): Determines which path resolver to use:
+  - `'xml'` → Uses `XMLPathResolver` (handles XML paths like `order.order-no`, `order@id`)
+  - `'json'` → Uses `JSONPathResolver` (handles JSON paths like `order.orderNo`, `order.id`)
+  - `'jsonl'` → Uses `JSONPathResolver` (same as JSON)
+
+**Example Configuration:**
+```typescript
+const mappingConfig: MappingConfig = {
+  version: '1.0',
+  mutation: 'createOrder',
+  sourceFormat: 'xml',  // ← Determines XMLPathResolver vs JSONPathResolver
+  fields: {
+    ref: { source: 'order@order-no', required: true },  // ← XML attribute syntax
+    totalPrice: { source: 'order.total', resolver: 'sdk.parseFloat' }
+  }
+};
+```
+
+**Note:** `direction` is NOT part of `MappingConfig`. It's only used in `MappingTemplate` (for template generation metadata) and is not used by `GraphQLMutationMapper`.
+
+### FieldConfig Interface
+
+```typescript
+interface FieldConfig {
+  // Value source
+  source?: string;        // Path to source data (supports wildcards like "items[*].node")
+  value?: any;           // Static value
+
+  // Validation
+  required?: boolean;     // Field is required. See note below about validation timing with resolvers.
+  _type?: string;        // GraphQL type (for validation)
+
+  // Transformation
+  transform?: string;     // Transformation function name
+  resolver?: string;     // Resolver function (sdk.* or custom.*)
+  defaultValue?: any;    // Default value if missing
+
+  // Array handling
+  _array?: boolean;       // Field is array (GraphQL mutation mapper)
+  isArray?: boolean;      // Treat source as array and map each element (UniversalMapper)
+  _autoWrap?: boolean;    // Wrap single value in array
+  _validation?: {
+    minItems?: number;
+    maxItems?: number;
+  };
+
+  // Nested objects/arrays
+  _nested?: boolean;      // Field is nested object (GraphQL mutation mapper)
+  fields?: Record<string, FieldConfig>;  // Nested field mappings (UniversalMapper)
+
+  // Metadata
+  description?: string;   // Field description
+  _comment?: string;      // Comment for documentation
+
+  // Nested fields (for objects and arrays - GraphQL mutation mapper)
+  [key: string]: any;     // Child field configurations
+}
+```
+
+**Array Field Mapping (`isArray` option):**
+
+When `isArray: true` is set along with `fields`, the mapper treats the source as an array and maps each element using the nested field mappings:
+
+```json
+{
+  "items": {
+    "source": "orderItems",
+    "isArray": true,
+    "fields": {
+      "id": { "source": "id" },
+      "name": { "source": "name" },
+      "quantity": { "source": "qty", "resolver": "sdk.parseInt" }
+    }
+  }
+}
+```
+
+This configuration:
+1. Extracts array from `orderItems`
+2. Maps each array element using the nested `fields` configuration
+3. Uses each array item as the context for nested field mapping
+
+**GraphQL Pagination Pattern:**
+
+Handle GraphQL edges/nodes with three equivalent patterns:
+
+**Option 1: Wildcard (extracts nodes)**
+```json
+{
+  "products": {
+    "source": "products.edges[*].node",
+    "isArray": true,
+    "fields": {
+      "id": { "source": "id" },       // Direct access
+      "ref": { "source": "ref" }
+    }
+  }
+}
+```
+
+**Option 2: Direct (extracts edges)**
+```json
+{
+  "products": {
+    "source": "products.edges",
+    "isArray": true,
+    "fields": {
+      "id": { "source": "node.id" },  // Need "node." prefix
+      "ref": { "source": "node.ref" }
+    }
+  }
+}
+```
+
+**Option 3: Auto-detection**
+```json
+{
+  "products": {
+    "source": "products",             // SDK detects { edges: [...] }
+    "isArray": true,
+    "fields": {
+      "id": { "source": "id" },       // Nodes auto-extracted
+      "ref": { "source": "ref" }
+    }
+  }
+}
+```
+
+The `[*]` wildcard is **optional** - all three patterns produce the same result.
+
+### Complete Configuration Example
+
+```json
+{
+  "version": "1.0",
+  "name": "SFCC Order to Fluent",
+  "description": "Maps SFCC order XML to Fluent createOrder mutation",
+  "mutation": "createOrder",
+  "operationName": "CreateOrderFromSFCC",
+  "sourceFormat": "xml",
+  "schemaValidation": true,
+
+  "arguments": {
+    "input": {
+      "_type": "CreateOrderInput!",
+
+      "ref": {
+        "source": "orders.order@order-no",
+        "required": true,
+        "description": "Order reference from SFCC"
+      },
+
+      "type": {
+        "value": "STANDARD",
+        "required": true
+      },
+
+      "retailer": {
+        "value": "${FLUENT_RETAILER_ID}",
+        "required": true
+      },
+
+      "items": {
+        "_type": "[CreateOrderItemInput]!",
+        "_array": true,
+        "source": "orders.order.product-lineitems.product-lineitem",
+        "_validation": {
+          "minItems": 1,
+          "maxItems": 100
+        },
+
+        "ref": {
+          "source": "product-id",
+          "required": true
+        },
+
+        "quantity": {
+          "source": "quantity",
+          "transform": "parseInt",
+          "required": true,
+          "defaultValue": 1
+        },
+
+        "paidPrice": {
+          "source": "net-price",
+          "transform": "parseFloat"
+        }
+      },
+
+      "fulfilmentChoice": {
+        "_type": "CreateFulfilmentChoiceInput",
+        "_nested": true,
+
+        "deliveryAddress": {
+          "_type": "CreateCustomerAddressInput",
+          "_nested": true,
+          "source": "orders.order.shipments.shipment.shipping-address",
+
+          "city": {
+            "source": "city",
+            "required": true
+          },
+
+          "country": {
+            "source": "country-code",
+            "required": true,
+            "transform": "toUpperCase"
+          }
+        }
+      }
+    }
+  },
+
+  "returnFields": ["id", "ref", "status", "createdOn"]
+}
+```
+
+### MappingHooks Interface
+
+Lifecycle hooks for custom preprocessing and postprocessing.
+
+```typescript
+interface MappingHooks {
+  beforeMapping?: (
+    sourceData: any,
+    context: MappingContext
+  ) => Promise<any> | any;
+
+  afterMapping?: (
+    variables: Record<string, any>,
+    context: MappingContext
+  ) => Promise<Record<string, any>> | Record<string, any>;
+}
+```
+
+**MappingContext Interface:**
+```typescript
+interface MappingContext {
+  mutation: string;
+  sourceFormat: 'xml' | 'json';
+  logger?: StructuredLogger;
+  metadata?: Record<string, any>;
+}
+```
+
+**Example Hooks:**
+```typescript
+const hooks: MappingHooks = {
+  beforeMapping: async (sourceData, context) => {
+    // Parse custom attributes
+    if (sourceData.customAttributes) {
+      sourceData.parsed = parseCustomAttributes(sourceData.customAttributes);
+    }
+    return sourceData;
+  },
+
+  afterMapping: async (variables, context) => {
+    // Calculate order total
+    variables.input.totalPrice = variables.input.items.reduce(
+      (sum, item) => sum + (item.paidPrice * item.quantity),
+      0
+    );
+
+    // Add metadata
+    variables.input.attributes = variables.input.attributes || [];
+    variables.input.attributes.push({
+      name: 'integration_source',
+      type: 'STRING',
+      value: JSON.stringify('SFCC')
+    });
+
+    return variables;
+  }
+};
+
+const payload = await mapper.map(sourceData, hooks);
+```
+
+### Built-in Transformations
+
+The mapper supports these built-in transformation functions:
+
+| Transform | Description | Example |
+|-----------|-------------|---------|
+| `parseInt` | Parse integer | `"42"` → `42` |
+| `parseFloat` | Parse float | `"3.14"` → `3.14` |
+| `toString` | Convert to string | `42` → `"42"` |
+| `toUpperCase` | Uppercase string | `"usa"` → `"USA"` |
+| `toLowerCase` | Lowercase string | `"USA"` → `"usa"` |
+| `trim` | Trim whitespace | `" text "` → `"text"` |
+| `toBoolean` | Parse boolean | `"true"` → `true` |
+| `toISO8601` | Format date | `Date` → `"2025-01-01T00:00:00Z"` |
+| `toDate` | Parse date | `"2025-01-01"` → `Date` |
+
+**Usage in Configuration:**
+```json
+{
+  "quantity": {
+    "source": "qty",
+    "transform": "parseInt"
+  },
+  "country": {
+    "source": "country_code",
+    "transform": "toUpperCase"
+  },
+  "updatedAt": {
+    "source": "last_modified",
+    "transform": "toISO8601"
+  }
+}
+```
+
+### Custom Transformations
+
+Add custom transformation functions during mapper initialization.
+
+```typescript
+const mapper = new GraphQLMutationMapper(
+  mappingConfig,
+  logger,
+  {
+    fluentClient: client,
+    customTransforms: {
+      toPhoneNumber: (value: string) => {
+        return value.replace(/\D/g, '').slice(0, 10);
+      },
+
+      calculateTotal: (items: any[]) => {
+        return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
+      },
+
+      formatAddress: (address: any) => {
+        return `${address.street}, ${address.city}, ${address.state} ${address.zip}`;
+      }
+    }
+  }
+);
+```
+
+**Use in Configuration:**
+```json
+{
+  "phone": {
+    "source": "customer.phone",
+    "transform": "toPhoneNumber"
+  },
+  "total": {
+    "source": "orderItems",
+    "transform": "calculateTotal"
+  }
+}
+```
+
+## Complete Examples
+
+### Complete Mapping Example
+
+```typescript
+import {
+  createClient,
+  GraphQLMutationMapper,
+  XMLParserService,
+  MappingHooks
+} from '@fluentcommerce/fc-connect-sdk';
+import mappingConfig from './mappings/sfcc-order-to-fluent.json';
+import { readFileSync } from 'fs';
+
+// 1. Initialize client
+const client = await createClient({
+  config: {
+    baseUrl: 'https://api.fluentcommerce.com',
+    clientId: process.env.FLUENT_CLIENT_ID,
+    clientSecret: process.env.FLUENT_CLIENT_SECRET,
+    username: process.env.FLUENT_USERNAME,
+    password: process.env.FLUENT_PASSWORD,
+    retailerId: '1'
+  }
+});
+
+// 2. Parse XML
+const xmlParser = new XMLParserService();
+const xmlContent = readFileSync('order.xml', 'utf-8');
+const parsedXml = await xmlParser.parse(xmlContent, {
+  includeAttributes: true,
+  attributePrefix: '@'
+});
+
+// 3. Configure hooks
+const hooks: MappingHooks = {
+  beforeMapping: async (data, context) => {
+    context.logger?.info('Preprocessing order data');
+    return data;
+  },
+
+  afterMapping: async (variables, context) => {
+    // Calculate total
+    variables.input.totalPrice = variables.input.items.reduce(
+      (sum, item) => sum + (item.paidPrice * item.quantity),
+      0
+    );
+
+    // Add audit metadata
+    variables.input.attributes = variables.input.attributes || [];
+    variables.input.attributes.push({
+      name: 'integration_source',
+      type: 'STRING',
+      value: JSON.stringify('SFCC')
+    });
+
+    context.logger?.info('Order total calculated', {
+      total: variables.input.totalPrice
+    });
+
+    return variables;
+  }
+};
+
+// 4. Initialize mapper
+const mapper = new GraphQLMutationMapper(
+  mappingConfig as any,
+  console,
+  { fluentClient: client }
+);
+
+// 5. Map data
+const payload = await mapper.map(parsedXml, hooks);
+
+// 6. Execute mutation
+const result = await client.graphql(payload);
+
+console.log('Order created:', result.data.createOrder);
+```
+
+### Environment Variables in Mappings
+
+Use environment variables for dynamic values:
+
+```json
+{
+  "retailer": {
+    "value": "${FLUENT_RETAILER_ID}",
+    "required": true
+  },
+  "createdBy": {
+    "value": "${INTEGRATION_NAME}"
+  }
+}
+```
+
+**Runtime Resolution:**
+- `"${FLUENT_RETAILER_ID}"` resolves to `process.env.FLUENT_RETAILER_ID`
+- Non-env strings pass through unchanged
+
+### Error Handling
+
+The mapper throws `MappingError` for validation failures:
+
+```typescript
+import { MappingError } from '@fluentcommerce/fc-connect-sdk';
+
+try {
+  const payload = await mapper.map(sourceData);
+} catch (error) {
+  if (error instanceof MappingError) {
+    console.error('Mapping failed:', {
+      field: error.field,
+      sourcePath: error.sourcePath,
+      message: error.message,
+      expectedType: error.expectedType,
+      actualType: error.actualType
+    });
+  }
+}
+```
+
+**Common Errors:**
+- `Required field 'ref' is missing or empty`
+- `Expected array but got object at path 'items'`
+- `Type mismatch: expected Int! but got String`
+- `Cannot resolve path 'order.missing'`
+
+## See Also
+
+- [GraphQL Mutation Mapping Guide](../../mapping/graphql-mutation-mapping/graphql-mutation-mapping-readme.md) - Detailed guide
+- [Module 7: Parsers](./api-reference-07-parsers.md) - XML and JSON parsers
+- [Module 5: Services](./api-reference-05-services.md) - UniversalMapper service
+- [Module 9: Error Handling](./api-reference-09-error-handling.md) - Error types and handling
+- [Examples: GraphQL Operations](../examples/) - See examples directory
+
+---
+
+**[← Previous: Authentication](./api-reference-03-authentication.md)** | **[API Reference Home](../api-reference-readme.md)** | **[Next: Services →](./api-reference-05-services.md)**