@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/01-TEMPLATES/versori/workflows/rubix-webhooks/template-webhook-rubix-fulfilment-to-sftp-xml-universal-mapper.md

@@ -1,1785 +1,1785 @@
----
-template_id: tpl-webhook-rubix-fulfilment-export-universal-mapper
-canonical_filename: template-webhook-rubix-fulfilment-to-sftp-xml-universal-mapper.md
-version: 2.0.0
-sdk_version: ^0.1.39
-runtime: versori
-direction: webhook
-source: fluent-rubix-workflow
-destination: sftp-xml
-entity: fulfilment
-format: xml
-logging: versori
-status: stable
-pattern: universal-mapper
-features:
-  - webhook-validation
-  - fire-and-forget
-  - background-processing
-  - xml-export
-  - sftp-integration
-  - graphql-queries
-  - universal-mapper
-  - external-mapping
-  - custom-resolvers
----
-
-# Template: Rubix Fulfilment Webhook → SFTP XML Export (UniversalMapper Pattern)
-
-**Template Version:** 2.0.0  
-**SDK Version:** `^0.1.39` - `npm install @fluentcommerce/fc-connect-sdk@^0.1.39`  
-**Last Updated:** 2025-01-25  
-**Deployment Target:** Versori Platform  
-**Mapping Pattern:** 🟢 **UNIVERSALMAPPER** (External JSON mapping + Custom resolvers)
-
-> **📖 Pattern Selection Guide:**
-> - **Use THIS template (UniversalMapper)** for: Reusable configs, multi-environment deployments, complex transformations, external mapping management
-> - **Use Inline version** for: Simple webhooks, tightly-coupled 3PL schemas, fast debugging
-> - **See also:** [template-webhook-rubix-fulfilment-to-sftp-xml-inline.md](./template-webhook-rubix-fulfilment-to-sftp-xml-inline.md)
-
-**🆕 Version 2.0.0 - Production Ready:**
-- ✅ **Fulfilment-specific template** - Focused on 3PL/WMS integration
-- ✅ **Production-ready modular structure** - Separate workflows, services, config, resolvers, types
-- ✅ **GraphQL fulfilment queries** - Fetch fulfilment + line items + order details
-- ✅ **Automatic pagination** - Handles fulfilments with 100+ items (up to 1000)
-- ✅ **External JSON mapping** - `config/fulfilment-xml-mapping.json` for XML structure
-- ✅ **UniversalMapper** - Transforms GraphQL data to XML structure with custom resolvers
-- ✅ **Custom resolvers** - Handle complex transformations (date formatting, nested data)
-- ✅ **XML generation** - Safe XML with automatic escaping via XMLBuilder
-- ✅ **SFTP upload** - Connection pooling with proper dispose()
-- ✅ **Critical fixes applied** - retailerId validation, SFTP options parameter, pagination
-- ✅ **Comprehensive documentation** - Testing, troubleshooting, monitoring
-
-**When to Use This Pattern:**
-- ✅ Complex XML structures (>20 fields)
-- ✅ XML structure changes frequently
-- ✅ Need environment-specific configurations
-- ✅ Multi-environment deployments (dev/staging/prod)
-- ✅ Reusable mapping configurations
-- ✅ Complex transformations requiring custom resolvers
-
----
-
-## Overview
-
-Receive fulfilment webhooks from Rubix workflows, query fulfilment details, transform with UniversalMapper, generate XML, and upload to 3PL/WMS SFTP server.
-
-**Pattern:**
-1. Validate webhook signature (~10-50ms)
-2. Return HTTP 200 OK immediately (fast acknowledgment)
-3. Background: Query fulfilment details → UniversalMapper transformation → Generate XML → Upload to SFTP (~2-5s)
-
-**Business Use Case:**
-- Rubix workflow sends webhook when fulfilment is created/updated
-- Handler queries fulfilment details (items, order, addresses)
-- UniversalMapper transforms GraphQL data using external JSON mapping
-- Custom resolvers handle complex transformations (dates, addresses, names)
-- Generates XML fulfillment notification for 3PL/WMS
-- Uploads to partner SFTP server for warehouse processing
-
----
-
-## STEP 1: Understand This Template
-
-### What This Template Does
-
-**Core Functionality:**
-- Receives FULFILMENT webhooks from Fluent Commerce Rubix workflows
-- Validates webhook signature for security
-- Returns fast HTTP 200 OK response (<100ms)
-- Background: Queries fulfilment via GraphQL → UniversalMapper transformation → XML generation → Uploads to SFTP
-
-**Key SDK Components:**
-- `WebhookValidationService` - Signature validation with RSA/HMAC support
-- `createClient()` - Universal client factory (auto-detects Versori context)
-- `client.graphql()` - Query fulfilment details with automatic pagination
-- `UniversalMapper` - Transform GraphQL data to XML structure using external JSON mapping
-- `XMLBuilder` - Safe XML generation with automatic escaping (after UniversalMapper)
-- `SftpDataSource` - SFTP operations with connection pooling
-- `ctx.credentials().getAccessToken()` - Retrieve SFTP credentials from Versori connection vault
-- Native Versori `log` - Structured logging from context
-
-**Pagination Support:**
-- Automatically handles fulfilments with 100+ line items
-- Uses two-query pattern: fulfilment details + paginated items
-- SDK auto-pagination: `pagination: { maxPages: 10 }` supports up to 1000 items
-- Logs pagination usage for monitoring
-
-**Critical Patterns:**
-- **Sync + Fire-and-Forget**: Fast validation, background processing
-- **Signature Validation**: Always validate `fluent-signature` or `flex.signature` headers
-- **Background Promises**: Use `.then().catch()` for error handling
-- **SFTP Credentials**: Retrieve from Versori connection vault (not activation variables)
-- **SFTP Cleanup**: Always call `dispose()` in finally blocks
-- **RetailerId Validation**: Check before `setRetailerId()` to prevent 401 errors
-- **External Mapping**: XML structure defined in JSON config file (not inline)
-- **Custom Resolvers**: Complex transformations separated into resolver functions
-
-### When to Use This Template
-
-✅ **USE THIS TEMPLATE FOR:**
-- Fulfilment created/updated webhooks from Rubix workflows
-- Export fulfilment details to 3PL/WMS via SFTP
-- Need XML format for warehouse management systems
-- Require signature validation for security
-- Need fast webhook acknowledgment + async processing
-- **Complex XML structures** requiring external configuration
-- **Multi-environment deployments** with different XML schemas
-- **Frequent XML structure changes** without code modifications
-
-❌ **DON'T USE FOR:**
-- Order webhooks (use order attribute update template)
-- Inventory webhooks (use inventory templates)
-- CSV/JSON exports (use format-specific templates)
-- Synchronous processing required (use standard http workflow)
-- **Simple XML structures** (<20 fields) - use inline mapping template instead
-
-### Business Use Cases
-
-**Use Case: 3PL Warehouse Fulfillment Notification**
-- Rubix workflow sends webhook when fulfilment moves to "ALLOCATED" status
-- Handler queries fulfilment details (items, quantities, order info)
-- UniversalMapper transforms data using external JSON mapping config
-- Custom resolvers format dates, addresses, and customer names
-- Generates XML fulfillment order for warehouse system
-- Uploads to 3PL SFTP server for pick/pack/ship processing
-- 3PL system imports XML and creates warehouse tasks
-
-**Why UniversalMapper Pattern:**
-- XML structure can be updated without code changes (edit JSON config)
-- Different XML schemas per environment (dev/staging/prod configs)
-- Complex transformations handled by reusable custom resolvers
-- Mapping configuration can be versioned and tested independently
-
----
-
-## STEP 2: Implementation Prompt for Claude Code
-
-**Copy this prompt and send to Claude Code to generate the complete implementation:**
-
-```
-Create a Versori webhook handler for Fluent Commerce Rubix FULFILMENT events with signature validation, GraphQL queries, UniversalMapper transformation, XML generation, and SFTP upload.
-
-REQUIREMENTS:
-1. Runtime: Versori Platform (HTTP webhook)
-2. Source: Rubix SendWebhook action (FULFILMENT entity type only)
-3. Destination: SFTP XML export to 3PL/WMS partner
-4. Format: XML with fulfilment details, line items, order info
-5. Entity: FULFILMENT
-
-KEY FEATURES:
-- Webhook signature validation using WebhookValidationService
-- Sync mode + fire-and-forget pattern for fast response
-- Background processing: GraphQL query → UniversalMapper transformation → XML generation → SFTP upload
-- **Automatic pagination** - Handles fulfilments with 100+ items (up to 1000 items)
-- Two-query pattern: Fulfilment details + paginated items query
-- **External JSON mapping** - `config/fulfilment-xml-mapping.json` for XML structure
-- **UniversalMapper** - Transforms GraphQL data to XML structure with custom resolvers
-- **Custom resolvers** - Handle complex transformations (date formatting, nested data)
-- Modular architecture (workflows/, services/, config/, resolvers/, types/)
-- Native Versori logging (no LoggingService)
-- SFTP cleanup with dispose() in finally blocks
-- Comprehensive error handling with SDK error types
-- RetailerId validation before setRetailerId()
-
-CRITICAL REQUIREMENTS:
-1. Webhook Mode: response: { mode: 'sync' }
-2. Signature Validation: WebhookValidationService with strictValidation: true
-3. RetailerId Validation: Check exists before client.setRetailerId()
-4. Background Processing: Fire-and-forget pattern (no await on background promise)
-5. GraphQL Queries: Two separate queries (fulfilment + items with pagination)
-6. Pagination: Use SDK automatic pagination with maxPages: 10, first: 100
-7. **External Mapping**: Use `config/fulfilment-xml-mapping.json` (NOT inline mapping)
-8. **UniversalMapper**: Transform GraphQL data to XML structure using mapping config
-9. **Custom Resolvers**: Use resolvers/fulfilment-resolvers.ts for complex transformations
-10. XML Generation: Use XMLBuilder with automatic escaping (after UniversalMapper)
-11. SFTP Upload: Include options parameter { overwrite: true, createDirectories: true }
-12. SFTP Cleanup: Always dispose() in finally block
-13. Error Handling: Import and handle DataSourceError, AuthenticationError, GraphQLError
-14. Type Safety: Use Logger, VersoriContext types (not any)
-
-SDK METHODS TO USE:
-- import { Buffer } from 'node:buffer' (CRITICAL for Versori/Deno)
-- createClient({ ...ctx, log })
-- await client.setRetailerId(retailerId) (with validation first!)
-- new WebhookValidationService({ strictValidation: true }, log)
-- await validator.validateWebhook(rawBody, headers, publicKey)
-- await client.graphql({ query, variables, pagination: { maxPages: 10 } })
-- import mappingConfig from '../config/fulfilment-xml-mapping.json' with { type: 'json' }
-- new UniversalMapper(mappingConfig, { customResolvers })
-- await mapper.map(fulfilmentData) - Transform GraphQL data to XML structure
-- new XMLBuilder({ prettyPrint: true, xmlDeclaration: true, encoding: 'UTF-8' })
-- xmlBuilder.build(mappedData, 'FulfilmentExport')
-- await ctx.credentials().getAccessToken('sftp_export_server') - Retrieve SFTP credentials from connection vault
-- Buffer.from(accessToken, 'base64').toString('utf-8') - Decode Basic Auth credentials
-- new SftpDataSource(config, log) - config includes connectionId: 'sftp_export_server'
-- await sftp.uploadFile(remotePath, buffer, { overwrite: true, createDirectories: true })
-- await sftp.dispose() (CRITICAL in finally block)
-
-FORBIDDEN PATTERNS:
-- ❌ LoggingService (use native log from context)
-- ❌ await on background processing (use fire-and-forget)
-- ❌ Inline mapping config (use external JSON file)
-- ❌ Manual object construction for XML (use UniversalMapper)
-- ❌ Missing dispose() for SFTP
-- ❌ Missing options parameter in uploadFile()
-- ❌ Missing retailerId validation before setRetailerId()
-- ❌ Storing SFTP credentials in activation variables (use Versori connection vault)
-- ❌ Using 'any' type (use Logger, VersoriContext from SDK)
-- ❌ Direct FluentClient instantiation (use createClient factory)
-- ❌ Generic error handling (use SDK error types)
-
-GRAPHQL QUERY STRUCTURE:
-
-**Single Query with Nested Items (Schema-Validated)**
-```graphql
-query GetFulfilment($id: ID!, $first: Int!, $after: String) {
-  fulfilment(id: $id) {
-    id
-    ref
-    status
-    deliveryType
-    order {
-      id
-      ref
-      customer { firstName, lastName, email }
-    }
-    toAddress {
-      name, street, street2, city, state, postcode, country
-    }
-    fromAddress {
-      name, street, street2, city, state, postcode, country
-    }
-    items(first: $first, after: $after) {
-      edges {
-        node {
-          id
-          ref
-          requestedQuantity
-          filledQuantity
-          rejectedQuantity
-          orderItem {
-            id
-            ref
-            productRef
-            product { name }
-          }
-        }
-        cursor
-      }
-      pageInfo {
-        hasNextPage
-      }
-    }
-    createdOn
-    updatedOn
-  }
-}
-```
-
-**Why Single Query?**
-- Items are nested under the fulfilment type in Fluent Commerce schema
-- Single query with `connectionPath: 'fulfilment.items'` for SDK pagination
-- SDK automatically handles pagination with `pagination: { maxPages: 10 }` config
-- More efficient than two separate queries (reduces GraphQL roundtrips)
-
-XML OUTPUT STRUCTURE:
-<FulfilmentExport>
-  <Fulfilment ref="FF-001" status="ALLOCATED">
-    <OrderRef>ORD-123</OrderRef>
-    <DeliveryType>STANDARD</DeliveryType>
-    <Customer>
-      <FirstName>John</FirstName>
-      <LastName>Smith</LastName>
-      <Email>john@example.com</Email>
-    </Customer>
-    <ToAddress>
-      <Name>John Smith</Name>
-      <Street>123 Main St</Street>
-      <City>New York</City>
-      <State>NY</State>
-      <Postcode>10001</Postcode>
-      <Country>US</Country>
-    </ToAddress>
-    <FromAddress>
-      <Name>Warehouse</Name>
-      <Street>456 Warehouse St</Street>
-      <City>Chicago</City>
-      <State>IL</State>
-      <Postcode>60601</Postcode>
-      <Country>US</Country>
-    </FromAddress>
-    <Items>
-      <Item ref="FFI-001">
-        <ProductRef>SKU-001</ProductRef>
-        <ProductName>Widget</ProductName>
-        <RequestedQuantity>2</RequestedQuantity>
-        <FilledQuantity>2</FilledQuantity>
-        <RejectedQuantity>0</RejectedQuantity>
-      </Item>
-    </Items>
-    <CreatedOn>2025-01-25T10:00:00Z</CreatedOn>
-    <UpdatedOn>2025-01-25T11:00:00Z</UpdatedOn>
-  </Fulfilment>
-</FulfilmentExport>
-
-GENERATE:
-1. package.json with dependencies
-2. index.ts (entry point - exports workflow)
-3. src/workflows/webhook/fulfilment-export-handler.ts (webhook entry)
-4. src/services/fulfilment-query.service.ts (GraphQL queries)
-5. src/services/xml-export.service.ts (UniversalMapper + XMLBuilder + SFTP upload)
-6. src/resolvers/fulfilment-resolvers.ts (Custom resolvers for XML transformations)
-7. src/config/fulfilment-xml-mapping.json (External JSON mapping configuration)
-8. src/types/fulfilment.types.ts (TypeScript interfaces)
-9. readme.md with setup instructions
-
-Ensure all code is production-ready with proper error handling, signature validation, SFTP cleanup, UniversalMapper transformation, external JSON mapping, custom resolvers, and type safety.
-```
-
----
-
-## STEP 3: Detailed Flow Documentation
-
-### Complete Processing Flow
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│ 1. RUBIX WEBHOOK RECEIVED                                   │
-│    POST https://{workspace}.versori.run/rubix-fulfilment    │
-│    Headers: fluent-signature                                │
-│    Body: { entityRef: "FF-001", entityType: "FULFILMENT" }  │
-└────────────────────┬────────────────────────────────────────┘
-                     │
-                     ▼
-┌─────────────────────────────────────────────────────────────┐
-│ 2. SIGNATURE VALIDATION (Synchronous, ~10-50ms)             │
-│    - Extract rawBody and headers                            │
-│    - Get fluentPublicKey from activation                    │
-│    - WebhookValidationService.validateWebhook()             │
-│    - Return 400 if invalid                                  │
-└────────────────────┬────────────────────────────────────────┘
-                     │
-                     ▼
-┌─────────────────────────────────────────────────────────────┐
-│ 3. PAYLOAD VALIDATION (Synchronous, ~5ms)                   │
-│    - Check entityRef exists                                 │
-│    - Check entityType === 'FULFILMENT'                      │
-│    - Check retailerId exists                                │
-│    - Return 400 if missing required fields                  │
-└────────────────────┬────────────────────────────────────────┘
-                     │
-                     ▼
-┌─────────────────────────────────────────────────────────────┐
-│ 4. HTTP 200 OK RESPONSE (Total: ~50ms)                      │
-│    - Return success immediately                             │
-│    - Background promise continues (fire-and-forget)         │
-└────────────────────┬────────────────────────────────────────┘
-                     │
-                     ▼ (Background - doesn't block response)
-┌─────────────────────────────────────────────────────────────┐
-│ 5. BACKGROUND PROCESSING (~2-5 seconds)                     │
-│    ┌─────────────────────────────────────────────────────┐  │
-│    │ 5a. Initialize Fluent Client (~100ms)               │  │
-│    │     - createClient({ ...ctx, log })                 │  │
-│    │     - Validate retailerId exists                   │  │
-│    │     - client.setRetailerId(retailerId)              │  │
-│    └─────────────────────────────────────────────────────┘  │
-│    ┌─────────────────────────────────────────────────────┐  │
-│    │ 5b. Query Fulfilment Details (~500-1500ms)          │  │
-│    │     - GraphQL query with nested fields              │  │
-│    │     - Fulfilment + items + order + addresses        │  │
-│    │     - Handle GraphQLError if query fails            │  │
-│    └─────────────────────────────────────────────────────┘  │
-│    ┌─────────────────────────────────────────────────────┐  │
-│    │ 5c. Transform with UniversalMapper (~100-200ms)      │  │
-│    │     - Load mapping config from JSON                  │  │
-│    │     - Apply SDK resolvers (trim, uppercase)          │  │
-│    │     - Apply custom resolvers (date formatting)       │  │
-│    │     - Transform GraphQL data to XML structure        │  │
-│    └─────────────────────────────────────────────────────┘  │
-│    ┌─────────────────────────────────────────────────────┐  │
-│    │ 5d. Generate XML (~50ms)                             │  │
-│    │     - XMLBuilder with mapped data                    │  │
-│    │     - XMLBuilder handles escaping automatically       │  │
-│    │     - Create Buffer from XML string                  │  │
-│    └─────────────────────────────────────────────────────┘  │
-│    ┌─────────────────────────────────────────────────────┐  │
-│    │ 5e. Upload to SFTP (~500-2000ms)                     │  │
-│    │     - Initialize SftpDataSource                        │  │
-│    │     - Upload with options parameter                  │  │
-│    │     - Handle DataSourceError if upload fails          │  │
-│    │     - ALWAYS dispose() in finally block              │  │
-│    └─────────────────────────────────────────────────────┘  │
-│    ┌─────────────────────────────────────────────────────┐  │
-│    │ 5f. Log Completion                                    │  │
-│    │     - Success: Log fulfilment ref and duration        │  │
-│    │     - Failure: Log error with category                │  │
-│    └─────────────────────────────────────────────────────┘  │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### Response Timing
-
-| Stage | Timing | Blocking |
-|-------|--------|----------|
-| **Signature Validation** | ~10-50ms | ✅ Yes (blocks response) |
-| **Payload Validation** | ~5ms | ✅ Yes (blocks response) |
-| **HTTP 200 Response** | ~50-100ms | ✅ Fast acknowledgment |
-| **GraphQL Query** | ~500-1500ms | ❌ No (background) |
-| **UniversalMapper Transformation** | ~100-200ms | ❌ No (background) |
-| **XML Generation** | ~50ms | ❌ No (background) |
-| **SFTP Upload** | ~500-2000ms | ❌ No (background) |
-| **Total Background** | ~2000-5000ms | ❌ Fire-and-forget |
-
----
-
-## STEP 4: Production Modular Structure
-
-### Complete Project Structure
-
-```
-rubix-fulfilment-export/
-├── package.json                              # Dependencies and Versori config
-├── tsconfig.json                             # TypeScript configuration
-├── readme.md                                 # Setup and deployment instructions
-├── index.ts                                  # Entry point - exports workflow
-└── src/
-    ├── workflows/
-    │   └── webhook/
-    │       └── fulfilment-export-handler.ts  # Webhook entry point
-    │
-    ├── services/
-    │   ├── fulfilment-query.service.ts       # GraphQL queries
-    │   └── xml-export.service.ts             # UniversalMapper + XMLBuilder + SFTP upload
-    │
-    ├── resolvers/
-    │   └── fulfilment-resolvers.ts           # Custom resolvers for XML transformations
-    │
-    ├── config/
-    │   └── fulfilment-xml-mapping.json       # External JSON mapping configuration
-    │
-    └── types/
-        └── fulfilment.types.ts               # TypeScript interfaces
-```
-
-**Why This Structure?**
-- ✅ **Clear separation**: Webhook handlers vs business logic
-- ✅ **Reusable services**: Query and export logic can be unit tested
-- ✅ **External config**: XML mapping changes don't require code changes
-- ✅ **Custom resolvers**: Complex transformations separated from mapping config
-- ✅ **Type safety**: TypeScript interfaces for better IDE support
-- ✅ **Scalable**: Easy to add more fulfilment webhooks or modify XML structure
-- ✅ **Testable**: Services can be mocked and tested independently
-- ✅ **Environment-specific**: Different mapping configs per environment
-
----
-
-## SDK Imports (Verified - Versori Optimized)
-
-```typescript
-// CRITICAL: Buffer import required for Versori/Deno runtime
-import { Buffer } from 'node:buffer';
-
-// FC Connect SDK imports
-import {
-  createClient,
-  WebhookValidationService,
-  UniversalMapper,
-  XMLBuilder,
-  SftpDataSource,
-  DataSourceError,
-  AuthenticationError,
-  GraphQLError,
-  type Logger,
-  type VersoriContext,
-} from '@fluentcommerce/fc-connect-sdk';
-
-// Versori platform imports
-import { webhook } from '@versori/run';
-import type { Context } from '@versori/run';
-```
-
----
-
-## Configuration
-
-### Activation Variables
-
-```json
-{
-  "fluentPublicKey": "-----BEGIN PUBLIC KEY-----...-----END PUBLIC KEY-----",
-  "sftpHost": "sftp.3pl-partner.com",
-  "sftpPort": 22,
-  "sftpRemotePath": "/incoming/fulfilments/"
-}
-```
-
-> **Important:** `sftpUsername` and `sftpPassword` are **NOT** stored in activation variables. They are securely retrieved from the `sftp_export_server` connection vault at runtime. See the SFTP Credential Management section below for details.
-
-### Connections
-
-| Connection | Description | Required |
-|------------|-------------|----------|
-| `fluent_commerce` | OAuth2 connection to Fluent Commerce | Yes |
-| `sftp_export_server` | Basic Auth connection for SFTP credentials (username/password) | Yes |
-
-## SFTP Credential Management
-
-Fetch credentials securely from Versori connection vault using `ctx.credentials().getAccessToken()`:
-
-**Benefits:**
-- ✅ Credentials stored securely in Versori vault
-- ✅ Centralized management - update in one place
-- ✅ Access control enforced by platform
-- ✅ No credentials in activation variables
-- ✅ Explicit error handling with validation
-
-### Setup Steps
-
-1. In Versori Dashboard → Connections → Add Connection
-2. Name: `sftp_export_server`
-3. Type: Basic Auth
-4. Enter SFTP username and password
-5. Save connection
-6. Reference in code: `ctx.credentials().getAccessToken('sftp_export_server')`
-
----
-
-## Complete Working Code
-
-### 1. Entry Point (index.ts)
-
-```typescript
-/**
- * Entry point - Export webhook workflow for Versori platform
- */
-
-export { rubixFulfilmentExportHandler } from './src/workflows/webhook/fulfilment-export-handler';
-```
-
-### 2. Webhook Handler (src/workflows/webhook/fulfilment-export-handler.ts)
-
-```typescript
-/**
- * Rubix Fulfilment Webhook Handler → SFTP XML Export
- *
- * Direction: Fluent Rubix Workflow (FULFILMENT) → Versori → GraphQL → UniversalMapper → XML → SFTP
- */
-
-import { Buffer } from 'node:buffer';
-import { webhook } from '@versori/run';
-import type { Context } from '@versori/run';
-import {
-  WebhookValidationService,
-  type Logger,
-} from '@fluentcommerce/fc-connect-sdk';
-import { processFulfilmentExport } from '../../services/fulfilment-query.service';
-
-export const rubixFulfilmentExportHandler = webhook('rubix-fulfilment', {
-  response: { mode: 'sync' }, // ✅ Sync mode: response sent when handler returns
-}, async (ctx: Context<any>) => {
-  const { log, activation } = ctx;
-
-  log.info('🚀 [WEBHOOK] Received Rubix fulfilment webhook', {
-    timestamp: new Date().toISOString(),
-    correlationId: activation?.id,
-  });
-
-  // ========================================
-  // STEP 1: VALIDATE SIGNATURE (Synchronous)
-  // ========================================
-
-  const publicKey = activation.getVariable('fluentPublicKey');
-  if (!publicKey) {
-    log.error('❌ [WEBHOOK] Missing fluentPublicKey configuration');
-    return {
-      status: 500,
-      body: {
-        success: false,
-        error: 'Missing fluentPublicKey configuration',
-        recommendation: 'Configure fluentPublicKey in activation variables',
-      },
-    };
-  }
-
-  // Extract raw body (Versori provides parsed data in ctx.data)
-  const rawBody = typeof ctx.data === 'string' ? ctx.data : JSON.stringify(ctx.data);
-
-  // Extract headers from request (ctx.request() is a function call)
-  const req = ctx.request?.() || {};
-  const headersObj = req.headers || {};
-  const headers = headersObj instanceof Headers
-    ? Object.fromEntries(headersObj.entries())
-    : headersObj;
-
-  log.info('🔍 [WEBHOOK] Validating webhook signature');
-
-  const validator = new WebhookValidationService({ strictValidation: true }, log as Logger);
-  const result = await validator.validateWebhook(rawBody, headers, publicKey);
-
-  if (!result.isValid) {
-    log.error('❌ [WEBHOOK] Invalid webhook signature', {
-      error: result.error,
-      algorithm: result.algorithm,
-    });
-    return {
-      status: 401,
-      body: {
-        success: false,
-        error: 'Invalid webhook signature',
-        recommendation: 'Verify fluentPublicKey matches Fluent environment',
-      },
-    };
-  }
-
-  log.info('✅ [WEBHOOK] Signature validated successfully', {
-    algorithm: result.algorithm,
-  });
-
-  // ========================================
-  // STEP 2: VALIDATE PAYLOAD (Synchronous)
-  // ========================================
-
-  const payload = typeof ctx.data === 'string' ? JSON.parse(ctx.data) : ctx.data;
-  const { entityRef, entityType, retailerId } = payload;
-
-  if (!entityRef) {
-    log.error('❌ [WEBHOOK] Missing entityRef in payload', { payload });
-    return {
-      status: 400,
-      body: {
-        success: false,
-        error: 'Missing entityRef in payload',
-        recommendation: 'Ensure Rubix SendWebhook includes fulfilment ref',
-      },
-    };
-  }
-
-  if (entityType !== 'FULFILMENT') {
-    log.error('❌ [WEBHOOK] Invalid entity type', { entityType, expected: 'FULFILMENT' });
-    return {
-      status: 400,
-      body: {
-        success: false,
-        error: `Invalid entity type: ${entityType}. Expected: FULFILMENT`,
-        recommendation: 'Use order-attribute-update template for ORDER webhooks',
-      },
-    };
-  }
-
-  if (!retailerId) {
-    log.error('❌ [WEBHOOK] Missing retailerId in payload', { payload });
-    return {
-      status: 400,
-      body: {
-        success: false,
-        error: 'Missing retailerId in payload',
-        recommendation: 'Ensure Rubix SendWebhook includes retailerId',
-      },
-    };
-  }
-
-  log.info('✅ [WEBHOOK] Validation passed, starting background processing', {
-    entityRef,
-    entityType,
-    retailerId,
-  });
-
-  // ========================================
-  // STEP 3: FIRE-AND-FORGET BACKGROUND PROCESSING
-  // ========================================
-
-  // ✅ Fire-and-forget: Start background processing WITHOUT await
-  // The promise continues execution after we return the response
-  processFulfilmentExport(ctx, payload)
-    .then(() => {
-      log.info('✅ [BACKGROUND] Fulfilment exported successfully', {
-        fulfilmentRef: entityRef,
-      });
-    })
-    .catch((error: unknown) => {
-      const errorMessage = error instanceof Error ? error.message : String(error);
-      log.error('❌ [BACKGROUND] Fulfilment export failed', {
-        fulfilmentRef: entityRef,
-        error: errorMessage,
-        stack: error instanceof Error ? error.stack : undefined,
-        errorType: error instanceof Error ? error.constructor.name : typeof error,
-      });
-    });
-
-  // Return immediately (response sent with this return value)
-  return {
-    status: 200,
-    body: {
-      success: true,
-      entityType,
-      fulfilmentRef: entityRef,
-      message: 'Webhook validated and export started in background',
-      timestamp: new Date().toISOString(),
-      correlationId: activation?.id,
-    },
-  };
-});
-```
-
-### 3. Fulfilment Query Service (src/services/fulfilment-query.service.ts)
-
-```typescript
-/**
- * Fulfilment Query Service
- *
- * Handles GraphQL queries for fulfilment details and orchestrates XML export
- */
-
-import {
-  createClient,
-  DataSourceError,
-  AuthenticationError,
-  GraphQLError,
-  type Logger,
-  type VersoriContext,
-} from '@fluentcommerce/fc-connect-sdk';
-import { exportFulfilmentToSFTP } from './xml-export.service';
-import type { RubixFulfilmentPayload, FulfilmentData } from '../types/fulfilment.types';
-
-// Single query with nested items (schema-validated structure)
-const FULFILMENT_QUERY = `
-  query GetFulfilment($id: ID!, $first: Int!, $after: String) {
-    fulfilment(id: $id) {
-      id
-      ref
-      status
-      deliveryType
-      order {
-        id
-        ref
-        customer {
-          firstName
-          lastName
-          email
-        }
-      }
-      toAddress {
-        name
-        street
-        street2
-        city
-        state
-        postcode
-        country
-      }
-      fromAddress {
-        name
-        street
-        street2
-        city
-        state
-        postcode
-        country
-      }
-      items(first: $first, after: $after) {
-        edges {
-          node {
-            id
-            ref
-            requestedQuantity
-            filledQuantity
-            rejectedQuantity
-            orderItem {
-              id
-              ref
-              productRef
-              product {
-                name
-              }
-            }
-          }
-          cursor
-        }
-        pageInfo {
-          hasNextPage
-        }
-      }
-      createdOn
-      updatedOn
-    }
-  }
-`;
-
-export async function processFulfilmentExport(
-  ctx: VersoriContext,
-  payload: RubixFulfilmentPayload
-): Promise<void> {
-  const log = ctx.log as Logger;
-  const { entityRef, retailerId } = payload;
-
-  const processingStartTime = Date.now();
-
-  log.info('🔄 [BACKGROUND] Starting fulfilment export', {
-    timestamp: new Date().toISOString(),
-    fulfilmentRef: entityRef,
-  });
-
-  try {
-    // ========================================
-    // STEP 1: VALIDATE RETAILER ID
-    // ========================================
-
-    if (!retailerId) {
-      log.error('❌ [BACKGROUND] Missing retailerId in payload', {
-        fulfilmentRef: entityRef,
-      });
-      throw new Error('retailerId is required for GraphQL operations');
-    }
-
-    // ========================================
-    // STEP 2: INITIALIZE FLUENT CLIENT
-    // ========================================
-
-    const client = await createClient({ ...ctx, log });
-    await client.setRetailerId(retailerId);
-
-    // ========================================
-    // STEP 3: QUERY FULFILMENT WITH NESTED ITEMS
-    // ========================================
-
-    log.info('🔍 [BACKGROUND] Querying fulfilment with items', { fulfilmentRef: entityRef });
-
-    const result = await client.graphql({
-      query: FULFILMENT_QUERY,
-      variables: {
-        id: entityRef,  // ✅ Use 'id' parameter (schema-validated)
-        first: 100,
-      },
-      pagination: {
-        connectionPath: 'fulfilment.items',  // ✅ Nested connection pagination
-        maxPages: 10, // Handles up to 1000 items (100 per page × 10 pages)
-      },
-    });
-
-    const fulfilmentData = result.data?.fulfilment as FulfilmentData | null;
-
-    if (!fulfilmentData) {
-      log.error('❌ [BACKGROUND] Fulfilment not found', { fulfilmentRef: entityRef });
-      throw new Error(`Fulfilment not found: ${entityRef}`);
-    }
-
-    const itemCount = fulfilmentData.items?.edges?.length || 0;
-
-    log.info('✅ [BACKGROUND] Fulfilment and items queried successfully', {
-      fulfilmentRef: fulfilmentData.ref,
-      status: fulfilmentData.status,
-      itemCount,
-      orderRef: fulfilmentData.order?.ref,
-      paginationUsed: result.metadata?.totalPages > 1,
-    });
-
-    // ========================================
-    // STEP 4: EXPORT TO SFTP
-    // ========================================
-
-    await exportFulfilmentToSFTP(ctx, fulfilmentData, log);
-
-    const duration = Date.now() - processingStartTime;
-    log.info('✅ [BACKGROUND] Fulfilment export completed', {
-      fulfilmentRef: entityRef,
-      duration: `${duration}ms`,
-    });
-  } catch (error: unknown) {
-    let errorMessage = 'Unknown error';
-    let recommendation: string | undefined;
-    let errorCategory = 'UNKNOWN';
-
-    if (error instanceof GraphQLError) {
-      errorMessage = error.message;
-      recommendation = 'Review GraphQL query syntax and field permissions';
-      errorCategory = 'GRAPHQL';
-    } else if (error instanceof AuthenticationError) {
-      errorMessage = error.message;
-      recommendation = 'Verify Fluent Commerce credentials and retailerId';
-      errorCategory = 'AUTHENTICATION';
-    } else if (error instanceof DataSourceError) {
-      errorMessage = error.message;
-      recommendation = 'Check SFTP configuration and connectivity';
-      errorCategory = 'DATA_SOURCE';
-    } else if (error instanceof Error) {
-      errorMessage = error.message;
-    } else {
-      errorMessage = String(error);
-    }
-
-    log.error('❌ [BACKGROUND] Fulfilment export failed', {
-      fulfilmentRef: entityRef,
-      error: errorMessage,
-      errorCategory,
-      recommendation,
-      stack: error instanceof Error ? error.stack : undefined,
-      errorType: error instanceof Error ? error.constructor.name : typeof error,
-    });
-
-    throw error;
-  }
-}
-```
-
-### 4. XML Export Service (src/services/xml-export.service.ts)
-
-```typescript
-/**
- * XML Export Service
- *
- * Handles XML generation and SFTP upload for fulfilment exports
- * Uses UniversalMapper with external JSON mapping configuration
- */
-
-import { Buffer } from 'node:buffer';
-import {
-  UniversalMapper,
-  XMLBuilder,
-  SftpDataSource,
-  type Logger,
-  type VersoriContext,
-} from '@fluentcommerce/fc-connect-sdk';
-import type { FulfilmentData } from '../types/fulfilment.types';
-import mappingConfig from '../config/fulfilment-xml-mapping.json' with { type: 'json' };
-import { customResolvers } from '../resolvers/fulfilment-resolvers';
-
-export async function exportFulfilmentToSFTP(
-  ctx: VersoriContext,
-  fulfilmentData: FulfilmentData,
-  log: Logger
-): Promise<void> {
-  const { activation } = ctx;
-
-  log.info('📝 [BACKGROUND] Generating XML for fulfilment', {
-    fulfilmentRef: fulfilmentData.ref,
-  });
-
-  // ========================================
-  // STEP 1: TRANSFORM DATA WITH UNIVERSALMAPPER
-  // ========================================
-
-  log.info('🔄 [BACKGROUND] Transforming fulfilment data with UniversalMapper', {
-    fulfilmentRef: fulfilmentData.ref,
-  });
-
-  const mapper = new UniversalMapper(mappingConfig, {
-    customResolvers,
-  });
-
-  const mappingResult = await mapper.map(fulfilmentData);
-
-  if (!mappingResult.success) {
-    log.error('❌ [BACKGROUND] Mapping failed', {
-      errors: mappingResult.errors,
-      fulfilmentRef: fulfilmentData.ref,
-    });
-    throw new Error(`Mapping failed: ${mappingResult.errors?.join(', ')}`);
-  }
-
-  const mappedData = mappingResult.data;
-
-  log.info('✅ [BACKGROUND] Data transformed successfully', {
-    fulfilmentRef: fulfilmentData.ref,
-    fieldCount: Object.keys(mappedData).length,
-  });
-
-  // ========================================
-  // STEP 2: GENERATE XML WITH XMLBUILDER
-  // ========================================
-
-  const xmlBuilder = new XMLBuilder({
-    prettyPrint: true,
-    xmlDeclaration: true,
-    encoding: 'UTF-8',
-  });
-
-  const xmlString = xmlBuilder.build(mappedData, 'FulfilmentExport');
-  const xmlBuffer = Buffer.from(xmlString, 'utf8');
-
-  log.info('✅ [BACKGROUND] XML generated successfully', {
-    fulfilmentRef: fulfilmentData.ref,
-    xmlSizeBytes: xmlBuffer.length,
-    xmlSizeKB: Math.round(xmlBuffer.length / 1024),
-  });
-
-  // ========================================
-  // STEP 3: UPLOAD TO SFTP
-  // ========================================
-
-  log.info('📤 [BACKGROUND] Preparing SFTP upload', {
-    fulfilmentRef: fulfilmentData.ref,
-  });
-
-  // ========================================
-  // SFTP CREDENTIAL RETRIEVAL
-  // ========================================
-
-  /**
-   * Retrieve SFTP credentials from connection configuration
-   * 
-   * Connection Name: 'sftp_export_server' (must match the connection name in Versori UI)
-   * Auth Type: Basic Authentication (username + password)
-   */
-  log.info('🔐 [BACKGROUND] Retrieving SFTP credentials from connection configuration');
-
-  let sftpUsername: string;
-  let sftpPassword: string;
-
-  try {
-    // Retrieve credentials from the 'sftp_export_server' connection
-    const sftpCred = await ctx.credentials().getAccessToken('sftp_export_server');
-
-    if (!sftpCred?.accessToken) {
-      throw new Error('No SFTP credentials found in connection configuration');
-    }
-
-    // Decode base64 accessToken to get "username:password"
-    const rawBasicAuth = Buffer.from(sftpCred.accessToken, 'base64').toString('utf-8');
-
-    // Split on ':' to extract username and password
-    const parts = rawBasicAuth.split(':');
-
-    if (parts.length !== 2) {
-      throw new Error('Invalid SFTP credential format - expected username:password');
-    }
-
-    sftpUsername = parts[0];
-    sftpPassword = parts[1];
-
-    log.info('✅ [BACKGROUND] SFTP credentials retrieved successfully', {
-      hasUsername: !!sftpUsername,
-      hasPassword: !!sftpPassword,
-      usernameLength: sftpUsername.length,
-      passwordLength: sftpPassword.length,
-    });
-  } catch (error: any) {
-    log.error('❌ [BACKGROUND] Failed to retrieve SFTP credentials', {
-      message: error instanceof Error ? error.message : String(error),
-      stack: error instanceof Error ? error.stack : undefined,
-      errorType: error instanceof Error ? error.constructor.name : 'Error',
-      recommendation: 'Please ensure the SFTP connection "sftp_export_server" is configured in the Connections section with Basic Authentication (username and password)',
-    });
-    throw new Error(
-      `Failed to retrieve SFTP credentials from connection configuration: ${error instanceof Error ? error.message : String(error)}. ` +
-      'Please ensure the SFTP connection is configured in the Connections section with Basic Authentication (username and password)'
-    );
-  }
-
-  // Get SFTP configuration from activation variables
-  const sftpHost = activation.getVariable('sftpHost');
-  const sftpPort = parseInt(activation.getVariable('sftpPort') || '22', 10);
-  const sftpRemotePath = activation.getVariable('sftpRemotePath') || '/incoming/fulfilments/';
-
-  if (!sftpHost) {
-    log.error('⚠️ [BACKGROUND] SFTP configuration missing', {
-      recommendation: 'Configure sftpHost activation variable',
-      fulfilmentRef: fulfilmentData.ref,
-    });
-    throw new Error('SFTP configuration missing: sftpHost is required');
-  }
-
-  const sftpConfig = {
-    type: 'SFTP_XML' as const,
-    connectionId: 'sftp_export_server',
-    name: 'Fulfilment XML Export',
-    settings: {
-      host: sftpHost,
-      port: sftpPort,
-      username: sftpUsername,
-      password: sftpPassword,
-    },
-  };
-
-  const sftp = new SftpDataSource(sftpConfig, log);
-
-  try {
-    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
-    const fileName = `fulfilment-${fulfilmentData.ref}-${timestamp}.xml`;
-    const remoteFilePath = `${sftpRemotePath}${fileName}`;
-
-    // ✅ CRITICAL FIX: Include options parameter
-    await sftp.uploadFile(remoteFilePath, xmlBuffer, {
-      overwrite: true,
-      createDirectories: true,
-    });
-
-    log.info('✅ [BACKGROUND] Fulfilment XML exported to SFTP', {
-      fulfilmentRef: fulfilmentData.ref,
-      remoteFilePath,
-      status: fulfilmentData.status,
-      fileSizeKB: Math.round(xmlBuffer.length / 1024),
-    });
-  } finally {
-    // ✅ CRITICAL: Always dispose SFTP connection
-    await sftp.dispose();
-    log.info('🔌 [BACKGROUND] SFTP connection disposed');
-  }
-}
-```
-
-### 5. Mapping Configuration (src/config/fulfilment-xml-mapping.json)
-
-**IMPORTANT: Array Mapping Patterns**
-
-The SDK supports **two patterns** for GraphQL edges/nodes arrays. Here's exactly what happens with each:
-
-## Step-by-Step: What Each Pattern Does
-
-### Input Data (GraphQL Response)
-```javascript
-{
-  items: {
-    edges: [
-      { node: { ref: "FFI-001", requestedQuantity: 2, orderItem: { productRef: "SKU-001" } } },
-      { node: { ref: "FFI-002", requestedQuantity: 1, orderItem: { productRef: "SKU-002" } } }
-    ]
-  }
-}
-```
-
----
-
-### Pattern 1: `source: "items.edges[*].node"` + `Item` wrapper
-
-**Config:**
-```json
-"Items": {
-  "source": "items.edges[*].node",
-  "isArray": true,
-  "fields": {
-    "Item": {
-      "fields": {
-        "@ref": { "source": "ref" },
-        "ProductRef": { "source": "orderItem.productRef" }
-      }
-    }
-  }
-}
-```
-
-**Step 1:** SDK extracts `items.edges[*].node`
-- Splits on `[*]` → `arrayPath="items.edges"`, `nodePath="node"`
-- Gets `items.edges` array: `[{ node: {...} }, { node: {...} }]`
-- Extracts `.node` from each → `[{ ref: "FFI-001", ... }, { ref: "FFI-002", ... }]`
-
-**Step 2:** For each node, maps nested `Item` fields
-- Node 1: `{ ref: "FFI-001", orderItem: { productRef: "SKU-001" } }`
-- Maps `"@ref": { "source": "ref" }` → extracts `node.ref` = `"FFI-001"`
-- Maps `"ProductRef": { "source": "orderItem.productRef" }` → extracts `node.orderItem.productRef` = `"SKU-001"`
-- Result: `{ Item: { "@ref": "FFI-001", "ProductRef": "SKU-001" } }`
-
-**Step 3:** Final mapped data
-```javascript
-{
-  Items: [
-    { Item: { "@ref": "FFI-001", "ProductRef": "SKU-001" } },
-    { Item: { "@ref": "FFI-002", "ProductRef": "SKU-002" } }
-  ]
-}
-```
-
-**Step 4:** XMLBuilder output
-```xml
-<Items>
-  <Item ref="FFI-001">
-    <ProductRef>SKU-001</ProductRef>
-  </Item>
-  <Item ref="FFI-002">
-    <ProductRef>SKU-002</ProductRef>
-  </Item>
-</Items>
-```
-
----
-
-### Pattern 2: `source: "items.edges"` + `Item` wrapper
-
-**Config:**
-```json
-"Items": {
-  "source": "items.edges",
-  "isArray": true,
-  "fields": {
-    "Item": {
-      "fields": {
-        "@ref": { "source": "node.ref" },
-        "ProductRef": { "source": "node.orderItem.productRef" }
-      }
-    }
-  }
-}
-```
-
-**Step 1:** SDK extracts `items.edges`
-- Gets array directly: `[{ node: {...} }, { node: {...} }]` (edges array)
-
-**Step 2:** For each edge, maps nested `Item` fields
-- Edge 1: `{ node: { ref: "FFI-001", orderItem: { productRef: "SKU-001" } } }`
-- Maps `"@ref": { "source": "node.ref" }` → extracts `edge.node.ref` = `"FFI-001"`
-- Maps `"ProductRef": { "source": "node.orderItem.productRef" }` → extracts `edge.node.orderItem.productRef` = `"SKU-001"`
-- Result: `{ Item: { "@ref": "FFI-001", "ProductRef": "SKU-001" } }`
-
-**Step 3:** Final mapped data (IDENTICAL to Pattern 1)
-```javascript
-{
-  Items: [
-    { Item: { "@ref": "FFI-001", "ProductRef": "SKU-001" } },
-    { Item: { "@ref": "FFI-002", "ProductRef": "SKU-002" } }
-  ]
-}
-```
-
-**Step 4:** XMLBuilder output (IDENTICAL to Pattern 1)
-```xml
-<Items>
-  <Item ref="FFI-001">
-    <ProductRef>SKU-001</ProductRef>
-  </Item>
-  <Item ref="FFI-002">
-    <ProductRef>SKU-002</ProductRef>
-  </Item>
-</Items>
-```
-
----
-
-## Key Differences
-
-| Aspect | Pattern 1 (`edges[*].node`) | Pattern 2 (`edges`) |
-|--------|----------------------------|---------------------|
-| **What SDK extracts** | Nodes directly: `[{ ref: "..." }, ...]` | Edges: `[{ node: {...} }, ...]` |
-| **Field paths** | `"ref"` (direct) | `"node.ref"` (need prefix) |
-| **Mapped data** | ✅ Same | ✅ Same |
-| **XML output** | ✅ Same (with `Item` wrapper) | ✅ Same (with `Item` wrapper) |
-| **Without `Item` wrapper** | ❌ Wrong XML | ❌ Wrong XML |
-
-## Why Both Work
-
-**Both patterns produce identical results** because:
-1. Pattern 1 extracts nodes first, then maps fields from nodes
-2. Pattern 2 extracts edges, then maps fields from `edge.node`
-3. Both end up with the same mapped data structure
-4. XMLBuilder converts the same structure to identical XML
-
-**The `Item` wrapper is required** for both patterns to create `<Item>` elements instead of flat `<@ref>` elements.
-
-**Recommendation:** Use Pattern 1 (`edges[*].node`) - cleaner field paths, less typing.
-
----
-
-**Full Mapping Configuration:**
-
-```json
-{
-  "name": "fulfilment-xml-mapping",
-  "version": "1.0.0",
-  "description": "Fluent Fulfilment → XML Export Mapping for 3PL/WMS",
-  "fields": {
-    "Fulfilment": {
-      "fields": {
-        "@ref": {
-          "source": "ref",
-          "required": true,
-          "resolver": "sdk.trim"
-        },
-        "@status": {
-          "source": "status",
-          "required": true,
-          "resolver": "sdk.uppercase"
-        },
-        "OrderRef": {
-          "source": "order.ref",
-          "required": true,
-          "resolver": "sdk.trim"
-        },
-        "DeliveryType": {
-          "source": "deliveryType",
-          "required": false,
-          "resolver": "sdk.trim"
-        },
-        "Customer": {
-          "source": "order.customer",
-          "fields": {
-            "FirstName": {
-              "source": "firstName",
-              "required": false,
-              "resolver": "sdk.trim"
-            },
-            "LastName": {
-              "source": "lastName",
-              "required": false,
-              "resolver": "sdk.trim"
-            },
-            "Email": {
-              "source": "email",
-              "required": false,
-              "resolver": "sdk.trim"
-            }
-          }
-        },
-        "ToAddress": {
-          "source": "toAddress",
-          "fields": {
-            "Name": { "source": "name", "required": false, "resolver": "sdk.trim" },
-            "Street": { "source": "street", "required": false, "resolver": "sdk.trim" },
-            "Street2": { "source": "street2", "required": false, "resolver": "sdk.trim" },
-            "City": { "source": "city", "required": false, "resolver": "sdk.trim" },
-            "State": { "source": "state", "required": false, "resolver": "sdk.trim" },
-            "Postcode": { "source": "postcode", "required": false, "resolver": "sdk.trim" },
-            "Country": { "source": "country", "required": false, "resolver": "sdk.trim" }
-          }
-        },
-        "FromAddress": {
-          "source": "fromAddress",
-          "fields": {
-            "Name": { "source": "name", "required": false, "resolver": "sdk.trim" },
-            "Street": { "source": "street", "required": false, "resolver": "sdk.trim" },
-            "Street2": { "source": "street2", "required": false, "resolver": "sdk.trim" },
-            "City": { "source": "city", "required": false, "resolver": "sdk.trim" },
-            "State": { "source": "state", "required": false, "resolver": "sdk.trim" },
-            "Postcode": { "source": "postcode", "required": false, "resolver": "sdk.trim" },
-            "Country": { "source": "country", "required": false, "resolver": "sdk.trim" }
-          }
-        },
-        "Items": {
-          "source": "items.edges[*].node",
-          "isArray": true,
-          "fields": {
-            "Item": {
-              "fields": {
-                "@ref": {
-                  "source": "ref",
-                  "required": true,
-                  "resolver": "sdk.trim"
-                },
-                "ProductRef": {
-                  "source": "orderItem.productRef",
-                  "required": false,
-                  "resolver": "sdk.trim"
-                },
-                "ProductName": {
-                  "source": "orderItem.product.name",
-                  "required": false,
-                  "resolver": "sdk.trim"
-                },
-                "RequestedQuantity": {
-                  "source": "requestedQuantity",
-                  "required": false,
-                  "resolver": "sdk.parseInt"
-                },
-                "FilledQuantity": {
-                  "source": "filledQuantity",
-                  "required": true,
-                  "resolver": "sdk.parseInt"
-                },
-                "RejectedQuantity": {
-                  "source": "rejectedQuantity",
-                  "required": true,
-                  "resolver": "sdk.parseInt"
-                }
-              }
-            }
-          }
-        },
-        "CreatedOn": {
-          "source": "createdOn",
-          "required": true,
-          "resolver": "custom.formatISO8601"
-        },
-        "UpdatedOn": {
-          "source": "updatedOn",
-          "required": true,
-          "resolver": "custom.formatISO8601"
-        }
-      }
-    }
-  }
-}
-```
-
-### 6. Custom Resolvers (src/resolvers/fulfilment-resolvers.ts)
-
-```typescript
-/**
- * Custom Resolvers for Fulfilment XML Mapping
- *
- * Handles complex transformations that SDK resolvers don't cover
- */
-
-export const customResolvers = {
-  /**
-   * Format ISO 8601 date string (ensures consistent format)
-   * 
-   * Resolver signature: (value, sourceData, config, helpers) => any | Promise<any>
-   */
-  'custom.formatISO8601': (
-    value: any,
-    sourceData: any,
-    config: any,
-    helpers: any
-  ): string => {
-    if (!value) return '';
-    
-    if (value instanceof Date) {
-      return value.toISOString();
-    }
-    
-    if (typeof value === 'string') {
-      // If already ISO format, return as-is
-      if (value.includes('T') && value.includes('Z')) {
-        return value;
-      }
-      // Try to parse and format
-      const date = new Date(value);
-      if (!isNaN(date.getTime())) {
-        return date.toISOString();
-      }
-    }
-    
-    return String(value || '');
-  },
-
-  /**
-   * Format address line (handles missing fields gracefully)
-   */
-  'custom.formatAddressLine': (address: any): string => {
-    if (!address) return '';
-    
-    const parts = [
-      address.street1,
-      address.street2,
-      address.city,
-      address.state,
-      address.postcode,
-      address.country,
-    ].filter(Boolean);
-    
-    return parts.join(', ');
-  },
-
-  /**
-   * Format customer full name
-   */
-  'custom.formatCustomerName': (customer: any): string => {
-    if (!customer) return '';
-    
-    const parts = [customer.firstName, customer.lastName].filter(Boolean);
-    return parts.join(' ') || '';
-  },
-};
-```
-
-### 7. Type Definitions (src/types/fulfilment.types.ts)
-
-```typescript
-/**
- * Type definitions for Rubix fulfilment webhooks and GraphQL responses
- */
-
-export interface RubixFulfilmentPayload {
-  id: string;
-  name: string;
-  accountId: string;
-  retailerId: string;
-  entityRef: string;
-  entityType: 'FULFILMENT';
-  entityStatus?: string;
-  type: 'NORMAL' | string;
-  rootEntityId?: string;
-  rootEntityType?: string;
-  rootEntityRef?: string;
-  attributes?: Record<string, any>;
-  context?: Record<string, any>;
-}
-
-export interface FulfilmentData {
-  id: string;
-  ref: string;
-  status: string;
-  deliveryType: string;
-  order?: {
-    id: string;
-    ref: string;
-    customer?: {
-      firstName: string;
-      lastName: string;
-      email: string;
-    };
-  };
-  items?: {
-    edges?: Array<{
-      node: {
-        id: string;
-        ref: string;
-        requestedQuantity?: number;
-        filledQuantity: number;
-        rejectedQuantity: number;
-        orderItem?: {
-          id: string;
-          ref: string;
-          productRef: string;
-          product?: {
-            name: string;
-          };
-        };
-      };
-    }>;
-  };
-  toAddress?: {
-    name?: string;
-    street?: string;
-    street2?: string;
-    city?: string;
-    state?: string;
-    postcode?: string;
-    country?: string;
-  };
-  fromAddress?: {
-    name?: string;
-    street?: string;
-    street2?: string;
-    city?: string;
-    state?: string;
-    postcode?: string;
-    country?: string;
-  };
-  createdOn: string;
-  updatedOn: string;
-}
-```
-
-### 8. Package Configuration (package.json)
-
-```json
-{
-  "name": "rubix-fulfilment-export",
-  "version": "2.0.0",
-  "description": "Rubix fulfilment webhook handler with SFTP XML export (UniversalMapper pattern)",
-  "type": "module",
-  "main": "index.ts",
-  "scripts": {
-    "dev": "versori dev",
-    "build": "versori build",
-    "deploy": "versori deploy",
-    "test": "jest",
-    "lint": "eslint src/**/*.ts"
-  },
-  "dependencies": {
-    "@fluentcommerce/fc-connect-sdk": "^0.1.39",
-    "@versori/run": "latest"
-  },
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "typescript": "^5.0.0",
-    "jest": "^29.0.0",
-    "@types/jest": "^29.0.0",
-    "eslint": "^8.0.0"
-  }
-}
-```
-
----
-
-## Key Patterns Explained
-
-### Pattern 1: External JSON Mapping Configuration
-
-```typescript
-// ✅ CORRECT - External JSON mapping
-import mappingConfig from '../config/fulfilment-xml-mapping.json' with { type: 'json' };
-const mapper = new UniversalMapper(mappingConfig, { customResolvers });
-const result = await mapper.map(fulfilmentData);
-
-// ❌ WRONG - Inline mapping (use inline template instead)
-const xmlData = {
-  Fulfilment: {
-    '@ref': fulfilmentData.ref,
-    // ... 50+ lines of inline mapping
-  }
-};
-```
-
-**Why:** External JSON allows XML structure changes without code modifications, supports environment-specific configs, and enables independent testing.
-
-### Pattern 2: Custom Resolvers for Complex Transformations
-
-```typescript
-// ✅ CORRECT - Custom resolver for date formatting
-export const customResolvers = {
-  'custom.formatISO8601': (value: string | Date | null | undefined): string => {
-    if (value instanceof Date) return value.toISOString();
-    // ... handle string dates
-  },
-};
-
-// In mapping config:
-{
-  "CreatedOn": {
-    "source": "createdOn",
-    "resolver": "custom.formatISO8601"
-  }
-}
-
-// ❌ WRONG - Inline transformation logic
-const createdOn = new Date(fulfilmentData.createdOn).toISOString();
-```
-
-**Why:** Custom resolvers are reusable, testable, and keep mapping config clean.
-
-### Pattern 3: UniversalMapper Before XMLBuilder
-
-```typescript
-// ✅ CORRECT - Transform first, then build XML
-const mapper = new UniversalMapper(mappingConfig, { customResolvers });
-const mappingResult = await mapper.map(fulfilmentData);
-const xmlString = xmlBuilder.build(mappingResult.data, 'FulfilmentExport');
-
-// ❌ WRONG - Build XML directly from GraphQL data
-const xmlString = xmlBuilder.build(fulfilmentData, 'FulfilmentExport');
-```
-
-**Why:** UniversalMapper handles transformations, validations, and field mapping before XML generation.
-
----
-
-## Testing
-
-### 1. Unit Tests
-
-```typescript
-// src/services/__tests__/xml-export.test.ts
-import { exportFulfilmentToSFTP } from '../xml-export.service';
-import mappingConfig from '../../config/fulfilment-xml-mapping.json' with { type: 'json' };
-
-describe('XML Export Service', () => {
-  test('should transform fulfilment data with UniversalMapper', async () => {
-    const mockFulfilmentData = {
-      ref: 'FF-001',
-      status: 'ALLOCATED',
-      // ... test data
-    };
-
-    // Verify mapping config is loaded
-    expect(mappingConfig).toBeDefined();
-    expect(mappingConfig.fields.Fulfilment).toBeDefined();
-  });
-});
-```
-
-### 2. Mapping Config Validation
-
-```typescript
-// src/config/__tests__/mapping-config.test.ts
-import mappingConfig from '../fulfilment-xml-mapping.json' with { type: 'json' };
-
-describe('Mapping Configuration', () => {
-  test('should have valid structure', () => {
-    expect(mappingConfig.name).toBe('fulfilment-xml-mapping');
-    expect(mappingConfig.fields).toBeDefined();
-    expect(mappingConfig.fields.Fulfilment).toBeDefined();
-  });
-
-  test('should use custom resolvers for dates', () => {
-    const createdOnField = mappingConfig.fields.Fulfilment.fields.CreatedOn;
-    expect(createdOnField.resolver).toBe('custom.formatISO8601');
-  });
-});
-```
-
----
-
-## Production Checklist
-
-- [ ] Configure `fluentPublicKey` activation variable
-- [ ] Configure Fluent Commerce connection in Versori
-- [ ] Configure `sftp_export_server` connection in Versori (Basic Auth with username/password)
-- [ ] Set SFTP activation variables (host, port, remotePath)
-- [ ] Verify SFTP remote path exists and is writable
-- [ ] Create Rubix workflow with SendWebhook action (FULFILMENT events)
-- [ ] Build Event payload with entityRef, entityType, retailerId
-- [ ] **Review and customize `config/fulfilment-xml-mapping.json`** for your 3PL schema
-- [ ] **Add custom resolvers** if needed for complex transformations
-- [ ] Test webhook signature validation
-- [ ] Test GraphQL query with real fulfilment ref
-- [ ] **Test UniversalMapper transformation** with sample data
-- [ ] **Test with large fulfilment (>100 items)** - Verify pagination works correctly
-- [ ] Test XML generation with special characters
-- [ ] Test SFTP upload and verify file on server
-- [ ] Test error scenarios (invalid signature, missing retailerId, SFTP failure)
-- [ ] Monitor response times (<100ms for validation)
-- [ ] Set up alerts for webhook/export failures
-- [ ] Document 3PL partner SFTP requirements
-- [ ] Test SFTP connection cleanup (check logs for dispose)
-- [ ] Verify pagination logs show correct item counts
-- [ ] **Version control mapping config** (track changes to XML structure)
-
----
-
-## Troubleshooting Guide
-
-| Issue | Cause | Solution |
-|-------|-------|----------|
-| "Invalid webhook signature" | Wrong public key | Verify fluentPublicKey matches Fluent environment |
-| "Missing retailerId" | Rubix payload incomplete | Add retailerId to Rubix Event payload builder |
-| "Fulfilment not found" | Invalid ref or permissions | Verify fulfilment exists and user has query permissions |
-| "Mapping failed" | Invalid mapping config | Validate JSON syntax and field paths in mapping config |
-| "Custom resolver not found" | Resolver not registered | Ensure customResolvers object includes all resolvers used in mapping |
-| "SFTP upload failed" | Connection/credentials | Test SFTP manually, verify credentials in connection and path |
-| "Failed to retrieve SFTP credentials" | Connection not configured | Ensure `sftp_export_server` connection exists with Basic Auth |
-| "SFTP connection pool exhausted" | Missing dispose() | Verify dispose() is in finally block |
-| "GraphQL query timeout" | Large dataset | Check pagination logs - pagination handles up to 1000 items |
-| "Missing items in XML" | Fulfilment >1000 items | Increase maxPages limit or implement chunked export |
-| "XML structure mismatch" | Mapping config outdated | Update `config/fulfilment-xml-mapping.json` to match 3PL schema |
-
----
-
-## Monitoring & Alerting
-
-### Success Response
-
-```json
-{
-  "success": true,
-  "entityType": "FULFILMENT",
-  "fulfilmentRef": "FF-001",
-  "message": "Webhook validated and export started in background",
-  "timestamp": "2025-01-25T14:30:00.000Z",
-  "correlationId": "act_123",
-  "processingMode": "async"
-}
-```
-
-### Key Metrics
-
-```typescript
-const METRICS = {
-  signatureValidationMs: 45,
-  totalResponseTimeMs: 50,
-  graphqlQueryMs: 1200,
-  universalMapperMs: 150,
-  xmlGenerationMs: 50,
-  sftpUploadMs: 980,
-  totalBackgroundMs: 2380,
-};
-```
-
----
-
-## Related Documentation
-
-- [Inline Mapping Template](./template-webhook-rubix-fulfilment-to-sftp-xml-inline.md) - For simple XML structures
-- [Order Attribute Update Template](./template-webhook-rubix-order-attribute-update.md) - For ORDER webhooks
-- [Webhook Validation Guide](../../../../02-CORE-GUIDES/webhook-validation/)
-- [UniversalMapper Guide](../../../../02-CORE-GUIDES/mapping/universal-mapper.md)
-- [Versori Platform Guide](../../../../04-REFERENCE/platforms/versori/)
-- [SFTP Data Sources Guide](../../../../02-CORE-GUIDES/data-sources/)
-
----
-
-**Pattern**: Fulfilment webhook → GraphQL query → UniversalMapper transformation → XML generation → SFTP upload  
-**✅ Production-Ready**: Comprehensive template with external mapping, custom resolvers, and all critical fixes applied  
-**Key Learning**: External JSON mapping enables XML structure changes without code modifications, custom resolvers handle complex transformations  
-**Critical**: SFTP dispose() in finally block, retailerId validation, fire-and-forget pattern, UniversalMapper before XMLBuilder
-
+---
+template_id: tpl-webhook-rubix-fulfilment-export-universal-mapper
+canonical_filename: template-webhook-rubix-fulfilment-to-sftp-xml-universal-mapper.md
+version: 2.0.0
+sdk_version: ^0.1.39
+runtime: versori
+direction: webhook
+source: fluent-rubix-workflow
+destination: sftp-xml
+entity: fulfilment
+format: xml
+logging: versori
+status: stable
+pattern: universal-mapper
+features:
+  - webhook-validation
+  - fire-and-forget
+  - background-processing
+  - xml-export
+  - sftp-integration
+  - graphql-queries
+  - universal-mapper
+  - external-mapping
+  - custom-resolvers
+---
+
+# Template: Rubix Fulfilment Webhook → SFTP XML Export (UniversalMapper Pattern)
+
+**Template Version:** 2.0.0  
+**SDK Version:** `^0.1.39` - `npm install @fluentcommerce/fc-connect-sdk@^0.1.39`  
+**Last Updated:** 2025-01-25  
+**Deployment Target:** Versori Platform  
+**Mapping Pattern:** 🟢 **UNIVERSALMAPPER** (External JSON mapping + Custom resolvers)
+
+> **📖 Pattern Selection Guide:**
+> - **Use THIS template (UniversalMapper)** for: Reusable configs, multi-environment deployments, complex transformations, external mapping management
+> - **Use Inline version** for: Simple webhooks, tightly-coupled 3PL schemas, fast debugging
+> - **See also:** [template-webhook-rubix-fulfilment-to-sftp-xml-inline.md](./template-webhook-rubix-fulfilment-to-sftp-xml-inline.md)
+
+**🆕 Version 2.0.0 - Production Ready:**
+- ✅ **Fulfilment-specific template** - Focused on 3PL/WMS integration
+- ✅ **Production-ready modular structure** - Separate workflows, services, config, resolvers, types
+- ✅ **GraphQL fulfilment queries** - Fetch fulfilment + line items + order details
+- ✅ **Automatic pagination** - Handles fulfilments with 100+ items (up to 1000)
+- ✅ **External JSON mapping** - `config/fulfilment-xml-mapping.json` for XML structure
+- ✅ **UniversalMapper** - Transforms GraphQL data to XML structure with custom resolvers
+- ✅ **Custom resolvers** - Handle complex transformations (date formatting, nested data)
+- ✅ **XML generation** - Safe XML with automatic escaping via XMLBuilder
+- ✅ **SFTP upload** - Connection pooling with proper dispose()
+- ✅ **Critical fixes applied** - retailerId validation, SFTP options parameter, pagination
+- ✅ **Comprehensive documentation** - Testing, troubleshooting, monitoring
+
+**When to Use This Pattern:**
+- ✅ Complex XML structures (>20 fields)
+- ✅ XML structure changes frequently
+- ✅ Need environment-specific configurations
+- ✅ Multi-environment deployments (dev/staging/prod)
+- ✅ Reusable mapping configurations
+- ✅ Complex transformations requiring custom resolvers
+
+---
+
+## Overview
+
+Receive fulfilment webhooks from Rubix workflows, query fulfilment details, transform with UniversalMapper, generate XML, and upload to 3PL/WMS SFTP server.
+
+**Pattern:**
+1. Validate webhook signature (~10-50ms)
+2. Return HTTP 200 OK immediately (fast acknowledgment)
+3. Background: Query fulfilment details → UniversalMapper transformation → Generate XML → Upload to SFTP (~2-5s)
+
+**Business Use Case:**
+- Rubix workflow sends webhook when fulfilment is created/updated
+- Handler queries fulfilment details (items, order, addresses)
+- UniversalMapper transforms GraphQL data using external JSON mapping
+- Custom resolvers handle complex transformations (dates, addresses, names)
+- Generates XML fulfillment notification for 3PL/WMS
+- Uploads to partner SFTP server for warehouse processing
+
+---
+
+## STEP 1: Understand This Template
+
+### What This Template Does
+
+**Core Functionality:**
+- Receives FULFILMENT webhooks from Fluent Commerce Rubix workflows
+- Validates webhook signature for security
+- Returns fast HTTP 200 OK response (<100ms)
+- Background: Queries fulfilment via GraphQL → UniversalMapper transformation → XML generation → Uploads to SFTP
+
+**Key SDK Components:**
+- `WebhookValidationService` - Signature validation with RSA/HMAC support
+- `createClient()` - Universal client factory (auto-detects Versori context)
+- `client.graphql()` - Query fulfilment details with automatic pagination
+- `UniversalMapper` - Transform GraphQL data to XML structure using external JSON mapping
+- `XMLBuilder` - Safe XML generation with automatic escaping (after UniversalMapper)
+- `SftpDataSource` - SFTP operations with connection pooling
+- `ctx.credentials().getAccessToken()` - Retrieve SFTP credentials from Versori connection vault
+- Native Versori `log` - Structured logging from context
+
+**Pagination Support:**
+- Automatically handles fulfilments with 100+ line items
+- Uses two-query pattern: fulfilment details + paginated items
+- SDK auto-pagination: `pagination: { maxPages: 10 }` supports up to 1000 items
+- Logs pagination usage for monitoring
+
+**Critical Patterns:**
+- **Sync + Fire-and-Forget**: Fast validation, background processing
+- **Signature Validation**: Always validate `fluent-signature` or `flex.signature` headers
+- **Background Promises**: Use `.then().catch()` for error handling
+- **SFTP Credentials**: Retrieve from Versori connection vault (not activation variables)
+- **SFTP Cleanup**: Always call `dispose()` in finally blocks
+- **RetailerId Validation**: Check before `setRetailerId()` to prevent 401 errors
+- **External Mapping**: XML structure defined in JSON config file (not inline)
+- **Custom Resolvers**: Complex transformations separated into resolver functions
+
+### When to Use This Template
+
+✅ **USE THIS TEMPLATE FOR:**
+- Fulfilment created/updated webhooks from Rubix workflows
+- Export fulfilment details to 3PL/WMS via SFTP
+- Need XML format for warehouse management systems
+- Require signature validation for security
+- Need fast webhook acknowledgment + async processing
+- **Complex XML structures** requiring external configuration
+- **Multi-environment deployments** with different XML schemas
+- **Frequent XML structure changes** without code modifications
+
+❌ **DON'T USE FOR:**
+- Order webhooks (use order attribute update template)
+- Inventory webhooks (use inventory templates)
+- CSV/JSON exports (use format-specific templates)
+- Synchronous processing required (use standard http workflow)
+- **Simple XML structures** (<20 fields) - use inline mapping template instead
+
+### Business Use Cases
+
+**Use Case: 3PL Warehouse Fulfillment Notification**
+- Rubix workflow sends webhook when fulfilment moves to "ALLOCATED" status
+- Handler queries fulfilment details (items, quantities, order info)
+- UniversalMapper transforms data using external JSON mapping config
+- Custom resolvers format dates, addresses, and customer names
+- Generates XML fulfillment order for warehouse system
+- Uploads to 3PL SFTP server for pick/pack/ship processing
+- 3PL system imports XML and creates warehouse tasks
+
+**Why UniversalMapper Pattern:**
+- XML structure can be updated without code changes (edit JSON config)
+- Different XML schemas per environment (dev/staging/prod configs)
+- Complex transformations handled by reusable custom resolvers
+- Mapping configuration can be versioned and tested independently
+
+---
+
+## STEP 2: Implementation Prompt for Claude Code
+
+**Copy this prompt and send to Claude Code to generate the complete implementation:**
+
+```
+Create a Versori webhook handler for Fluent Commerce Rubix FULFILMENT events with signature validation, GraphQL queries, UniversalMapper transformation, XML generation, and SFTP upload.
+
+REQUIREMENTS:
+1. Runtime: Versori Platform (HTTP webhook)
+2. Source: Rubix SendWebhook action (FULFILMENT entity type only)
+3. Destination: SFTP XML export to 3PL/WMS partner
+4. Format: XML with fulfilment details, line items, order info
+5. Entity: FULFILMENT
+
+KEY FEATURES:
+- Webhook signature validation using WebhookValidationService
+- Sync mode + fire-and-forget pattern for fast response
+- Background processing: GraphQL query → UniversalMapper transformation → XML generation → SFTP upload
+- **Automatic pagination** - Handles fulfilments with 100+ items (up to 1000 items)
+- Two-query pattern: Fulfilment details + paginated items query
+- **External JSON mapping** - `config/fulfilment-xml-mapping.json` for XML structure
+- **UniversalMapper** - Transforms GraphQL data to XML structure with custom resolvers
+- **Custom resolvers** - Handle complex transformations (date formatting, nested data)
+- Modular architecture (workflows/, services/, config/, resolvers/, types/)
+- Native Versori logging (no LoggingService)
+- SFTP cleanup with dispose() in finally blocks
+- Comprehensive error handling with SDK error types
+- RetailerId validation before setRetailerId()
+
+CRITICAL REQUIREMENTS:
+1. Webhook Mode: response: { mode: 'sync' }
+2. Signature Validation: WebhookValidationService with strictValidation: true
+3. RetailerId Validation: Check exists before client.setRetailerId()
+4. Background Processing: Fire-and-forget pattern (no await on background promise)
+5. GraphQL Queries: Two separate queries (fulfilment + items with pagination)
+6. Pagination: Use SDK automatic pagination with maxPages: 10, first: 100
+7. **External Mapping**: Use `config/fulfilment-xml-mapping.json` (NOT inline mapping)
+8. **UniversalMapper**: Transform GraphQL data to XML structure using mapping config
+9. **Custom Resolvers**: Use resolvers/fulfilment-resolvers.ts for complex transformations
+10. XML Generation: Use XMLBuilder with automatic escaping (after UniversalMapper)
+11. SFTP Upload: Include options parameter { overwrite: true, createDirectories: true }
+12. SFTP Cleanup: Always dispose() in finally block
+13. Error Handling: Import and handle DataSourceError, AuthenticationError, GraphQLError
+14. Type Safety: Use Logger, VersoriContext types (not any)
+
+SDK METHODS TO USE:
+- import { Buffer } from 'node:buffer' (CRITICAL for Versori/Deno)
+- createClient({ ...ctx, log })
+- await client.setRetailerId(retailerId) (with validation first!)
+- new WebhookValidationService({ strictValidation: true }, log)
+- await validator.validateWebhook(rawBody, headers, publicKey)
+- await client.graphql({ query, variables, pagination: { maxPages: 10 } })
+- import mappingConfig from '../config/fulfilment-xml-mapping.json' with { type: 'json' }
+- new UniversalMapper(mappingConfig, { customResolvers })
+- await mapper.map(fulfilmentData) - Transform GraphQL data to XML structure
+- new XMLBuilder({ prettyPrint: true, xmlDeclaration: true, encoding: 'UTF-8' })
+- xmlBuilder.build(mappedData, 'FulfilmentExport')
+- await ctx.credentials().getAccessToken('sftp_export_server') - Retrieve SFTP credentials from connection vault
+- Buffer.from(accessToken, 'base64').toString('utf-8') - Decode Basic Auth credentials
+- new SftpDataSource(config, log) - config includes connectionId: 'sftp_export_server'
+- await sftp.uploadFile(remotePath, buffer, { overwrite: true, createDirectories: true })
+- await sftp.dispose() (CRITICAL in finally block)
+
+FORBIDDEN PATTERNS:
+- ❌ LoggingService (use native log from context)
+- ❌ await on background processing (use fire-and-forget)
+- ❌ Inline mapping config (use external JSON file)
+- ❌ Manual object construction for XML (use UniversalMapper)
+- ❌ Missing dispose() for SFTP
+- ❌ Missing options parameter in uploadFile()
+- ❌ Missing retailerId validation before setRetailerId()
+- ❌ Storing SFTP credentials in activation variables (use Versori connection vault)
+- ❌ Using 'any' type (use Logger, VersoriContext from SDK)
+- ❌ Direct FluentClient instantiation (use createClient factory)
+- ❌ Generic error handling (use SDK error types)
+
+GRAPHQL QUERY STRUCTURE:
+
+**Single Query with Nested Items (Schema-Validated)**
+```graphql
+query GetFulfilment($id: ID!, $first: Int!, $after: String) {
+  fulfilment(id: $id) {
+    id
+    ref
+    status
+    deliveryType
+    order {
+      id
+      ref
+      customer { firstName, lastName, email }
+    }
+    toAddress {
+      name, street, street2, city, state, postcode, country
+    }
+    fromAddress {
+      name, street, street2, city, state, postcode, country
+    }
+    items(first: $first, after: $after) {
+      edges {
+        node {
+          id
+          ref
+          requestedQuantity
+          filledQuantity
+          rejectedQuantity
+          orderItem {
+            id
+            ref
+            productRef
+            product { name }
+          }
+        }
+        cursor
+      }
+      pageInfo {
+        hasNextPage
+      }
+    }
+    createdOn
+    updatedOn
+  }
+}
+```
+
+**Why Single Query?**
+- Items are nested under the fulfilment type in Fluent Commerce schema
+- Single query with `connectionPath: 'fulfilment.items'` for SDK pagination
+- SDK automatically handles pagination with `pagination: { maxPages: 10 }` config
+- More efficient than two separate queries (reduces GraphQL roundtrips)
+
+XML OUTPUT STRUCTURE:
+<FulfilmentExport>
+  <Fulfilment ref="FF-001" status="ALLOCATED">
+    <OrderRef>ORD-123</OrderRef>
+    <DeliveryType>STANDARD</DeliveryType>
+    <Customer>
+      <FirstName>John</FirstName>
+      <LastName>Smith</LastName>
+      <Email>john@example.com</Email>
+    </Customer>
+    <ToAddress>
+      <Name>John Smith</Name>
+      <Street>123 Main St</Street>
+      <City>New York</City>
+      <State>NY</State>
+      <Postcode>10001</Postcode>
+      <Country>US</Country>
+    </ToAddress>
+    <FromAddress>
+      <Name>Warehouse</Name>
+      <Street>456 Warehouse St</Street>
+      <City>Chicago</City>
+      <State>IL</State>
+      <Postcode>60601</Postcode>
+      <Country>US</Country>
+    </FromAddress>
+    <Items>
+      <Item ref="FFI-001">
+        <ProductRef>SKU-001</ProductRef>
+        <ProductName>Widget</ProductName>
+        <RequestedQuantity>2</RequestedQuantity>
+        <FilledQuantity>2</FilledQuantity>
+        <RejectedQuantity>0</RejectedQuantity>
+      </Item>
+    </Items>
+    <CreatedOn>2025-01-25T10:00:00Z</CreatedOn>
+    <UpdatedOn>2025-01-25T11:00:00Z</UpdatedOn>
+  </Fulfilment>
+</FulfilmentExport>
+
+GENERATE:
+1. package.json with dependencies
+2. index.ts (entry point - exports workflow)
+3. src/workflows/webhook/fulfilment-export-handler.ts (webhook entry)
+4. src/services/fulfilment-query.service.ts (GraphQL queries)
+5. src/services/xml-export.service.ts (UniversalMapper + XMLBuilder + SFTP upload)
+6. src/resolvers/fulfilment-resolvers.ts (Custom resolvers for XML transformations)
+7. src/config/fulfilment-xml-mapping.json (External JSON mapping configuration)
+8. src/types/fulfilment.types.ts (TypeScript interfaces)
+9. readme.md with setup instructions
+
+Ensure all code is production-ready with proper error handling, signature validation, SFTP cleanup, UniversalMapper transformation, external JSON mapping, custom resolvers, and type safety.
+```
+
+---
+
+## STEP 3: Detailed Flow Documentation
+
+### Complete Processing Flow
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ 1. RUBIX WEBHOOK RECEIVED                                   │
+│    POST https://{workspace}.versori.run/rubix-fulfilment    │
+│    Headers: fluent-signature                                │
+│    Body: { entityRef: "FF-001", entityType: "FULFILMENT" }  │
+└────────────────────┬────────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────────┐
+│ 2. SIGNATURE VALIDATION (Synchronous, ~10-50ms)             │
+│    - Extract rawBody and headers                            │
+│    - Get fluentPublicKey from activation                    │
+│    - WebhookValidationService.validateWebhook()             │
+│    - Return 400 if invalid                                  │
+└────────────────────┬────────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────────┐
+│ 3. PAYLOAD VALIDATION (Synchronous, ~5ms)                   │
+│    - Check entityRef exists                                 │
+│    - Check entityType === 'FULFILMENT'                      │
+│    - Check retailerId exists                                │
+│    - Return 400 if missing required fields                  │
+└────────────────────┬────────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────────┐
+│ 4. HTTP 200 OK RESPONSE (Total: ~50ms)                      │
+│    - Return success immediately                             │
+│    - Background promise continues (fire-and-forget)         │
+└────────────────────┬────────────────────────────────────────┘
+                     │
+                     ▼ (Background - doesn't block response)
+┌─────────────────────────────────────────────────────────────┐
+│ 5. BACKGROUND PROCESSING (~2-5 seconds)                     │
+│    ┌─────────────────────────────────────────────────────┐  │
+│    │ 5a. Initialize Fluent Client (~100ms)               │  │
+│    │     - createClient({ ...ctx, log })                 │  │
+│    │     - Validate retailerId exists                   │  │
+│    │     - client.setRetailerId(retailerId)              │  │
+│    └─────────────────────────────────────────────────────┘  │
+│    ┌─────────────────────────────────────────────────────┐  │
+│    │ 5b. Query Fulfilment Details (~500-1500ms)          │  │
+│    │     - GraphQL query with nested fields              │  │
+│    │     - Fulfilment + items + order + addresses        │  │
+│    │     - Handle GraphQLError if query fails            │  │
+│    └─────────────────────────────────────────────────────┘  │
+│    ┌─────────────────────────────────────────────────────┐  │
+│    │ 5c. Transform with UniversalMapper (~100-200ms)      │  │
+│    │     - Load mapping config from JSON                  │  │
+│    │     - Apply SDK resolvers (trim, uppercase)          │  │
+│    │     - Apply custom resolvers (date formatting)       │  │
+│    │     - Transform GraphQL data to XML structure        │  │
+│    └─────────────────────────────────────────────────────┘  │
+│    ┌─────────────────────────────────────────────────────┐  │
+│    │ 5d. Generate XML (~50ms)                             │  │
+│    │     - XMLBuilder with mapped data                    │  │
+│    │     - XMLBuilder handles escaping automatically       │  │
+│    │     - Create Buffer from XML string                  │  │
+│    └─────────────────────────────────────────────────────┘  │
+│    ┌─────────────────────────────────────────────────────┐  │
+│    │ 5e. Upload to SFTP (~500-2000ms)                     │  │
+│    │     - Initialize SftpDataSource                        │  │
+│    │     - Upload with options parameter                  │  │
+│    │     - Handle DataSourceError if upload fails          │  │
+│    │     - ALWAYS dispose() in finally block              │  │
+│    └─────────────────────────────────────────────────────┘  │
+│    ┌─────────────────────────────────────────────────────┐  │
+│    │ 5f. Log Completion                                    │  │
+│    │     - Success: Log fulfilment ref and duration        │  │
+│    │     - Failure: Log error with category                │  │
+│    └─────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Response Timing
+
+| Stage | Timing | Blocking |
+|-------|--------|----------|
+| **Signature Validation** | ~10-50ms | ✅ Yes (blocks response) |
+| **Payload Validation** | ~5ms | ✅ Yes (blocks response) |
+| **HTTP 200 Response** | ~50-100ms | ✅ Fast acknowledgment |
+| **GraphQL Query** | ~500-1500ms | ❌ No (background) |
+| **UniversalMapper Transformation** | ~100-200ms | ❌ No (background) |
+| **XML Generation** | ~50ms | ❌ No (background) |
+| **SFTP Upload** | ~500-2000ms | ❌ No (background) |
+| **Total Background** | ~2000-5000ms | ❌ Fire-and-forget |
+
+---
+
+## STEP 4: Production Modular Structure
+
+### Complete Project Structure
+
+```
+rubix-fulfilment-export/
+├── package.json                              # Dependencies and Versori config
+├── tsconfig.json                             # TypeScript configuration
+├── readme.md                                 # Setup and deployment instructions
+├── index.ts                                  # Entry point - exports workflow
+└── src/
+    ├── workflows/
+    │   └── webhook/
+    │       └── fulfilment-export-handler.ts  # Webhook entry point
+    │
+    ├── services/
+    │   ├── fulfilment-query.service.ts       # GraphQL queries
+    │   └── xml-export.service.ts             # UniversalMapper + XMLBuilder + SFTP upload
+    │
+    ├── resolvers/
+    │   └── fulfilment-resolvers.ts           # Custom resolvers for XML transformations
+    │
+    ├── config/
+    │   └── fulfilment-xml-mapping.json       # External JSON mapping configuration
+    │
+    └── types/
+        └── fulfilment.types.ts               # TypeScript interfaces
+```
+
+**Why This Structure?**
+- ✅ **Clear separation**: Webhook handlers vs business logic
+- ✅ **Reusable services**: Query and export logic can be unit tested
+- ✅ **External config**: XML mapping changes don't require code changes
+- ✅ **Custom resolvers**: Complex transformations separated from mapping config
+- ✅ **Type safety**: TypeScript interfaces for better IDE support
+- ✅ **Scalable**: Easy to add more fulfilment webhooks or modify XML structure
+- ✅ **Testable**: Services can be mocked and tested independently
+- ✅ **Environment-specific**: Different mapping configs per environment
+
+---
+
+## SDK Imports (Verified - Versori Optimized)
+
+```typescript
+// CRITICAL: Buffer import required for Versori/Deno runtime
+import { Buffer } from 'node:buffer';
+
+// FC Connect SDK imports
+import {
+  createClient,
+  WebhookValidationService,
+  UniversalMapper,
+  XMLBuilder,
+  SftpDataSource,
+  DataSourceError,
+  AuthenticationError,
+  GraphQLError,
+  type Logger,
+  type VersoriContext,
+} from '@fluentcommerce/fc-connect-sdk';
+
+// Versori platform imports
+import { webhook } from '@versori/run';
+import type { Context } from '@versori/run';
+```
+
+---
+
+## Configuration
+
+### Activation Variables
+
+```json
+{
+  "fluentPublicKey": "-----BEGIN PUBLIC KEY-----...-----END PUBLIC KEY-----",
+  "sftpHost": "sftp.3pl-partner.com",
+  "sftpPort": 22,
+  "sftpRemotePath": "/incoming/fulfilments/"
+}
+```
+
+> **Important:** `sftpUsername` and `sftpPassword` are **NOT** stored in activation variables. They are securely retrieved from the `sftp_export_server` connection vault at runtime. See the SFTP Credential Management section below for details.
+
+### Connections
+
+| Connection | Description | Required |
+|------------|-------------|----------|
+| `fluent_commerce` | OAuth2 connection to Fluent Commerce | Yes |
+| `sftp_export_server` | Basic Auth connection for SFTP credentials (username/password) | Yes |
+
+## SFTP Credential Management
+
+Fetch credentials securely from Versori connection vault using `ctx.credentials().getAccessToken()`:
+
+**Benefits:**
+- ✅ Credentials stored securely in Versori vault
+- ✅ Centralized management - update in one place
+- ✅ Access control enforced by platform
+- ✅ No credentials in activation variables
+- ✅ Explicit error handling with validation
+
+### Setup Steps
+
+1. In Versori Dashboard → Connections → Add Connection
+2. Name: `sftp_export_server`
+3. Type: Basic Auth
+4. Enter SFTP username and password
+5. Save connection
+6. Reference in code: `ctx.credentials().getAccessToken('sftp_export_server')`
+
+---
+
+## Complete Working Code
+
+### 1. Entry Point (index.ts)
+
+```typescript
+/**
+ * Entry point - Export webhook workflow for Versori platform
+ */
+
+export { rubixFulfilmentExportHandler } from './src/workflows/webhook/fulfilment-export-handler';
+```
+
+### 2. Webhook Handler (src/workflows/webhook/fulfilment-export-handler.ts)
+
+```typescript
+/**
+ * Rubix Fulfilment Webhook Handler → SFTP XML Export
+ *
+ * Direction: Fluent Rubix Workflow (FULFILMENT) → Versori → GraphQL → UniversalMapper → XML → SFTP
+ */
+
+import { Buffer } from 'node:buffer';
+import { webhook } from '@versori/run';
+import type { Context } from '@versori/run';
+import {
+  WebhookValidationService,
+  type Logger,
+} from '@fluentcommerce/fc-connect-sdk';
+import { processFulfilmentExport } from '../../services/fulfilment-query.service';
+
+export const rubixFulfilmentExportHandler = webhook('rubix-fulfilment', {
+  response: { mode: 'sync' }, // ✅ Sync mode: response sent when handler returns
+}, async (ctx: Context<any>) => {
+  const { log, activation } = ctx;
+
+  log.info('🚀 [WEBHOOK] Received Rubix fulfilment webhook', {
+    timestamp: new Date().toISOString(),
+    correlationId: activation?.id,
+  });
+
+  // ========================================
+  // STEP 1: VALIDATE SIGNATURE (Synchronous)
+  // ========================================
+
+  const publicKey = activation.getVariable('fluentPublicKey');
+  if (!publicKey) {
+    log.error('❌ [WEBHOOK] Missing fluentPublicKey configuration');
+    return {
+      status: 500,
+      body: {
+        success: false,
+        error: 'Missing fluentPublicKey configuration',
+        recommendation: 'Configure fluentPublicKey in activation variables',
+      },
+    };
+  }
+
+  // Extract raw body (Versori provides parsed data in ctx.data)
+  const rawBody = typeof ctx.data === 'string' ? ctx.data : JSON.stringify(ctx.data);
+
+  // Extract headers from request (ctx.request() is a function call)
+  const req = ctx.request?.() || {};
+  const headersObj = req.headers || {};
+  const headers = headersObj instanceof Headers
+    ? Object.fromEntries(headersObj.entries())
+    : headersObj;
+
+  log.info('🔍 [WEBHOOK] Validating webhook signature');
+
+  const validator = new WebhookValidationService({ strictValidation: true }, log as Logger);
+  const result = await validator.validateWebhook(rawBody, headers, publicKey);
+
+  if (!result.isValid) {
+    log.error('❌ [WEBHOOK] Invalid webhook signature', {
+      error: result.error,
+      algorithm: result.algorithm,
+    });
+    return {
+      status: 401,
+      body: {
+        success: false,
+        error: 'Invalid webhook signature',
+        recommendation: 'Verify fluentPublicKey matches Fluent environment',
+      },
+    };
+  }
+
+  log.info('✅ [WEBHOOK] Signature validated successfully', {
+    algorithm: result.algorithm,
+  });
+
+  // ========================================
+  // STEP 2: VALIDATE PAYLOAD (Synchronous)
+  // ========================================
+
+  const payload = typeof ctx.data === 'string' ? JSON.parse(ctx.data) : ctx.data;
+  const { entityRef, entityType, retailerId } = payload;
+
+  if (!entityRef) {
+    log.error('❌ [WEBHOOK] Missing entityRef in payload', { payload });
+    return {
+      status: 400,
+      body: {
+        success: false,
+        error: 'Missing entityRef in payload',
+        recommendation: 'Ensure Rubix SendWebhook includes fulfilment ref',
+      },
+    };
+  }
+
+  if (entityType !== 'FULFILMENT') {
+    log.error('❌ [WEBHOOK] Invalid entity type', { entityType, expected: 'FULFILMENT' });
+    return {
+      status: 400,
+      body: {
+        success: false,
+        error: `Invalid entity type: ${entityType}. Expected: FULFILMENT`,
+        recommendation: 'Use order-attribute-update template for ORDER webhooks',
+      },
+    };
+  }
+
+  if (!retailerId) {
+    log.error('❌ [WEBHOOK] Missing retailerId in payload', { payload });
+    return {
+      status: 400,
+      body: {
+        success: false,
+        error: 'Missing retailerId in payload',
+        recommendation: 'Ensure Rubix SendWebhook includes retailerId',
+      },
+    };
+  }
+
+  log.info('✅ [WEBHOOK] Validation passed, starting background processing', {
+    entityRef,
+    entityType,
+    retailerId,
+  });
+
+  // ========================================
+  // STEP 3: FIRE-AND-FORGET BACKGROUND PROCESSING
+  // ========================================
+
+  // ✅ Fire-and-forget: Start background processing WITHOUT await
+  // The promise continues execution after we return the response
+  processFulfilmentExport(ctx, payload)
+    .then(() => {
+      log.info('✅ [BACKGROUND] Fulfilment exported successfully', {
+        fulfilmentRef: entityRef,
+      });
+    })
+    .catch((error: unknown) => {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      log.error('❌ [BACKGROUND] Fulfilment export failed', {
+        fulfilmentRef: entityRef,
+        error: errorMessage,
+        stack: error instanceof Error ? error.stack : undefined,
+        errorType: error instanceof Error ? error.constructor.name : typeof error,
+      });
+    });
+
+  // Return immediately (response sent with this return value)
+  return {
+    status: 200,
+    body: {
+      success: true,
+      entityType,
+      fulfilmentRef: entityRef,
+      message: 'Webhook validated and export started in background',
+      timestamp: new Date().toISOString(),
+      correlationId: activation?.id,
+    },
+  };
+});
+```
+
+### 3. Fulfilment Query Service (src/services/fulfilment-query.service.ts)
+
+```typescript
+/**
+ * Fulfilment Query Service
+ *
+ * Handles GraphQL queries for fulfilment details and orchestrates XML export
+ */
+
+import {
+  createClient,
+  DataSourceError,
+  AuthenticationError,
+  GraphQLError,
+  type Logger,
+  type VersoriContext,
+} from '@fluentcommerce/fc-connect-sdk';
+import { exportFulfilmentToSFTP } from './xml-export.service';
+import type { RubixFulfilmentPayload, FulfilmentData } from '../types/fulfilment.types';
+
+// Single query with nested items (schema-validated structure)
+const FULFILMENT_QUERY = `
+  query GetFulfilment($id: ID!, $first: Int!, $after: String) {
+    fulfilment(id: $id) {
+      id
+      ref
+      status
+      deliveryType
+      order {
+        id
+        ref
+        customer {
+          firstName
+          lastName
+          email
+        }
+      }
+      toAddress {
+        name
+        street
+        street2
+        city
+        state
+        postcode
+        country
+      }
+      fromAddress {
+        name
+        street
+        street2
+        city
+        state
+        postcode
+        country
+      }
+      items(first: $first, after: $after) {
+        edges {
+          node {
+            id
+            ref
+            requestedQuantity
+            filledQuantity
+            rejectedQuantity
+            orderItem {
+              id
+              ref
+              productRef
+              product {
+                name
+              }
+            }
+          }
+          cursor
+        }
+        pageInfo {
+          hasNextPage
+        }
+      }
+      createdOn
+      updatedOn
+    }
+  }
+`;
+
+export async function processFulfilmentExport(
+  ctx: VersoriContext,
+  payload: RubixFulfilmentPayload
+): Promise<void> {
+  const log = ctx.log as Logger;
+  const { entityRef, retailerId } = payload;
+
+  const processingStartTime = Date.now();
+
+  log.info('🔄 [BACKGROUND] Starting fulfilment export', {
+    timestamp: new Date().toISOString(),
+    fulfilmentRef: entityRef,
+  });
+
+  try {
+    // ========================================
+    // STEP 1: VALIDATE RETAILER ID
+    // ========================================
+
+    if (!retailerId) {
+      log.error('❌ [BACKGROUND] Missing retailerId in payload', {
+        fulfilmentRef: entityRef,
+      });
+      throw new Error('retailerId is required for GraphQL operations');
+    }
+
+    // ========================================
+    // STEP 2: INITIALIZE FLUENT CLIENT
+    // ========================================
+
+    const client = await createClient({ ...ctx, log });
+    await client.setRetailerId(retailerId);
+
+    // ========================================
+    // STEP 3: QUERY FULFILMENT WITH NESTED ITEMS
+    // ========================================
+
+    log.info('🔍 [BACKGROUND] Querying fulfilment with items', { fulfilmentRef: entityRef });
+
+    const result = await client.graphql({
+      query: FULFILMENT_QUERY,
+      variables: {
+        id: entityRef,  // ✅ Use 'id' parameter (schema-validated)
+        first: 100,
+      },
+      pagination: {
+        connectionPath: 'fulfilment.items',  // ✅ Nested connection pagination
+        maxPages: 10, // Handles up to 1000 items (100 per page × 10 pages)
+      },
+    });
+
+    const fulfilmentData = result.data?.fulfilment as FulfilmentData | null;
+
+    if (!fulfilmentData) {
+      log.error('❌ [BACKGROUND] Fulfilment not found', { fulfilmentRef: entityRef });
+      throw new Error(`Fulfilment not found: ${entityRef}`);
+    }
+
+    const itemCount = fulfilmentData.items?.edges?.length || 0;
+
+    log.info('✅ [BACKGROUND] Fulfilment and items queried successfully', {
+      fulfilmentRef: fulfilmentData.ref,
+      status: fulfilmentData.status,
+      itemCount,
+      orderRef: fulfilmentData.order?.ref,
+      paginationUsed: result.metadata?.totalPages > 1,
+    });
+
+    // ========================================
+    // STEP 4: EXPORT TO SFTP
+    // ========================================
+
+    await exportFulfilmentToSFTP(ctx, fulfilmentData, log);
+
+    const duration = Date.now() - processingStartTime;
+    log.info('✅ [BACKGROUND] Fulfilment export completed', {
+      fulfilmentRef: entityRef,
+      duration: `${duration}ms`,
+    });
+  } catch (error: unknown) {
+    let errorMessage = 'Unknown error';
+    let recommendation: string | undefined;
+    let errorCategory = 'UNKNOWN';
+
+    if (error instanceof GraphQLError) {
+      errorMessage = error.message;
+      recommendation = 'Review GraphQL query syntax and field permissions';
+      errorCategory = 'GRAPHQL';
+    } else if (error instanceof AuthenticationError) {
+      errorMessage = error.message;
+      recommendation = 'Verify Fluent Commerce credentials and retailerId';
+      errorCategory = 'AUTHENTICATION';
+    } else if (error instanceof DataSourceError) {
+      errorMessage = error.message;
+      recommendation = 'Check SFTP configuration and connectivity';
+      errorCategory = 'DATA_SOURCE';
+    } else if (error instanceof Error) {
+      errorMessage = error.message;
+    } else {
+      errorMessage = String(error);
+    }
+
+    log.error('❌ [BACKGROUND] Fulfilment export failed', {
+      fulfilmentRef: entityRef,
+      error: errorMessage,
+      errorCategory,
+      recommendation,
+      stack: error instanceof Error ? error.stack : undefined,
+      errorType: error instanceof Error ? error.constructor.name : typeof error,
+    });
+
+    throw error;
+  }
+}
+```
+
+### 4. XML Export Service (src/services/xml-export.service.ts)
+
+```typescript
+/**
+ * XML Export Service
+ *
+ * Handles XML generation and SFTP upload for fulfilment exports
+ * Uses UniversalMapper with external JSON mapping configuration
+ */
+
+import { Buffer } from 'node:buffer';
+import {
+  UniversalMapper,
+  XMLBuilder,
+  SftpDataSource,
+  type Logger,
+  type VersoriContext,
+} from '@fluentcommerce/fc-connect-sdk';
+import type { FulfilmentData } from '../types/fulfilment.types';
+import mappingConfig from '../config/fulfilment-xml-mapping.json' with { type: 'json' };
+import { customResolvers } from '../resolvers/fulfilment-resolvers';
+
+export async function exportFulfilmentToSFTP(
+  ctx: VersoriContext,
+  fulfilmentData: FulfilmentData,
+  log: Logger
+): Promise<void> {
+  const { activation } = ctx;
+
+  log.info('📝 [BACKGROUND] Generating XML for fulfilment', {
+    fulfilmentRef: fulfilmentData.ref,
+  });
+
+  // ========================================
+  // STEP 1: TRANSFORM DATA WITH UNIVERSALMAPPER
+  // ========================================
+
+  log.info('🔄 [BACKGROUND] Transforming fulfilment data with UniversalMapper', {
+    fulfilmentRef: fulfilmentData.ref,
+  });
+
+  const mapper = new UniversalMapper(mappingConfig, {
+    customResolvers,
+  });
+
+  const mappingResult = await mapper.map(fulfilmentData);
+
+  if (!mappingResult.success) {
+    log.error('❌ [BACKGROUND] Mapping failed', {
+      errors: mappingResult.errors,
+      fulfilmentRef: fulfilmentData.ref,
+    });
+    throw new Error(`Mapping failed: ${mappingResult.errors?.join(', ')}`);
+  }
+
+  const mappedData = mappingResult.data;
+
+  log.info('✅ [BACKGROUND] Data transformed successfully', {
+    fulfilmentRef: fulfilmentData.ref,
+    fieldCount: Object.keys(mappedData).length,
+  });
+
+  // ========================================
+  // STEP 2: GENERATE XML WITH XMLBUILDER
+  // ========================================
+
+  const xmlBuilder = new XMLBuilder({
+    prettyPrint: true,
+    xmlDeclaration: true,
+    encoding: 'UTF-8',
+  });
+
+  const xmlString = xmlBuilder.build(mappedData, 'FulfilmentExport');
+  const xmlBuffer = Buffer.from(xmlString, 'utf8');
+
+  log.info('✅ [BACKGROUND] XML generated successfully', {
+    fulfilmentRef: fulfilmentData.ref,
+    xmlSizeBytes: xmlBuffer.length,
+    xmlSizeKB: Math.round(xmlBuffer.length / 1024),
+  });
+
+  // ========================================
+  // STEP 3: UPLOAD TO SFTP
+  // ========================================
+
+  log.info('📤 [BACKGROUND] Preparing SFTP upload', {
+    fulfilmentRef: fulfilmentData.ref,
+  });
+
+  // ========================================
+  // SFTP CREDENTIAL RETRIEVAL
+  // ========================================
+
+  /**
+   * Retrieve SFTP credentials from connection configuration
+   * 
+   * Connection Name: 'sftp_export_server' (must match the connection name in Versori UI)
+   * Auth Type: Basic Authentication (username + password)
+   */
+  log.info('🔐 [BACKGROUND] Retrieving SFTP credentials from connection configuration');
+
+  let sftpUsername: string;
+  let sftpPassword: string;
+
+  try {
+    // Retrieve credentials from the 'sftp_export_server' connection
+    const sftpCred = await ctx.credentials().getAccessToken('sftp_export_server');
+
+    if (!sftpCred?.accessToken) {
+      throw new Error('No SFTP credentials found in connection configuration');
+    }
+
+    // Decode base64 accessToken to get "username:password"
+    const rawBasicAuth = Buffer.from(sftpCred.accessToken, 'base64').toString('utf-8');
+
+    // Split on ':' to extract username and password
+    const parts = rawBasicAuth.split(':');
+
+    if (parts.length !== 2) {
+      throw new Error('Invalid SFTP credential format - expected username:password');
+    }
+
+    sftpUsername = parts[0];
+    sftpPassword = parts[1];
+
+    log.info('✅ [BACKGROUND] SFTP credentials retrieved successfully', {
+      hasUsername: !!sftpUsername,
+      hasPassword: !!sftpPassword,
+      usernameLength: sftpUsername.length,
+      passwordLength: sftpPassword.length,
+    });
+  } catch (error: any) {
+    log.error('❌ [BACKGROUND] Failed to retrieve SFTP credentials', {
+      message: error instanceof Error ? error.message : String(error),
+      stack: error instanceof Error ? error.stack : undefined,
+      errorType: error instanceof Error ? error.constructor.name : 'Error',
+      recommendation: 'Please ensure the SFTP connection "sftp_export_server" is configured in the Connections section with Basic Authentication (username and password)',
+    });
+    throw new Error(
+      `Failed to retrieve SFTP credentials from connection configuration: ${error instanceof Error ? error.message : String(error)}. ` +
+      'Please ensure the SFTP connection is configured in the Connections section with Basic Authentication (username and password)'
+    );
+  }
+
+  // Get SFTP configuration from activation variables
+  const sftpHost = activation.getVariable('sftpHost');
+  const sftpPort = parseInt(activation.getVariable('sftpPort') || '22', 10);
+  const sftpRemotePath = activation.getVariable('sftpRemotePath') || '/incoming/fulfilments/';
+
+  if (!sftpHost) {
+    log.error('⚠️ [BACKGROUND] SFTP configuration missing', {
+      recommendation: 'Configure sftpHost activation variable',
+      fulfilmentRef: fulfilmentData.ref,
+    });
+    throw new Error('SFTP configuration missing: sftpHost is required');
+  }
+
+  const sftpConfig = {
+    type: 'SFTP_XML' as const,
+    connectionId: 'sftp_export_server',
+    name: 'Fulfilment XML Export',
+    settings: {
+      host: sftpHost,
+      port: sftpPort,
+      username: sftpUsername,
+      password: sftpPassword,
+    },
+  };
+
+  const sftp = new SftpDataSource(sftpConfig, log);
+
+  try {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const fileName = `fulfilment-${fulfilmentData.ref}-${timestamp}.xml`;
+    const remoteFilePath = `${sftpRemotePath}${fileName}`;
+
+    // ✅ CRITICAL FIX: Include options parameter
+    await sftp.uploadFile(remoteFilePath, xmlBuffer, {
+      overwrite: true,
+      createDirectories: true,
+    });
+
+    log.info('✅ [BACKGROUND] Fulfilment XML exported to SFTP', {
+      fulfilmentRef: fulfilmentData.ref,
+      remoteFilePath,
+      status: fulfilmentData.status,
+      fileSizeKB: Math.round(xmlBuffer.length / 1024),
+    });
+  } finally {
+    // ✅ CRITICAL: Always dispose SFTP connection
+    await sftp.dispose();
+    log.info('🔌 [BACKGROUND] SFTP connection disposed');
+  }
+}
+```
+
+### 5. Mapping Configuration (src/config/fulfilment-xml-mapping.json)
+
+**IMPORTANT: Array Mapping Patterns**
+
+The SDK supports **two patterns** for GraphQL edges/nodes arrays. Here's exactly what happens with each:
+
+## Step-by-Step: What Each Pattern Does
+
+### Input Data (GraphQL Response)
+```javascript
+{
+  items: {
+    edges: [
+      { node: { ref: "FFI-001", requestedQuantity: 2, orderItem: { productRef: "SKU-001" } } },
+      { node: { ref: "FFI-002", requestedQuantity: 1, orderItem: { productRef: "SKU-002" } } }
+    ]
+  }
+}
+```
+
+---
+
+### Pattern 1: `source: "items.edges[*].node"` + `Item` wrapper
+
+**Config:**
+```json
+"Items": {
+  "source": "items.edges[*].node",
+  "isArray": true,
+  "fields": {
+    "Item": {
+      "fields": {
+        "@ref": { "source": "ref" },
+        "ProductRef": { "source": "orderItem.productRef" }
+      }
+    }
+  }
+}
+```
+
+**Step 1:** SDK extracts `items.edges[*].node`
+- Splits on `[*]` → `arrayPath="items.edges"`, `nodePath="node"`
+- Gets `items.edges` array: `[{ node: {...} }, { node: {...} }]`
+- Extracts `.node` from each → `[{ ref: "FFI-001", ... }, { ref: "FFI-002", ... }]`
+
+**Step 2:** For each node, maps nested `Item` fields
+- Node 1: `{ ref: "FFI-001", orderItem: { productRef: "SKU-001" } }`
+- Maps `"@ref": { "source": "ref" }` → extracts `node.ref` = `"FFI-001"`
+- Maps `"ProductRef": { "source": "orderItem.productRef" }` → extracts `node.orderItem.productRef` = `"SKU-001"`
+- Result: `{ Item: { "@ref": "FFI-001", "ProductRef": "SKU-001" } }`
+
+**Step 3:** Final mapped data
+```javascript
+{
+  Items: [
+    { Item: { "@ref": "FFI-001", "ProductRef": "SKU-001" } },
+    { Item: { "@ref": "FFI-002", "ProductRef": "SKU-002" } }
+  ]
+}
+```
+
+**Step 4:** XMLBuilder output
+```xml
+<Items>
+  <Item ref="FFI-001">
+    <ProductRef>SKU-001</ProductRef>
+  </Item>
+  <Item ref="FFI-002">
+    <ProductRef>SKU-002</ProductRef>
+  </Item>
+</Items>
+```
+
+---
+
+### Pattern 2: `source: "items.edges"` + `Item` wrapper
+
+**Config:**
+```json
+"Items": {
+  "source": "items.edges",
+  "isArray": true,
+  "fields": {
+    "Item": {
+      "fields": {
+        "@ref": { "source": "node.ref" },
+        "ProductRef": { "source": "node.orderItem.productRef" }
+      }
+    }
+  }
+}
+```
+
+**Step 1:** SDK extracts `items.edges`
+- Gets array directly: `[{ node: {...} }, { node: {...} }]` (edges array)
+
+**Step 2:** For each edge, maps nested `Item` fields
+- Edge 1: `{ node: { ref: "FFI-001", orderItem: { productRef: "SKU-001" } } }`
+- Maps `"@ref": { "source": "node.ref" }` → extracts `edge.node.ref` = `"FFI-001"`
+- Maps `"ProductRef": { "source": "node.orderItem.productRef" }` → extracts `edge.node.orderItem.productRef` = `"SKU-001"`
+- Result: `{ Item: { "@ref": "FFI-001", "ProductRef": "SKU-001" } }`
+
+**Step 3:** Final mapped data (IDENTICAL to Pattern 1)
+```javascript
+{
+  Items: [
+    { Item: { "@ref": "FFI-001", "ProductRef": "SKU-001" } },
+    { Item: { "@ref": "FFI-002", "ProductRef": "SKU-002" } }
+  ]
+}
+```
+
+**Step 4:** XMLBuilder output (IDENTICAL to Pattern 1)
+```xml
+<Items>
+  <Item ref="FFI-001">
+    <ProductRef>SKU-001</ProductRef>
+  </Item>
+  <Item ref="FFI-002">
+    <ProductRef>SKU-002</ProductRef>
+  </Item>
+</Items>
+```
+
+---
+
+## Key Differences
+
+| Aspect | Pattern 1 (`edges[*].node`) | Pattern 2 (`edges`) |
+|--------|----------------------------|---------------------|
+| **What SDK extracts** | Nodes directly: `[{ ref: "..." }, ...]` | Edges: `[{ node: {...} }, ...]` |
+| **Field paths** | `"ref"` (direct) | `"node.ref"` (need prefix) |
+| **Mapped data** | ✅ Same | ✅ Same |
+| **XML output** | ✅ Same (with `Item` wrapper) | ✅ Same (with `Item` wrapper) |
+| **Without `Item` wrapper** | ❌ Wrong XML | ❌ Wrong XML |
+
+## Why Both Work
+
+**Both patterns produce identical results** because:
+1. Pattern 1 extracts nodes first, then maps fields from nodes
+2. Pattern 2 extracts edges, then maps fields from `edge.node`
+3. Both end up with the same mapped data structure
+4. XMLBuilder converts the same structure to identical XML
+
+**The `Item` wrapper is required** for both patterns to create `<Item>` elements instead of flat `<@ref>` elements.
+
+**Recommendation:** Use Pattern 1 (`edges[*].node`) - cleaner field paths, less typing.
+
+---
+
+**Full Mapping Configuration:**
+
+```json
+{
+  "name": "fulfilment-xml-mapping",
+  "version": "1.0.0",
+  "description": "Fluent Fulfilment → XML Export Mapping for 3PL/WMS",
+  "fields": {
+    "Fulfilment": {
+      "fields": {
+        "@ref": {
+          "source": "ref",
+          "required": true,
+          "resolver": "sdk.trim"
+        },
+        "@status": {
+          "source": "status",
+          "required": true,
+          "resolver": "sdk.uppercase"
+        },
+        "OrderRef": {
+          "source": "order.ref",
+          "required": true,
+          "resolver": "sdk.trim"
+        },
+        "DeliveryType": {
+          "source": "deliveryType",
+          "required": false,
+          "resolver": "sdk.trim"
+        },
+        "Customer": {
+          "source": "order.customer",
+          "fields": {
+            "FirstName": {
+              "source": "firstName",
+              "required": false,
+              "resolver": "sdk.trim"
+            },
+            "LastName": {
+              "source": "lastName",
+              "required": false,
+              "resolver": "sdk.trim"
+            },
+            "Email": {
+              "source": "email",
+              "required": false,
+              "resolver": "sdk.trim"
+            }
+          }
+        },
+        "ToAddress": {
+          "source": "toAddress",
+          "fields": {
+            "Name": { "source": "name", "required": false, "resolver": "sdk.trim" },
+            "Street": { "source": "street", "required": false, "resolver": "sdk.trim" },
+            "Street2": { "source": "street2", "required": false, "resolver": "sdk.trim" },
+            "City": { "source": "city", "required": false, "resolver": "sdk.trim" },
+            "State": { "source": "state", "required": false, "resolver": "sdk.trim" },
+            "Postcode": { "source": "postcode", "required": false, "resolver": "sdk.trim" },
+            "Country": { "source": "country", "required": false, "resolver": "sdk.trim" }
+          }
+        },
+        "FromAddress": {
+          "source": "fromAddress",
+          "fields": {
+            "Name": { "source": "name", "required": false, "resolver": "sdk.trim" },
+            "Street": { "source": "street", "required": false, "resolver": "sdk.trim" },
+            "Street2": { "source": "street2", "required": false, "resolver": "sdk.trim" },
+            "City": { "source": "city", "required": false, "resolver": "sdk.trim" },
+            "State": { "source": "state", "required": false, "resolver": "sdk.trim" },
+            "Postcode": { "source": "postcode", "required": false, "resolver": "sdk.trim" },
+            "Country": { "source": "country", "required": false, "resolver": "sdk.trim" }
+          }
+        },
+        "Items": {
+          "source": "items.edges[*].node",
+          "isArray": true,
+          "fields": {
+            "Item": {
+              "fields": {
+                "@ref": {
+                  "source": "ref",
+                  "required": true,
+                  "resolver": "sdk.trim"
+                },
+                "ProductRef": {
+                  "source": "orderItem.productRef",
+                  "required": false,
+                  "resolver": "sdk.trim"
+                },
+                "ProductName": {
+                  "source": "orderItem.product.name",
+                  "required": false,
+                  "resolver": "sdk.trim"
+                },
+                "RequestedQuantity": {
+                  "source": "requestedQuantity",
+                  "required": false,
+                  "resolver": "sdk.parseInt"
+                },
+                "FilledQuantity": {
+                  "source": "filledQuantity",
+                  "required": true,
+                  "resolver": "sdk.parseInt"
+                },
+                "RejectedQuantity": {
+                  "source": "rejectedQuantity",
+                  "required": true,
+                  "resolver": "sdk.parseInt"
+                }
+              }
+            }
+          }
+        },
+        "CreatedOn": {
+          "source": "createdOn",
+          "required": true,
+          "resolver": "custom.formatISO8601"
+        },
+        "UpdatedOn": {
+          "source": "updatedOn",
+          "required": true,
+          "resolver": "custom.formatISO8601"
+        }
+      }
+    }
+  }
+}
+```
+
+### 6. Custom Resolvers (src/resolvers/fulfilment-resolvers.ts)
+
+```typescript
+/**
+ * Custom Resolvers for Fulfilment XML Mapping
+ *
+ * Handles complex transformations that SDK resolvers don't cover
+ */
+
+export const customResolvers = {
+  /**
+   * Format ISO 8601 date string (ensures consistent format)
+   * 
+   * Resolver signature: (value, sourceData, config, helpers) => any | Promise<any>
+   */
+  'custom.formatISO8601': (
+    value: any,
+    sourceData: any,
+    config: any,
+    helpers: any
+  ): string => {
+    if (!value) return '';
+    
+    if (value instanceof Date) {
+      return value.toISOString();
+    }
+    
+    if (typeof value === 'string') {
+      // If already ISO format, return as-is
+      if (value.includes('T') && value.includes('Z')) {
+        return value;
+      }
+      // Try to parse and format
+      const date = new Date(value);
+      if (!isNaN(date.getTime())) {
+        return date.toISOString();
+      }
+    }
+    
+    return String(value || '');
+  },
+
+  /**
+   * Format address line (handles missing fields gracefully)
+   */
+  'custom.formatAddressLine': (address: any): string => {
+    if (!address) return '';
+    
+    const parts = [
+      address.street1,
+      address.street2,
+      address.city,
+      address.state,
+      address.postcode,
+      address.country,
+    ].filter(Boolean);
+    
+    return parts.join(', ');
+  },
+
+  /**
+   * Format customer full name
+   */
+  'custom.formatCustomerName': (customer: any): string => {
+    if (!customer) return '';
+    
+    const parts = [customer.firstName, customer.lastName].filter(Boolean);
+    return parts.join(' ') || '';
+  },
+};
+```
+
+### 7. Type Definitions (src/types/fulfilment.types.ts)
+
+```typescript
+/**
+ * Type definitions for Rubix fulfilment webhooks and GraphQL responses
+ */
+
+export interface RubixFulfilmentPayload {
+  id: string;
+  name: string;
+  accountId: string;
+  retailerId: string;
+  entityRef: string;
+  entityType: 'FULFILMENT';
+  entityStatus?: string;
+  type: 'NORMAL' | string;
+  rootEntityId?: string;
+  rootEntityType?: string;
+  rootEntityRef?: string;
+  attributes?: Record<string, any>;
+  context?: Record<string, any>;
+}
+
+export interface FulfilmentData {
+  id: string;
+  ref: string;
+  status: string;
+  deliveryType: string;
+  order?: {
+    id: string;
+    ref: string;
+    customer?: {
+      firstName: string;
+      lastName: string;
+      email: string;
+    };
+  };
+  items?: {
+    edges?: Array<{
+      node: {
+        id: string;
+        ref: string;
+        requestedQuantity?: number;
+        filledQuantity: number;
+        rejectedQuantity: number;
+        orderItem?: {
+          id: string;
+          ref: string;
+          productRef: string;
+          product?: {
+            name: string;
+          };
+        };
+      };
+    }>;
+  };
+  toAddress?: {
+    name?: string;
+    street?: string;
+    street2?: string;
+    city?: string;
+    state?: string;
+    postcode?: string;
+    country?: string;
+  };
+  fromAddress?: {
+    name?: string;
+    street?: string;
+    street2?: string;
+    city?: string;
+    state?: string;
+    postcode?: string;
+    country?: string;
+  };
+  createdOn: string;
+  updatedOn: string;
+}
+```
+
+### 8. Package Configuration (package.json)
+
+```json
+{
+  "name": "rubix-fulfilment-export",
+  "version": "2.0.0",
+  "description": "Rubix fulfilment webhook handler with SFTP XML export (UniversalMapper pattern)",
+  "type": "module",
+  "main": "index.ts",
+  "scripts": {
+    "dev": "versori dev",
+    "build": "versori build",
+    "deploy": "versori deploy",
+    "test": "jest",
+    "lint": "eslint src/**/*.ts"
+  },
+  "dependencies": {
+    "@fluentcommerce/fc-connect-sdk": "^0.1.39",
+    "@versori/run": "latest"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0",
+    "jest": "^29.0.0",
+    "@types/jest": "^29.0.0",
+    "eslint": "^8.0.0"
+  }
+}
+```
+
+---
+
+## Key Patterns Explained
+
+### Pattern 1: External JSON Mapping Configuration
+
+```typescript
+// ✅ CORRECT - External JSON mapping
+import mappingConfig from '../config/fulfilment-xml-mapping.json' with { type: 'json' };
+const mapper = new UniversalMapper(mappingConfig, { customResolvers });
+const result = await mapper.map(fulfilmentData);
+
+// ❌ WRONG - Inline mapping (use inline template instead)
+const xmlData = {
+  Fulfilment: {
+    '@ref': fulfilmentData.ref,
+    // ... 50+ lines of inline mapping
+  }
+};
+```
+
+**Why:** External JSON allows XML structure changes without code modifications, supports environment-specific configs, and enables independent testing.
+
+### Pattern 2: Custom Resolvers for Complex Transformations
+
+```typescript
+// ✅ CORRECT - Custom resolver for date formatting
+export const customResolvers = {
+  'custom.formatISO8601': (value: string | Date | null | undefined): string => {
+    if (value instanceof Date) return value.toISOString();
+    // ... handle string dates
+  },
+};
+
+// In mapping config:
+{
+  "CreatedOn": {
+    "source": "createdOn",
+    "resolver": "custom.formatISO8601"
+  }
+}
+
+// ❌ WRONG - Inline transformation logic
+const createdOn = new Date(fulfilmentData.createdOn).toISOString();
+```
+
+**Why:** Custom resolvers are reusable, testable, and keep mapping config clean.
+
+### Pattern 3: UniversalMapper Before XMLBuilder
+
+```typescript
+// ✅ CORRECT - Transform first, then build XML
+const mapper = new UniversalMapper(mappingConfig, { customResolvers });
+const mappingResult = await mapper.map(fulfilmentData);
+const xmlString = xmlBuilder.build(mappingResult.data, 'FulfilmentExport');
+
+// ❌ WRONG - Build XML directly from GraphQL data
+const xmlString = xmlBuilder.build(fulfilmentData, 'FulfilmentExport');
+```
+
+**Why:** UniversalMapper handles transformations, validations, and field mapping before XML generation.
+
+---
+
+## Testing
+
+### 1. Unit Tests
+
+```typescript
+// src/services/__tests__/xml-export.test.ts
+import { exportFulfilmentToSFTP } from '../xml-export.service';
+import mappingConfig from '../../config/fulfilment-xml-mapping.json' with { type: 'json' };
+
+describe('XML Export Service', () => {
+  test('should transform fulfilment data with UniversalMapper', async () => {
+    const mockFulfilmentData = {
+      ref: 'FF-001',
+      status: 'ALLOCATED',
+      // ... test data
+    };
+
+    // Verify mapping config is loaded
+    expect(mappingConfig).toBeDefined();
+    expect(mappingConfig.fields.Fulfilment).toBeDefined();
+  });
+});
+```
+
+### 2. Mapping Config Validation
+
+```typescript
+// src/config/__tests__/mapping-config.test.ts
+import mappingConfig from '../fulfilment-xml-mapping.json' with { type: 'json' };
+
+describe('Mapping Configuration', () => {
+  test('should have valid structure', () => {
+    expect(mappingConfig.name).toBe('fulfilment-xml-mapping');
+    expect(mappingConfig.fields).toBeDefined();
+    expect(mappingConfig.fields.Fulfilment).toBeDefined();
+  });
+
+  test('should use custom resolvers for dates', () => {
+    const createdOnField = mappingConfig.fields.Fulfilment.fields.CreatedOn;
+    expect(createdOnField.resolver).toBe('custom.formatISO8601');
+  });
+});
+```
+
+---
+
+## Production Checklist
+
+- [ ] Configure `fluentPublicKey` activation variable
+- [ ] Configure Fluent Commerce connection in Versori
+- [ ] Configure `sftp_export_server` connection in Versori (Basic Auth with username/password)
+- [ ] Set SFTP activation variables (host, port, remotePath)
+- [ ] Verify SFTP remote path exists and is writable
+- [ ] Create Rubix workflow with SendWebhook action (FULFILMENT events)
+- [ ] Build Event payload with entityRef, entityType, retailerId
+- [ ] **Review and customize `config/fulfilment-xml-mapping.json`** for your 3PL schema
+- [ ] **Add custom resolvers** if needed for complex transformations
+- [ ] Test webhook signature validation
+- [ ] Test GraphQL query with real fulfilment ref
+- [ ] **Test UniversalMapper transformation** with sample data
+- [ ] **Test with large fulfilment (>100 items)** - Verify pagination works correctly
+- [ ] Test XML generation with special characters
+- [ ] Test SFTP upload and verify file on server
+- [ ] Test error scenarios (invalid signature, missing retailerId, SFTP failure)
+- [ ] Monitor response times (<100ms for validation)
+- [ ] Set up alerts for webhook/export failures
+- [ ] Document 3PL partner SFTP requirements
+- [ ] Test SFTP connection cleanup (check logs for dispose)
+- [ ] Verify pagination logs show correct item counts
+- [ ] **Version control mapping config** (track changes to XML structure)
+
+---
+
+## Troubleshooting Guide
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| "Invalid webhook signature" | Wrong public key | Verify fluentPublicKey matches Fluent environment |
+| "Missing retailerId" | Rubix payload incomplete | Add retailerId to Rubix Event payload builder |
+| "Fulfilment not found" | Invalid ref or permissions | Verify fulfilment exists and user has query permissions |
+| "Mapping failed" | Invalid mapping config | Validate JSON syntax and field paths in mapping config |
+| "Custom resolver not found" | Resolver not registered | Ensure customResolvers object includes all resolvers used in mapping |
+| "SFTP upload failed" | Connection/credentials | Test SFTP manually, verify credentials in connection and path |
+| "Failed to retrieve SFTP credentials" | Connection not configured | Ensure `sftp_export_server` connection exists with Basic Auth |
+| "SFTP connection pool exhausted" | Missing dispose() | Verify dispose() is in finally block |
+| "GraphQL query timeout" | Large dataset | Check pagination logs - pagination handles up to 1000 items |
+| "Missing items in XML" | Fulfilment >1000 items | Increase maxPages limit or implement chunked export |
+| "XML structure mismatch" | Mapping config outdated | Update `config/fulfilment-xml-mapping.json` to match 3PL schema |
+
+---
+
+## Monitoring & Alerting
+
+### Success Response
+
+```json
+{
+  "success": true,
+  "entityType": "FULFILMENT",
+  "fulfilmentRef": "FF-001",
+  "message": "Webhook validated and export started in background",
+  "timestamp": "2025-01-25T14:30:00.000Z",
+  "correlationId": "act_123",
+  "processingMode": "async"
+}
+```
+
+### Key Metrics
+
+```typescript
+const METRICS = {
+  signatureValidationMs: 45,
+  totalResponseTimeMs: 50,
+  graphqlQueryMs: 1200,
+  universalMapperMs: 150,
+  xmlGenerationMs: 50,
+  sftpUploadMs: 980,
+  totalBackgroundMs: 2380,
+};
+```
+
+---
+
+## Related Documentation
+
+- [Inline Mapping Template](./template-webhook-rubix-fulfilment-to-sftp-xml-inline.md) - For simple XML structures
+- [Order Attribute Update Template](./template-webhook-rubix-order-attribute-update.md) - For ORDER webhooks
+- [Webhook Validation Guide](../../../../02-CORE-GUIDES/webhook-validation/)
+- [UniversalMapper Guide](../../../../02-CORE-GUIDES/mapping/universal-mapper.md)
+- [Versori Platform Guide](../../../../04-REFERENCE/platforms/versori/)
+- [SFTP Data Sources Guide](../../../../02-CORE-GUIDES/data-sources/)
+
+---
+
+**Pattern**: Fulfilment webhook → GraphQL query → UniversalMapper transformation → XML generation → SFTP upload  
+**✅ Production-Ready**: Comprehensive template with external mapping, custom resolvers, and all critical fixes applied  
+**Key Learning**: External JSON mapping enables XML structure changes without code modifications, custom resolvers handle complex transformations  
+**Critical**: SFTP dispose() in finally block, retailerId validation, fire-and-forget pattern, UniversalMapper before XMLBuilder
+