@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

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

@@ -1,888 +1,888 @@
----
-template_id: tpl-webhook-generic-xml-order
-canonical_filename: template-webhook-generic-xml-order.md
-sdk_version: ^0.1.39
-runtime: versori
-direction: ingestion
-source: webhook-xml
-destination: fluent-graphql
-entity: order
-format: xml
-logging: versori
-status: stable
-features:
-  - external-json-config
-  - memory-management
-  - enhanced-logging
-  - audit-trail
----
-
-# Template: Webhook - Generic XML Order to Fluent GraphQL
-
-**SDK Version:** @fluentcommerce/fc-connect-sdk@^0.1.39
-**Last Updated:** 2025-01-24
-**Deployment Target:** Versori Platform
-
-**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 generic XML orders via Versori HTTP webhook and create orders in Fluent Commerce using GraphQL mutations.
-
-**Complexity**: Medium
-
-**Runtime**: Versori Platform
-
-**Estimated Lines**: ~600 lines (modular structure)
-
----
-
-## STEP 1: Understand This Template
-
-**What This Template Does:**
-
-- Versori HTTP webhook endpoint receiving XML order data
-- XML parsing with optional nodes config for nested/escaped XML segments
-- GraphQL mutation mapping from XML structure to Fluent schema
-- Custom resolvers for data transformation and API calls
-- Memory management (clears large XML payloads after mapping)
-- Error handling and structured response formatting
-- Audit trail (save input/output to filesystem for debugging)
-- **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
-- `XMLParserService` - XML parsing with nodes extraction
-- Native Versori `log` - Use `log` from context
-
-**Entity Type:**
-
-- **Order** - Fluent entity for order creation
-- **GraphQL Mutation** - Uses `createOrder` mutation (not Event API)
-
-**Critical Patterns:**
-
-- **Sync + Fire-and-Forget**: Webhook validates quickly, returns immediately, processes in background
-- **External JSON Config**: Mapping configuration in separate JSON file (`config/order-mapping.json`)
-- **Modular Architecture**: Separate services, workflows, config, types folders
-- **Memory Management**: Clears large XML payloads from memory after mapping
-- **Background Processing**: Long-running operations (GraphQL mutations) happen asynchronously
-- **Error Handling**: Comprehensive error handling with structured logging and recommendations
-- **Activation Variables**: Configuration via Versori activation variables (OUTPUT_DIR, validateConnectionOnStart)
-
-**When to Use This Template:**
-
-- ✅ Real-time order ingestion from external systems (SFCC, Shopify, custom)
-- ✅ XML order format (can be adapted for JSON)
-- ✅ Need fast webhook response (don't wait for order creation)
-- ✅ Single order per webhook call
-- ✅ Need audit trail for debugging
-
-**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)
-
----
-
-## 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 generic XML order ingestion to Fluent Commerce GraphQL.
-
-REQUIREMENTS:
-1. Runtime: Versori Platform (HTTP webhook)
-2. Source: XML order data via HTTP POST webhook
-3. Destination: Fluent Commerce GraphQL API (createOrder mutation)
-4. Format: XML with optional nodes extraction
-5. Entity: Order (GraphQL mutation)
-
-KEY FEATURES:
-- Sync + fire-and-forget pattern (fast webhook response, background processing)
-- External JSON mapping configuration (not inline TypeScript)
-- Modular architecture (workflows/, services/, config/, types/)
-- XML parsing with optional nodes config for nested XML segments
-- GraphQLMutationMapper for XML → GraphQL transformation
-- 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' } (fast response)
-2. Background Processing: Fire-and-forget pattern (no await on long operations)
-3. Mapping Config: External JSON file (config/order-mapping.json)
-4. Modular Structure: Separate services/, config/, types/ folders
-5. Native Logging: Use log from context (no LoggingService)
-6. Error Handling: Structured error responses with recommendations
-
-SDK METHODS TO USE:
-- createClient({ ...ctx, log }) - Pass full Versori context
-- new GraphQLMutationMapper(mappingConfig, log, { fluentClient: client }) - Initialize mapper
-- mapper.mapWithNodes(xmlData, customResolvers, context) - Map XML with custom resolvers (REQUIRED for custom resolvers)
-- mapper.map(xmlData) - Map XML without custom resolvers (built-in SDK resolvers only)
-- mapWithNodes() now returns query automatically (no need for buildMutation())
-- client.graphql({ query, variables }) - Execute GraphQL mutation
-
-FORBIDDEN PATTERNS:
-- ❌ Inline mapping config (use external JSON)
-- ❌ await on background processing (use fire-and-forget)
-- ❌ LoggingService (use native log from context)
-- ❌ All code in one file (use modular structure)
-- ❌ async mode webhook (use sync + fire-and-forget)
-```
-
----
-
-## STEP 3: Detailed Flow Documentation
-
-### Complete Processing Flow
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│ 1. WEBHOOK RECEIVED                                         │
-│    POST https://{workspace}.versori.run/generic-xml-order  │
-│    Content-Type: application/xml                             │
-│    Body: <Order>...</Order>                                  │
-└────────────────────┬────────────────────────────────────────┘
-                     │
-                     ▼
-┌─────────────────────────────────────────────────────────────┐
-│ 2. QUICK VALIDATION (Synchronous, ~10-50ms)                 │
-│    - Check fluent_commerce connection exists                 │
-│    - Validate XML payload present                           │
-│    - Return HTTP 200 OK immediately                         │
-└────────────────────┬────────────────────────────────────────┘
-                     │
-                     ▼
-┌─────────────────────────────────────────────────────────────┐
-│ 3. BACKGROUND PROCESSING (Fire-and-Forget)                   │
-│    ┌─────────────────────────────────────────────────────┐  │
-│    │ 3a. Initialize Fluent Client                        │  │
-│    │     - createClient({ ...ctx, log })                 │  │
-│    └─────────────────────────────────────────────────────┘  │
-│    ┌─────────────────────────────────────────────────────┐  │
-│    │ 3b. Parse XML (if needed)                           │  │
-│    │     - Versori auto-parses XML to object             │  │
-│    │     - Optional: Extract nested XML segments         │  │
-│    └─────────────────────────────────────────────────────┘  │
-│    ┌─────────────────────────────────────────────────────┐  │
-│    │ 3c. Map XML to GraphQL Variables                    │  │
-│    │     - Load mapping config from JSON                 │  │
-│    │     - GraphQLMutationMapper.mapWithNodes() (REQUIRED for custom resolvers)│  │
-│    │     - Apply custom resolvers                        │  │
-│    └─────────────────────────────────────────────────────┘  │
-│    ┌─────────────────────────────────────────────────────┐  │
-│    │ 3d. Generate GraphQL Mutation                       │  │
-│    │     - Query returned in result.query                │  │
-│    └─────────────────────────────────────────────────────┘  │
-│    ┌─────────────────────────────────────────────────────┐  │
-│    │ 3e. Execute GraphQL Mutation                        │  │
-│    │     - client.graphql({ query, variables })          │  │
-│    └─────────────────────────────────────────────────────┘  │
-│    ┌─────────────────────────────────────────────────────┐  │
-│    │ 3f. Save Audit Trail (Optional)                      │  │
-│    │     - 1-incoming-xml.json                           │  │
-│    │     - 2-mapped-variables.json                       │  │
-│    │     - 3-graphql-response.json                       │  │
-│    └─────────────────────────────────────────────────────┘  │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### Response Timing
-
-| Stage | Timing | Blocking |
-|-------|--------|----------|
-| **Webhook Validation** | ~10-50ms | ✅ Yes (blocks response) |
-| **Background Processing** | ~500-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 (~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
-
-```
-generic-xml-order-ingestion/
-├── package.json                              # Dependencies and Versori config
-├── index.ts                                  # Entry point - exports all workflows
-└── src/
-    ├── workflows/
-    │   └── webhook/
-    │       └── order-ingestion.ts            # Webhook: Receive XML orders
-    │
-    ├── services/
-    │   └── order-processing.service.ts       # Shared orchestration logic (reusable)
-    │
-    ├── config/
-    │   └── 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
-- ✅ **Type safety**: TypeScript interfaces for better IDE support
-- ✅ **Scalable**: Easy to add new webhooks or services
-
----
-
-### File: `package.json`
-
-```json
-{
-  "name": "generic-xml-order-ingestion",
-  "version": "2.0.0",
-  "description": "Generic XML Order Ingestion Webhook to Fluent Commerce",
-  "type": "module",
-  "versori": {
-    "workflows": "./index.ts"
-  },
-  "scripts": {
-    "lint": "eslint . --ext .ts",
-    "typecheck": "tsc --noEmit"
-  },
-  "dependencies": {
-    "@fluentcommerce/fc-connect-sdk": "^0.1.39",
-    "@versori/run": "latest"
-  },
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "typescript": "^5.0.0"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  }
-}
-```
-
----
-
-### File: `index.ts`
-
-```typescript
-/**
- * Entry point - Export all workflows for Versori platform
- *
- * This file exports all workflows to be registered with Versori.
- * Each workflow is defined in its own file for better organization.
- */
-
-export { genericXmlOrder } from './src/workflows/webhook/order-ingestion';
-```
-
----
-
-### File: `src/types/order.types.ts`
-
-```typescript
-/**
- * Type definitions for order ingestion
- */
-export interface OrderIngestionResult {
-  success: boolean;
-  orderId?: string;
-  orderRef?: string;
-  error?: string;
-  recommendation?: string;
-  timestamp: string;
-  duration: number;
-}
-
-export interface OrderMappingConfig {
-  mutation: string;
-  sourceFormat: 'xml' | 'json';
-  nodes?: {
-    [key: string]: {
-      extract: string;
-      parse: 'xml' | 'json';
-      required: boolean;
-    };
-  };
-  fields: {
-    [key: string]: any;
-  };
-}
-```
-
----
-
-### File: `src/config/order-mapping.json`
-
-```json
-{
-  "mutation": "createOrder",
-  "sourceFormat": "xml",
-  "returnFields": ["id", "ref", "status"],
-  "nodes": {
-    "order": {
-      "extract": "Envelope.Body.OrderEnvelope",
-      "parse": "xml",
-      "required": false
-    }
-  },
-  "fields": {
-    "ref": {
-      "source": "$order.Order@id",
-      "resolver": "sdk.toString",
-      "required": true
-    },
-    "type": {
-      "source": "$order.Order@type",
-      "defaultValue": "HD"
-    },
-    "retailer": {
-      "fields": {
-        "id": {
-          "value": "2"
-        }
-      }
-    },
-    "customer": {
-      "fields": {
-        "firstName": {
-          "source": "$order.Order.Customer.FirstName"
-        },
-        "lastName": {
-          "source": "$order.Order.Customer.LastName"
-        },
-        "username": {
-          "source": "$order.Order.Customer.Email",
-          "resolver": "sdk.lowercase"
-        }
-      }
-    },
-    "items": {
-      "source": "$order.Order.Items.Item",
-      "isArray": true,
-      "fields": {
-        "ref": {
-          "source": "$.@id",
-          "resolver": "sdk.toString"
-        },
-        "productRef": {
-          "source": "$.Sku",
-          "resolver": "sdk.toString"
-        },
-        "quantity": {
-          "source": "$.Quantity",
-          "resolver": "sdk.parseInt"
-        },
-        "price": {
-          "source": "$.Price",
-          "resolver": "sdk.parseFloat"
-        },
-        "currency": {
-          "source": "$order.Order.Currency",
-          "defaultValue": "USD"
-        }
-      }
-    },
-    "totalPrice": {
-      "source": "$order.Order.Totals.Subtotal",
-      "resolver": "sdk.parseFloat"
-    },
-    "totalTaxPrice": {
-      "source": "$order.Order.Totals.Tax",
-      "resolver": "sdk.parseFloat",
-      "defaultValue": 0
-    }
-  }
-}
-```
-
----
-
-### File: `src/services/order-processing.service.ts`
-
-```typescript
-/**
- * Order Processing Service
- *
- * Orchestrates the complete order ingestion process:
- * 1. Validate webhook payload
- * 2. Extract and parse nested XML (if needed)
- * 3. Apply field mapping with custom resolvers
- * 4. Create order via GraphQL API
- * 5. Audit trail (save input/output files)
- */
-
-import { Buffer } from 'node:buffer';
-import { createClient, GraphQLMutationMapper, classifyErrors } from '@fluentcommerce/fc-connect-sdk';
-import type { OrderIngestionResult } from '../types/order.types';
-import mappingConfig from '../config/order-mapping.json' with { type: 'json' };
-
-/**
- * Process order ingestion (background processing)
- *
- * @param ctx - Versori context object containing fetch, connections, log, activation, data
- * @param xmlData - Parsed XML order data
- * @param executionStartTime - Workflow start time for duration tracking
- */
-export async function processOrderInBackground(
-  ctx: any,
-  xmlData: any,
-  executionStartTime: number
-): Promise<OrderIngestionResult> {
-  const { log, activation, connections, openKv } = ctx;
-
-  try {
-    log.info('🔄 [BACKGROUND] Starting background order processing', {
-      correlationId: activation?.id,
-      timestamp: new Date().toISOString(),
-    });
-
-    // ========================================
-    // STEP 2: CLIENT INITIALIZATION
-    // ========================================
-
-    // Optional: Validate connection immediately (fail-fast mode for webhooks)
-    // Set activation variable 'validateConnectionOnStart' = 'true' to enable
-    const validateConnection = activation?.getVariable('validateConnectionOnStart') === 'true';
-
-    if (validateConnection) {
-      log.info('🔍 [BACKGROUND] Connection validation enabled', {
-        note: 'This executes query { me { ref } } to verify authentication',
-      });
-    }
-
-    const client = await createClient(ctx, validateConnection ? { validateConnection: true } : undefined);
-
-    if (validateConnection) {
-      log.info('✅ [BACKGROUND] Connection validated successfully - authentication confirmed');
-    }
-
-    log.info('🔌 [BACKGROUND] Fluent client initialized');
-
-    // ========================================
-    // STEP 3: MAPPING AND TRANSFORMATION
-    // ========================================
-
-    log.info('🔄 [BACKGROUND] Applying mapping');
-
-    // Apply mapping with optional nodes processing
-    // RESOLVERS: Custom transformation logic (async allowed)
-    // CONTEXT: Pass fluentClient to resolvers for API calls
-    const mapper = new GraphQLMutationMapper(mappingConfig as any, log, { fluentClient: client as any });
-
-    // Optional custom resolvers
-    const customResolvers = {
-      'custom.ensureRef': (value: any) => String(value || `ORD-${Date.now()}`),
-    };
-
-    // Use mapWithNodes() when custom resolvers are present (REQUIRED)
-    // map() does NOT accept custom resolvers parameter
-    // Returns MapWithNodesResult with query auto-generated!
-    const result = await mapper.mapWithNodes(xmlData, customResolvers as any, {
-      fluentClient: client as any,
-      config: {},
-      helpers: { fluentClient: client as any, logger: log },
-    });
-
-    if (!result.success) {
-      log.error('❌ [BACKGROUND] Mapping failed', {
-        errors: result.errors,
-        errorCount: result.errors?.length || 0,
-      });
-      return {
-        success: false,
-        error: 'Mapping validation failed',
-        recommendation: 'Check mapping configuration JSON and verify source paths match incoming XML structure',
-        timestamp: new Date().toISOString(),
-        duration: Date.now() - executionStartTime,
-      };
-    }
-
-    const orderRef = (result.data as any)?.input?.ref || 'unknown';
-    log.info('✅ [BACKGROUND] Mapping completed', {
-      orderRef,
-      fieldsCount: Object.keys((result.data as any)?.input || {}).length,
-    });
-
-    // ========================================
-    // STEP 4: AUDIT TRAIL (SAVE INPUT DATA)
-    // ========================================
-
-    // 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];
-      
-      // Save 1: Original XML (parsed by Versori) - save BEFORE memory cleanup
-      await kv.set([...auditKey, 'incoming-xml'], xmlData);
-      
-      // Save 2: Mapped Fluent variables (ready for GraphQL)
-      await kv.set([...auditKey, 'mapped-variables'], 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,
-        note: 'Continuing with order creation',
-      });
-    }
-
-    // ✅ PRODUCTION: Memory cleanup for large XML payloads (after saving audit trail)
-    try {
-      if (xmlData && typeof xmlData === 'object') {
-        // Clear large XML data from memory after mapping and audit trail
-        Object.keys(xmlData).forEach(key => delete (xmlData as any)[key]);
-      }
-    } catch (cleanupError) {
-      // Non-blocking - continue processing
-      log.debug('Memory cleanup skipped', { note: 'Non-critical' });
-    }
-
-    // ========================================
-    // STEP 5: CREATE ORDER VIA GRAPHQL API
-    // ========================================
-
-    log.info('📡 [BACKGROUND] Creating order in Fluent Commerce', { orderRef });
-
-    // mapWithNodes() now auto-generates query - no need to call buildMutation()!
-    log.info('📝 [BACKGROUND] GraphQL mutation auto-generated', { orderRef });
-
-    // Execute mutation (query is auto-generated in result)
-    log.info('🚀 [BACKGROUND] Executing GraphQL mutation', { orderRef });
-    const response = await client.graphql({
-      query: result.query,
-      variables: result.variables  // ✅ Use variables (wrapped if fields pattern)
-    });
-
-    if (response.errors?.length) {
-      // Classify GraphQL errors to determine retry strategy
-      const classification = classifyErrors(response.errors);
-      
-      log.error('❌ [BACKGROUND] GraphQL execution errors', {
-        orderRef,
-        errorCode: classification.errorCode,
-        retryable: classification.retryable,
-        action: classification.action,
-        message: classification.userMessage,
-        errors: response.errors,
-        errorCount: response.errors.length,
-      });
-      return {
-        success: false,
-        error: 'GraphQL mutation execution failed',
-        recommendation: 'Review GraphQL errors and verify order data structure',
-        timestamp: new Date().toISOString(),
-        duration: Date.now() - executionStartTime,
-      };
-    }
-
-    const orderId = response.data?.createOrder?.id;
-    log.info('✅ [BACKGROUND] Order created successfully', {
-      orderRef,
-      orderId,
-    });
-
-    // Save GraphQL response to audit trail (KV storage)
-    try {
-      const kv = openKv(':project:');
-      const timestamp = new Date().toISOString();
-      const auditKey = ['orders', 'audit', orderRef, timestamp, 'graphql-response'];
-      await kv.set(auditKey, response);
-      log.info('GraphQL response saved to KV storage', { orderRef, timestamp });
-    } catch (kvError: any) {
-      log.warn('Failed to save GraphQL response to KV', {
-        error: kvError.message,
-        note: 'Non-critical',
-      });
-    }
-
-    // Duration tracking
-    const duration = Date.now() - executionStartTime;
-    log.info('🎉 [BACKGROUND] Order processed successfully', {
-      orderRef,
-      orderId,
-      duration: `${duration}ms`,
-      timestamp: new Date().toISOString(),
-    });
-
-    return {
-      success: true,
-      orderId,
-      orderRef,
-      timestamp: new Date().toISOString(),
-      duration,
-    };
-  } catch (error: any) {
-    const duration = Date.now() - executionStartTime;
-    log.error('❌ [BACKGROUND] Unhandled error in order processing', {
-      error: error instanceof Error ? error.message : String(error),
-      errorType: error instanceof Error ? error.constructor.name : 'Error',
-      stack: error instanceof Error ? error.stack : undefined,
-      recommendation: error.message?.includes('authentication') || error.message?.includes('401')
-        ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
-        : error.message?.includes('mapping') || error.message?.includes('field')
-        ? 'Check mapping configuration JSON and verify source paths match incoming XML structure'
-        : error.message?.includes('connection') || error.message?.includes('timeout')
-        ? 'Check network connectivity and Fluent Commerce API availability'
-        : error.message?.includes('validation') || error.message?.includes('required')
-        ? 'Ensure all required fields are present in the webhook payload'
-        : 'Review error details and check webhook payload structure',
-      correlationId: activation?.id,
-      duration,
-    });
-
-    return {
-      success: false,
-      error: error instanceof Error ? error.message : String(error),
-      recommendation: error.message?.includes('authentication') || error.message?.includes('401')
-        ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
-        : 'Review error details and check webhook payload structure',
-      timestamp: new Date().toISOString(),
-      duration,
-    };
-  }
-}
-```
-
----
-
-### File: `src/workflows/webhook/order-ingestion.ts`
-
-```typescript
-/**
- * Generic XML Order Ingestion Webhook
- *
- * Versori Endpoint: POST https://{workspace}.versori.run/generic-xml-order
- * Content-Type: application/xml
- *
- * Pattern: Sync + Fire-and-Forget
- * - Quick validation (synchronous)
- * - Background processing (fire-and-forget)
- * - Fast webhook response (~10-50ms)
- */
-
-import { webhook, http } from '@versori/run';
-import type { Context } from '@versori/run';
-import { processOrderInBackground } from '../../services/order-processing.service';
-
-/**
- * Generic XML Order Ingestion Webhook
- *
- * Sync mode: Response sent when handler returns
- * Fire-and-forget: Background processing continues after response
- */
-export const genericXmlOrder = webhook('generic-xml-order', {
-  response: { mode: 'sync' }, // ✅ Sync mode: response sent when handler returns
-}).then(
-  http('validate-and-process', { connection: 'fluent_commerce' }, async (ctx: Context<any>) => {
-    const { log, activation, connections, data } = ctx;
-    const executionStartTime = Date.now();
-
-    log.info('🚀 [WEBHOOK] Received generic XML order webhook', {
-      correlationId: activation?.id,
-      timestamp: new Date().toISOString(),
-    });
-
-    // Quick validation (synchronous)
-    if (!connections || !connections.fluent_commerce) {
-      log.error('❌ [WEBHOOK] Configuration error: Missing fluent_commerce connection', {
-        recommendation: 'Configure fluent_commerce connection in Connections section with OAuth2 credentials',
-      });
-      return {
-        status: 500,
-        body: {
-          success: false,
-          message: 'Missing fluent_commerce connection',
-          recommendation: 'Configure fluent_commerce connection in Connections section with OAuth2 credentials',
-          timestamp: new Date().toISOString(),
-        },
-      };
-    }
-
-    // Get webhook payload (Versori pre-parses XML)
-    const xmlData = activation.body || data;
-
-    if (!xmlData) {
-      log.error('❌ [WEBHOOK] Validation error: No XML data received in webhook', {
-        recommendation: 'Ensure webhook payload contains valid XML order data',
-      });
-      return {
-        status: 400,
-        body: {
-          success: false,
-          message: 'No XML data received',
-          recommendation: 'Ensure webhook payload contains valid XML order data',
-          timestamp: new Date().toISOString(),
-        },
-      };
-    }
-
-    log.info('✅ [WEBHOOK] Validation passed, starting background processing', {
-      correlationId: activation?.id,
-    });
-
-    // ✅ Fire-and-forget: Start background processing WITHOUT await
-    // The promise continues execution after we return the response
-    processOrderInBackground(ctx, xmlData, executionStartTime)
-      .then((result) => {
-        if (result.success) {
-          log.info('✅ [BACKGROUND] Order processing completed successfully', {
-            orderId: result.orderId,
-            orderRef: result.orderRef,
-            duration: result.duration,
-            correlationId: activation?.id,
-          });
-        } else {
-          log.error('❌ [BACKGROUND] Order processing failed', {
-            error: result.error,
-            recommendation: result.recommendation,
-            correlationId: activation?.id,
-          });
-        }
-      })
-      .catch((error: unknown) => {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        log.error('❌ [BACKGROUND] Order processing failed with exception', {
-          error: errorMessage,
-          stack: error instanceof Error ? error.stack : undefined,
-          errorType: error instanceof Error ? error.constructor.name : typeof error,
-          correlationId: activation?.id,
-        });
-      });
-
-    // Return immediately (response sent with this return value)
-    return {
-      status: 200,
-      body: {
-        success: true,
-        message: 'Order ingestion started in background',
-        timestamp: new Date().toISOString(),
-      },
-    };
-  })
-);
-```
-
----
-
-## STEP 5: Configuration
-
-### Activation Variables
-
-Configure these in Versori Activation Variables:
-
-| Variable | Description | Required | Default | Example |
-|----------|-------------|----------|---------|---------|
-| `OUTPUT_DIR` | Directory for audit trail files | No | `./output` | `./audit-trail` |
-| `validateConnectionOnStart` | Validate Fluent connection on startup (fail-fast mode) | No | `false` | `true` |
-
-**Usage in Code:**
-```typescript
-const outputDir = activation?.getVariable('OUTPUT_DIR') || './output';
-const validateConnection = activation?.getVariable('validateConnectionOnStart') === 'true';
-```
-
-### Connection Configuration
-
-**Required Connection:** `fluent_commerce`
-
-- **Type**: OAuth2
-- **Credentials**: Client ID, Client Secret, Base URL
-- **Scope**: Order creation permissions
-
----
-
-## STEP 6: Testing
-
-### Test Webhook Request
-
-```bash
-curl -X POST https://{workspace}.versori.run/generic-xml-order \
-  -H "Content-Type: application/xml" \
-  -d '<Order>
-    <Order id="ORD-001" type="HD">
-      <Customer>
-        <FirstName>John</FirstName>
-        <LastName>Doe</LastName>
-        <Email>john.doe@example.com</Email>
-      </Customer>
-      <Items>
-        <Item id="ITEM-001">
-          <Sku>SKU-12345</Sku>
-          <Quantity>2</Quantity>
-          <Price>29.99</Price>
-        </Item>
-      </Items>
-      <Totals>
-        <Subtotal>59.98</Subtotal>
-        <Tax>4.80</Tax>
-      </Totals>
-      <Currency>USD</Currency>
-    </Order>
-  </Order>'
-```
-
-### Expected Response
-
-```json
-{
-  "success": true,
-  "message": "Order ingestion started in background",
-  "timestamp": "2025-01-25T10:30:00.000Z"
-}
-```
-
-**Response Time**: ~10-50ms (fast acknowledgment)
-
-**Background Processing**: Order creation happens asynchronously (~500-2000ms)
-
----
-
-## STEP 7: Troubleshooting
-
-### Common Issues
-
-**1. Missing fluent_commerce connection**
-- **Error**: `Missing fluent_commerce connection`
-- **Solution**: Configure `fluent_commerce` connection in Versori Connections section
-
-**2. Mapping validation failed**
-- **Error**: `Mapping validation failed`
-- **Solution**: Check `config/order-mapping.json` and verify source paths match XML structure
-
-**3. GraphQL execution errors**
-- **Error**: `GraphQL mutation execution failed`
-- **Solution**: Review GraphQL errors in logs, verify order data structure
-
-**4. Slow webhook response**
-- **Error**: Webhook takes >100ms to respond
-- **Solution**: Ensure using sync mode + fire-and-forget pattern (not awaiting background processing)
-
----
-
-## STEP 8: Next Steps
-
-1. **Customize Mapping**: Edit `src/config/order-mapping.json` for your XML structure
-2. **Add Custom Resolvers**: Extend `customResolvers` in `order-processing.service.ts`
-3. **Enable Audit Trail**: Set `OUTPUT_DIR` activation variable
-4. **Monitor Background Processing**: Check Versori logs for `[BACKGROUND]` tagged messages
-5. **Add Error Notifications**: Integrate with monitoring/alerting systems
-
----
-
-**Need Help?**
-- Review SDK documentation: `/docs/readme.md`
-- Check example connectors: `/connectors/Sample versori connectors/`
-- Versori platform documentation: Check your platform's docs
+---
+template_id: tpl-webhook-generic-xml-order
+canonical_filename: template-webhook-generic-xml-order.md
+sdk_version: ^0.1.39
+runtime: versori
+direction: ingestion
+source: webhook-xml
+destination: fluent-graphql
+entity: order
+format: xml
+logging: versori
+status: stable
+features:
+  - external-json-config
+  - memory-management
+  - enhanced-logging
+  - audit-trail
+---
+
+# Template: Webhook - Generic XML Order to Fluent GraphQL
+
+**SDK Version:** @fluentcommerce/fc-connect-sdk@^0.1.39
+**Last Updated:** 2025-01-24
+**Deployment Target:** Versori Platform
+
+**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 generic XML orders via Versori HTTP webhook and create orders in Fluent Commerce using GraphQL mutations.
+
+**Complexity**: Medium
+
+**Runtime**: Versori Platform
+
+**Estimated Lines**: ~600 lines (modular structure)
+
+---
+
+## STEP 1: Understand This Template
+
+**What This Template Does:**
+
+- Versori HTTP webhook endpoint receiving XML order data
+- XML parsing with optional nodes config for nested/escaped XML segments
+- GraphQL mutation mapping from XML structure to Fluent schema
+- Custom resolvers for data transformation and API calls
+- Memory management (clears large XML payloads after mapping)
+- Error handling and structured response formatting
+- Audit trail (save input/output to filesystem for debugging)
+- **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
+- `XMLParserService` - XML parsing with nodes extraction
+- Native Versori `log` - Use `log` from context
+
+**Entity Type:**
+
+- **Order** - Fluent entity for order creation
+- **GraphQL Mutation** - Uses `createOrder` mutation (not Event API)
+
+**Critical Patterns:**
+
+- **Sync + Fire-and-Forget**: Webhook validates quickly, returns immediately, processes in background
+- **External JSON Config**: Mapping configuration in separate JSON file (`config/order-mapping.json`)
+- **Modular Architecture**: Separate services, workflows, config, types folders
+- **Memory Management**: Clears large XML payloads from memory after mapping
+- **Background Processing**: Long-running operations (GraphQL mutations) happen asynchronously
+- **Error Handling**: Comprehensive error handling with structured logging and recommendations
+- **Activation Variables**: Configuration via Versori activation variables (OUTPUT_DIR, validateConnectionOnStart)
+
+**When to Use This Template:**
+
+- ✅ Real-time order ingestion from external systems (SFCC, Shopify, custom)
+- ✅ XML order format (can be adapted for JSON)
+- ✅ Need fast webhook response (don't wait for order creation)
+- ✅ Single order per webhook call
+- ✅ Need audit trail for debugging
+
+**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)
+
+---
+
+## 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 generic XML order ingestion to Fluent Commerce GraphQL.
+
+REQUIREMENTS:
+1. Runtime: Versori Platform (HTTP webhook)
+2. Source: XML order data via HTTP POST webhook
+3. Destination: Fluent Commerce GraphQL API (createOrder mutation)
+4. Format: XML with optional nodes extraction
+5. Entity: Order (GraphQL mutation)
+
+KEY FEATURES:
+- Sync + fire-and-forget pattern (fast webhook response, background processing)
+- External JSON mapping configuration (not inline TypeScript)
+- Modular architecture (workflows/, services/, config/, types/)
+- XML parsing with optional nodes config for nested XML segments
+- GraphQLMutationMapper for XML → GraphQL transformation
+- 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' } (fast response)
+2. Background Processing: Fire-and-forget pattern (no await on long operations)
+3. Mapping Config: External JSON file (config/order-mapping.json)
+4. Modular Structure: Separate services/, config/, types/ folders
+5. Native Logging: Use log from context (no LoggingService)
+6. Error Handling: Structured error responses with recommendations
+
+SDK METHODS TO USE:
+- createClient({ ...ctx, log }) - Pass full Versori context
+- new GraphQLMutationMapper(mappingConfig, log, { fluentClient: client }) - Initialize mapper
+- mapper.mapWithNodes(xmlData, customResolvers, context) - Map XML with custom resolvers (REQUIRED for custom resolvers)
+- mapper.map(xmlData) - Map XML without custom resolvers (built-in SDK resolvers only)
+- mapWithNodes() now returns query automatically (no need for buildMutation())
+- client.graphql({ query, variables }) - Execute GraphQL mutation
+
+FORBIDDEN PATTERNS:
+- ❌ Inline mapping config (use external JSON)
+- ❌ await on background processing (use fire-and-forget)
+- ❌ LoggingService (use native log from context)
+- ❌ All code in one file (use modular structure)
+- ❌ async mode webhook (use sync + fire-and-forget)
+```
+
+---
+
+## STEP 3: Detailed Flow Documentation
+
+### Complete Processing Flow
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ 1. WEBHOOK RECEIVED                                         │
+│    POST https://{workspace}.versori.run/generic-xml-order  │
+│    Content-Type: application/xml                             │
+│    Body: <Order>...</Order>                                  │
+└────────────────────┬────────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────────┐
+│ 2. QUICK VALIDATION (Synchronous, ~10-50ms)                 │
+│    - Check fluent_commerce connection exists                 │
+│    - Validate XML payload present                           │
+│    - Return HTTP 200 OK immediately                         │
+└────────────────────┬────────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────────┐
+│ 3. BACKGROUND PROCESSING (Fire-and-Forget)                   │
+│    ┌─────────────────────────────────────────────────────┐  │
+│    │ 3a. Initialize Fluent Client                        │  │
+│    │     - createClient({ ...ctx, log })                 │  │
+│    └─────────────────────────────────────────────────────┘  │
+│    ┌─────────────────────────────────────────────────────┐  │
+│    │ 3b. Parse XML (if needed)                           │  │
+│    │     - Versori auto-parses XML to object             │  │
+│    │     - Optional: Extract nested XML segments         │  │
+│    └─────────────────────────────────────────────────────┘  │
+│    ┌─────────────────────────────────────────────────────┐  │
+│    │ 3c. Map XML to GraphQL Variables                    │  │
+│    │     - Load mapping config from JSON                 │  │
+│    │     - GraphQLMutationMapper.mapWithNodes() (REQUIRED for custom resolvers)│  │
+│    │     - Apply custom resolvers                        │  │
+│    └─────────────────────────────────────────────────────┘  │
+│    ┌─────────────────────────────────────────────────────┐  │
+│    │ 3d. Generate GraphQL Mutation                       │  │
+│    │     - Query returned in result.query                │  │
+│    └─────────────────────────────────────────────────────┘  │
+│    ┌─────────────────────────────────────────────────────┐  │
+│    │ 3e. Execute GraphQL Mutation                        │  │
+│    │     - client.graphql({ query, variables })          │  │
+│    └─────────────────────────────────────────────────────┘  │
+│    ┌─────────────────────────────────────────────────────┐  │
+│    │ 3f. Save Audit Trail (Optional)                      │  │
+│    │     - 1-incoming-xml.json                           │  │
+│    │     - 2-mapped-variables.json                       │  │
+│    │     - 3-graphql-response.json                       │  │
+│    └─────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Response Timing
+
+| Stage | Timing | Blocking |
+|-------|--------|----------|
+| **Webhook Validation** | ~10-50ms | ✅ Yes (blocks response) |
+| **Background Processing** | ~500-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 (~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
+
+```
+generic-xml-order-ingestion/
+├── package.json                              # Dependencies and Versori config
+├── index.ts                                  # Entry point - exports all workflows
+└── src/
+    ├── workflows/
+    │   └── webhook/
+    │       └── order-ingestion.ts            # Webhook: Receive XML orders
+    │
+    ├── services/
+    │   └── order-processing.service.ts       # Shared orchestration logic (reusable)
+    │
+    ├── config/
+    │   └── 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
+- ✅ **Type safety**: TypeScript interfaces for better IDE support
+- ✅ **Scalable**: Easy to add new webhooks or services
+
+---
+
+### File: `package.json`
+
+```json
+{
+  "name": "generic-xml-order-ingestion",
+  "version": "2.0.0",
+  "description": "Generic XML Order Ingestion Webhook to Fluent Commerce",
+  "type": "module",
+  "versori": {
+    "workflows": "./index.ts"
+  },
+  "scripts": {
+    "lint": "eslint . --ext .ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@fluentcommerce/fc-connect-sdk": "^0.1.39",
+    "@versori/run": "latest"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}
+```
+
+---
+
+### File: `index.ts`
+
+```typescript
+/**
+ * Entry point - Export all workflows for Versori platform
+ *
+ * This file exports all workflows to be registered with Versori.
+ * Each workflow is defined in its own file for better organization.
+ */
+
+export { genericXmlOrder } from './src/workflows/webhook/order-ingestion';
+```
+
+---
+
+### File: `src/types/order.types.ts`
+
+```typescript
+/**
+ * Type definitions for order ingestion
+ */
+export interface OrderIngestionResult {
+  success: boolean;
+  orderId?: string;
+  orderRef?: string;
+  error?: string;
+  recommendation?: string;
+  timestamp: string;
+  duration: number;
+}
+
+export interface OrderMappingConfig {
+  mutation: string;
+  sourceFormat: 'xml' | 'json';
+  nodes?: {
+    [key: string]: {
+      extract: string;
+      parse: 'xml' | 'json';
+      required: boolean;
+    };
+  };
+  fields: {
+    [key: string]: any;
+  };
+}
+```
+
+---
+
+### File: `src/config/order-mapping.json`
+
+```json
+{
+  "mutation": "createOrder",
+  "sourceFormat": "xml",
+  "returnFields": ["id", "ref", "status"],
+  "nodes": {
+    "order": {
+      "extract": "Envelope.Body.OrderEnvelope",
+      "parse": "xml",
+      "required": false
+    }
+  },
+  "fields": {
+    "ref": {
+      "source": "$order.Order@id",
+      "resolver": "sdk.toString",
+      "required": true
+    },
+    "type": {
+      "source": "$order.Order@type",
+      "defaultValue": "HD"
+    },
+    "retailer": {
+      "fields": {
+        "id": {
+          "value": "2"
+        }
+      }
+    },
+    "customer": {
+      "fields": {
+        "firstName": {
+          "source": "$order.Order.Customer.FirstName"
+        },
+        "lastName": {
+          "source": "$order.Order.Customer.LastName"
+        },
+        "username": {
+          "source": "$order.Order.Customer.Email",
+          "resolver": "sdk.lowercase"
+        }
+      }
+    },
+    "items": {
+      "source": "$order.Order.Items.Item",
+      "isArray": true,
+      "fields": {
+        "ref": {
+          "source": "$.@id",
+          "resolver": "sdk.toString"
+        },
+        "productRef": {
+          "source": "$.Sku",
+          "resolver": "sdk.toString"
+        },
+        "quantity": {
+          "source": "$.Quantity",
+          "resolver": "sdk.parseInt"
+        },
+        "price": {
+          "source": "$.Price",
+          "resolver": "sdk.parseFloat"
+        },
+        "currency": {
+          "source": "$order.Order.Currency",
+          "defaultValue": "USD"
+        }
+      }
+    },
+    "totalPrice": {
+      "source": "$order.Order.Totals.Subtotal",
+      "resolver": "sdk.parseFloat"
+    },
+    "totalTaxPrice": {
+      "source": "$order.Order.Totals.Tax",
+      "resolver": "sdk.parseFloat",
+      "defaultValue": 0
+    }
+  }
+}
+```
+
+---
+
+### File: `src/services/order-processing.service.ts`
+
+```typescript
+/**
+ * Order Processing Service
+ *
+ * Orchestrates the complete order ingestion process:
+ * 1. Validate webhook payload
+ * 2. Extract and parse nested XML (if needed)
+ * 3. Apply field mapping with custom resolvers
+ * 4. Create order via GraphQL API
+ * 5. Audit trail (save input/output files)
+ */
+
+import { Buffer } from 'node:buffer';
+import { createClient, GraphQLMutationMapper, classifyErrors } from '@fluentcommerce/fc-connect-sdk';
+import type { OrderIngestionResult } from '../types/order.types';
+import mappingConfig from '../config/order-mapping.json' with { type: 'json' };
+
+/**
+ * Process order ingestion (background processing)
+ *
+ * @param ctx - Versori context object containing fetch, connections, log, activation, data
+ * @param xmlData - Parsed XML order data
+ * @param executionStartTime - Workflow start time for duration tracking
+ */
+export async function processOrderInBackground(
+  ctx: any,
+  xmlData: any,
+  executionStartTime: number
+): Promise<OrderIngestionResult> {
+  const { log, activation, connections, openKv } = ctx;
+
+  try {
+    log.info('🔄 [BACKGROUND] Starting background order processing', {
+      correlationId: activation?.id,
+      timestamp: new Date().toISOString(),
+    });
+
+    // ========================================
+    // STEP 2: CLIENT INITIALIZATION
+    // ========================================
+
+    // Optional: Validate connection immediately (fail-fast mode for webhooks)
+    // Set activation variable 'validateConnectionOnStart' = 'true' to enable
+    const validateConnection = activation?.getVariable('validateConnectionOnStart') === 'true';
+
+    if (validateConnection) {
+      log.info('🔍 [BACKGROUND] Connection validation enabled', {
+        note: 'This executes query { me { ref } } to verify authentication',
+      });
+    }
+
+    const client = await createClient(ctx, validateConnection ? { validateConnection: true } : undefined);
+
+    if (validateConnection) {
+      log.info('✅ [BACKGROUND] Connection validated successfully - authentication confirmed');
+    }
+
+    log.info('🔌 [BACKGROUND] Fluent client initialized');
+
+    // ========================================
+    // STEP 3: MAPPING AND TRANSFORMATION
+    // ========================================
+
+    log.info('🔄 [BACKGROUND] Applying mapping');
+
+    // Apply mapping with optional nodes processing
+    // RESOLVERS: Custom transformation logic (async allowed)
+    // CONTEXT: Pass fluentClient to resolvers for API calls
+    const mapper = new GraphQLMutationMapper(mappingConfig as any, log, { fluentClient: client as any });
+
+    // Optional custom resolvers
+    const customResolvers = {
+      'custom.ensureRef': (value: any) => String(value || `ORD-${Date.now()}`),
+    };
+
+    // Use mapWithNodes() when custom resolvers are present (REQUIRED)
+    // map() does NOT accept custom resolvers parameter
+    // Returns MapWithNodesResult with query auto-generated!
+    const result = await mapper.mapWithNodes(xmlData, customResolvers as any, {
+      fluentClient: client as any,
+      config: {},
+      helpers: { fluentClient: client as any, logger: log },
+    });
+
+    if (!result.success) {
+      log.error('❌ [BACKGROUND] Mapping failed', {
+        errors: result.errors,
+        errorCount: result.errors?.length || 0,
+      });
+      return {
+        success: false,
+        error: 'Mapping validation failed',
+        recommendation: 'Check mapping configuration JSON and verify source paths match incoming XML structure',
+        timestamp: new Date().toISOString(),
+        duration: Date.now() - executionStartTime,
+      };
+    }
+
+    const orderRef = (result.data as any)?.input?.ref || 'unknown';
+    log.info('✅ [BACKGROUND] Mapping completed', {
+      orderRef,
+      fieldsCount: Object.keys((result.data as any)?.input || {}).length,
+    });
+
+    // ========================================
+    // STEP 4: AUDIT TRAIL (SAVE INPUT DATA)
+    // ========================================
+
+    // 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];
+      
+      // Save 1: Original XML (parsed by Versori) - save BEFORE memory cleanup
+      await kv.set([...auditKey, 'incoming-xml'], xmlData);
+      
+      // Save 2: Mapped Fluent variables (ready for GraphQL)
+      await kv.set([...auditKey, 'mapped-variables'], 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,
+        note: 'Continuing with order creation',
+      });
+    }
+
+    // ✅ PRODUCTION: Memory cleanup for large XML payloads (after saving audit trail)
+    try {
+      if (xmlData && typeof xmlData === 'object') {
+        // Clear large XML data from memory after mapping and audit trail
+        Object.keys(xmlData).forEach(key => delete (xmlData as any)[key]);
+      }
+    } catch (cleanupError) {
+      // Non-blocking - continue processing
+      log.debug('Memory cleanup skipped', { note: 'Non-critical' });
+    }
+
+    // ========================================
+    // STEP 5: CREATE ORDER VIA GRAPHQL API
+    // ========================================
+
+    log.info('📡 [BACKGROUND] Creating order in Fluent Commerce', { orderRef });
+
+    // mapWithNodes() now auto-generates query - no need to call buildMutation()!
+    log.info('📝 [BACKGROUND] GraphQL mutation auto-generated', { orderRef });
+
+    // Execute mutation (query is auto-generated in result)
+    log.info('🚀 [BACKGROUND] Executing GraphQL mutation', { orderRef });
+    const response = await client.graphql({
+      query: result.query,
+      variables: result.variables  // ✅ Use variables (wrapped if fields pattern)
+    });
+
+    if (response.errors?.length) {
+      // Classify GraphQL errors to determine retry strategy
+      const classification = classifyErrors(response.errors);
+      
+      log.error('❌ [BACKGROUND] GraphQL execution errors', {
+        orderRef,
+        errorCode: classification.errorCode,
+        retryable: classification.retryable,
+        action: classification.action,
+        message: classification.userMessage,
+        errors: response.errors,
+        errorCount: response.errors.length,
+      });
+      return {
+        success: false,
+        error: 'GraphQL mutation execution failed',
+        recommendation: 'Review GraphQL errors and verify order data structure',
+        timestamp: new Date().toISOString(),
+        duration: Date.now() - executionStartTime,
+      };
+    }
+
+    const orderId = response.data?.createOrder?.id;
+    log.info('✅ [BACKGROUND] Order created successfully', {
+      orderRef,
+      orderId,
+    });
+
+    // Save GraphQL response to audit trail (KV storage)
+    try {
+      const kv = openKv(':project:');
+      const timestamp = new Date().toISOString();
+      const auditKey = ['orders', 'audit', orderRef, timestamp, 'graphql-response'];
+      await kv.set(auditKey, response);
+      log.info('GraphQL response saved to KV storage', { orderRef, timestamp });
+    } catch (kvError: any) {
+      log.warn('Failed to save GraphQL response to KV', {
+        error: kvError.message,
+        note: 'Non-critical',
+      });
+    }
+
+    // Duration tracking
+    const duration = Date.now() - executionStartTime;
+    log.info('🎉 [BACKGROUND] Order processed successfully', {
+      orderRef,
+      orderId,
+      duration: `${duration}ms`,
+      timestamp: new Date().toISOString(),
+    });
+
+    return {
+      success: true,
+      orderId,
+      orderRef,
+      timestamp: new Date().toISOString(),
+      duration,
+    };
+  } catch (error: any) {
+    const duration = Date.now() - executionStartTime;
+    log.error('❌ [BACKGROUND] Unhandled error in order processing', {
+      error: error instanceof Error ? error.message : String(error),
+      errorType: error instanceof Error ? error.constructor.name : 'Error',
+      stack: error instanceof Error ? error.stack : undefined,
+      recommendation: error.message?.includes('authentication') || error.message?.includes('401')
+        ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
+        : error.message?.includes('mapping') || error.message?.includes('field')
+        ? 'Check mapping configuration JSON and verify source paths match incoming XML structure'
+        : error.message?.includes('connection') || error.message?.includes('timeout')
+        ? 'Check network connectivity and Fluent Commerce API availability'
+        : error.message?.includes('validation') || error.message?.includes('required')
+        ? 'Ensure all required fields are present in the webhook payload'
+        : 'Review error details and check webhook payload structure',
+      correlationId: activation?.id,
+      duration,
+    });
+
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+      recommendation: error.message?.includes('authentication') || error.message?.includes('401')
+        ? 'Verify fluent_commerce connection and OAuth2 credentials in Connections section'
+        : 'Review error details and check webhook payload structure',
+      timestamp: new Date().toISOString(),
+      duration,
+    };
+  }
+}
+```
+
+---
+
+### File: `src/workflows/webhook/order-ingestion.ts`
+
+```typescript
+/**
+ * Generic XML Order Ingestion Webhook
+ *
+ * Versori Endpoint: POST https://{workspace}.versori.run/generic-xml-order
+ * Content-Type: application/xml
+ *
+ * Pattern: Sync + Fire-and-Forget
+ * - Quick validation (synchronous)
+ * - Background processing (fire-and-forget)
+ * - Fast webhook response (~10-50ms)
+ */
+
+import { webhook, http } from '@versori/run';
+import type { Context } from '@versori/run';
+import { processOrderInBackground } from '../../services/order-processing.service';
+
+/**
+ * Generic XML Order Ingestion Webhook
+ *
+ * Sync mode: Response sent when handler returns
+ * Fire-and-forget: Background processing continues after response
+ */
+export const genericXmlOrder = webhook('generic-xml-order', {
+  response: { mode: 'sync' }, // ✅ Sync mode: response sent when handler returns
+}).then(
+  http('validate-and-process', { connection: 'fluent_commerce' }, async (ctx: Context<any>) => {
+    const { log, activation, connections, data } = ctx;
+    const executionStartTime = Date.now();
+
+    log.info('🚀 [WEBHOOK] Received generic XML order webhook', {
+      correlationId: activation?.id,
+      timestamp: new Date().toISOString(),
+    });
+
+    // Quick validation (synchronous)
+    if (!connections || !connections.fluent_commerce) {
+      log.error('❌ [WEBHOOK] Configuration error: Missing fluent_commerce connection', {
+        recommendation: 'Configure fluent_commerce connection in Connections section with OAuth2 credentials',
+      });
+      return {
+        status: 500,
+        body: {
+          success: false,
+          message: 'Missing fluent_commerce connection',
+          recommendation: 'Configure fluent_commerce connection in Connections section with OAuth2 credentials',
+          timestamp: new Date().toISOString(),
+        },
+      };
+    }
+
+    // Get webhook payload (Versori pre-parses XML)
+    const xmlData = activation.body || data;
+
+    if (!xmlData) {
+      log.error('❌ [WEBHOOK] Validation error: No XML data received in webhook', {
+        recommendation: 'Ensure webhook payload contains valid XML order data',
+      });
+      return {
+        status: 400,
+        body: {
+          success: false,
+          message: 'No XML data received',
+          recommendation: 'Ensure webhook payload contains valid XML order data',
+          timestamp: new Date().toISOString(),
+        },
+      };
+    }
+
+    log.info('✅ [WEBHOOK] Validation passed, starting background processing', {
+      correlationId: activation?.id,
+    });
+
+    // ✅ Fire-and-forget: Start background processing WITHOUT await
+    // The promise continues execution after we return the response
+    processOrderInBackground(ctx, xmlData, executionStartTime)
+      .then((result) => {
+        if (result.success) {
+          log.info('✅ [BACKGROUND] Order processing completed successfully', {
+            orderId: result.orderId,
+            orderRef: result.orderRef,
+            duration: result.duration,
+            correlationId: activation?.id,
+          });
+        } else {
+          log.error('❌ [BACKGROUND] Order processing failed', {
+            error: result.error,
+            recommendation: result.recommendation,
+            correlationId: activation?.id,
+          });
+        }
+      })
+      .catch((error: unknown) => {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        log.error('❌ [BACKGROUND] Order processing failed with exception', {
+          error: errorMessage,
+          stack: error instanceof Error ? error.stack : undefined,
+          errorType: error instanceof Error ? error.constructor.name : typeof error,
+          correlationId: activation?.id,
+        });
+      });
+
+    // Return immediately (response sent with this return value)
+    return {
+      status: 200,
+      body: {
+        success: true,
+        message: 'Order ingestion started in background',
+        timestamp: new Date().toISOString(),
+      },
+    };
+  })
+);
+```
+
+---
+
+## STEP 5: Configuration
+
+### Activation Variables
+
+Configure these in Versori Activation Variables:
+
+| Variable | Description | Required | Default | Example |
+|----------|-------------|----------|---------|---------|
+| `OUTPUT_DIR` | Directory for audit trail files | No | `./output` | `./audit-trail` |
+| `validateConnectionOnStart` | Validate Fluent connection on startup (fail-fast mode) | No | `false` | `true` |
+
+**Usage in Code:**
+```typescript
+const outputDir = activation?.getVariable('OUTPUT_DIR') || './output';
+const validateConnection = activation?.getVariable('validateConnectionOnStart') === 'true';
+```
+
+### Connection Configuration
+
+**Required Connection:** `fluent_commerce`
+
+- **Type**: OAuth2
+- **Credentials**: Client ID, Client Secret, Base URL
+- **Scope**: Order creation permissions
+
+---
+
+## STEP 6: Testing
+
+### Test Webhook Request
+
+```bash
+curl -X POST https://{workspace}.versori.run/generic-xml-order \
+  -H "Content-Type: application/xml" \
+  -d '<Order>
+    <Order id="ORD-001" type="HD">
+      <Customer>
+        <FirstName>John</FirstName>
+        <LastName>Doe</LastName>
+        <Email>john.doe@example.com</Email>
+      </Customer>
+      <Items>
+        <Item id="ITEM-001">
+          <Sku>SKU-12345</Sku>
+          <Quantity>2</Quantity>
+          <Price>29.99</Price>
+        </Item>
+      </Items>
+      <Totals>
+        <Subtotal>59.98</Subtotal>
+        <Tax>4.80</Tax>
+      </Totals>
+      <Currency>USD</Currency>
+    </Order>
+  </Order>'
+```
+
+### Expected Response
+
+```json
+{
+  "success": true,
+  "message": "Order ingestion started in background",
+  "timestamp": "2025-01-25T10:30:00.000Z"
+}
+```
+
+**Response Time**: ~10-50ms (fast acknowledgment)
+
+**Background Processing**: Order creation happens asynchronously (~500-2000ms)
+
+---
+
+## STEP 7: Troubleshooting
+
+### Common Issues
+
+**1. Missing fluent_commerce connection**
+- **Error**: `Missing fluent_commerce connection`
+- **Solution**: Configure `fluent_commerce` connection in Versori Connections section
+
+**2. Mapping validation failed**
+- **Error**: `Mapping validation failed`
+- **Solution**: Check `config/order-mapping.json` and verify source paths match XML structure
+
+**3. GraphQL execution errors**
+- **Error**: `GraphQL mutation execution failed`
+- **Solution**: Review GraphQL errors in logs, verify order data structure
+
+**4. Slow webhook response**
+- **Error**: Webhook takes >100ms to respond
+- **Solution**: Ensure using sync mode + fire-and-forget pattern (not awaiting background processing)
+
+---
+
+## STEP 8: Next Steps
+
+1. **Customize Mapping**: Edit `src/config/order-mapping.json` for your XML structure
+2. **Add Custom Resolvers**: Extend `customResolvers` in `order-processing.service.ts`
+3. **Enable Audit Trail**: Set `OUTPUT_DIR` activation variable
+4. **Monitor Background Processing**: Check Versori logs for `[BACKGROUND]` tagged messages
+5. **Add Error Notifications**: Integrate with monitoring/alerting systems
+
+---
+
+**Need Help?**
+- Review SDK documentation: `/docs/readme.md`
+- Check example connectors: `/connectors/Sample versori connectors/`
+- Versori platform documentation: Check your platform's docs