@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/01-TEMPLATES/versori/webhooks/template-webhook-xml-order-ingestion.md

@@ -1,2029 +1,2029 @@
----
-template_id: tpl-webhook-xml-order-ingestion-sfcc
-canonical_filename: template-webhook-xml-order-ingestion.md
-sdk_version: ^0.1.41
-runtime: versori
-direction: ingestion
-source: webhook-xml-sfcc
-destination: fluent-graphql
-entity: order
-format: xml
-logging: versori
-status: production-ready
-last_updated: 2025-11-13
----
-
-# Template: Webhook - SFCC XML Order Ingestion
-
-**FC Connect SDK Use Case Guide**
-
-> **SDK**: [@fluentcommerce/fc-connect-sdk](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk)
-> **Version**: Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
-
-**Context**: Receive SFCC XML orders via Versori HTTP webhook and create orders in Fluent Commerce using GraphQL mutations.
-
-**Complexity**: Medium
-
-**Runtime**: Versori Platform
-
-**Estimated Lines**: ~500 lines (modular structure)
-
----
-
-## STEP 1: Understand This Template
-
-**What This Template Does:**
-
-- Versori HTTP webhook endpoint receiving XML order data (SFCC native format)
-- XML parsing with automatic Versori XML-to-object conversion (incoming XML)
-- GraphQL mutation mapping from SFCC native XML structure to Fluent schema
-- Uses ONLY SFCC native fields (orders.order.*) - no Radial XML dependency
-- Custom resolvers for data transformation, name parsing, and order type derivation
-- Error handling and structured response formatting
-- **Response Options**: JSON (default) or XML (with custom Response handler)
-- **Sync + Fire-and-Forget Pattern**: Fast webhook response, background processing
-
-**Key SDK Components:**
-
-- `createClient()` - Universal client factory (auto-detects Versori context)
-- `GraphQLMutationMapper` - XML/JSON → GraphQL mutation mapping
-- Native Versori `log` - Use `log` from context
-- No XML parsing needed (Versori handles automatically)
-
-**Entity Type:**
-
-- **Order** - Fluent entity for order creation
-- **GraphQL Mutation** - Uses `createOrder` mutation (not Event API)
-
-**Critical Patterns:**
-
-- **XML Response Pattern**: Production-ready XML response handling with proper Content-Type headers
-- **Logger Adapter**: Type-safe logging with SDK Logger interface
-- **Sync + Fire-and-Forget**: Webhook validates quickly, returns immediately, processes in background
-- **External JSON Config**: Mapping configuration in separate JSON file (`config/sfcc-to-fluent-order-mapping.json`)
-- **Modular Architecture**: Separate services, workflows, config, types folders
-- **Integration Variables Validation**: Fail-fast validation of required configuration
-- **Initial Deployment Monitoring**: Temporary full payload logging for troubleshooting
-- **SFCC Native Only**: No Radial XML dependency - simpler and more maintainable
-
-**When to Use This Template:**
-
-- ✅ SFCC native XML order ingestion (orders.order.* structure)
-- ✅ Need fast webhook response (don't wait for order creation)
-- ✅ Single order per webhook call
-- ✅ BOPIS (Buy Online Pick Up In Store) and standard shipping orders
-- ✅ Custom resolvers for complex transformations (name parsing, address normalization)
-- ✅ Want simpler template without Radial XML complexity
-
-**When NOT to Use:**
-
-- ❌ Bulk order processing (use Batch API or scheduled workflows)
-- ❌ Order updates (use GraphQL `updateOrder` mutation)
-- ❌ CSV/JSON formats (use appropriate format template)
-- ❌ Need synchronous order creation (wait for result before responding)
-- ❌ Orders requiring Radial-specific fields (use Radial template instead)
-
----
-
-## STEP 2: Implementation Prompt for Claude Code
-
-**Copy this prompt and send to Claude Code to generate the complete implementation:**
-
-```
-Create a Versori webhook workflow for SFCC XML order ingestion to Fluent Commerce GraphQL.
-
-REQUIREMENTS:
-1. Runtime: Versori Platform (HTTP webhook)
-2. Source: SFCC XML order data via HTTP POST webhook
-3. Destination: Fluent Commerce GraphQL API (createOrder mutation)
-4. Format: XML (Versori auto-parses to object)
-5. Entity: Order (GraphQL mutation)
-
-KEY FEATURES:
-- Sync + fire-and-forget pattern (fast webhook response, background processing)
-- External JSON mapping configuration (config/sfcc-to-fluent-order-mapping.json)
-- Modular architecture (workflows/, services/, config/, types/)
-- SFCC native fields ONLY (no Radial XML)
-- GraphQLMutationMapper with standard map() method (no nodes)
-- Custom resolvers for data transformation
-- Audit trail (save input/output files)
-- Comprehensive error handling with structured logging
-
-CRITICAL REQUIREMENTS:
-1. Webhook Mode: response: { mode: 'sync' } with XML onSuccess/onError handlers
-2. Response Format: XML with proper Content-Type headers (production standard for SFCC)
-3. Logger Adapter: Create typed Logger adapter from Versori log
-4. Background Processing: Fire-and-forget pattern (no await on long operations)
-5. Mapping Config: External JSON file (config/sfcc-to-fluent-order-mapping.json)
-6. Custom Resolvers: USE mapWithNodes() when you have custom resolvers (REQUIRED)
-7. Integration Variables: Fail-fast validation of required config (fluentRetailerId)
-8. Modular Structure: Separate services/, config/, types/ folders
-9. Step Documentation: Use visual separator blocks for each workflow step
-10. Error Handling: Structured error responses with recommendations
-
-SDK METHODS TO USE (v0.1.41+):
-- createClient({ ...ctx, log }) - Pass full Versori context
-- Logger adapter pattern - Type-safe logging wrapper
-- new GraphQLMutationMapper(mappingConfig, logger, { customResolvers, fluentClient: client }) - Initialize mapper with resolvers (RECOMMENDED)
-- mapper.mapWithNodes(xmlData, undefined, context) - Map with constructor resolvers (auto-returns query)
-- result.query and result.variables - Auto-generated from mapWithNodes()
-- client.graphql({ query: result.query, variables: result.variables }) - Execute mutation
-
-FORBIDDEN PATTERNS:
-- ❌ Inline mapping config (use external JSON)
-- ❌ await on background processing (use fire-and-forget)
-- ❌ Passing log directly to SDK (use Logger adapter)
-- ❌ All code in one file (use modular structure)
-- ❌ async mode webhook (use sync + fire-and-forget)
-- ❌ Radial XML references (use SFCC native only)
-- ❌ buildMutation() calls (mapWithNodes() auto-generates query in v0.1.41+)
-- ❌ Silent config fallbacks (fail-fast on missing required variables)
-```
-
----
-
-## STEP 3: Detailed Flow Documentation
-
-### Complete Processing Flow
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│ 1. WEBHOOK RECEIVED                                         │
-│    POST https://{workspace}.versori.run/sfcc-order-create   │
-│    Content-Type: application/xml                             │
-│    Body: <orders xmlns="..."><order order-no="...">         │
-│          <original-order-no>...</original-order-no>          │
-│          <customer>...</customer>                            │
-│          <product-lineitems>...</product-lineitems>          │
-│          <shipments>...</shipments>                          │
-│          <totals>...</totals>                                │
-│          <payments>...</payments>                            │
-│          </order></orders>                                   │
-└────────────────────┬────────────────────────────────────────┘
-                     │
-                     ▼
-┌─────────────────────────────────────────────────────────────┐
-│ 2. QUICK VALIDATION (Synchronous, ~10-50ms)                 │
-│    - Check fluent_commerce connection exists                 │
-│    - Validate SFCC XML payload present                      │
-│    - Validate required fields (original-order-no, customer) │
-│    - Return HTTP 200 OK immediately                         │
-└────────────────────┬────────────────────────────────────────┘
-                     │
-                     ▼
-┌─────────────────────────────────────────────────────────────┐
-│ 3. BACKGROUND PROCESSING (Fire-and-Forget)                   │
-│    ┌─────────────────────────────────────────────────────┐  │
-│    │ 3a. Initialize Fluent Client                        │  │
-│    │     - createClient({ ...ctx, log })                 │  │
-│    └─────────────────────────────────────────────────────┘  │
-│    ┌─────────────────────────────────────────────────────┐  │
-│    │ 3b. Validate SFCC Structure                         │  │
-│    │     - Check required SFCC native fields             │  │
-│    │     - Validate order structure                      │  │
-│    └─────────────────────────────────────────────────────┘  │
-│    ┌─────────────────────────────────────────────────────┐  │
-│    │ 3c. Map SFCC Native XML to GraphQL Variables       │  │
-│    │     - Load mapping config from JSON                 │  │
-│    │     - Use SFCC native fields ONLY (orders.order.*) │  │
-│    │     - GraphQLMutationMapper.mapWithNodes() (REQUIRED for custom resolvers)│  │
-│    │     - Apply custom resolvers                        │  │
-│    │     - Returns { query, variables } (GraphQLPayload) │  │
-│    └─────────────────────────────────────────────────────┘  │
-│    ┌─────────────────────────────────────────────────────┐  │
-│    │ 3d. Execute GraphQL Mutation                        │  │
-│    │     - client.graphql(payload) - one simple step!    │  │
-│    └─────────────────────────────────────────────────────┘  │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### Response Timing
-
-| Stage | Timing | Blocking |
-|-------|--------|----------|
-| **Webhook Validation** | ~10-50ms | ✅ Yes (blocks response) |
-| **Background Processing** | ~1000-2000ms | ❌ No (fire-and-forget) |
-| **Total Response Time** | ~10-50ms | ✅ Fast response |
-
-**Key Benefit**: Webhook caller receives immediate acknowledgment (~50ms) while order creation happens in background (~1-2s).
-
----
-
-## STEP 4: Production Modular Structure
-
-> **✅ This section shows the COMPLETE production-ready modular structure.**
-> All files are shown with proper imports/exports and folder organization.
-
-### Complete Project Structure
-
-```
-sfcc-xml-order-ingestion/
-├── package.json                              # Dependencies and Versori config
-├── index.ts                                  # Entry point - exports all workflows
-└── src/
-    ├── workflows/
-    │   └── webhook/
-    │       └── order-ingestion.ts            # Webhook: Receive SFCC XML orders
-    │
-    ├── services/
-    │   └── order-processing.service.ts       # Shared orchestration logic (reusable)
-    │
-    ├── resolvers/
-    │   ├── index.ts                          # Export all resolvers
-    │   ├── types.ts                          # TypeScript interfaces
-    │   ├── order-resolvers.ts                # Order-level resolvers
-    │   ├── fulfillment-resolvers.ts          # Shipment/fulfillment resolvers
-    │   ├── item-resolvers.ts                 # Product line item resolvers
-    │   └── payment-resolvers.ts              # Payment resolvers
-    │
-    ├── config/
-    │   └── sfcc-to-fluent-order-mapping.json # Mapping configuration (external JSON)
-    │
-    └── types/
-        └── order.types.ts                    # TypeScript interfaces
-```
-
-**Why This Structure?**
-
-- ✅ **Clear separation**: Webhook handlers vs business logic
-- ✅ **Reusable services**: Order processing logic can be reused
-- ✅ **External config**: Mapping changes don't require code changes
-- ✅ **Custom resolvers**: Separate file for complex transformations
-- ✅ **Type safety**: TypeScript interfaces for better IDE support
-- ✅ **Scalable**: Easy to add new webhooks or services
-
----
-
----
-
-## CRITICAL: XML Response Architecture (Production Pattern)
-
-### Overview
-
-This template uses **XML responses** as the PRIMARY pattern for SFCC integration. This is the production-proven approach used in real SFCC → Fluent integrations.
-
-### How XML Response Handling Works
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│ ARCHITECTURE FLOW                                               │
-├─────────────────────────────────────────────────────────────────┤
-│                                                                 │
-│  1. Workflow Steps Return XML Strings                          │
-│     ↓ ctx.data = "<OrderProcessingResponse>...</>"             │
-│                                                                 │
-│  2. onSuccess Handler Receives Context                         │
-│     ↓ ctx = { data: xmlString, executionId: "..." }           │
-│                                                                 │
-│  3. Handler Wraps in Response Object                           │
-│     ↓ new Response(ctx.data, { headers: {...} })              │
-│                                                                 │
-│  4. Framework Streams Response Directly                        │
-│     ↓ No JSON encoding - pure XML stream                       │
-│                                                                 │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-### Response Format Examples
-
-**Success Response:**
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<OrderProcessingResponse>
-  <Status>success</Status>
-  <Message>Order successfully processed and created in Fluent Commerce</Message>
-  <FluentOrderId>6370</FluentOrderId>
-  <FluentOrderRef>0017326966182_G_postman_test_1760703173226</FluentOrderRef>
-  <SFCCOrderRef>0017326966182_G_postman_test_1760703173226</SFCCOrderRef>
-  <Timestamp>2025-11-13T12:12:54.229Z</Timestamp>
-</OrderProcessingResponse>
-```
-
-**Error Response:**
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<OrderProcessingResponse>
-  <Status>error</Status>
-  <Message>Failed to process order</Message>
-  <Error>Missing required field: original-order-no</Error>
-  <Timestamp>2025-11-13T12:12:54.229Z</Timestamp>
-</OrderProcessingResponse>
-```
-
-### Key Benefits
-
-- ✅ **SFCC Native**: SFCC systems expect XML responses
-- ✅ **Type Safety**: Structured XML schema
-- ✅ **Execution Tracking**: X-Execution-Id header for troubleshooting
-- ✅ **Proper Content-Type**: application/xml; charset=utf-8
-- ✅ **Framework Streaming**: Direct XML stream (no JSON wrapper)
-
----
-
-## XML Handling Patterns
-
-### Incoming XML (Versori Auto-Parsing)
-
-**CRITICAL**: Versori automatically parses XML when `Content-Type: application/xml` is set.
-
-```typescript
-// ✅ CORRECT - Versori auto-parses XML into object
-// When SFCC sends: POST /webhook with Content-Type: application/xml
-// Versori automatically converts XML string → parsed object
-// ctx.data is already a parsed object, NOT a string
-
-export const webhook = webhook('order-ingestion', { response: { mode: 'sync' } })
-  .then(http('process', { connection: 'fluent_commerce' }, async (ctx) => {
-    // ctx.data is already parsed! No manual parsing needed
-    const sfccData = ctx.data; // Already an object: { orders: { order: {...} } }
-
-    // Validate structure
-    if (!sfccData.orders?.order) {
-      throw new Error('Invalid XML structure: missing orders.order');
-    }
-
-    // Use mapWithNodes() because we have custom resolvers
-    // ✅ Resolvers passed in constructor, so pass undefined here (or override if needed)
-    const result = await mapper.mapWithNodes(sfccData, undefined, context);
-  }));
-
-// ❌ WRONG - Don't try to parse manually
-const xmlString = ctx.data; // This is already parsed!
-const parsed = parseXML(xmlString); // Unnecessary!
-```
-
-**Why This Matters:**
-- Versori handles XML parsing automatically
-- `ctx.data` is always a parsed object when Content-Type is `application/xml`
-- No need for `XMLParserService` or manual parsing in Versori workflows
-- Simply validate the structure and use directly
-
-### Outgoing XML (Production-Ready Pattern)
-
-**RECOMMENDED FOR SFCC**: Use XML responses with custom handlers for production SFCC integrations.
-
-**XML Response Pattern (RECOMMENDED)**
-```typescript
-import { XMLBuilder } from '@fluentcommerce/fc-connect-sdk';
-
-export const webhook = webhook('order-ingestion', {
-  response: {
-    mode: 'sync',
-    /**
-     * onSuccess Handler for XML Response
-     *
-     * This handler wraps the XML response string with proper headers.
-     * The workflow steps return XML strings via ctx.data, and this
-     * handler wraps them in Response objects for proper streaming.
-     *
-     * @param ctx - Context containing:
-     *   - ctx.data: The XML response string from the final workflow step
-     *   - ctx.executionId: Unique identifier for this execution
-     * @returns Response object with XML body and proper headers
-     */
-    onSuccess: (ctx) => new Response(ctx.data, {
-      status: 200,
-      headers: {
-        'Content-Type': 'application/xml; charset=utf-8',
-        'X-Execution-Id': ctx.executionId
-      }
-    }),
-    /**
-     * onError Handler for XML Error Response
-     *
-     * This handler wraps error responses with proper status and headers.
-     * Returns XML format for consistent error responses.
-     *
-     * @param ctx - Context containing:
-     *   - ctx.data: The error XML string from the .catch() step
-     *   - ctx.executionId: Unique identifier for tracking failed executions
-     * @returns Response object with error XML and 500 status
-     */
-    onError: (ctx) => new Response(ctx.data, {
-      status: 500,
-      headers: {
-        'Content-Type': 'application/xml; charset=utf-8',
-        'X-Execution-Id': ctx.executionId
-      }
-    })
-  }
-})
-  .then(http('process', { connection: 'fluent_commerce' }, async (ctx) => {
-    // Process order...
-    const orderId = '12345';
-    const orderRef = 'ORD-001';
-    
-    // Build XML response string
-    const builder = new XMLBuilder({
-      xmlDeclaration: true,  // Adds <?xml version="1.0" encoding="UTF-8"?>
-      prettyPrint: true,     // Format with indentation
-      encoding: 'UTF-8'
-    });
-
-    const responseData = {
-      Status: 'success',
-      FluentOrderId: orderId,
-      FluentOrderRef: orderRef,
-      Timestamp: new Date().toISOString()
-    };
-
-    // Return XML string (onSuccess handler wraps it in Response)
-    return builder.build(responseData, 'OrderProcessingResponse');
-  }))
-  .catch(({ data, log }) => {
-    // Return error XML string (onError handler wraps it)
-    return `<?xml version="1.0" encoding="UTF-8"?>
-<OrderProcessingResponse>
-  <Status>error</Status>
-  <Error>${data instanceof Error ? data.message : String(data)}</Error>
-</OrderProcessingResponse>`;
-  });
-// Response: <?xml version="1.0"?><OrderProcessingResponse>...
-// Content-Type: application/xml; charset=utf-8
-```
-
-**Alternative: JSON Response (Simple Testing)**
-
-For testing or non-SFCC systems, you can use JSON responses:
-
-```typescript
-export const webhook = webhook('order-ingestion', {
-  response: { mode: 'sync' }
-})
-  .then(http('process', { connection: 'fluent_commerce' }, async (ctx) => {
-    // Returns JSON object - Versori auto-encodes
-    return {
-      success: true,
-      orderId: '12345',
-      orderRef: 'ORD-001'
-    };
-  }));
-// Response: {"success":true,"orderId":"12345","orderRef":"ORD-001"}
-// Content-Type: application/json
-```
-
-**Key Decision Points:**
-
-| Pattern | Use When | Response Type |
-|---------|----------|---------------|
-| **XML Response** | Production SFCC integration | XML with proper headers |
-| **JSON Response** | Testing, non-SFCC systems | JSON auto-encoded |
-
-**Key Points:**
-- ✅ **XML (Recommended)**: Requires custom `onSuccess`/`onError` handlers with `Response` objects
-- ✅ **JSON (Testing)**: Default behavior, no custom handler needed
-- ✅ Workflow steps return raw strings (XML) or objects (JSON)
-- ✅ Response handlers wrap in `Response` objects with proper Content-Type
-
----
-
-## SDK Methods Used
-
-```typescript
-// Core SDK imports
-// FC Connect SDK v0.1.41+
-// Install: npm install @fluentcommerce/fc-connect-sdk@^0.1.41
-// Docs: https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk/
-// GitHub: https://github.com/fluentcommerce/fc-connect-sdk
-
-import { createClient, GraphQLMutationMapper, XMLBuilder } from '@fluentcommerce/fc-connect-sdk';
-import type { Logger } from '@fluentcommerce/fc-connect-sdk';
-
-// ═══════════════════════════════════════════════════════════════
-// LOGGER ADAPTER PATTERN (Production-Proven)
-// ═══════════════════════════════════════════════════════════════
-// Create typed Logger adapter from Versori log
-// Benefits:
-// - Type safety with SDK Logger interface
-// - Centralized logging (easy to modify all calls)
-// - Clear separation between Versori log and SDK Logger
-const logger: Logger = {
-  info: (msg: string, meta?: any) => log.info(msg, meta),
-  error: (msg: string, error?: Error, meta?: any) => log.error(msg, meta),
-  warn: (msg: string, meta?: any) => log.info(msg, meta),
-  debug: (msg: string, meta?: any) => log.info(msg, meta)
-};
-
-// Key methods
-createClient(ctx); // Auto-detects Versori context
-// ✅ RECOMMENDED: Pass resolvers in constructor
-new GraphQLMutationMapper(config, logger, { customResolvers, fluentClient: client }); 
-// ✅ Alternative: Pass resolvers to mapWithNodes (constructor resolvers merged)
-mapper.mapWithNodes(data, resolvers, context); 
-// ✅ v0.1.41+: mapWithNodes() auto-returns query and variables
-const result = await mapper.mapWithNodes(data, undefined, context); // Use constructor resolvers
-// result.query - Auto-generated GraphQL mutation
-// result.variables - Auto-wrapped variables (input object)
-client.graphql({ query: result.query, variables: result.variables }); // Execute
-```
-
-### Why GraphQLMutationMapper (Not UniversalMapper)?
-
-**GraphQLMutationMapper** is the right choice for this template because:
-
-✅ **Automatic Mutation Building**: Automatically generates GraphQL mutation query from mapping config
-✅ **Input Wrapping**: Automatically wraps mapped data in `input` object (Fluent API requirement)
-✅ **GraphQL-Specific**: Designed specifically for GraphQL mutations with schema awareness
-
-**UniversalMapper** would require:
-- ❌ Manual GraphQL mutation query building
-- ❌ Manual `input` wrapping
-- ❌ More boilerplate code
-
-**Use UniversalMapper when**: You need general-purpose data transformation (CSV → JSON, GraphQL → Parquet, etc.)
-**Use GraphQLMutationMapper when**: You need XML/JSON → GraphQL mutations (this template's use case)
-
----
-
-## Complete Working Code
-
-### 1. Entry Point (index.ts)
-
-```typescript
-/**
- * Entry point - Export all workflows for Versori platform
- */
-
-// Webhook workflows
-export { sfccOrderCreate } from './workflows/webhook/sfcc-order-create';
-```
-
-### 2. Workflow Entry Point (workflows/webhook/sfcc-order-create.ts)
-
-```typescript
-/**
- * ═══════════════════════════════════════════════════════════════════════════════
- * SFCC → FLUENT ORDER CREATE WEBHOOK (Production Pattern)
- * ═══════════════════════════════════════════════════════════════════════════════
- *
- * PURPOSE:
- * This webhook receives order data from Salesforce Commerce Cloud (SFCC) as XML
- * in the request body. It validates, transforms, and creates orders in Fluent
- * Commerce via GraphQL mutations.
- *
- * WEBHOOK CONFIGURATION:
- * - Response mode: synchronous (caller waits for response)
- * - Response format: XML (OrderProcessingResponse)
- * - CORS: enabled (allows cross-origin requests)
- * - Expected payload: XML in request body (Content-Type: application/xml)
- *
- * ARCHITECTURE:
- * Uses production-proven patterns from real SFCC integrations:
- * - XML response handling with proper Content-Type headers
- * - Logger adapter for type-safe logging
- * - Fire-and-forget background processing
- * - Fail-fast validation of required configuration
- * - Visual step documentation blocks
- *
- * WORKFLOW STEPS:
- * 1. Validate XML structure and required fields
- * 2. Apply mapping with custom resolvers
- * 3. Execute GraphQL mutation to create order
- * 4. Build XML response with order creation results
- * ═══════════════════════════════════════════════════════════════════════════════
- */
-
-import { webhook, http, fn } from '@versori/run';
-import type { Context } from '@versori/run';
-import { createClient, GraphQLMutationMapper } from '@fluentcommerce/fc-connect-sdk';
-import type { Logger } from '@fluentcommerce/fc-connect-sdk';
-import { allResolvers } from '../../resolvers';
-import mappingConfig from '../../config/sfcc-to-fluent-order-mapping.json' with { type: 'json' };
-import { XMLBuilder } from '@fluentcommerce/fc-connect-sdk';
-
-/**
- * ═══════════════════════════════════════════════════════════════════════════════
- * XML RESPONSE ARCHITECTURE (Production Pattern)
- * ═══════════════════════════════════════════════════════════════════════════════
- *
- * This webhook uses XML responses as the PRIMARY pattern for SFCC integration.
- * The onSuccess and onError handlers wrap XML strings in Response objects with
- * proper Content-Type headers.
- *
- * RESPONSE FORMAT:
- * Success:
- * <?xml version="1.0" encoding="UTF-8"?>
- * <OrderProcessingResponse>
- *   <Status>success</Status>
- *   <Message>Order successfully processed and created in Fluent Commerce</Message>
- *   <FluentOrderId>6370</FluentOrderId>
- *   <FluentOrderRef>0017326966182_G_postman_test_1760703173226</FluentOrderRef>
- *   <SFCCOrderRef>0017326966182_G_postman_test_1760703173226</SFCCOrderRef>
- *   <Timestamp>2025-11-13T12:12:54.229Z</Timestamp>
- * </OrderProcessingResponse>
- *
- * Error:
- * <?xml version="1.0" encoding="UTF-8"?>
- * <OrderProcessingResponse>
- *   <Status>error</Status>
- *   <Message>Failed to process order</Message>
- *   <Error>Error details here</Error>
- *   <Timestamp>2025-11-13T12:12:54.229Z</Timestamp>
- * </OrderProcessingResponse>
- *
- * HOW IT WORKS:
- * 1. Workflow steps return XML strings via ctx.data
- * 2. onSuccess handler receives ctx with the XML string in ctx.data
- * 3. Handler creates Response with Content-Type: application/xml
- * 4. Framework streams the Response directly (no JSON encoding)
- * ═══════════════════════════════════════════════════════════════════════════════
- */
-export const sfccOrderCreate = webhook('sfcc-order-create', {
-  response: {
-    mode: 'sync',
-    /**
-     * onSuccess Handler for XML Response
-     *
-     * This handler wraps the XML response string with proper headers.
-     * Similar to production SFCC workflows, this ensures the XML is
-     * streamed directly without JSON encoding.
-     *
-     * @param ctx - Context containing:
-     *   - ctx.data: The XML response string from the final workflow step
-     *   - ctx.executionId: Unique identifier for this execution
-     * @returns Response object with XML body and proper headers
-     */
-    onSuccess: (ctx) => new Response(ctx.data, {
-      status: 200,
-      headers: {
-        'Content-Type': 'application/xml; charset=utf-8',
-        'X-Execution-Id': ctx.executionId
-      }
-    }),
-    /**
-     * onError Handler for XML Error Response
-     *
-     * This handler wraps error responses with proper status and headers.
-     * Returns XML format for consistent error responses.
-     *
-     * @param ctx - Context containing:
-     *   - ctx.data: The error XML string from the .catch() step
-     *   - ctx.executionId: Unique identifier for tracking failed executions
-     * @returns Response object with error XML and 500 status
-     */
-    onError: (ctx) => new Response(ctx.data, {
-      status: 500,
-      headers: {
-        'Content-Type': 'application/xml; charset=utf-8',
-        'X-Execution-Id': ctx.executionId
-      }
-    })
-  },
-  cors: true
-}).then(
-  /**
-   * ═══════════════════════════════════════════════════════════════════════════════
-   * STEP 1: VALIDATE XML STRUCTURE
-   * ═══════════════════════════════════════════════════════════════════════════════
-   *
-   * This step validates that the incoming data is properly parsed XML from Versori.
-   * Uses fail-fast validation pattern to catch configuration issues early.
-   * ═══════════════════════════════════════════════════════════════════════════════
-   */
-  fn('validate-xml-structure', async ({ data, log, activation }) => {
-    // ─────────────────────────────────────────────────────────────────────────
-    // LOGGER ADAPTER PATTERN (Production-Proven)
-    // ─────────────────────────────────────────────────────────────────────────
-    // Create Logger Adapter for type-safe SDK logging
-    // Benefits:
-    // - Explicit interface contract (TypeScript Logger type)
-    // - Centralized logging adapter (easy to modify all log calls)
-    // - Type safety enforced
-    // - Clear separation between Versori log and SDK Logger
-    const logger: Logger = {
-      info: (msg: string, meta?: any) => log.info(msg, meta),
-      error: (msg: string, error?: Error, meta?: any) => log.error(msg, meta),
-      warn: (msg: string, meta?: any) => log.info(msg, meta),
-      debug: (msg: string, meta?: any) => log.info(msg, meta)
-    };
-
-    logger.info('Starting SFCC order webhook processing');
-
-    // ─────────────────────────────────────────────────────────────────────────
-    // INITIAL DEPLOYMENT MONITORING PATTERN
-    // ─────────────────────────────────────────────────────────────────────────
-    // TEMPORARY: Complete XML log for short-term monitoring (first 2-4 weeks)
-    // TODO: Remove this log once integration is stable and monitoring is complete
-    // Purpose: Helps catch XML structure issues and field mapping problems early
-    // Impact: Increases log volume - remove after stabilization
-    // ─────────────────────────────────────────────────────────────────────────
-    logger.info('Complete incoming XML data', { completeData: data });
-
-    // ─────────────────────────────────────────────────────────────────────────
-    // Validate Pre-Parsed XML Object from Versori
-    // ─────────────────────────────────────────────────────────────────────────
-    if (typeof data !== 'object' || data === null || !('orders' in data)) {
-      throw new Error(
-        `Invalid data format. Expected XML (as pre-parsed object with 'orders' root). ` +
-        `Received: ${typeof data}. ` +
-        `Please ensure you are sending XML with Content-Type: application/xml.`
-      );
-    }
-
-    logger.info('XML structure validated successfully');
-
-    return {
-      parsedXml: data,
-      logger
-    };
-  })
-)
-
-/**
- * ═══════════════════════════════════════════════════════════════════════════════
- * STEP 2: MAP WITH RESOLVERS USING SDK NODES PATTERN
- * ═══════════════════════════════════════════════════════════════════════════════
- *
- * This step applies field mappings and executes custom resolvers using the SDK's
- * mapWithNodes() method. This method is REQUIRED when using custom resolvers.
- *
- * v0.1.41+ Improvement: mapWithNodes() auto-returns query and variables
- * ═══════════════════════════════════════════════════════════════════════════════
- */
-.then(
-  http('map-with-resolvers', {
-    connection: 'fluent_commerce'
-  }, async (ctx) => {
-    const { data, log, activation } = ctx;
-    const { parsedXml, logger } = data;
-
-    logger.info('Mapping SFCC order to Fluent Commerce with custom resolvers');
-
-    try {
-      const fluentClient = await createClient(ctx);
-
-      // ═════════════════════════════════════════════════════════════════════
-      // INTEGRATION VARIABLES VALIDATION (Fail-Fast Pattern)
-      // ═════════════════════════════════════════════════════════════════════
-      // Production pattern: Validate required configuration early
-      // Benefits:
-      // - Fails immediately with explicit error message
-      // - Tells user EXACTLY what's wrong and where to fix it
-      // - Better than silent fallback to default (hides config issues)
-      // - Provides audit trail of successful retrieval
-      const fluentRetailerId = activation.getVariable('fluentRetailerId') as string;
-
-      if (!fluentRetailerId) {
-        throw new Error(
-          'fluentRetailerId integration variable is required but not set. ' +
-          'Please set this variable in Versori Activations > Variables section.'
-        );
-      }
-
-      logger.info('Using retailer ID from integration variables', { retailerId: fluentRetailerId });
-
-      // ═════════════════════════════════════════════════════════════════════
-      // INITIALIZE MAPPER WITH RESOLVERS IN CONSTRUCTOR (Recommended Pattern)
-      // ═════════════════════════════════════════════════════════════════════
-      // ✅ CORRECT: Pass resolvers in constructor options
-      // This is consistent with UniversalMapper and allows resolvers to be reused
-      const mapper = new GraphQLMutationMapper(
-        mappingConfig as any,
-        logger,
-        { 
-          customResolvers: allResolvers,  // ✅ Resolvers in constructor
-          fluentClient: fluentClient as any,
-        }
-      );
-
-      // ═════════════════════════════════════════════════════════════════════
-      // CREATE RESOLVER CONTEXT
-      // ═════════════════════════════════════════════════════════════════════
-      // Pass configuration to custom resolvers
-      // SDK automatically provides helpers (get, ensureArray, logger, etc.)
-      // You only need to pass custom config and fluentClient
-      const resolverContext = {
-        fluentClient: fluentClient as any,
-        config: {
-          retailerId: fluentRetailerId,
-          defaultCountry: 'US',
-          companyName: 'YourCompany'  // Customize per deployment
-        },
-        // ✅ SDK automatically provides helpers.get, helpers.ensureArray, helpers.logger
-        // No need to manually create them - SDK handles XML attributes via path resolver
-        // ✅ Resolvers can access config via helpers.context.config.retailerId
-        //    OR via the config parameter (3rd param): config.retailerId
-      };
-
-      // Execute mapping WITH custom resolvers
-      // ✅ v0.1.41+: mapWithNodes() auto-generates query and variables
-      // ✅ Resolvers from constructor are automatically used (can override with 2nd param)
-      const mappingResult = await mapper.mapWithNodes(
-        parsedXml,
-        undefined,  // Use constructor resolvers (or pass override resolvers here)
-        resolverContext
-      );
-
-      if (!mappingResult.success) {
-        throw new Error(`Mapping failed: ${mappingResult.errors?.join(', ')}`);
-      }
-
-      const orderRef = mappingResult.data?.input?.ref || 'unknown';
-
-      logger.info('Successfully mapped order data with custom resolvers', { orderRef });
-
-      return {
-        mappedData: mappingResult.data,
-        mappingResult,  // ✅ Contains auto-generated query and variables
-        orderRef,
-        fluentClient,
-        logger
-      };
-    } catch (error) {
-      log.error('Error during mapping with resolvers', {
-        error: error instanceof Error ? error.message : String(error),
-        stack: error instanceof Error ? error.stack : undefined
-      });
-      throw error;
-    }
-  })
-)
-
-/**
- * ═══════════════════════════════════════════════════════════════════════════════
- * STEP 3: EXECUTE GRAPHQL MUTATION
- * ═══════════════════════════════════════════════════════════════════════════════
- *
- * Execute the GraphQL mutation using auto-generated query from mapWithNodes().
- * v0.1.41+ automatically wraps variables and generates query.
- * ═══════════════════════════════════════════════════════════════════════════════
- */
-.then(
-  http('execute-graphql-mutation', {
-    connection: 'fluent_commerce'
-  }, async (ctx) => {
-    const { data, log } = ctx;
-    const { mappingResult, orderRef, fluentClient, logger } = data;
-
-    logger.info('Executing createOrder GraphQL mutation', { orderRef });
-
-    try {
-      // ✅ v0.1.41+: Use auto-generated query and variables from mapWithNodes()
-      // No need to call buildMutation() - query is already generated
-      const mutationResult = await (fluentClient as any).graphql({
-        query: mappingResult.query,      // ✅ Auto-generated mutation query
-        variables: mappingResult.variables  // ✅ Auto-wrapped variables
-      });
-
-      if (mutationResult.errors && mutationResult.errors.length > 0) {
-        logger.error('GraphQL mutation returned errors', {
-          errors: mutationResult.errors,
-          orderRef
-        });
-        throw new Error(`GraphQL errors: ${JSON.stringify(mutationResult.errors)}`);
-      }
-
-      const createdOrder = (mutationResult.data as any)?.createOrder;
-
-      if (!createdOrder) {
-        throw new Error('No order data returned from createOrder mutation');
-      }
-
-      // Access fields specified in returnFields (id, ref, status, totalPrice)
-      logger.info('Successfully created order in Fluent Commerce', {
-        fluentOrderId: createdOrder.id,      // From returnFields
-        fluentOrderRef: createdOrder.ref,    // From returnFields
-        status: createdOrder.status,         // From returnFields
-        totalPrice: createdOrder.totalPrice, // From returnFields
-        sfccOrderRef: orderRef
-      });
-
-      return {
-        success: true,
-        fluentOrderId: createdOrder.id,
-        fluentOrderRef: createdOrder.ref,
-        sfccOrderRef: orderRef,
-        orderData: createdOrder
-      };
-    } catch (error) {
-      log.error('Error executing GraphQL mutation', {
-        error: error instanceof Error ? error.message : String(error),
-        orderRef
-      });
-      throw error;
-    }
-  })
-)
-
-/**
- * ═══════════════════════════════════════════════════════════════════════════════
- * STEP 4: BUILD XML RESPONSE
- * ═══════════════════════════════════════════════════════════════════════════════
- *
- * IMPORTANT: Return the XML string here.
- * The onSuccess handler will wrap it in a Response with:
- * - Content-Type: application/xml
- * - Status: 200
- * - X-Execution-Id header
- *
- * This keeps the workflow logic focused on data transformation while
- * the framework handles HTTP response formatting.
- * ═══════════════════════════════════════════════════════════════════════════════
- */
-.then(
-  fn('build-xml-response', ({ data, log }) => {
-    log.info('Building XML response for SFCC order processing', {
-      fluentOrderId: data.fluentOrderId,
-      fluentOrderRef: data.fluentOrderRef,
-      sfccOrderRef: data.sfccOrderRef
-    });
-
-    // Initialize XML Builder (SDK-provided)
-    const builder = new XMLBuilder({
-      xmlDeclaration: true,  // Adds <?xml version="1.0" encoding="UTF-8"?>
-      prettyPrint: true,     // Format with indentation (default: true)
-      indent: '  ',          // Two-space indentation (default)
-      encoding: 'UTF-8'      // XML encoding (default)
-    });
-
-    // Build XML response data
-    const responseData = {
-      Status: 'success',
-      Message: 'Order successfully processed and created in Fluent Commerce',
-      FluentOrderId: data.fluentOrderId,
-      FluentOrderRef: data.fluentOrderRef,
-      SFCCOrderRef: data.sfccOrderRef,
-      Timestamp: new Date().toISOString()
-    };
-
-    // Build XML with root element
-    const xmlString = builder.build(responseData, 'OrderProcessingResponse');
-
-    log.info('Successfully built XML response', {
-      orderRef: data.sfccOrderRef,
-      xmlLength: xmlString.length
-    });
-
-    /**
-     * Return just the XML string here.
-     * The onSuccess handler will wrap it in a Response object with:
-     * - Content-Type: application/xml
-     * - Status: 200
-     * - X-Execution-Id header
-     */
-    return xmlString;
-  })
-)
-
-/**
- * ═══════════════════════════════════════════════════════════════════════════════
- * ERROR HANDLING
- * ═══════════════════════════════════════════════════════════════════════════════
- *
- * Return error XML string that will be wrapped by onError handler with status 500.
- * ═══════════════════════════════════════════════════════════════════════════════
- */
-.catch(({ data, log }) => {
-  log.error('Order processing failed', {
-    error: data instanceof Error ? data.message : String(data)
-  });
-
-  /**
-   * Build error XML that will be wrapped by onError handler.
-   * The onError handler will receive this string in ctx.data and wrap it
-   * in a Response object with proper status and headers.
-   */
-  const errorXml = `<?xml version="1.0" encoding="UTF-8"?>
-<OrderProcessingResponse>
-  <Status>error</Status>
-  <Message>Failed to process order</Message>
-  <Error>${data instanceof Error ? data.message : String(data)}</Error>
-  <Timestamp>${new Date().toISOString()}</Timestamp>
-</OrderProcessingResponse>`;
-
-  /**
-   * Return the error XML string.
-   * The onError handler will wrap it in a Response with status 500.
-   */
-  return errorXml;
-});
-```
-
-### 3. Service Implementation (services/order-ingestion.service.ts)
-
-```typescript
-/**
- * SFCC Order Ingestion Service
- *
- * Orchestrates the complete order ingestion process:
- * 1. Validate webhook payload
- * 2. Validate SFCC structure
- * 3. Apply field mapping with custom resolvers
- * 4. Create order via GraphQL API
- * 5. Audit trail (save input/output files)
- */
-
-import { createClient, GraphQLMutationMapper } from '@fluentcommerce/fc-connect-sdk';
-import { allResolvers } from '../resolvers';
-import mappingConfig from '../config/sfcc-to-fluent-order-mapping.json' with { type: 'json' };
-
-/**
- * Process SFCC order ingestion
- *
- * @param ctx - Versori context object containing fetch, connections, log, activation, data
- * @param executionStartTime - Workflow start time for duration tracking
- */
-export async function processOrderIngestion(ctx: any, executionStartTime: number) {
-  const { log, data, activation } = ctx;
-
-  log.info('Starting SFCC order processing');
-
-  try {
-    const sfccData = data;
-
-    if (!sfccData) {
-      log.error('No order data received');
-      return {
-        success: false,
-        error: 'No order data received',
-        timestamp: new Date().toISOString(),
-        duration: Date.now() - executionStartTime,
-      };
-    }
-
-    if (!sfccData.orders?.order) {
-      log.error('Invalid order structure: missing orders.order');
-      return {
-        success: false,
-        error: 'Invalid order structure: missing orders.order',
-        timestamp: new Date().toISOString(),
-        duration: Date.now() - executionStartTime,
-      };
-    }
-
-    const order = sfccData.orders.order;
-    if (!order['original-order-no']) {
-      log.error('Missing required field: original-order-no');
-      return {
-        success: false,
-        error: 'Missing required field: original-order-no',
-        timestamp: new Date().toISOString(),
-        duration: Date.now() - executionStartTime,
-      };
-    }
-
-    if (!order.customer?.['customer-no']) {
-      log.error('Missing required field: customer.customer-no');
-      return {
-        success: false,
-        error: 'Missing required field: customer.customer-no',
-        timestamp: new Date().toISOString(),
-        duration: Date.now() - executionStartTime,
-      };
-    }
-
-    const fluentClient = await createClient(ctx);
-    log.info('Fluent client initialized');
-
-    log.info('Applying mapping');
-
-    const retailerId = activation?.getVariable('fluentRetailerId') as string;
-    
-    if (!retailerId) {
-      log.error('Missing required variable: fluentRetailerId');
-      return {
-        success: false,
-        error: 'Missing required configuration: fluentRetailerId',
-        timestamp: new Date().toISOString(),
-        duration: Date.now() - executionStartTime,
-      };
-    }
-
-    const productCatalogueRef = activation?.getVariable('productCatalogueRef') as string || 'PC:MASTER:2';
-
-    const mapper = new GraphQLMutationMapper(
-      mappingConfig as any,
-      log,
-      { 
-        customResolvers: allResolvers,
-        fluentClient: fluentClient as any,
-      }
-    );
-
-    const resolverContext = {
-      fluentClient: fluentClient as any,
-      config: {
-        retailerId: retailerId,
-        defaultOrderType: 'HD',
-        defaultCountry: 'US',
-        productCatalogueRef: productCatalogueRef,
-      },
-    };
-
-    const result = await mapper.mapWithNodes(sfccData, undefined, resolverContext);
-
-    if (!result.success) {
-      log.error('Mapping failed', { errors: result.errors });
-      return {
-        success: false,
-        error: `Mapping failed: ${result.errors?.join(', ')}`,
-        timestamp: new Date().toISOString(),
-        duration: Date.now() - executionStartTime,
-      };
-    }
-
-    const orderRef = sfccData.orders?.order?.['original-order-no'] || 'unknown';
-
-    log.info('Mapping completed', { orderRef });
-
-    // Save audit trail to KV storage (Versori-compatible - file system is read-only)
-    try {
-      const kv = openKv(':project:');
-      const timestamp = new Date().toISOString();
-      const auditKey = ['orders', 'audit', orderRef, timestamp];
-      
-      await kv.set([...auditKey, 'sfcc-input'], sfccData);
-      await kv.set([...auditKey, 'fluent-mapped'], result.data);
-      
-      log.info('Audit trail saved to KV storage', { orderRef, timestamp });
-    } catch (kvError: any) {
-      log.warn('Failed to save audit trail to KV', { error: kvError.message });
-    }
-
-    log.info('Creating order in Fluent Commerce', { orderRef });
-
-    const mutationRes = await (fluentClient as any).graphql({
-      query: result.query,
-      variables: result.variables
-    });
-
-    if (mutationRes.errors && mutationRes.errors.length > 0) {
-      log.error('GraphQL mutation failed', { errors: mutationRes.errors });
-      
-      // Save error to KV storage
-      try {
-        const kv = openKv(':project:');
-        const timestamp = new Date().toISOString();
-        const auditKey = ['orders', 'audit', orderRef, timestamp, 'fluent-error'];
-        await kv.set(auditKey, mutationRes);
-      } catch (kvError) {
-        // Ignore KV save errors
-      }
-      
-      return {
-        success: false,
-        error: `GraphQL mutation failed: ${mutationRes.errors.map((e: any) => e.message).join(', ')}`,
-        timestamp: new Date().toISOString(),
-        duration: Date.now() - executionStartTime,
-      };
-    }
-
-    const createOrderData = (mutationRes as any)?.data?.createOrder;
-
-    if (!createOrderData) {
-      log.error('No order data returned from API');
-      return {
-        success: false,
-        error: 'No order data returned from GraphQL mutation',
-        timestamp: new Date().toISOString(),
-        duration: Date.now() - executionStartTime,
-      };
-    }
-
-    // Save successful response to KV storage
-    try {
-      const kv = openKv(':project:');
-      const timestamp = new Date().toISOString();
-      const auditKey = ['orders', 'audit', orderRef, timestamp, 'fluent-response'];
-      await kv.set(auditKey, mutationRes);
-    } catch (kvError) {
-      // Ignore KV save errors
-    }
-
-    log.info('Order created in Fluent Commerce', {
-      orderId: createOrderData?.id,
-      orderRef: createOrderData?.ref,
-    });
-
-    return {
-      success: true,
-      data: {
-        sfccOrderRef: orderRef,
-        fluentOrderId: createOrderData?.id,
-        fluentOrderRef: createOrderData?.ref,
-        timestamp: new Date().toISOString(),
-      },
-      duration: Date.now() - executionStartTime,
-    };
-  } catch (error: any) {
-    log.error('Fatal error', {
-      error: error instanceof Error ? error.message : String(error),
-      stack: error instanceof Error ? error.stack : undefined,
-    });
-
-    return {
-      success: false,
-      error: error instanceof Error ? error.message : String(error),
-      timestamp: new Date().toISOString(),
-      duration: Date.now() - executionStartTime,
-    };
-  }
-}
-```
-
-### 4. Mapping Configuration (config/sfcc-to-fluent-order-mapping.json)
-
-```json
-{
-  "direction": "ingest",
-  "sourceFormat": "xml",
-  "mutation": "createOrder",
-  "returnFields": ["id", "ref", "status", "totalPrice"],
-  "fields": {
-    "ref": {
-      "source": "orders.order.original-order-no",
-      "resolver": "sdk.toString",
-      "comment": "Order reference from SFCC native field (REQUIRED)"
-    },
-    "type": {
-      "resolver": "custom.deriveOrderType",
-      "comment": "Derive from shipment count: 1 shipment = HD, multiple = MULTI (REQUIRED)"
-    },
-    "retailer.id": {
-      "value": "${RETAILER_ID}",
-      "comment": "From environment variable or configuration (REQUIRED)"
-    },
-    "totalPrice": {
-      "source": "orders.order.totals.order-total.net-price",
-      "resolver": "sdk.parseFloat",
-      "comment": "Order total net price from SFCC totals (REQUIRED)"
-    },
-    "totalTaxPrice": {
-      "source": "orders.order.totals.order-total.tax",
-      "resolver": "sdk.parseFloat",
-      "comment": "Order total tax from SFCC totals (REQUIRED)"
-    },
-    "attributes": {
-      "resolver": "custom.buildOrderAttributes",
-      "comment": "Order-level attributes: order-date, created-by, invoice-no, totals JSON"
-    },
-    "customer": {
-      "fields": {
-        "ref": {
-          "source": "orders.order.customer.customer-no",
-          "resolver": "sdk.toString",
-          "comment": "Customer reference from SFCC (REQUIRED)"
-        },
-        "firstName": {
-          "source": "orders.order.customer.customer-name",
-          "resolver": "custom.extractFirstName",
-          "comment": "Extract first name from customer-name"
-        },
-        "lastName": {
-          "source": "orders.order.customer.customer-name",
-          "resolver": "custom.extractLastName",
-          "comment": "Extract last name from customer-name"
-        },
-        "primaryEmail": {
-          "source": "orders.order.customer.customer-email",
-          "resolver": "sdk.toString",
-          "comment": "Customer email from SFCC (REQUIRED)"
-        }
-      }
-    },
-    "billingAddress": {
-      "fields": {
-        "name": {
-          "source": "orders.order.customer.billing-address.first-name",
-          "resolver": "custom.combineBillingName",
-          "comment": "Combine first-name + last-name"
-        },
-        "street": {
-          "source": "orders.order.customer.billing-address.address1",
-          "resolver": "sdk.toString",
-          "comment": "Billing address line 1 (REQUIRED)"
-        },
-        "street2": {
-          "source": "orders.order.customer.billing-address.address2",
-          "resolver": "sdk.toString",
-          "comment": "Billing address line 2 (optional)"
-        },
-        "city": {
-          "source": "orders.order.customer.billing-address.city",
-          "resolver": "sdk.toString",
-          "comment": "Billing city (REQUIRED)"
-        },
-        "state": {
-          "source": "orders.order.customer.billing-address.state-code",
-          "resolver": "sdk.toString",
-          "comment": "Billing state code (REQUIRED)"
-        },
-        "postcode": {
-          "source": "orders.order.customer.billing-address.postal-code",
-          "resolver": "sdk.toString",
-          "comment": "Billing postal code (REQUIRED)"
-        },
-        "country": {
-          "source": "orders.order.customer.billing-address.country-code",
-          "resolver": "custom.normalizeCountryCode",
-          "comment": "Normalize country code (us → US)"
-        }
-      },
-      "attributes": {
-        "resolver": "custom.buildBillingAddressAttributes",
-        "comment": "Billing address phone and custom attributes"
-      }
-    },
-    "items": {
-      "source": "orders.order.product-lineitems.product-lineitem",
-      "isArray": true,
-      "fields": {
-        "ref": {
-          "source": "$.position",
-          "resolver": "custom.createItemRef",
-          "comment": "Item reference from position (REQUIRED)"
-        },
-        "productRef": {
-          "source": "$.product-id",
-          "resolver": "sdk.toString",
-          "comment": "Product reference from SFCC product-id (REQUIRED)"
-        },
-        "productCatalogueRef": {
-          "resolver": "custom.getProductCatalogueRef",
-          "comment": "Default product catalogue"
-        },
-        "quantity": {
-          "source": "$.quantity",
-          "resolver": "sdk.parseFloat",
-          "comment": "Quantity from SFCC (REQUIRED)"
-        },
-        "price": {
-          "source": "$.base-price",
-          "resolver": "sdk.parseFloat",
-          "comment": "Base price per item from SFCC (REQUIRED)"
-        },
-        "totalPrice": {
-          "source": "$.net-price",
-          "resolver": "sdk.parseFloat",
-          "comment": "Total price (net-price) from SFCC (REQUIRED)"
-        },
-        "taxPrice": {
-          "source": "$.tax",
-          "resolver": "sdk.parseFloat",
-          "comment": "Tax amount from SFCC (REQUIRED)"
-        },
-        "currency": {
-          "source": "orders.order.currency",
-          "resolver": "sdk.toString",
-          "comment": "Currency from order level (REQUIRED)"
-        },
-        "attributes": {
-          "resolver": "custom.buildItemAttributes",
-          "comment": "Item attributes: position, tax-basis, tax-rate, shipment-id, gift, custom-attributes"
-        }
-      }
-    },
-    "fulfilmentChoices": {
-      "source": "orders.order.shipments.shipment",
-      "isArray": true,
-      "fields": {
-        "type": {
-          "source": "$.shipping-method",
-          "resolver": "custom.mapShippingMethodToFulfilmentType",
-          "comment": "Map ISPU → BOPIS, STANDARD_SHIPPING → SHIP_TO_HOME (REQUIRED)"
-        },
-        "pickupLocationRef": {
-          "source": "$.custom-attributes.custom-attribute[attribute-id=fromStoreId]",
-          "resolver": "sdk.toString",
-          "comment": "Store ID for BOPIS orders"
-        },
-        "deliveryType": {
-          "source": "orders.order.shipping-lineitems.shipping-lineitem.item-id",
-          "resolver": "sdk.toString",
-          "comment": "Delivery type (STANDARD_SHIPPING, etc.)"
-        },
-        "deliveryAddress": {
-          "fields": {
-            "name": {
-              "source": "$.shipping-address.first-name",
-              "resolver": "custom.combineShippingName",
-              "comment": "Combine first-name + last-name"
-            },
-            "street": {
-              "source": "$.shipping-address.address1",
-              "resolver": "sdk.toString",
-              "comment": "Shipping address line 1 (REQUIRED)"
-            },
-            "street2": {
-              "source": "$.shipping-address.address2",
-              "resolver": "sdk.toString",
-              "comment": "Shipping address line 2 (optional)"
-            },
-            "city": {
-              "source": "$.shipping-address.city",
-              "resolver": "sdk.toString",
-              "comment": "Shipping city (REQUIRED)"
-            },
-            "state": {
-              "source": "$.shipping-address.state-code",
-              "resolver": "sdk.toString",
-              "comment": "Shipping state code (REQUIRED)"
-            },
-            "postcode": {
-              "source": "$.shipping-address.postal-code",
-              "resolver": "sdk.toString",
-              "comment": "Shipping postal code (REQUIRED)"
-            },
-            "country": {
-              "source": "$.shipping-address.country-code",
-              "resolver": "custom.normalizeCountryCode",
-              "comment": "Normalize country code (US → US)"
-            }
-          },
-          "attributes": {
-            "resolver": "custom.buildFulfilmentAddressAttributes",
-            "comment": "Shipping address phone and custom attributes"
-          }
-        },
-        "attributes": {
-          "resolver": "custom.buildFulfilmentChoicesAttributes",
-          "comment": "Fulfilment attributes: gift, totals JSON (merchandize-total, shipping-total, shipment-total), custom-attributes"
-        }
-      }
-    },
-    "financialTransactions": {
-      "source": "orders.order.payments.payment",
-      "isArray": true,
-      "fields": {
-        "ref": {
-          "source": "$.transaction-id",
-          "resolver": "sdk.toString",
-          "comment": "Transaction ID from SFCC (REQUIRED)"
-        },
-        "type": {
-          "value": "AUTHORIZATION",
-          "comment": "Payment type (REQUIRED)"
-        },
-        "amount": {
-          "source": "$.amount",
-          "resolver": "sdk.parseFloat",
-          "comment": "Payment amount from SFCC (REQUIRED)"
-        },
-        "currency": {
-          "source": "orders.order.currency",
-          "resolver": "sdk.toString",
-          "comment": "Currency from order level (REQUIRED)"
-        },
-        "paymentMethod": {
-          "source": "$.custom-method.method-name",
-          "resolver": "custom.mapPaymentMethod",
-          "comment": "Payment method (KLARNA, CreditCard, etc.) (REQUIRED)"
-        },
-        "externalTransactionCode": {
-          "source": "$.custom-attributes.custom-attribute[attribute-id=klarnaAuthorizationCode]",
-          "resolver": "sdk.toString",
-          "comment": "Authorization code (Klarna, etc.)"
-        },
-        "externalTransactionId": {
-          "source": "$.custom-method.custom-attributes.custom-attribute[attribute-id=klarnaClientToken]",
-          "resolver": "sdk.toString",
-          "comment": "External transaction ID (Klarna client token, etc.)"
-        },
-        "attributes": {
-          "resolver": "custom.buildPaymentAttributes",
-          "comment": "Payment attributes: processor-id, custom-attributes"
-        }
-      }
-    }
-  },
-  "returnFields": ["id", "ref", "status", "totalPrice"]
-}
-```
-
-**Note:** The `returnFields` array specifies which fields are returned in the GraphQL mutation response. These fields are available in `mutationRes.data.createOrder` after executing the mutation. If omitted, defaults to `["id", "ref"]`.
-
-### 5. Custom Resolvers (src/resolvers/order-resolvers.ts)
-
-```typescript
-/**
- * Order Resolvers for SFCC Native → Fluent
- *
- * Maps from SFCC native structure to Fluent order fields
- */
-
-import type { ResolverMap } from './types';
-
-export const orderResolvers: ResolverMap = {
-  /**
-   * Derive order type from SFCC order structure
-   * Example: 1 shipment → "HD", multiple shipments → "MULTI"
-   */
-  'custom.deriveOrderType': (value: any, data: any, config: any, helpers: any): string => {
-    const sfccData = data.root || data || {};
-    const shipments = helpers.ensureArray(helpers.get(sfccData, 'orders.order.shipments.shipment'));
-
-    if (shipments.length > 1) {
-      return 'MULTI';
-    }
-
-    return config.defaultOrderType || 'HD';
-  },
-
-  /**
-   * Get product catalogue reference
-   * Returns default catalogue ref for all items
-   */
-  'custom.getProductCatalogueRef': (value: any, data: any, config: any, helpers: any): string => {
-    return process.env.PRODUCT_CATALOGUE_REF || 'PC:MASTER:2';
-  },
-
-  /**
-   * Build order-level attributes from SFCC fields
-   * Extracts order metadata (order-date, created-by, invoice-no, totals)
-   */
-  'custom.buildOrderAttributes': (
-    value: any,
-    data: any,
-    config: any,
-    helpers: any
-  ): Array<{ name: string; type: string; value: any }> => {
-    const sfccData = data.root || data || {};
-    const order = helpers.get(sfccData, 'orders.order');
-    const attributes: Array<{ name: string; type: string; value: any }> = [];
-
-    // Order date
-    const orderDate = helpers.get(order, 'order-date');
-    if (orderDate) {
-      attributes.push({
-        name: 'order-date',
-        type: 'String',
-        value: orderDate,
-      });
-    }
-
-    // Created by
-    const createdBy = helpers.get(order, 'created-by');
-    if (createdBy) {
-      attributes.push({
-        name: 'created-by',
-        type: 'String',
-        value: createdBy,
-      });
-    }
-
-    // Invoice number
-    const invoiceNo = helpers.get(order, 'invoice-no');
-    if (invoiceNo) {
-      attributes.push({
-        name: 'invoice-no',
-        type: 'String',
-        value: invoiceNo,
-      });
-    }
-
-    // Order totals as JSON
-    const totals = helpers.get(order, 'totals');
-    if (totals) {
-      attributes.push({
-        name: 'totals',
-        type: 'JSON',
-        value: JSON.stringify(totals),
-      });
-    }
-
-    return attributes;
-  },
-};
-```
-
-### 6. Additional Resolvers (src/resolvers/fulfillment-resolvers.ts, item-resolvers.ts, payment-resolvers.ts)
-
-```typescript
-/**
- * Fulfillment Resolvers
- * Handle SFCC shipment data → Fluent fulfilmentChoices
- */
-
-export const fulfillmentResolvers: ResolverMap = {
-  /**
-   * Extract first name from SFCC customer-name field
-   * Example: "John Smith" → "John"
-   */
-  'custom.extractFirstName': (value: any, data: any, config: any, helpers: any): string => {
-    if (!value) return '';
-    const parts = String(value).trim().split(/\s+/);
-    return parts[0] || '';
-  },
-
-  /**
-   * Extract last name from SFCC customer-name field
-   * Example: "John Smith" → "Smith"
-   */
-  'custom.extractLastName': (value: any, data: any, config: any, helpers: any): string => {
-    if (!value) return '';
-    const parts = String(value).trim().split(/\s+/);
-    return parts.length > 1 ? parts.slice(1).join(' ') : '';
-  },
-
-  /**
-   * Combine billing address first-name and last-name
-   * Example: "John" + "Smith" → "John Smith"
-   */
-  'custom.combineBillingName': (value: any, data: any, config: any, helpers: any): string => {
-    const sfccData = data.root || data || {};
-    const firstName = value || helpers.get(sfccData, 'orders.order.customer.billing-address.first-name') || '';
-    const lastName = helpers.get(sfccData, 'orders.order.customer.billing-address.last-name') || '';
-    return `${firstName} ${lastName}`.trim();
-  },
-
-  /**
-   * Combine shipping address first-name and last-name
-   * Example: "Acme" + "Store" → "Acme Store"
-   */
-  'custom.combineShippingName': (value: any, data: any, config: any, helpers: any): string => {
-    const sfccData = data.root || data || {};
-    const firstName = value || helpers.get(sfccData, 'orders.order.shipments.shipment.shipping-address.first-name') || '';
-    const lastName = helpers.get(sfccData, 'orders.order.shipments.shipment.shipping-address.last-name') || '';
-    return `${firstName} ${lastName}`.trim();
-  },
-
-  /**
-   * Normalize country code to uppercase
-   * Example: "us" → "US", "US" → "US"
-   */
-  'custom.normalizeCountryCode': (value: any, data: any, config: any, helpers: any): string => {
-    if (!value) return config.defaultCountry || 'US';
-    return String(value).toUpperCase();
-  },
-
-  /**
-   * Map SFCC shipping-method to Fluent fulfilment type
-   * Example: "ISPU" → "BOPIS", "STANDARD_SHIPPING" → "SHIP_TO_HOME"
-   */
-  'custom.mapShippingMethodToFulfilmentType': (value: any, data: any, config: any, helpers: any): string => {
-    const shippingMethod = String(value || '').toUpperCase();
-    const mapping: Record<string, string> = {
-      ISPU: 'BOPIS',
-      STANDARD_SHIPPING: 'SHIP_TO_HOME',
-      EXPRESS_SHIPPING: 'SHIP_TO_HOME',
-      GROUND_SHIPPING: 'SHIP_TO_HOME',
-    };
-    return mapping[shippingMethod] || 'SHIP_TO_HOME';
-  },
-
-  /**
-   * Build billing address attributes (phone)
-   */
-  'custom.buildBillingAddressAttributes': (
-    value: any,
-    data: any,
-    config: any,
-    helpers: any
-  ): Array<{ name: string; type: string; value: any }> => {
-    const sfccData = data.root || data || {};
-    const attributes: Array<{ name: string; type: string; value: any }> = [];
-
-    const phone = helpers.get(sfccData, 'orders.order.customer.billing-address.phone');
-    if (phone) {
-      attributes.push({ name: 'phone', type: 'String', value: String(phone) });
-    }
-
-    return attributes;
-  },
-
-  /**
-   * Build fulfilment address attributes (phone)
-   */
-  'custom.buildFulfilmentAddressAttributes': (
-    value: any,
-    data: any,
-    config: any,
-    helpers: any
-  ): Array<{ name: string; type: string; value: any }> => {
-    const sfccData = data.root || data || {};
-    const attributes: Array<{ name: string; type: string; value: any }> = [];
-
-    const phone = helpers.get(sfccData, 'orders.order.shipments.shipment.shipping-address.phone');
-    if (phone) {
-      attributes.push({ name: 'phone', type: 'String', value: String(phone) });
-    }
-
-    return attributes;
-  },
-
-  /**
-   * Build fulfilment choices attributes
-   * Includes gift flag, totals JSON, and custom attributes
-   */
-  'custom.buildFulfilmentChoicesAttributes': (
-    value: any,
-    data: any,
-    config: any,
-    helpers: any
-  ): Array<{ name: string; type: string; value: any }> => {
-    const sfccData = data.root || data || {};
-    const attributes: Array<{ name: string; type: string; value: any }> = [];
-
-    // Gift flag
-    const gift = helpers.get(sfccData, 'orders.order.shipments.shipment.gift');
-    if (gift !== undefined) {
-      attributes.push({ name: 'gift', type: 'Boolean', value: gift === 'true' || gift === true });
-    }
-
-    // Shipment totals as JSON
-    const totals = helpers.get(sfccData, 'orders.order.shipments.shipment.totals');
-    if (totals) {
-      attributes.push({
-        name: 'totals',
-        type: 'JSON',
-        value: JSON.stringify(totals),
-      });
-    }
-
-    // Custom attributes (fromStoreId, shipmentType, etc.)
-    const customAttrs = helpers.ensureArray(
-      helpers.get(sfccData, 'orders.order.shipments.shipment.custom-attributes.custom-attribute')
-    );
-    for (const attr of customAttrs) {
-      const attrId = attr['@attribute-id'];
-      const attrValue = attr._ || attr['#text'] || attr;
-      if (attrId && attrValue !== undefined) {
-        attributes.push({
-          name: attrId,
-          type: 'String',
-          value: String(attrValue),
-        });
-      }
-    }
-
-    return attributes;
-  },
-};
-
-/**
- * Item Resolvers
- * Handle SFCC product-lineitem data → Fluent order items
- */
-
-export const itemResolvers: ResolverMap = {
-  /**
-   * Create item reference from position
-   * Example: position "1" → "item_1"
-   */
-  'custom.createItemRef': (value: any, data: any, config: any, helpers: any): string => {
-    const position = String(value || '1');
-    return `item_${position}`;
-  },
-
-  /**
-   * Build item attributes
-   * Includes position, tax-basis, tax-rate, shipment-id, gift, custom-attributes
-   */
-  'custom.buildItemAttributes': (
-    value: any,
-    data: any,
-    config: any,
-    helpers: any
-  ): Array<{ name: string; type: string; value: any }> => {
-    const itemData = data || {};
-    const sfccData = data.root || data || {};
-    const attributes: Array<{ name: string; type: string; value: any }> = [];
-
-    // Position
-    const position = itemData.position || helpers.get(sfccData, 'orders.order.product-lineitems.product-lineitem.position');
-    if (position) {
-      attributes.push({ name: 'position', type: 'String', value: String(position) });
-    }
-
-    // Tax basis
-    const taxBasis = itemData['tax-basis'] || helpers.get(sfccData, 'orders.order.product-lineitems.product-lineitem.tax-basis');
-    if (taxBasis) {
-      attributes.push({ name: 'tax-basis', type: 'String', value: String(taxBasis) });
-    }
-
-    // Tax rate
-    const taxRate = itemData['tax-rate'] || helpers.get(sfccData, 'orders.order.product-lineitems.product-lineitem.tax-rate');
-    if (taxRate) {
-      attributes.push({ name: 'tax-rate', type: 'String', value: String(taxRate) });
-    }
-
-    // Shipment ID
-    const shipmentId = itemData['shipment-id'] || helpers.get(sfccData, 'orders.order.product-lineitems.product-lineitem.shipment-id');
-    if (shipmentId) {
-      attributes.push({ name: 'shipment-id', type: 'String', value: String(shipmentId) });
-    }
-
-    // Gift flag
-    const gift = itemData.gift || helpers.get(sfccData, 'orders.order.product-lineitems.product-lineitem.gift');
-    if (gift !== undefined) {
-      attributes.push({ name: 'gift', type: 'Boolean', value: gift === 'true' || gift === true });
-    }
-
-    // Custom attributes (fromStoreId, storeQty, etc.)
-    const customAttrs = helpers.ensureArray(
-      itemData['custom-attributes']?.['custom-attribute'] ||
-      helpers.get(sfccData, 'orders.order.product-lineitems.product-lineitem.custom-attributes.custom-attribute')
-    );
-    for (const attr of customAttrs) {
-      const attrId = attr['@attribute-id'];
-      const attrValue = attr._ || attr['#text'] || attr;
-      if (attrId && attrValue !== undefined) {
-        attributes.push({
-          name: attrId,
-          type: 'String',
-          value: String(attrValue),
-        });
-      }
-    }
-
-    return attributes;
-  },
-};
-
-/**
- * Payment Resolvers
- * Handle SFCC payment data → Fluent financialTransactions
- */
-
-export const paymentResolvers: ResolverMap = {
-  /**
-   * Map SFCC payment method to Fluent payment method
-   * Example: "KLARNA" → "KLARNA", "CreditCard" → "CreditCard"
-   */
-  'custom.mapPaymentMethod': (value: any, data: any, config: any, helpers: any): string => {
-    const methodName = String(value || '').toUpperCase();
-    const mapping: Record<string, string> = {
-      KLARNA: 'KLARNA',
-      CREDITCARD: 'CreditCard',
-      PAYPAL: 'PayPal',
-      APPLEPAY: 'ApplePay',
-      GOOGLEPAY: 'GooglePay',
-    };
-    return mapping[methodName] || methodName;
-  },
-
-  /**
-   * Build payment attributes
-   * Includes processor-id, custom-attributes (klarnaAuthorizationCode, etc.)
-   */
-  'custom.buildPaymentAttributes': (
-    value: any,
-    data: any,
-    config: any,
-    helpers: any
-  ): Array<{ name: string; type: string; value: any }> => {
-    const paymentData = data || {};
-    const sfccData = data.root || data || {};
-    const attributes: Array<{ name: string; type: string; value: any }> = [];
-
-    // Processor ID
-    const processorId = paymentData['processor-id'] || helpers.get(sfccData, 'orders.order.payments.payment.processor-id');
-    if (processorId) {
-      attributes.push({ name: 'processor-id', type: 'String', value: String(processorId) });
-    }
-
-    // Custom attributes
-    const customAttrs = helpers.ensureArray(
-      paymentData['custom-attributes']?.['custom-attribute'] ||
-      helpers.get(sfccData, 'orders.order.payments.payment.custom-attributes.custom-attribute')
-    );
-    for (const attr of customAttrs) {
-      const attrId = attr['@attribute-id'];
-      const attrValue = attr._ || attr['#text'] || attr;
-      if (attrId && attrValue !== undefined) {
-        attributes.push({
-          name: attrId,
-          type: 'String',
-          value: String(attrValue),
-        });
-      }
-    }
-
-    return attributes;
-  },
-};
-```
-
-### 7. Resolver Types (src/resolvers/types.ts)
-
-```typescript
-/**
- * Type definitions for custom resolvers
- */
-
-export interface ResolverHelpers {
-  logger?: any;
-  fluentClient?: any;
-  get: (obj: any, path: string) => any;
-  ensureArray: (val: any) => any[];
-}
-
-export type ResolverFunction = (
-  value: any,
-  data: any,
-  config: any,
-  helpers: ResolverHelpers
-) => any | Promise<any>;
-
-export type ResolverMap = Record<string, ResolverFunction>;
-```
-
-### 8. Export All Resolvers (src/resolvers/index.ts)
-
-```typescript
-/**
- * All custom resolvers for SFCC native mapping
- */
-
-import { orderResolvers } from './order-resolvers';
-import { fulfillmentResolvers } from './fulfillment-resolvers';
-import { itemResolvers } from './item-resolvers';
-import { paymentResolvers } from './payment-resolvers';
-
-export const allResolvers = {
-  ...orderResolvers,
-  ...fulfillmentResolvers,
-  ...itemResolvers,
-  ...paymentResolvers,
-};
-
-// Export individual resolver maps for testing
-export { orderResolvers, fulfillmentResolvers, itemResolvers, paymentResolvers };
-```
-
-### 9. Versori Deployment Files
-
-#### package.json
-
-```json
-{
-  "name": "sfcc-order-webhook",
-  "version": "1.0.0",
-  "type": "module",
-  "dependencies": {
-    "@fluentcommerce/fc-connect-sdk": "^0.1.41",
-    "@versori/run": "latest"
-  }
-}
-```
-
-#### import_map.json
-
-```json
-{
-  "imports": {
-    "@fluentcommerce/fc-connect-sdk": "https://esm.sh/@fluentcommerce/fc-connect-sdk@0.1.41",
-    "@versori/run": "https://esm.sh/@versori/run@latest",
-    "node:buffer": "https://deno.land/std@0.224.0/node/buffer.ts",
-    "node:fs": "https://deno.land/std@0.224.0/node/fs.ts",
-    "node:path": "https://deno.land/std@0.224.0/node/path.ts"
-  }
-}
-```
-
----
-
-## Common Issues
-
-### Issue 1: "Missing required field: orders.order"
-
-**Cause**: XML structure doesn't match expected SFCC format
-
-**Solution**: Validate XML structure
-
-```typescript
-// Check structure
-if (!sfccData.orders?.order) {
-  throw new Error('Invalid XML structure: missing orders.order');
-}
-```
-
-### Issue 2: "Order type is undefined"
-
-**Cause**: Resolver not deriving order type correctly
-
-**Solution**: Check shipments array
-
-```typescript
-const shipments = helpers.ensureArray(helpers.get(sfccData, 'orders.order.shipments.shipment'));
-return shipments.length > 1 ? 'MULTI' : 'HD';
-```
-
-### Issue 3: "Expected array at path but got object"
-
-**Cause**: XML parser doesn't create arrays for single items
-
-**Solution**: Use `helpers.ensureArray()` in resolvers
-
-```typescript
-// ✅ CORRECT - wraps single items
-const items = helpers.ensureArray(helpers.get(sfccData, 'orders.order.product-lineitems.product-lineitem'));
-```
-
----
-
-## Production Checklist
-
-Before deploying to production:
-
-- [ ] Set proper environment variables in Versori (RETAILER_ID, PRODUCT_CATALOGUE_REF)
-- [ ] Configure error alerting/monitoring
-- [ ] Test with real SFCC webhook payload
-- [ ] Test all resolver edge cases (missing data, null values)
-- [ ] Set up log aggregation
-- [ ] Configure connection retry logic for transient failures
-- [ ] Document any customer-specific field mappings
-
----
-
-**Next Steps**: For more advanced SFCC integration patterns, explore the Radial XML version of this template for orders requiring Radial-specific fields.
+---
+template_id: tpl-webhook-xml-order-ingestion-sfcc
+canonical_filename: template-webhook-xml-order-ingestion.md
+sdk_version: ^0.1.41
+runtime: versori
+direction: ingestion
+source: webhook-xml-sfcc
+destination: fluent-graphql
+entity: order
+format: xml
+logging: versori
+status: production-ready
+last_updated: 2025-11-13
+---
+
+# Template: Webhook - SFCC XML Order Ingestion
+
+**FC Connect SDK Use Case Guide**
+
+> **SDK**: [@fluentcommerce/fc-connect-sdk](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk)
+> **Version**: Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
+
+**Context**: Receive SFCC XML orders via Versori HTTP webhook and create orders in Fluent Commerce using GraphQL mutations.
+
+**Complexity**: Medium
+
+**Runtime**: Versori Platform
+
+**Estimated Lines**: ~500 lines (modular structure)
+
+---
+
+## STEP 1: Understand This Template
+
+**What This Template Does:**
+
+- Versori HTTP webhook endpoint receiving XML order data (SFCC native format)
+- XML parsing with automatic Versori XML-to-object conversion (incoming XML)
+- GraphQL mutation mapping from SFCC native XML structure to Fluent schema
+- Uses ONLY SFCC native fields (orders.order.*) - no Radial XML dependency
+- Custom resolvers for data transformation, name parsing, and order type derivation
+- Error handling and structured response formatting
+- **Response Options**: JSON (default) or XML (with custom Response handler)
+- **Sync + Fire-and-Forget Pattern**: Fast webhook response, background processing
+
+**Key SDK Components:**
+
+- `createClient()` - Universal client factory (auto-detects Versori context)
+- `GraphQLMutationMapper` - XML/JSON → GraphQL mutation mapping
+- Native Versori `log` - Use `log` from context
+- No XML parsing needed (Versori handles automatically)
+
+**Entity Type:**
+
+- **Order** - Fluent entity for order creation
+- **GraphQL Mutation** - Uses `createOrder` mutation (not Event API)
+
+**Critical Patterns:**
+
+- **XML Response Pattern**: Production-ready XML response handling with proper Content-Type headers
+- **Logger Adapter**: Type-safe logging with SDK Logger interface
+- **Sync + Fire-and-Forget**: Webhook validates quickly, returns immediately, processes in background
+- **External JSON Config**: Mapping configuration in separate JSON file (`config/sfcc-to-fluent-order-mapping.json`)
+- **Modular Architecture**: Separate services, workflows, config, types folders
+- **Integration Variables Validation**: Fail-fast validation of required configuration
+- **Initial Deployment Monitoring**: Temporary full payload logging for troubleshooting
+- **SFCC Native Only**: No Radial XML dependency - simpler and more maintainable
+
+**When to Use This Template:**
+
+- ✅ SFCC native XML order ingestion (orders.order.* structure)
+- ✅ Need fast webhook response (don't wait for order creation)
+- ✅ Single order per webhook call
+- ✅ BOPIS (Buy Online Pick Up In Store) and standard shipping orders
+- ✅ Custom resolvers for complex transformations (name parsing, address normalization)
+- ✅ Want simpler template without Radial XML complexity
+
+**When NOT to Use:**
+
+- ❌ Bulk order processing (use Batch API or scheduled workflows)
+- ❌ Order updates (use GraphQL `updateOrder` mutation)
+- ❌ CSV/JSON formats (use appropriate format template)
+- ❌ Need synchronous order creation (wait for result before responding)
+- ❌ Orders requiring Radial-specific fields (use Radial template instead)
+
+---
+
+## STEP 2: Implementation Prompt for Claude Code
+
+**Copy this prompt and send to Claude Code to generate the complete implementation:**
+
+```
+Create a Versori webhook workflow for SFCC XML order ingestion to Fluent Commerce GraphQL.
+
+REQUIREMENTS:
+1. Runtime: Versori Platform (HTTP webhook)
+2. Source: SFCC XML order data via HTTP POST webhook
+3. Destination: Fluent Commerce GraphQL API (createOrder mutation)
+4. Format: XML (Versori auto-parses to object)
+5. Entity: Order (GraphQL mutation)
+
+KEY FEATURES:
+- Sync + fire-and-forget pattern (fast webhook response, background processing)
+- External JSON mapping configuration (config/sfcc-to-fluent-order-mapping.json)
+- Modular architecture (workflows/, services/, config/, types/)
+- SFCC native fields ONLY (no Radial XML)
+- GraphQLMutationMapper with standard map() method (no nodes)
+- Custom resolvers for data transformation
+- Audit trail (save input/output files)
+- Comprehensive error handling with structured logging
+
+CRITICAL REQUIREMENTS:
+1. Webhook Mode: response: { mode: 'sync' } with XML onSuccess/onError handlers
+2. Response Format: XML with proper Content-Type headers (production standard for SFCC)
+3. Logger Adapter: Create typed Logger adapter from Versori log
+4. Background Processing: Fire-and-forget pattern (no await on long operations)
+5. Mapping Config: External JSON file (config/sfcc-to-fluent-order-mapping.json)
+6. Custom Resolvers: USE mapWithNodes() when you have custom resolvers (REQUIRED)
+7. Integration Variables: Fail-fast validation of required config (fluentRetailerId)
+8. Modular Structure: Separate services/, config/, types/ folders
+9. Step Documentation: Use visual separator blocks for each workflow step
+10. Error Handling: Structured error responses with recommendations
+
+SDK METHODS TO USE (v0.1.41+):
+- createClient({ ...ctx, log }) - Pass full Versori context
+- Logger adapter pattern - Type-safe logging wrapper
+- new GraphQLMutationMapper(mappingConfig, logger, { customResolvers, fluentClient: client }) - Initialize mapper with resolvers (RECOMMENDED)
+- mapper.mapWithNodes(xmlData, undefined, context) - Map with constructor resolvers (auto-returns query)
+- result.query and result.variables - Auto-generated from mapWithNodes()
+- client.graphql({ query: result.query, variables: result.variables }) - Execute mutation
+
+FORBIDDEN PATTERNS:
+- ❌ Inline mapping config (use external JSON)
+- ❌ await on background processing (use fire-and-forget)
+- ❌ Passing log directly to SDK (use Logger adapter)
+- ❌ All code in one file (use modular structure)
+- ❌ async mode webhook (use sync + fire-and-forget)
+- ❌ Radial XML references (use SFCC native only)
+- ❌ buildMutation() calls (mapWithNodes() auto-generates query in v0.1.41+)
+- ❌ Silent config fallbacks (fail-fast on missing required variables)
+```
+
+---
+
+## STEP 3: Detailed Flow Documentation
+
+### Complete Processing Flow
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ 1. WEBHOOK RECEIVED                                         │
+│    POST https://{workspace}.versori.run/sfcc-order-create   │
+│    Content-Type: application/xml                             │
+│    Body: <orders xmlns="..."><order order-no="...">         │
+│          <original-order-no>...</original-order-no>          │
+│          <customer>...</customer>                            │
+│          <product-lineitems>...</product-lineitems>          │
+│          <shipments>...</shipments>                          │
+│          <totals>...</totals>                                │
+│          <payments>...</payments>                            │
+│          </order></orders>                                   │
+└────────────────────┬────────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────────┐
+│ 2. QUICK VALIDATION (Synchronous, ~10-50ms)                 │
+│    - Check fluent_commerce connection exists                 │
+│    - Validate SFCC XML payload present                      │
+│    - Validate required fields (original-order-no, customer) │
+│    - Return HTTP 200 OK immediately                         │
+└────────────────────┬────────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────────┐
+│ 3. BACKGROUND PROCESSING (Fire-and-Forget)                   │
+│    ┌─────────────────────────────────────────────────────┐  │
+│    │ 3a. Initialize Fluent Client                        │  │
+│    │     - createClient({ ...ctx, log })                 │  │
+│    └─────────────────────────────────────────────────────┘  │
+│    ┌─────────────────────────────────────────────────────┐  │
+│    │ 3b. Validate SFCC Structure                         │  │
+│    │     - Check required SFCC native fields             │  │
+│    │     - Validate order structure                      │  │
+│    └─────────────────────────────────────────────────────┘  │
+│    ┌─────────────────────────────────────────────────────┐  │
+│    │ 3c. Map SFCC Native XML to GraphQL Variables       │  │
+│    │     - Load mapping config from JSON                 │  │
+│    │     - Use SFCC native fields ONLY (orders.order.*) │  │
+│    │     - GraphQLMutationMapper.mapWithNodes() (REQUIRED for custom resolvers)│  │
+│    │     - Apply custom resolvers                        │  │
+│    │     - Returns { query, variables } (GraphQLPayload) │  │
+│    └─────────────────────────────────────────────────────┘  │
+│    ┌─────────────────────────────────────────────────────┐  │
+│    │ 3d. Execute GraphQL Mutation                        │  │
+│    │     - client.graphql(payload) - one simple step!    │  │
+│    └─────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Response Timing
+
+| Stage | Timing | Blocking |
+|-------|--------|----------|
+| **Webhook Validation** | ~10-50ms | ✅ Yes (blocks response) |
+| **Background Processing** | ~1000-2000ms | ❌ No (fire-and-forget) |
+| **Total Response Time** | ~10-50ms | ✅ Fast response |
+
+**Key Benefit**: Webhook caller receives immediate acknowledgment (~50ms) while order creation happens in background (~1-2s).
+
+---
+
+## STEP 4: Production Modular Structure
+
+> **✅ This section shows the COMPLETE production-ready modular structure.**
+> All files are shown with proper imports/exports and folder organization.
+
+### Complete Project Structure
+
+```
+sfcc-xml-order-ingestion/
+├── package.json                              # Dependencies and Versori config
+├── index.ts                                  # Entry point - exports all workflows
+└── src/
+    ├── workflows/
+    │   └── webhook/
+    │       └── order-ingestion.ts            # Webhook: Receive SFCC XML orders
+    │
+    ├── services/
+    │   └── order-processing.service.ts       # Shared orchestration logic (reusable)
+    │
+    ├── resolvers/
+    │   ├── index.ts                          # Export all resolvers
+    │   ├── types.ts                          # TypeScript interfaces
+    │   ├── order-resolvers.ts                # Order-level resolvers
+    │   ├── fulfillment-resolvers.ts          # Shipment/fulfillment resolvers
+    │   ├── item-resolvers.ts                 # Product line item resolvers
+    │   └── payment-resolvers.ts              # Payment resolvers
+    │
+    ├── config/
+    │   └── sfcc-to-fluent-order-mapping.json # Mapping configuration (external JSON)
+    │
+    └── types/
+        └── order.types.ts                    # TypeScript interfaces
+```
+
+**Why This Structure?**
+
+- ✅ **Clear separation**: Webhook handlers vs business logic
+- ✅ **Reusable services**: Order processing logic can be reused
+- ✅ **External config**: Mapping changes don't require code changes
+- ✅ **Custom resolvers**: Separate file for complex transformations
+- ✅ **Type safety**: TypeScript interfaces for better IDE support
+- ✅ **Scalable**: Easy to add new webhooks or services
+
+---
+
+---
+
+## CRITICAL: XML Response Architecture (Production Pattern)
+
+### Overview
+
+This template uses **XML responses** as the PRIMARY pattern for SFCC integration. This is the production-proven approach used in real SFCC → Fluent integrations.
+
+### How XML Response Handling Works
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ ARCHITECTURE FLOW                                               │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  1. Workflow Steps Return XML Strings                          │
+│     ↓ ctx.data = "<OrderProcessingResponse>...</>"             │
+│                                                                 │
+│  2. onSuccess Handler Receives Context                         │
+│     ↓ ctx = { data: xmlString, executionId: "..." }           │
+│                                                                 │
+│  3. Handler Wraps in Response Object                           │
+│     ↓ new Response(ctx.data, { headers: {...} })              │
+│                                                                 │
+│  4. Framework Streams Response Directly                        │
+│     ↓ No JSON encoding - pure XML stream                       │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Response Format Examples
+
+**Success Response:**
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<OrderProcessingResponse>
+  <Status>success</Status>
+  <Message>Order successfully processed and created in Fluent Commerce</Message>
+  <FluentOrderId>6370</FluentOrderId>
+  <FluentOrderRef>0017326966182_G_postman_test_1760703173226</FluentOrderRef>
+  <SFCCOrderRef>0017326966182_G_postman_test_1760703173226</SFCCOrderRef>
+  <Timestamp>2025-11-13T12:12:54.229Z</Timestamp>
+</OrderProcessingResponse>
+```
+
+**Error Response:**
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<OrderProcessingResponse>
+  <Status>error</Status>
+  <Message>Failed to process order</Message>
+  <Error>Missing required field: original-order-no</Error>
+  <Timestamp>2025-11-13T12:12:54.229Z</Timestamp>
+</OrderProcessingResponse>
+```
+
+### Key Benefits
+
+- ✅ **SFCC Native**: SFCC systems expect XML responses
+- ✅ **Type Safety**: Structured XML schema
+- ✅ **Execution Tracking**: X-Execution-Id header for troubleshooting
+- ✅ **Proper Content-Type**: application/xml; charset=utf-8
+- ✅ **Framework Streaming**: Direct XML stream (no JSON wrapper)
+
+---
+
+## XML Handling Patterns
+
+### Incoming XML (Versori Auto-Parsing)
+
+**CRITICAL**: Versori automatically parses XML when `Content-Type: application/xml` is set.
+
+```typescript
+// ✅ CORRECT - Versori auto-parses XML into object
+// When SFCC sends: POST /webhook with Content-Type: application/xml
+// Versori automatically converts XML string → parsed object
+// ctx.data is already a parsed object, NOT a string
+
+export const webhook = webhook('order-ingestion', { response: { mode: 'sync' } })
+  .then(http('process', { connection: 'fluent_commerce' }, async (ctx) => {
+    // ctx.data is already parsed! No manual parsing needed
+    const sfccData = ctx.data; // Already an object: { orders: { order: {...} } }
+
+    // Validate structure
+    if (!sfccData.orders?.order) {
+      throw new Error('Invalid XML structure: missing orders.order');
+    }
+
+    // Use mapWithNodes() because we have custom resolvers
+    // ✅ Resolvers passed in constructor, so pass undefined here (or override if needed)
+    const result = await mapper.mapWithNodes(sfccData, undefined, context);
+  }));
+
+// ❌ WRONG - Don't try to parse manually
+const xmlString = ctx.data; // This is already parsed!
+const parsed = parseXML(xmlString); // Unnecessary!
+```
+
+**Why This Matters:**
+- Versori handles XML parsing automatically
+- `ctx.data` is always a parsed object when Content-Type is `application/xml`
+- No need for `XMLParserService` or manual parsing in Versori workflows
+- Simply validate the structure and use directly
+
+### Outgoing XML (Production-Ready Pattern)
+
+**RECOMMENDED FOR SFCC**: Use XML responses with custom handlers for production SFCC integrations.
+
+**XML Response Pattern (RECOMMENDED)**
+```typescript
+import { XMLBuilder } from '@fluentcommerce/fc-connect-sdk';
+
+export const webhook = webhook('order-ingestion', {
+  response: {
+    mode: 'sync',
+    /**
+     * onSuccess Handler for XML Response
+     *
+     * This handler wraps the XML response string with proper headers.
+     * The workflow steps return XML strings via ctx.data, and this
+     * handler wraps them in Response objects for proper streaming.
+     *
+     * @param ctx - Context containing:
+     *   - ctx.data: The XML response string from the final workflow step
+     *   - ctx.executionId: Unique identifier for this execution
+     * @returns Response object with XML body and proper headers
+     */
+    onSuccess: (ctx) => new Response(ctx.data, {
+      status: 200,
+      headers: {
+        'Content-Type': 'application/xml; charset=utf-8',
+        'X-Execution-Id': ctx.executionId
+      }
+    }),
+    /**
+     * onError Handler for XML Error Response
+     *
+     * This handler wraps error responses with proper status and headers.
+     * Returns XML format for consistent error responses.
+     *
+     * @param ctx - Context containing:
+     *   - ctx.data: The error XML string from the .catch() step
+     *   - ctx.executionId: Unique identifier for tracking failed executions
+     * @returns Response object with error XML and 500 status
+     */
+    onError: (ctx) => new Response(ctx.data, {
+      status: 500,
+      headers: {
+        'Content-Type': 'application/xml; charset=utf-8',
+        'X-Execution-Id': ctx.executionId
+      }
+    })
+  }
+})
+  .then(http('process', { connection: 'fluent_commerce' }, async (ctx) => {
+    // Process order...
+    const orderId = '12345';
+    const orderRef = 'ORD-001';
+    
+    // Build XML response string
+    const builder = new XMLBuilder({
+      xmlDeclaration: true,  // Adds <?xml version="1.0" encoding="UTF-8"?>
+      prettyPrint: true,     // Format with indentation
+      encoding: 'UTF-8'
+    });
+
+    const responseData = {
+      Status: 'success',
+      FluentOrderId: orderId,
+      FluentOrderRef: orderRef,
+      Timestamp: new Date().toISOString()
+    };
+
+    // Return XML string (onSuccess handler wraps it in Response)
+    return builder.build(responseData, 'OrderProcessingResponse');
+  }))
+  .catch(({ data, log }) => {
+    // Return error XML string (onError handler wraps it)
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<OrderProcessingResponse>
+  <Status>error</Status>
+  <Error>${data instanceof Error ? data.message : String(data)}</Error>
+</OrderProcessingResponse>`;
+  });
+// Response: <?xml version="1.0"?><OrderProcessingResponse>...
+// Content-Type: application/xml; charset=utf-8
+```
+
+**Alternative: JSON Response (Simple Testing)**
+
+For testing or non-SFCC systems, you can use JSON responses:
+
+```typescript
+export const webhook = webhook('order-ingestion', {
+  response: { mode: 'sync' }
+})
+  .then(http('process', { connection: 'fluent_commerce' }, async (ctx) => {
+    // Returns JSON object - Versori auto-encodes
+    return {
+      success: true,
+      orderId: '12345',
+      orderRef: 'ORD-001'
+    };
+  }));
+// Response: {"success":true,"orderId":"12345","orderRef":"ORD-001"}
+// Content-Type: application/json
+```
+
+**Key Decision Points:**
+
+| Pattern | Use When | Response Type |
+|---------|----------|---------------|
+| **XML Response** | Production SFCC integration | XML with proper headers |
+| **JSON Response** | Testing, non-SFCC systems | JSON auto-encoded |
+
+**Key Points:**
+- ✅ **XML (Recommended)**: Requires custom `onSuccess`/`onError` handlers with `Response` objects
+- ✅ **JSON (Testing)**: Default behavior, no custom handler needed
+- ✅ Workflow steps return raw strings (XML) or objects (JSON)
+- ✅ Response handlers wrap in `Response` objects with proper Content-Type
+
+---
+
+## SDK Methods Used
+
+```typescript
+// Core SDK imports
+// FC Connect SDK v0.1.41+
+// Install: npm install @fluentcommerce/fc-connect-sdk@^0.1.41
+// Docs: https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk/
+// GitHub: https://github.com/fluentcommerce/fc-connect-sdk
+
+import { createClient, GraphQLMutationMapper, XMLBuilder } from '@fluentcommerce/fc-connect-sdk';
+import type { Logger } from '@fluentcommerce/fc-connect-sdk';
+
+// ═══════════════════════════════════════════════════════════════
+// LOGGER ADAPTER PATTERN (Production-Proven)
+// ═══════════════════════════════════════════════════════════════
+// Create typed Logger adapter from Versori log
+// Benefits:
+// - Type safety with SDK Logger interface
+// - Centralized logging (easy to modify all calls)
+// - Clear separation between Versori log and SDK Logger
+const logger: Logger = {
+  info: (msg: string, meta?: any) => log.info(msg, meta),
+  error: (msg: string, error?: Error, meta?: any) => log.error(msg, meta),
+  warn: (msg: string, meta?: any) => log.info(msg, meta),
+  debug: (msg: string, meta?: any) => log.info(msg, meta)
+};
+
+// Key methods
+createClient(ctx); // Auto-detects Versori context
+// ✅ RECOMMENDED: Pass resolvers in constructor
+new GraphQLMutationMapper(config, logger, { customResolvers, fluentClient: client }); 
+// ✅ Alternative: Pass resolvers to mapWithNodes (constructor resolvers merged)
+mapper.mapWithNodes(data, resolvers, context); 
+// ✅ v0.1.41+: mapWithNodes() auto-returns query and variables
+const result = await mapper.mapWithNodes(data, undefined, context); // Use constructor resolvers
+// result.query - Auto-generated GraphQL mutation
+// result.variables - Auto-wrapped variables (input object)
+client.graphql({ query: result.query, variables: result.variables }); // Execute
+```
+
+### Why GraphQLMutationMapper (Not UniversalMapper)?
+
+**GraphQLMutationMapper** is the right choice for this template because:
+
+✅ **Automatic Mutation Building**: Automatically generates GraphQL mutation query from mapping config
+✅ **Input Wrapping**: Automatically wraps mapped data in `input` object (Fluent API requirement)
+✅ **GraphQL-Specific**: Designed specifically for GraphQL mutations with schema awareness
+
+**UniversalMapper** would require:
+- ❌ Manual GraphQL mutation query building
+- ❌ Manual `input` wrapping
+- ❌ More boilerplate code
+
+**Use UniversalMapper when**: You need general-purpose data transformation (CSV → JSON, GraphQL → Parquet, etc.)
+**Use GraphQLMutationMapper when**: You need XML/JSON → GraphQL mutations (this template's use case)
+
+---
+
+## Complete Working Code
+
+### 1. Entry Point (index.ts)
+
+```typescript
+/**
+ * Entry point - Export all workflows for Versori platform
+ */
+
+// Webhook workflows
+export { sfccOrderCreate } from './workflows/webhook/sfcc-order-create';
+```
+
+### 2. Workflow Entry Point (workflows/webhook/sfcc-order-create.ts)
+
+```typescript
+/**
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * SFCC → FLUENT ORDER CREATE WEBHOOK (Production Pattern)
+ * ═══════════════════════════════════════════════════════════════════════════════
+ *
+ * PURPOSE:
+ * This webhook receives order data from Salesforce Commerce Cloud (SFCC) as XML
+ * in the request body. It validates, transforms, and creates orders in Fluent
+ * Commerce via GraphQL mutations.
+ *
+ * WEBHOOK CONFIGURATION:
+ * - Response mode: synchronous (caller waits for response)
+ * - Response format: XML (OrderProcessingResponse)
+ * - CORS: enabled (allows cross-origin requests)
+ * - Expected payload: XML in request body (Content-Type: application/xml)
+ *
+ * ARCHITECTURE:
+ * Uses production-proven patterns from real SFCC integrations:
+ * - XML response handling with proper Content-Type headers
+ * - Logger adapter for type-safe logging
+ * - Fire-and-forget background processing
+ * - Fail-fast validation of required configuration
+ * - Visual step documentation blocks
+ *
+ * WORKFLOW STEPS:
+ * 1. Validate XML structure and required fields
+ * 2. Apply mapping with custom resolvers
+ * 3. Execute GraphQL mutation to create order
+ * 4. Build XML response with order creation results
+ * ═══════════════════════════════════════════════════════════════════════════════
+ */
+
+import { webhook, http, fn } from '@versori/run';
+import type { Context } from '@versori/run';
+import { createClient, GraphQLMutationMapper } from '@fluentcommerce/fc-connect-sdk';
+import type { Logger } from '@fluentcommerce/fc-connect-sdk';
+import { allResolvers } from '../../resolvers';
+import mappingConfig from '../../config/sfcc-to-fluent-order-mapping.json' with { type: 'json' };
+import { XMLBuilder } from '@fluentcommerce/fc-connect-sdk';
+
+/**
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * XML RESPONSE ARCHITECTURE (Production Pattern)
+ * ═══════════════════════════════════════════════════════════════════════════════
+ *
+ * This webhook uses XML responses as the PRIMARY pattern for SFCC integration.
+ * The onSuccess and onError handlers wrap XML strings in Response objects with
+ * proper Content-Type headers.
+ *
+ * RESPONSE FORMAT:
+ * Success:
+ * <?xml version="1.0" encoding="UTF-8"?>
+ * <OrderProcessingResponse>
+ *   <Status>success</Status>
+ *   <Message>Order successfully processed and created in Fluent Commerce</Message>
+ *   <FluentOrderId>6370</FluentOrderId>
+ *   <FluentOrderRef>0017326966182_G_postman_test_1760703173226</FluentOrderRef>
+ *   <SFCCOrderRef>0017326966182_G_postman_test_1760703173226</SFCCOrderRef>
+ *   <Timestamp>2025-11-13T12:12:54.229Z</Timestamp>
+ * </OrderProcessingResponse>
+ *
+ * Error:
+ * <?xml version="1.0" encoding="UTF-8"?>
+ * <OrderProcessingResponse>
+ *   <Status>error</Status>
+ *   <Message>Failed to process order</Message>
+ *   <Error>Error details here</Error>
+ *   <Timestamp>2025-11-13T12:12:54.229Z</Timestamp>
+ * </OrderProcessingResponse>
+ *
+ * HOW IT WORKS:
+ * 1. Workflow steps return XML strings via ctx.data
+ * 2. onSuccess handler receives ctx with the XML string in ctx.data
+ * 3. Handler creates Response with Content-Type: application/xml
+ * 4. Framework streams the Response directly (no JSON encoding)
+ * ═══════════════════════════════════════════════════════════════════════════════
+ */
+export const sfccOrderCreate = webhook('sfcc-order-create', {
+  response: {
+    mode: 'sync',
+    /**
+     * onSuccess Handler for XML Response
+     *
+     * This handler wraps the XML response string with proper headers.
+     * Similar to production SFCC workflows, this ensures the XML is
+     * streamed directly without JSON encoding.
+     *
+     * @param ctx - Context containing:
+     *   - ctx.data: The XML response string from the final workflow step
+     *   - ctx.executionId: Unique identifier for this execution
+     * @returns Response object with XML body and proper headers
+     */
+    onSuccess: (ctx) => new Response(ctx.data, {
+      status: 200,
+      headers: {
+        'Content-Type': 'application/xml; charset=utf-8',
+        'X-Execution-Id': ctx.executionId
+      }
+    }),
+    /**
+     * onError Handler for XML Error Response
+     *
+     * This handler wraps error responses with proper status and headers.
+     * Returns XML format for consistent error responses.
+     *
+     * @param ctx - Context containing:
+     *   - ctx.data: The error XML string from the .catch() step
+     *   - ctx.executionId: Unique identifier for tracking failed executions
+     * @returns Response object with error XML and 500 status
+     */
+    onError: (ctx) => new Response(ctx.data, {
+      status: 500,
+      headers: {
+        'Content-Type': 'application/xml; charset=utf-8',
+        'X-Execution-Id': ctx.executionId
+      }
+    })
+  },
+  cors: true
+}).then(
+  /**
+   * ═══════════════════════════════════════════════════════════════════════════════
+   * STEP 1: VALIDATE XML STRUCTURE
+   * ═══════════════════════════════════════════════════════════════════════════════
+   *
+   * This step validates that the incoming data is properly parsed XML from Versori.
+   * Uses fail-fast validation pattern to catch configuration issues early.
+   * ═══════════════════════════════════════════════════════════════════════════════
+   */
+  fn('validate-xml-structure', async ({ data, log, activation }) => {
+    // ─────────────────────────────────────────────────────────────────────────
+    // LOGGER ADAPTER PATTERN (Production-Proven)
+    // ─────────────────────────────────────────────────────────────────────────
+    // Create Logger Adapter for type-safe SDK logging
+    // Benefits:
+    // - Explicit interface contract (TypeScript Logger type)
+    // - Centralized logging adapter (easy to modify all log calls)
+    // - Type safety enforced
+    // - Clear separation between Versori log and SDK Logger
+    const logger: Logger = {
+      info: (msg: string, meta?: any) => log.info(msg, meta),
+      error: (msg: string, error?: Error, meta?: any) => log.error(msg, meta),
+      warn: (msg: string, meta?: any) => log.info(msg, meta),
+      debug: (msg: string, meta?: any) => log.info(msg, meta)
+    };
+
+    logger.info('Starting SFCC order webhook processing');
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // INITIAL DEPLOYMENT MONITORING PATTERN
+    // ─────────────────────────────────────────────────────────────────────────
+    // TEMPORARY: Complete XML log for short-term monitoring (first 2-4 weeks)
+    // TODO: Remove this log once integration is stable and monitoring is complete
+    // Purpose: Helps catch XML structure issues and field mapping problems early
+    // Impact: Increases log volume - remove after stabilization
+    // ─────────────────────────────────────────────────────────────────────────
+    logger.info('Complete incoming XML data', { completeData: data });
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Validate Pre-Parsed XML Object from Versori
+    // ─────────────────────────────────────────────────────────────────────────
+    if (typeof data !== 'object' || data === null || !('orders' in data)) {
+      throw new Error(
+        `Invalid data format. Expected XML (as pre-parsed object with 'orders' root). ` +
+        `Received: ${typeof data}. ` +
+        `Please ensure you are sending XML with Content-Type: application/xml.`
+      );
+    }
+
+    logger.info('XML structure validated successfully');
+
+    return {
+      parsedXml: data,
+      logger
+    };
+  })
+)
+
+/**
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * STEP 2: MAP WITH RESOLVERS USING SDK NODES PATTERN
+ * ═══════════════════════════════════════════════════════════════════════════════
+ *
+ * This step applies field mappings and executes custom resolvers using the SDK's
+ * mapWithNodes() method. This method is REQUIRED when using custom resolvers.
+ *
+ * v0.1.41+ Improvement: mapWithNodes() auto-returns query and variables
+ * ═══════════════════════════════════════════════════════════════════════════════
+ */
+.then(
+  http('map-with-resolvers', {
+    connection: 'fluent_commerce'
+  }, async (ctx) => {
+    const { data, log, activation } = ctx;
+    const { parsedXml, logger } = data;
+
+    logger.info('Mapping SFCC order to Fluent Commerce with custom resolvers');
+
+    try {
+      const fluentClient = await createClient(ctx);
+
+      // ═════════════════════════════════════════════════════════════════════
+      // INTEGRATION VARIABLES VALIDATION (Fail-Fast Pattern)
+      // ═════════════════════════════════════════════════════════════════════
+      // Production pattern: Validate required configuration early
+      // Benefits:
+      // - Fails immediately with explicit error message
+      // - Tells user EXACTLY what's wrong and where to fix it
+      // - Better than silent fallback to default (hides config issues)
+      // - Provides audit trail of successful retrieval
+      const fluentRetailerId = activation.getVariable('fluentRetailerId') as string;
+
+      if (!fluentRetailerId) {
+        throw new Error(
+          'fluentRetailerId integration variable is required but not set. ' +
+          'Please set this variable in Versori Activations > Variables section.'
+        );
+      }
+
+      logger.info('Using retailer ID from integration variables', { retailerId: fluentRetailerId });
+
+      // ═════════════════════════════════════════════════════════════════════
+      // INITIALIZE MAPPER WITH RESOLVERS IN CONSTRUCTOR (Recommended Pattern)
+      // ═════════════════════════════════════════════════════════════════════
+      // ✅ CORRECT: Pass resolvers in constructor options
+      // This is consistent with UniversalMapper and allows resolvers to be reused
+      const mapper = new GraphQLMutationMapper(
+        mappingConfig as any,
+        logger,
+        { 
+          customResolvers: allResolvers,  // ✅ Resolvers in constructor
+          fluentClient: fluentClient as any,
+        }
+      );
+
+      // ═════════════════════════════════════════════════════════════════════
+      // CREATE RESOLVER CONTEXT
+      // ═════════════════════════════════════════════════════════════════════
+      // Pass configuration to custom resolvers
+      // SDK automatically provides helpers (get, ensureArray, logger, etc.)
+      // You only need to pass custom config and fluentClient
+      const resolverContext = {
+        fluentClient: fluentClient as any,
+        config: {
+          retailerId: fluentRetailerId,
+          defaultCountry: 'US',
+          companyName: 'YourCompany'  // Customize per deployment
+        },
+        // ✅ SDK automatically provides helpers.get, helpers.ensureArray, helpers.logger
+        // No need to manually create them - SDK handles XML attributes via path resolver
+        // ✅ Resolvers can access config via helpers.context.config.retailerId
+        //    OR via the config parameter (3rd param): config.retailerId
+      };
+
+      // Execute mapping WITH custom resolvers
+      // ✅ v0.1.41+: mapWithNodes() auto-generates query and variables
+      // ✅ Resolvers from constructor are automatically used (can override with 2nd param)
+      const mappingResult = await mapper.mapWithNodes(
+        parsedXml,
+        undefined,  // Use constructor resolvers (or pass override resolvers here)
+        resolverContext
+      );
+
+      if (!mappingResult.success) {
+        throw new Error(`Mapping failed: ${mappingResult.errors?.join(', ')}`);
+      }
+
+      const orderRef = mappingResult.data?.input?.ref || 'unknown';
+
+      logger.info('Successfully mapped order data with custom resolvers', { orderRef });
+
+      return {
+        mappedData: mappingResult.data,
+        mappingResult,  // ✅ Contains auto-generated query and variables
+        orderRef,
+        fluentClient,
+        logger
+      };
+    } catch (error) {
+      log.error('Error during mapping with resolvers', {
+        error: error instanceof Error ? error.message : String(error),
+        stack: error instanceof Error ? error.stack : undefined
+      });
+      throw error;
+    }
+  })
+)
+
+/**
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * STEP 3: EXECUTE GRAPHQL MUTATION
+ * ═══════════════════════════════════════════════════════════════════════════════
+ *
+ * Execute the GraphQL mutation using auto-generated query from mapWithNodes().
+ * v0.1.41+ automatically wraps variables and generates query.
+ * ═══════════════════════════════════════════════════════════════════════════════
+ */
+.then(
+  http('execute-graphql-mutation', {
+    connection: 'fluent_commerce'
+  }, async (ctx) => {
+    const { data, log } = ctx;
+    const { mappingResult, orderRef, fluentClient, logger } = data;
+
+    logger.info('Executing createOrder GraphQL mutation', { orderRef });
+
+    try {
+      // ✅ v0.1.41+: Use auto-generated query and variables from mapWithNodes()
+      // No need to call buildMutation() - query is already generated
+      const mutationResult = await (fluentClient as any).graphql({
+        query: mappingResult.query,      // ✅ Auto-generated mutation query
+        variables: mappingResult.variables  // ✅ Auto-wrapped variables
+      });
+
+      if (mutationResult.errors && mutationResult.errors.length > 0) {
+        logger.error('GraphQL mutation returned errors', {
+          errors: mutationResult.errors,
+          orderRef
+        });
+        throw new Error(`GraphQL errors: ${JSON.stringify(mutationResult.errors)}`);
+      }
+
+      const createdOrder = (mutationResult.data as any)?.createOrder;
+
+      if (!createdOrder) {
+        throw new Error('No order data returned from createOrder mutation');
+      }
+
+      // Access fields specified in returnFields (id, ref, status, totalPrice)
+      logger.info('Successfully created order in Fluent Commerce', {
+        fluentOrderId: createdOrder.id,      // From returnFields
+        fluentOrderRef: createdOrder.ref,    // From returnFields
+        status: createdOrder.status,         // From returnFields
+        totalPrice: createdOrder.totalPrice, // From returnFields
+        sfccOrderRef: orderRef
+      });
+
+      return {
+        success: true,
+        fluentOrderId: createdOrder.id,
+        fluentOrderRef: createdOrder.ref,
+        sfccOrderRef: orderRef,
+        orderData: createdOrder
+      };
+    } catch (error) {
+      log.error('Error executing GraphQL mutation', {
+        error: error instanceof Error ? error.message : String(error),
+        orderRef
+      });
+      throw error;
+    }
+  })
+)
+
+/**
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * STEP 4: BUILD XML RESPONSE
+ * ═══════════════════════════════════════════════════════════════════════════════
+ *
+ * IMPORTANT: Return the XML string here.
+ * The onSuccess handler will wrap it in a Response with:
+ * - Content-Type: application/xml
+ * - Status: 200
+ * - X-Execution-Id header
+ *
+ * This keeps the workflow logic focused on data transformation while
+ * the framework handles HTTP response formatting.
+ * ═══════════════════════════════════════════════════════════════════════════════
+ */
+.then(
+  fn('build-xml-response', ({ data, log }) => {
+    log.info('Building XML response for SFCC order processing', {
+      fluentOrderId: data.fluentOrderId,
+      fluentOrderRef: data.fluentOrderRef,
+      sfccOrderRef: data.sfccOrderRef
+    });
+
+    // Initialize XML Builder (SDK-provided)
+    const builder = new XMLBuilder({
+      xmlDeclaration: true,  // Adds <?xml version="1.0" encoding="UTF-8"?>
+      prettyPrint: true,     // Format with indentation (default: true)
+      indent: '  ',          // Two-space indentation (default)
+      encoding: 'UTF-8'      // XML encoding (default)
+    });
+
+    // Build XML response data
+    const responseData = {
+      Status: 'success',
+      Message: 'Order successfully processed and created in Fluent Commerce',
+      FluentOrderId: data.fluentOrderId,
+      FluentOrderRef: data.fluentOrderRef,
+      SFCCOrderRef: data.sfccOrderRef,
+      Timestamp: new Date().toISOString()
+    };
+
+    // Build XML with root element
+    const xmlString = builder.build(responseData, 'OrderProcessingResponse');
+
+    log.info('Successfully built XML response', {
+      orderRef: data.sfccOrderRef,
+      xmlLength: xmlString.length
+    });
+
+    /**
+     * Return just the XML string here.
+     * The onSuccess handler will wrap it in a Response object with:
+     * - Content-Type: application/xml
+     * - Status: 200
+     * - X-Execution-Id header
+     */
+    return xmlString;
+  })
+)
+
+/**
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * ERROR HANDLING
+ * ═══════════════════════════════════════════════════════════════════════════════
+ *
+ * Return error XML string that will be wrapped by onError handler with status 500.
+ * ═══════════════════════════════════════════════════════════════════════════════
+ */
+.catch(({ data, log }) => {
+  log.error('Order processing failed', {
+    error: data instanceof Error ? data.message : String(data)
+  });
+
+  /**
+   * Build error XML that will be wrapped by onError handler.
+   * The onError handler will receive this string in ctx.data and wrap it
+   * in a Response object with proper status and headers.
+   */
+  const errorXml = `<?xml version="1.0" encoding="UTF-8"?>
+<OrderProcessingResponse>
+  <Status>error</Status>
+  <Message>Failed to process order</Message>
+  <Error>${data instanceof Error ? data.message : String(data)}</Error>
+  <Timestamp>${new Date().toISOString()}</Timestamp>
+</OrderProcessingResponse>`;
+
+  /**
+   * Return the error XML string.
+   * The onError handler will wrap it in a Response with status 500.
+   */
+  return errorXml;
+});
+```
+
+### 3. Service Implementation (services/order-ingestion.service.ts)
+
+```typescript
+/**
+ * SFCC Order Ingestion Service
+ *
+ * Orchestrates the complete order ingestion process:
+ * 1. Validate webhook payload
+ * 2. Validate SFCC structure
+ * 3. Apply field mapping with custom resolvers
+ * 4. Create order via GraphQL API
+ * 5. Audit trail (save input/output files)
+ */
+
+import { createClient, GraphQLMutationMapper } from '@fluentcommerce/fc-connect-sdk';
+import { allResolvers } from '../resolvers';
+import mappingConfig from '../config/sfcc-to-fluent-order-mapping.json' with { type: 'json' };
+
+/**
+ * Process SFCC order ingestion
+ *
+ * @param ctx - Versori context object containing fetch, connections, log, activation, data
+ * @param executionStartTime - Workflow start time for duration tracking
+ */
+export async function processOrderIngestion(ctx: any, executionStartTime: number) {
+  const { log, data, activation } = ctx;
+
+  log.info('Starting SFCC order processing');
+
+  try {
+    const sfccData = data;
+
+    if (!sfccData) {
+      log.error('No order data received');
+      return {
+        success: false,
+        error: 'No order data received',
+        timestamp: new Date().toISOString(),
+        duration: Date.now() - executionStartTime,
+      };
+    }
+
+    if (!sfccData.orders?.order) {
+      log.error('Invalid order structure: missing orders.order');
+      return {
+        success: false,
+        error: 'Invalid order structure: missing orders.order',
+        timestamp: new Date().toISOString(),
+        duration: Date.now() - executionStartTime,
+      };
+    }
+
+    const order = sfccData.orders.order;
+    if (!order['original-order-no']) {
+      log.error('Missing required field: original-order-no');
+      return {
+        success: false,
+        error: 'Missing required field: original-order-no',
+        timestamp: new Date().toISOString(),
+        duration: Date.now() - executionStartTime,
+      };
+    }
+
+    if (!order.customer?.['customer-no']) {
+      log.error('Missing required field: customer.customer-no');
+      return {
+        success: false,
+        error: 'Missing required field: customer.customer-no',
+        timestamp: new Date().toISOString(),
+        duration: Date.now() - executionStartTime,
+      };
+    }
+
+    const fluentClient = await createClient(ctx);
+    log.info('Fluent client initialized');
+
+    log.info('Applying mapping');
+
+    const retailerId = activation?.getVariable('fluentRetailerId') as string;
+    
+    if (!retailerId) {
+      log.error('Missing required variable: fluentRetailerId');
+      return {
+        success: false,
+        error: 'Missing required configuration: fluentRetailerId',
+        timestamp: new Date().toISOString(),
+        duration: Date.now() - executionStartTime,
+      };
+    }
+
+    const productCatalogueRef = activation?.getVariable('productCatalogueRef') as string || 'PC:MASTER:2';
+
+    const mapper = new GraphQLMutationMapper(
+      mappingConfig as any,
+      log,
+      { 
+        customResolvers: allResolvers,
+        fluentClient: fluentClient as any,
+      }
+    );
+
+    const resolverContext = {
+      fluentClient: fluentClient as any,
+      config: {
+        retailerId: retailerId,
+        defaultOrderType: 'HD',
+        defaultCountry: 'US',
+        productCatalogueRef: productCatalogueRef,
+      },
+    };
+
+    const result = await mapper.mapWithNodes(sfccData, undefined, resolverContext);
+
+    if (!result.success) {
+      log.error('Mapping failed', { errors: result.errors });
+      return {
+        success: false,
+        error: `Mapping failed: ${result.errors?.join(', ')}`,
+        timestamp: new Date().toISOString(),
+        duration: Date.now() - executionStartTime,
+      };
+    }
+
+    const orderRef = sfccData.orders?.order?.['original-order-no'] || 'unknown';
+
+    log.info('Mapping completed', { orderRef });
+
+    // Save audit trail to KV storage (Versori-compatible - file system is read-only)
+    try {
+      const kv = openKv(':project:');
+      const timestamp = new Date().toISOString();
+      const auditKey = ['orders', 'audit', orderRef, timestamp];
+      
+      await kv.set([...auditKey, 'sfcc-input'], sfccData);
+      await kv.set([...auditKey, 'fluent-mapped'], result.data);
+      
+      log.info('Audit trail saved to KV storage', { orderRef, timestamp });
+    } catch (kvError: any) {
+      log.warn('Failed to save audit trail to KV', { error: kvError.message });
+    }
+
+    log.info('Creating order in Fluent Commerce', { orderRef });
+
+    const mutationRes = await (fluentClient as any).graphql({
+      query: result.query,
+      variables: result.variables
+    });
+
+    if (mutationRes.errors && mutationRes.errors.length > 0) {
+      log.error('GraphQL mutation failed', { errors: mutationRes.errors });
+      
+      // Save error to KV storage
+      try {
+        const kv = openKv(':project:');
+        const timestamp = new Date().toISOString();
+        const auditKey = ['orders', 'audit', orderRef, timestamp, 'fluent-error'];
+        await kv.set(auditKey, mutationRes);
+      } catch (kvError) {
+        // Ignore KV save errors
+      }
+      
+      return {
+        success: false,
+        error: `GraphQL mutation failed: ${mutationRes.errors.map((e: any) => e.message).join(', ')}`,
+        timestamp: new Date().toISOString(),
+        duration: Date.now() - executionStartTime,
+      };
+    }
+
+    const createOrderData = (mutationRes as any)?.data?.createOrder;
+
+    if (!createOrderData) {
+      log.error('No order data returned from API');
+      return {
+        success: false,
+        error: 'No order data returned from GraphQL mutation',
+        timestamp: new Date().toISOString(),
+        duration: Date.now() - executionStartTime,
+      };
+    }
+
+    // Save successful response to KV storage
+    try {
+      const kv = openKv(':project:');
+      const timestamp = new Date().toISOString();
+      const auditKey = ['orders', 'audit', orderRef, timestamp, 'fluent-response'];
+      await kv.set(auditKey, mutationRes);
+    } catch (kvError) {
+      // Ignore KV save errors
+    }
+
+    log.info('Order created in Fluent Commerce', {
+      orderId: createOrderData?.id,
+      orderRef: createOrderData?.ref,
+    });
+
+    return {
+      success: true,
+      data: {
+        sfccOrderRef: orderRef,
+        fluentOrderId: createOrderData?.id,
+        fluentOrderRef: createOrderData?.ref,
+        timestamp: new Date().toISOString(),
+      },
+      duration: Date.now() - executionStartTime,
+    };
+  } catch (error: any) {
+    log.error('Fatal error', {
+      error: error instanceof Error ? error.message : String(error),
+      stack: error instanceof Error ? error.stack : undefined,
+    });
+
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+      timestamp: new Date().toISOString(),
+      duration: Date.now() - executionStartTime,
+    };
+  }
+}
+```
+
+### 4. Mapping Configuration (config/sfcc-to-fluent-order-mapping.json)
+
+```json
+{
+  "direction": "ingest",
+  "sourceFormat": "xml",
+  "mutation": "createOrder",
+  "returnFields": ["id", "ref", "status", "totalPrice"],
+  "fields": {
+    "ref": {
+      "source": "orders.order.original-order-no",
+      "resolver": "sdk.toString",
+      "comment": "Order reference from SFCC native field (REQUIRED)"
+    },
+    "type": {
+      "resolver": "custom.deriveOrderType",
+      "comment": "Derive from shipment count: 1 shipment = HD, multiple = MULTI (REQUIRED)"
+    },
+    "retailer.id": {
+      "value": "${RETAILER_ID}",
+      "comment": "From environment variable or configuration (REQUIRED)"
+    },
+    "totalPrice": {
+      "source": "orders.order.totals.order-total.net-price",
+      "resolver": "sdk.parseFloat",
+      "comment": "Order total net price from SFCC totals (REQUIRED)"
+    },
+    "totalTaxPrice": {
+      "source": "orders.order.totals.order-total.tax",
+      "resolver": "sdk.parseFloat",
+      "comment": "Order total tax from SFCC totals (REQUIRED)"
+    },
+    "attributes": {
+      "resolver": "custom.buildOrderAttributes",
+      "comment": "Order-level attributes: order-date, created-by, invoice-no, totals JSON"
+    },
+    "customer": {
+      "fields": {
+        "ref": {
+          "source": "orders.order.customer.customer-no",
+          "resolver": "sdk.toString",
+          "comment": "Customer reference from SFCC (REQUIRED)"
+        },
+        "firstName": {
+          "source": "orders.order.customer.customer-name",
+          "resolver": "custom.extractFirstName",
+          "comment": "Extract first name from customer-name"
+        },
+        "lastName": {
+          "source": "orders.order.customer.customer-name",
+          "resolver": "custom.extractLastName",
+          "comment": "Extract last name from customer-name"
+        },
+        "primaryEmail": {
+          "source": "orders.order.customer.customer-email",
+          "resolver": "sdk.toString",
+          "comment": "Customer email from SFCC (REQUIRED)"
+        }
+      }
+    },
+    "billingAddress": {
+      "fields": {
+        "name": {
+          "source": "orders.order.customer.billing-address.first-name",
+          "resolver": "custom.combineBillingName",
+          "comment": "Combine first-name + last-name"
+        },
+        "street": {
+          "source": "orders.order.customer.billing-address.address1",
+          "resolver": "sdk.toString",
+          "comment": "Billing address line 1 (REQUIRED)"
+        },
+        "street2": {
+          "source": "orders.order.customer.billing-address.address2",
+          "resolver": "sdk.toString",
+          "comment": "Billing address line 2 (optional)"
+        },
+        "city": {
+          "source": "orders.order.customer.billing-address.city",
+          "resolver": "sdk.toString",
+          "comment": "Billing city (REQUIRED)"
+        },
+        "state": {
+          "source": "orders.order.customer.billing-address.state-code",
+          "resolver": "sdk.toString",
+          "comment": "Billing state code (REQUIRED)"
+        },
+        "postcode": {
+          "source": "orders.order.customer.billing-address.postal-code",
+          "resolver": "sdk.toString",
+          "comment": "Billing postal code (REQUIRED)"
+        },
+        "country": {
+          "source": "orders.order.customer.billing-address.country-code",
+          "resolver": "custom.normalizeCountryCode",
+          "comment": "Normalize country code (us → US)"
+        }
+      },
+      "attributes": {
+        "resolver": "custom.buildBillingAddressAttributes",
+        "comment": "Billing address phone and custom attributes"
+      }
+    },
+    "items": {
+      "source": "orders.order.product-lineitems.product-lineitem",
+      "isArray": true,
+      "fields": {
+        "ref": {
+          "source": "$.position",
+          "resolver": "custom.createItemRef",
+          "comment": "Item reference from position (REQUIRED)"
+        },
+        "productRef": {
+          "source": "$.product-id",
+          "resolver": "sdk.toString",
+          "comment": "Product reference from SFCC product-id (REQUIRED)"
+        },
+        "productCatalogueRef": {
+          "resolver": "custom.getProductCatalogueRef",
+          "comment": "Default product catalogue"
+        },
+        "quantity": {
+          "source": "$.quantity",
+          "resolver": "sdk.parseFloat",
+          "comment": "Quantity from SFCC (REQUIRED)"
+        },
+        "price": {
+          "source": "$.base-price",
+          "resolver": "sdk.parseFloat",
+          "comment": "Base price per item from SFCC (REQUIRED)"
+        },
+        "totalPrice": {
+          "source": "$.net-price",
+          "resolver": "sdk.parseFloat",
+          "comment": "Total price (net-price) from SFCC (REQUIRED)"
+        },
+        "taxPrice": {
+          "source": "$.tax",
+          "resolver": "sdk.parseFloat",
+          "comment": "Tax amount from SFCC (REQUIRED)"
+        },
+        "currency": {
+          "source": "orders.order.currency",
+          "resolver": "sdk.toString",
+          "comment": "Currency from order level (REQUIRED)"
+        },
+        "attributes": {
+          "resolver": "custom.buildItemAttributes",
+          "comment": "Item attributes: position, tax-basis, tax-rate, shipment-id, gift, custom-attributes"
+        }
+      }
+    },
+    "fulfilmentChoices": {
+      "source": "orders.order.shipments.shipment",
+      "isArray": true,
+      "fields": {
+        "type": {
+          "source": "$.shipping-method",
+          "resolver": "custom.mapShippingMethodToFulfilmentType",
+          "comment": "Map ISPU → BOPIS, STANDARD_SHIPPING → SHIP_TO_HOME (REQUIRED)"
+        },
+        "pickupLocationRef": {
+          "source": "$.custom-attributes.custom-attribute[attribute-id=fromStoreId]",
+          "resolver": "sdk.toString",
+          "comment": "Store ID for BOPIS orders"
+        },
+        "deliveryType": {
+          "source": "orders.order.shipping-lineitems.shipping-lineitem.item-id",
+          "resolver": "sdk.toString",
+          "comment": "Delivery type (STANDARD_SHIPPING, etc.)"
+        },
+        "deliveryAddress": {
+          "fields": {
+            "name": {
+              "source": "$.shipping-address.first-name",
+              "resolver": "custom.combineShippingName",
+              "comment": "Combine first-name + last-name"
+            },
+            "street": {
+              "source": "$.shipping-address.address1",
+              "resolver": "sdk.toString",
+              "comment": "Shipping address line 1 (REQUIRED)"
+            },
+            "street2": {
+              "source": "$.shipping-address.address2",
+              "resolver": "sdk.toString",
+              "comment": "Shipping address line 2 (optional)"
+            },
+            "city": {
+              "source": "$.shipping-address.city",
+              "resolver": "sdk.toString",
+              "comment": "Shipping city (REQUIRED)"
+            },
+            "state": {
+              "source": "$.shipping-address.state-code",
+              "resolver": "sdk.toString",
+              "comment": "Shipping state code (REQUIRED)"
+            },
+            "postcode": {
+              "source": "$.shipping-address.postal-code",
+              "resolver": "sdk.toString",
+              "comment": "Shipping postal code (REQUIRED)"
+            },
+            "country": {
+              "source": "$.shipping-address.country-code",
+              "resolver": "custom.normalizeCountryCode",
+              "comment": "Normalize country code (US → US)"
+            }
+          },
+          "attributes": {
+            "resolver": "custom.buildFulfilmentAddressAttributes",
+            "comment": "Shipping address phone and custom attributes"
+          }
+        },
+        "attributes": {
+          "resolver": "custom.buildFulfilmentChoicesAttributes",
+          "comment": "Fulfilment attributes: gift, totals JSON (merchandize-total, shipping-total, shipment-total), custom-attributes"
+        }
+      }
+    },
+    "financialTransactions": {
+      "source": "orders.order.payments.payment",
+      "isArray": true,
+      "fields": {
+        "ref": {
+          "source": "$.transaction-id",
+          "resolver": "sdk.toString",
+          "comment": "Transaction ID from SFCC (REQUIRED)"
+        },
+        "type": {
+          "value": "AUTHORIZATION",
+          "comment": "Payment type (REQUIRED)"
+        },
+        "amount": {
+          "source": "$.amount",
+          "resolver": "sdk.parseFloat",
+          "comment": "Payment amount from SFCC (REQUIRED)"
+        },
+        "currency": {
+          "source": "orders.order.currency",
+          "resolver": "sdk.toString",
+          "comment": "Currency from order level (REQUIRED)"
+        },
+        "paymentMethod": {
+          "source": "$.custom-method.method-name",
+          "resolver": "custom.mapPaymentMethod",
+          "comment": "Payment method (KLARNA, CreditCard, etc.) (REQUIRED)"
+        },
+        "externalTransactionCode": {
+          "source": "$.custom-attributes.custom-attribute[attribute-id=klarnaAuthorizationCode]",
+          "resolver": "sdk.toString",
+          "comment": "Authorization code (Klarna, etc.)"
+        },
+        "externalTransactionId": {
+          "source": "$.custom-method.custom-attributes.custom-attribute[attribute-id=klarnaClientToken]",
+          "resolver": "sdk.toString",
+          "comment": "External transaction ID (Klarna client token, etc.)"
+        },
+        "attributes": {
+          "resolver": "custom.buildPaymentAttributes",
+          "comment": "Payment attributes: processor-id, custom-attributes"
+        }
+      }
+    }
+  },
+  "returnFields": ["id", "ref", "status", "totalPrice"]
+}
+```
+
+**Note:** The `returnFields` array specifies which fields are returned in the GraphQL mutation response. These fields are available in `mutationRes.data.createOrder` after executing the mutation. If omitted, defaults to `["id", "ref"]`.
+
+### 5. Custom Resolvers (src/resolvers/order-resolvers.ts)
+
+```typescript
+/**
+ * Order Resolvers for SFCC Native → Fluent
+ *
+ * Maps from SFCC native structure to Fluent order fields
+ */
+
+import type { ResolverMap } from './types';
+
+export const orderResolvers: ResolverMap = {
+  /**
+   * Derive order type from SFCC order structure
+   * Example: 1 shipment → "HD", multiple shipments → "MULTI"
+   */
+  'custom.deriveOrderType': (value: any, data: any, config: any, helpers: any): string => {
+    const sfccData = data.root || data || {};
+    const shipments = helpers.ensureArray(helpers.get(sfccData, 'orders.order.shipments.shipment'));
+
+    if (shipments.length > 1) {
+      return 'MULTI';
+    }
+
+    return config.defaultOrderType || 'HD';
+  },
+
+  /**
+   * Get product catalogue reference
+   * Returns default catalogue ref for all items
+   */
+  'custom.getProductCatalogueRef': (value: any, data: any, config: any, helpers: any): string => {
+    return process.env.PRODUCT_CATALOGUE_REF || 'PC:MASTER:2';
+  },
+
+  /**
+   * Build order-level attributes from SFCC fields
+   * Extracts order metadata (order-date, created-by, invoice-no, totals)
+   */
+  'custom.buildOrderAttributes': (
+    value: any,
+    data: any,
+    config: any,
+    helpers: any
+  ): Array<{ name: string; type: string; value: any }> => {
+    const sfccData = data.root || data || {};
+    const order = helpers.get(sfccData, 'orders.order');
+    const attributes: Array<{ name: string; type: string; value: any }> = [];
+
+    // Order date
+    const orderDate = helpers.get(order, 'order-date');
+    if (orderDate) {
+      attributes.push({
+        name: 'order-date',
+        type: 'String',
+        value: orderDate,
+      });
+    }
+
+    // Created by
+    const createdBy = helpers.get(order, 'created-by');
+    if (createdBy) {
+      attributes.push({
+        name: 'created-by',
+        type: 'String',
+        value: createdBy,
+      });
+    }
+
+    // Invoice number
+    const invoiceNo = helpers.get(order, 'invoice-no');
+    if (invoiceNo) {
+      attributes.push({
+        name: 'invoice-no',
+        type: 'String',
+        value: invoiceNo,
+      });
+    }
+
+    // Order totals as JSON
+    const totals = helpers.get(order, 'totals');
+    if (totals) {
+      attributes.push({
+        name: 'totals',
+        type: 'JSON',
+        value: JSON.stringify(totals),
+      });
+    }
+
+    return attributes;
+  },
+};
+```
+
+### 6. Additional Resolvers (src/resolvers/fulfillment-resolvers.ts, item-resolvers.ts, payment-resolvers.ts)
+
+```typescript
+/**
+ * Fulfillment Resolvers
+ * Handle SFCC shipment data → Fluent fulfilmentChoices
+ */
+
+export const fulfillmentResolvers: ResolverMap = {
+  /**
+   * Extract first name from SFCC customer-name field
+   * Example: "John Smith" → "John"
+   */
+  'custom.extractFirstName': (value: any, data: any, config: any, helpers: any): string => {
+    if (!value) return '';
+    const parts = String(value).trim().split(/\s+/);
+    return parts[0] || '';
+  },
+
+  /**
+   * Extract last name from SFCC customer-name field
+   * Example: "John Smith" → "Smith"
+   */
+  'custom.extractLastName': (value: any, data: any, config: any, helpers: any): string => {
+    if (!value) return '';
+    const parts = String(value).trim().split(/\s+/);
+    return parts.length > 1 ? parts.slice(1).join(' ') : '';
+  },
+
+  /**
+   * Combine billing address first-name and last-name
+   * Example: "John" + "Smith" → "John Smith"
+   */
+  'custom.combineBillingName': (value: any, data: any, config: any, helpers: any): string => {
+    const sfccData = data.root || data || {};
+    const firstName = value || helpers.get(sfccData, 'orders.order.customer.billing-address.first-name') || '';
+    const lastName = helpers.get(sfccData, 'orders.order.customer.billing-address.last-name') || '';
+    return `${firstName} ${lastName}`.trim();
+  },
+
+  /**
+   * Combine shipping address first-name and last-name
+   * Example: "Acme" + "Store" → "Acme Store"
+   */
+  'custom.combineShippingName': (value: any, data: any, config: any, helpers: any): string => {
+    const sfccData = data.root || data || {};
+    const firstName = value || helpers.get(sfccData, 'orders.order.shipments.shipment.shipping-address.first-name') || '';
+    const lastName = helpers.get(sfccData, 'orders.order.shipments.shipment.shipping-address.last-name') || '';
+    return `${firstName} ${lastName}`.trim();
+  },
+
+  /**
+   * Normalize country code to uppercase
+   * Example: "us" → "US", "US" → "US"
+   */
+  'custom.normalizeCountryCode': (value: any, data: any, config: any, helpers: any): string => {
+    if (!value) return config.defaultCountry || 'US';
+    return String(value).toUpperCase();
+  },
+
+  /**
+   * Map SFCC shipping-method to Fluent fulfilment type
+   * Example: "ISPU" → "BOPIS", "STANDARD_SHIPPING" → "SHIP_TO_HOME"
+   */
+  'custom.mapShippingMethodToFulfilmentType': (value: any, data: any, config: any, helpers: any): string => {
+    const shippingMethod = String(value || '').toUpperCase();
+    const mapping: Record<string, string> = {
+      ISPU: 'BOPIS',
+      STANDARD_SHIPPING: 'SHIP_TO_HOME',
+      EXPRESS_SHIPPING: 'SHIP_TO_HOME',
+      GROUND_SHIPPING: 'SHIP_TO_HOME',
+    };
+    return mapping[shippingMethod] || 'SHIP_TO_HOME';
+  },
+
+  /**
+   * Build billing address attributes (phone)
+   */
+  'custom.buildBillingAddressAttributes': (
+    value: any,
+    data: any,
+    config: any,
+    helpers: any
+  ): Array<{ name: string; type: string; value: any }> => {
+    const sfccData = data.root || data || {};
+    const attributes: Array<{ name: string; type: string; value: any }> = [];
+
+    const phone = helpers.get(sfccData, 'orders.order.customer.billing-address.phone');
+    if (phone) {
+      attributes.push({ name: 'phone', type: 'String', value: String(phone) });
+    }
+
+    return attributes;
+  },
+
+  /**
+   * Build fulfilment address attributes (phone)
+   */
+  'custom.buildFulfilmentAddressAttributes': (
+    value: any,
+    data: any,
+    config: any,
+    helpers: any
+  ): Array<{ name: string; type: string; value: any }> => {
+    const sfccData = data.root || data || {};
+    const attributes: Array<{ name: string; type: string; value: any }> = [];
+
+    const phone = helpers.get(sfccData, 'orders.order.shipments.shipment.shipping-address.phone');
+    if (phone) {
+      attributes.push({ name: 'phone', type: 'String', value: String(phone) });
+    }
+
+    return attributes;
+  },
+
+  /**
+   * Build fulfilment choices attributes
+   * Includes gift flag, totals JSON, and custom attributes
+   */
+  'custom.buildFulfilmentChoicesAttributes': (
+    value: any,
+    data: any,
+    config: any,
+    helpers: any
+  ): Array<{ name: string; type: string; value: any }> => {
+    const sfccData = data.root || data || {};
+    const attributes: Array<{ name: string; type: string; value: any }> = [];
+
+    // Gift flag
+    const gift = helpers.get(sfccData, 'orders.order.shipments.shipment.gift');
+    if (gift !== undefined) {
+      attributes.push({ name: 'gift', type: 'Boolean', value: gift === 'true' || gift === true });
+    }
+
+    // Shipment totals as JSON
+    const totals = helpers.get(sfccData, 'orders.order.shipments.shipment.totals');
+    if (totals) {
+      attributes.push({
+        name: 'totals',
+        type: 'JSON',
+        value: JSON.stringify(totals),
+      });
+    }
+
+    // Custom attributes (fromStoreId, shipmentType, etc.)
+    const customAttrs = helpers.ensureArray(
+      helpers.get(sfccData, 'orders.order.shipments.shipment.custom-attributes.custom-attribute')
+    );
+    for (const attr of customAttrs) {
+      const attrId = attr['@attribute-id'];
+      const attrValue = attr._ || attr['#text'] || attr;
+      if (attrId && attrValue !== undefined) {
+        attributes.push({
+          name: attrId,
+          type: 'String',
+          value: String(attrValue),
+        });
+      }
+    }
+
+    return attributes;
+  },
+};
+
+/**
+ * Item Resolvers
+ * Handle SFCC product-lineitem data → Fluent order items
+ */
+
+export const itemResolvers: ResolverMap = {
+  /**
+   * Create item reference from position
+   * Example: position "1" → "item_1"
+   */
+  'custom.createItemRef': (value: any, data: any, config: any, helpers: any): string => {
+    const position = String(value || '1');
+    return `item_${position}`;
+  },
+
+  /**
+   * Build item attributes
+   * Includes position, tax-basis, tax-rate, shipment-id, gift, custom-attributes
+   */
+  'custom.buildItemAttributes': (
+    value: any,
+    data: any,
+    config: any,
+    helpers: any
+  ): Array<{ name: string; type: string; value: any }> => {
+    const itemData = data || {};
+    const sfccData = data.root || data || {};
+    const attributes: Array<{ name: string; type: string; value: any }> = [];
+
+    // Position
+    const position = itemData.position || helpers.get(sfccData, 'orders.order.product-lineitems.product-lineitem.position');
+    if (position) {
+      attributes.push({ name: 'position', type: 'String', value: String(position) });
+    }
+
+    // Tax basis
+    const taxBasis = itemData['tax-basis'] || helpers.get(sfccData, 'orders.order.product-lineitems.product-lineitem.tax-basis');
+    if (taxBasis) {
+      attributes.push({ name: 'tax-basis', type: 'String', value: String(taxBasis) });
+    }
+
+    // Tax rate
+    const taxRate = itemData['tax-rate'] || helpers.get(sfccData, 'orders.order.product-lineitems.product-lineitem.tax-rate');
+    if (taxRate) {
+      attributes.push({ name: 'tax-rate', type: 'String', value: String(taxRate) });
+    }
+
+    // Shipment ID
+    const shipmentId = itemData['shipment-id'] || helpers.get(sfccData, 'orders.order.product-lineitems.product-lineitem.shipment-id');
+    if (shipmentId) {
+      attributes.push({ name: 'shipment-id', type: 'String', value: String(shipmentId) });
+    }
+
+    // Gift flag
+    const gift = itemData.gift || helpers.get(sfccData, 'orders.order.product-lineitems.product-lineitem.gift');
+    if (gift !== undefined) {
+      attributes.push({ name: 'gift', type: 'Boolean', value: gift === 'true' || gift === true });
+    }
+
+    // Custom attributes (fromStoreId, storeQty, etc.)
+    const customAttrs = helpers.ensureArray(
+      itemData['custom-attributes']?.['custom-attribute'] ||
+      helpers.get(sfccData, 'orders.order.product-lineitems.product-lineitem.custom-attributes.custom-attribute')
+    );
+    for (const attr of customAttrs) {
+      const attrId = attr['@attribute-id'];
+      const attrValue = attr._ || attr['#text'] || attr;
+      if (attrId && attrValue !== undefined) {
+        attributes.push({
+          name: attrId,
+          type: 'String',
+          value: String(attrValue),
+        });
+      }
+    }
+
+    return attributes;
+  },
+};
+
+/**
+ * Payment Resolvers
+ * Handle SFCC payment data → Fluent financialTransactions
+ */
+
+export const paymentResolvers: ResolverMap = {
+  /**
+   * Map SFCC payment method to Fluent payment method
+   * Example: "KLARNA" → "KLARNA", "CreditCard" → "CreditCard"
+   */
+  'custom.mapPaymentMethod': (value: any, data: any, config: any, helpers: any): string => {
+    const methodName = String(value || '').toUpperCase();
+    const mapping: Record<string, string> = {
+      KLARNA: 'KLARNA',
+      CREDITCARD: 'CreditCard',
+      PAYPAL: 'PayPal',
+      APPLEPAY: 'ApplePay',
+      GOOGLEPAY: 'GooglePay',
+    };
+    return mapping[methodName] || methodName;
+  },
+
+  /**
+   * Build payment attributes
+   * Includes processor-id, custom-attributes (klarnaAuthorizationCode, etc.)
+   */
+  'custom.buildPaymentAttributes': (
+    value: any,
+    data: any,
+    config: any,
+    helpers: any
+  ): Array<{ name: string; type: string; value: any }> => {
+    const paymentData = data || {};
+    const sfccData = data.root || data || {};
+    const attributes: Array<{ name: string; type: string; value: any }> = [];
+
+    // Processor ID
+    const processorId = paymentData['processor-id'] || helpers.get(sfccData, 'orders.order.payments.payment.processor-id');
+    if (processorId) {
+      attributes.push({ name: 'processor-id', type: 'String', value: String(processorId) });
+    }
+
+    // Custom attributes
+    const customAttrs = helpers.ensureArray(
+      paymentData['custom-attributes']?.['custom-attribute'] ||
+      helpers.get(sfccData, 'orders.order.payments.payment.custom-attributes.custom-attribute')
+    );
+    for (const attr of customAttrs) {
+      const attrId = attr['@attribute-id'];
+      const attrValue = attr._ || attr['#text'] || attr;
+      if (attrId && attrValue !== undefined) {
+        attributes.push({
+          name: attrId,
+          type: 'String',
+          value: String(attrValue),
+        });
+      }
+    }
+
+    return attributes;
+  },
+};
+```
+
+### 7. Resolver Types (src/resolvers/types.ts)
+
+```typescript
+/**
+ * Type definitions for custom resolvers
+ */
+
+export interface ResolverHelpers {
+  logger?: any;
+  fluentClient?: any;
+  get: (obj: any, path: string) => any;
+  ensureArray: (val: any) => any[];
+}
+
+export type ResolverFunction = (
+  value: any,
+  data: any,
+  config: any,
+  helpers: ResolverHelpers
+) => any | Promise<any>;
+
+export type ResolverMap = Record<string, ResolverFunction>;
+```
+
+### 8. Export All Resolvers (src/resolvers/index.ts)
+
+```typescript
+/**
+ * All custom resolvers for SFCC native mapping
+ */
+
+import { orderResolvers } from './order-resolvers';
+import { fulfillmentResolvers } from './fulfillment-resolvers';
+import { itemResolvers } from './item-resolvers';
+import { paymentResolvers } from './payment-resolvers';
+
+export const allResolvers = {
+  ...orderResolvers,
+  ...fulfillmentResolvers,
+  ...itemResolvers,
+  ...paymentResolvers,
+};
+
+// Export individual resolver maps for testing
+export { orderResolvers, fulfillmentResolvers, itemResolvers, paymentResolvers };
+```
+
+### 9. Versori Deployment Files
+
+#### package.json
+
+```json
+{
+  "name": "sfcc-order-webhook",
+  "version": "1.0.0",
+  "type": "module",
+  "dependencies": {
+    "@fluentcommerce/fc-connect-sdk": "^0.1.41",
+    "@versori/run": "latest"
+  }
+}
+```
+
+#### import_map.json
+
+```json
+{
+  "imports": {
+    "@fluentcommerce/fc-connect-sdk": "https://esm.sh/@fluentcommerce/fc-connect-sdk@0.1.41",
+    "@versori/run": "https://esm.sh/@versori/run@latest",
+    "node:buffer": "https://deno.land/std@0.224.0/node/buffer.ts",
+    "node:fs": "https://deno.land/std@0.224.0/node/fs.ts",
+    "node:path": "https://deno.land/std@0.224.0/node/path.ts"
+  }
+}
+```
+
+---
+
+## Common Issues
+
+### Issue 1: "Missing required field: orders.order"
+
+**Cause**: XML structure doesn't match expected SFCC format
+
+**Solution**: Validate XML structure
+
+```typescript
+// Check structure
+if (!sfccData.orders?.order) {
+  throw new Error('Invalid XML structure: missing orders.order');
+}
+```
+
+### Issue 2: "Order type is undefined"
+
+**Cause**: Resolver not deriving order type correctly
+
+**Solution**: Check shipments array
+
+```typescript
+const shipments = helpers.ensureArray(helpers.get(sfccData, 'orders.order.shipments.shipment'));
+return shipments.length > 1 ? 'MULTI' : 'HD';
+```
+
+### Issue 3: "Expected array at path but got object"
+
+**Cause**: XML parser doesn't create arrays for single items
+
+**Solution**: Use `helpers.ensureArray()` in resolvers
+
+```typescript
+// ✅ CORRECT - wraps single items
+const items = helpers.ensureArray(helpers.get(sfccData, 'orders.order.product-lineitems.product-lineitem'));
+```
+
+---
+
+## Production Checklist
+
+Before deploying to production:
+
+- [ ] Set proper environment variables in Versori (RETAILER_ID, PRODUCT_CATALOGUE_REF)
+- [ ] Configure error alerting/monitoring
+- [ ] Test with real SFCC webhook payload
+- [ ] Test all resolver edge cases (missing data, null values)
+- [ ] Set up log aggregation
+- [ ] Configure connection retry logic for transient failures
+- [ ] Document any customer-specific field mappings
+
+---
+
+**Next Steps**: For more advanced SFCC integration patterns, explore the Radial XML version of this template for orders requiring Radial-specific fields.