@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/01-TEMPLATES/standalone/standalone-sftp-xml-graphql.md

@@ -1,1444 +1,1444 @@
-# Standalone: SFTP XML → Fluent GraphQL
-
-**FC Connect SDK Use Case Guide**
-
-> **SDK**: [@fluentcommerce/fc-connect-sdk](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk)
-> **Version**: Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
-
-**Context**: Node.js script that reads XML order files from SFTP and creates orders in Fluent Commerce via GraphQL mutations
-
-**Complexity**: Medium
-
-**Runtime**: Node.js ≥18 / Deno
-
-**Estimated Lines**: ~600 lines
-
-## What You'll Build
-
-- Standalone Node.js/Deno script
-- OAuth2 authentication
-- SFTP connection and file operations
-- XML parsing with validation
-- GraphQL mutation mapping
-- Custom resolvers for transformations
-- File archival after processing
-- Error handling and logging
-
-## SDK Methods Used
-
-- `createClient({ config: { baseUrl, clientId, clientSecret, retailerId } })` - OAuth2 client
-- `SftpDataSource(config, logger)` - SFTP operations
-- `XMLParserService` - XML parsing
-- `GraphQLMutationMapper(config, logger, { fluentClient, customResolvers })` - Map XML to GraphQL
-- `mapper.mapSafe(xmlData)` - Transform data with error handling (recommended) OR `mapper.map(xmlData)` - Transform data (throws on error) OR `mapper.mapWithNodes(xmlData)` - Transform with custom resolvers
-- `client.graphql({ query, variables })` - Execute mutation
-
----
-
-## SFTP Credential Configuration
-
-### For Standalone Scripts (Node.js/Deno)
-
-**Standalone environments** load SFTP credentials from environment variables or configuration files:
-
-```typescript
-import { SftpDataSource } from '@fluentcommerce/fc-connect-sdk';
-
-// Load from environment variables (recommended)
-const sftp = new SftpDataSource({
-  type: 'SFTP_XML',
-  connectionId: 'sftp-orders',
-  name: 'Order SFTP',
-  settings: {
-    host: process.env.SFTP_HOST || 'sftp.example.com',
-    port: parseInt(process.env.SFTP_PORT || '22'),
-    username: process.env.SFTP_USERNAME,
-
-    // Option 1: Password authentication
-    password: process.env.SFTP_PASSWORD,
-
-    // Option 2: SSH private key authentication (more secure)
-    // privateKey: fs.readFileSync(process.env.SFTP_KEY_PATH, 'utf8'),
-    // passphrase: process.env.SFTP_PASSPHRASE,
-  }
-}, logger);
-```
-
-**Environment Variable Setup:**
-
-```bash
-# .env file
-SFTP_HOST=sftp.example.com
-SFTP_PORT=22
-SFTP_USERNAME=your-username
-SFTP_PASSWORD=your-password
-
-# OR use SSH key
-# SFTP_PRIVATE_KEY_PATH=/path/to/private/key
-# SFTP_PASSPHRASE=key-passphrase
-```
-
-### For Versori Platform Deployments
-
-**Versori platform** uses connection-based credential management. See the comprehensive guide:
-
-- [SFTP Credential Access & Security](../../02-CORE-GUIDES/data-sources/data-sources-sftp-credential-access-security.md)
-
-**Key Differences:**
-
-| Aspect | Standalone (Node.js/Deno) | Versori Platform |
-|--------|---------------------------|------------------|
-| **Credential Storage** | Environment variables, files | Versori connections |
-| **Access Method** | Direct configuration | `connectionVariables`, `credentials()`, or `activation.connections` |
-| **Security** | Manual secret management | Platform-managed encryption |
-| **Rotation** | Manual updates | Centralized rotation |
-
-**Security Best Practices:**
-
-- Never hardcode credentials in source code
-- Use environment variables or secret management systems
-- Store SSH keys securely with appropriate file permissions
-- Rotate credentials regularly
-- Use SSH key authentication over passwords when possible
-
----
-
-## Complete Working Script
-
-This standalone script demonstrates a complete SFTP-to-Fluent order integration workflow.
-
-### Step 1: Install Dependencies
-
-```bash
-npm install @fluentcommerce/fc-connect-sdk ssh2-sftp-client dotenv
-npm install --save-dev @types/ssh2-sftp-client @types/node typescript
-```
-
-### Step 2: Environment Configuration
-
-Create `.env` file:
-
-```bash
-# Fluent Commerce OAuth2
-FLUENT_BASE_URL=https://yourinstance.api.fluentcommerce.com
-FLUENT_CLIENT_ID=your-oauth-client-id
-FLUENT_CLIENT_SECRET=your-oauth-client-secret
-FLUENT_RETAILER_ID=your-retailer-id
-
-# SFTP Connection
-SFTP_HOST=sftp.example.com
-SFTP_PORT=22
-SFTP_USERNAME=sftp-user
-SFTP_PASSWORD=sftp-password
-
-# OR use SSH key
-# SFTP_PRIVATE_KEY_PATH=/path/to/private/key
-# SFTP_PASSPHRASE=key-passphrase
-
-# Processing Options
-SFTP_REMOTE_PATH=/orders/incoming
-SFTP_ARCHIVE_PATH=/orders/processed
-SFTP_ERROR_PATH=/orders/errors
-FILE_PATTERN=ORDER_*.xml
-POLLING_INTERVAL_MS=60000
-```
-
-### Step 3: Main Script Implementation
-
-Create `sftp-order-sync.ts`:
-
-```typescript
-import 'dotenv/config';
-
-// FC Connect SDK+
-// Install: npm install @fluentcommerce/fc-connect-sdk@latest
-// Docs: https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk
-// GitHub: https://github.com/fluentcommerce/fc-connect-sdk
-
-import {
-  createClient,
-  classifyErrors,
-  SftpDataSource,
-  XMLParserService,
-  GraphQLMutationMapper,
-  createConsoleLogger,
-  toStructuredLogger
-} from '@fluentcommerce/fc-connect-sdk';
-
-import type {
-  FluentClient,
-  StructuredLogger,
-  MappingConfig
-} from '@fluentcommerce/fc-connect-sdk';
-
-import { readFileSync } from 'fs';
-import { join } from 'path';
-
-// ============================================================================
-// CONFIGURATION
-// ============================================================================
-
-const config = {
-  fluent: {
-    baseUrl: process.env.FLUENT_BASE_URL!,
-    clientId: process.env.FLUENT_CLIENT_ID!,
-    clientSecret: process.env.FLUENT_CLIENT_SECRET!,
-    retailerId: process.env.FLUENT_RETAILER_ID!,
-  },
-  sftp: {
-    host: process.env.SFTP_HOST!,
-    port: parseInt(process.env.SFTP_PORT || '22'),
-    username: process.env.SFTP_USERNAME!,
-    password: process.env.SFTP_PASSWORD,
-    privateKey: process.env.SFTP_PRIVATE_KEY_PATH
-      ? readFileSync(process.env.SFTP_PRIVATE_KEY_PATH, 'utf8')
-      : undefined,
-    passphrase: process.env.SFTP_PASSPHRASE,
-    remotePath: process.env.SFTP_REMOTE_PATH || '/orders/incoming',
-    archivePath: process.env.SFTP_ARCHIVE_PATH || '/orders/processed',
-    errorPath: process.env.SFTP_ERROR_PATH || '/orders/errors',
-    filePattern: process.env.FILE_PATTERN || 'ORDER_*.xml',
-  },
-  processing: {
-    pollingInterval: parseInt(process.env.POLLING_INTERVAL_MS || '60000'),
-    batchSize: 100,
-  },
-};
-
-// ============================================================================
-// GRAPHQL MAPPING CONFIGURATION
-// ============================================================================
-
-const orderMappingConfig: MappingConfig = {
-  version: '1.0',
-  name: 'SFTP XML Order to Fluent',
-  mutation: 'createOrder',
-  sourceFormat: 'xml',
-  operationName: 'CreateOrderFromSFTP',
-  arguments: {
-    input: {
-      _type: 'CreateOrderInput!',
-      // Order reference
-      ref: {
-        source: 'order.@id',
-        required: true,
-      },
-      // Order type
-      type: {
-        value: 'HD', // Home delivery
-      },
-      // Retailer reference
-      retailer: {
-        id: {
-          value: config.fluent.retailerId,
-        },
-      },
-      // Customer information
-      customer: {
-        firstName: {
-          source: 'order.customer.first-name',
-          transform: 'trim',
-          required: true,
-        },
-        lastName: {
-          source: 'order.customer.last-name',
-          transform: 'trim',
-          required: true,
-        },
-        email: {
-          source: 'order.customer.email',
-          transform: 'toLowerCase',
-          required: true,
-        },
-        phone: {
-          source: 'order.customer.phone',
-          transform: 'trim',
-        },
-      },
-      // Delivery address
-      fulfilmentChoice: {
-        deliveryType: {
-          value: 'STANDARD',
-        },
-        deliveryAddress: {
-          name: {
-            source: 'order.shipping.name',
-          },
-          street: {
-            source: 'order.shipping.street',
-            required: true,
-          },
-          city: {
-            source: 'order.shipping.city',
-            required: true,
-          },
-          state: {
-            source: 'order.shipping.state',
-          },
-          postcode: {
-            source: 'order.shipping.postcode',
-            required: true,
-          },
-          country: {
-            source: 'order.shipping.country',
-            required: true,
-          },
-        },
-      },
-      // Order items array
-      items: {
-        _array: true,
-        _autoWrap: true, // Convert single item to array
-        source: 'order.items.item',
-        _validation: {
-          minItems: 1,
-        },
-        // Fields for each item
-        ref: {
-          source: '@id',
-          required: true,
-        },
-        productRef: {
-          source: 'sku',
-          required: true,
-        },
-        quantity: {
-          source: 'quantity',
-          transform: 'parseInt',
-          required: true,
-        },
-        price: {
-          source: 'price',
-          transform: 'parseFloat',
-          required: true,
-        },
-        totalPrice: {
-          source: 'total-price',
-          transform: 'parseFloat',
-          required: true,
-        },
-        currency: {
-          value: 'USD',
-        },
-      },
-      // Order totals
-      totalPrice: {
-        source: 'order.totals.subtotal',
-        transform: 'parseFloat',
-        required: true,
-      },
-      totalTaxPrice: {
-        source: 'order.totals.tax',
-        transform: 'parseFloat',
-        defaultValue: 0,
-      },
-      // Custom attributes
-      attributes: {
-        orderDate: {
-          source: 'order.@order-date',
-          transform: 'toISO8601',
-        },
-        externalSystem: {
-          value: 'SFTP_XML',
-        },
-        sourceFile: {
-          // This will be set by custom resolver
-        },
-      },
-    },
-  },
-  returnFields: [
-    'id',
-    'ref',
-    'status',
-    'createdOn',
-    'totalPrice',
-    'customer { firstName lastName email }',
-    'items { ref productRef quantity price }',
-  ],
-  customTransforms: {
-    // Add custom transform for phone number normalization
-    normalizePhone: (value: unknown) => {
-      if (!value || typeof value !== 'string') return value;
-      // Remove all non-digit characters
-      return value.replace(/\D/g, '');
-    },
-  },
-};
-
-// ============================================================================
-// LOGGING SETUP
-// ============================================================================
-
-const logger: StructuredLogger = toStructuredLogger(createConsoleLogger(), { logLevel: 'info' });
-
-// ============================================================================
-// INITIALIZE SERVICES
-// ============================================================================
-
-let fluentClient: FluentClient;
-let sftpSource: SftpDataSource;
-let xmlParser: XMLParserService;
-let mutationMapper: GraphQLMutationMapper;
-
-async function initializeServices() {
-  logger.info('Initializing services...');
-
-  // Create Fluent client with OAuth2
-  fluentClient = await createClient({ config: config.fluent });
-
-  // Create SFTP data source
-  sftpSource = new SftpDataSource({
-    type: 'SFTP_XML',
-    connectionId: 'sftp-orders',
-    name: 'Order SFTP',
-    settings: {
-      host: config.sftp.host,
-      port: config.sftp.port,
-      username: config.sftp.username,
-      password: config.sftp.password,
-      privateKey: config.sftp.privateKey,
-      passphrase: config.sftp.passphrase,
-      remotePath: config.sftp.remotePath,
-      filePattern: config.sftp.filePattern,
-      connectionTimeout: 30000,
-      keepAliveInterval: 10000,
-    },
-  }, logger);
-
-  // Create XML parser
-  xmlParser = new XMLParserService();
-
-  // Create GraphQL mutation mapper
-  mutationMapper = new GraphQLMutationMapper(orderMappingConfig, logger, { fluentClient: fluentClient });
-
-  logger.info('Services initialized successfully');
-}
-
-// ============================================================================
-// FILE PROCESSING
-// ============================================================================
-
-interface ProcessingStats {
-  filesProcessed: number;
-  filesSucceeded: number;
-  filesFailed: number;
-  ordersCreated: number;
-  errors: Array<{ file: string; error: string }>;
-}
-
-async function processOrderFiles(): Promise<ProcessingStats> {
-  const stats: ProcessingStats = {
-    filesProcessed: 0,
-    filesSucceeded: 0,
-    filesFailed: 0,
-    ordersCreated: 0,
-    errors: [],
-  };
-
-  try {
-    logger.info('Listing files from SFTP', {
-      path: config.sftp.remotePath,
-      pattern: config.sftp.filePattern,
-    });
-
-    // List files from SFTP
-    const files = await sftpSource.listFiles({
-      remotePath: config.sftp.remotePath,
-      filePattern: config.sftp.filePattern,
-    });
-
-    logger.info(`Found ${files.length} files to process`);
-
-    // Process each file
-    for (const file of files) {
-      stats.filesProcessed++;
-
-      try {
-        logger.info(`Processing file: ${file.name}`, {
-          size: file.size,
-          lastModified: file.lastModified,
-        });
-
-        await processOrderFile(file.name, stats);
-        stats.filesSucceeded++;
-      } catch (error: any) {
-        stats.filesFailed++;
-        stats.errors.push({
-          file: file.name,
-          error: error.message,
-        });
-
-        logger.error(`Failed to process file: ${file.name}`, error);
-
-        // Move to error folder
-        try {
-          const errorPath = `${config.sftp.errorPath}/${file.name}`;
-          await sftpSource.moveFile(file.path, errorPath, true); // Use file.path for source (full path)
-          logger.info(`Moved failed file to: ${errorPath}`);
-        } catch (moveError: any) {
-          logger.error('Failed to move file to error folder', moveError);
-        }
-      }
-    }
-
-    logger.info('Processing cycle completed', stats);
-  } catch (error: any) {
-    logger.error('Error during file listing', error);
-    throw error;
-  }
-
-  return stats;
-}
-
-async function processOrderFile(fileName: string, stats: ProcessingStats): Promise<void> {
-  // Step 1: Download XML file from SFTP
-  logger.debug('Downloading file from SFTP', { fileName });
-  const xmlContent = await sftpSource.downloadFile(fileName, { encoding: 'utf8' }) as string;
-  logger.debug('Downloaded file', {
-    fileName,
-    size: xmlContent.length,
-  });
-
-  // Step 2: Parse XML
-  logger.debug('Parsing XML', { fileName });
-  const parsedXml = await xmlParser.parse(xmlContent, {
-    includeAttributes: true,
-    parseNumbers: true,
-    parseBooleans: true,
-    normalizeWhitespace: true,
-  });
-
-  logger.debug('XML parsed successfully', {
-    fileName,
-    rootElements: Object.keys(parsedXml),
-  });
-
-  // Step 3: Map to GraphQL mutation using custom resolvers
-  logger.debug('Mapping XML to GraphQL mutation', { fileName });
-
-  const customResolvers = {
-    // Resolver to inject source file name into attributes
-    'custom.sourceFile': () => fileName,
-
-    // Resolver to calculate item total if not provided
-    'custom.calculateItemTotal': (value: any, context: any) => {
-      const quantity = context.quantity || 1;
-      const price = context.price || 0;
-      return quantity * price;
-    },
-  };
-
-  // Use mapSafe() for error-safe mapping (recommended for production)
-  const result = await mutationMapper.mapSafe(parsedXml, {
-    beforeMapping: async (data, ctx) => {
-      ctx.logger?.debug('Before mapping hook', {
-        hasOrder: !!data.order,
-      });
-      return data;
-    },
-    afterMapping: async (variables, ctx) => {
-      // Inject source file name via custom attribute
-      if (variables.input && typeof variables.input === 'object') {
-        const input = variables.input as any;
-        if (input.attributes) {
-          input.attributes.sourceFile = fileName;
-        }
-      }
-
-      ctx.logger?.debug('After mapping hook', {
-        ref: (variables.input as any)?.ref,
-        itemCount: (variables.input as any)?.items?.length,
-      });
-
-      return variables;
-    },
-  });
-
-  // Check for mapping errors
-  if (!result.success) {
-    logger.error('Mapping failed', {
-      fileName,
-      errors: result.errors,
-    });
-    return; // Skip this file
-  }
-
-  logger.debug('Mapping completed', {
-    fileName,
-    orderRef: (result.variables.input as any)?.ref,
-    itemCount: (result.variables.input as any)?.items?.length,
-  });
-
-  // Step 4: Execute GraphQL mutation
-  logger.info('Creating order in Fluent', {
-    fileName,
-    orderRef: (result.variables.input as any)?.ref,
-  });
-
-  const apiResult = await fluentClient.graphql({
-    query: result.query,
-    variables: result.variables,
-  });
-
-  if (apiResult.errors && apiResult.errors.length > 0) {
-    // Classify GraphQL errors to determine retry strategy
-    const classification = classifyErrors(apiResult.errors);
-    
-    logger.error('GraphQL errors', {
-      fileName,
-      errorCode: classification.errorCode,
-      retryable: classification.retryable,
-      action: classification.action,
-      message: classification.userMessage,
-      errors: apiResult.errors,
-    });
-    
-    // Don't retry non-retryable errors (e.g., order already exists)
-    if (!classification.retryable) {
-      throw new Error(classification.userMessage);
-    }
-    
-    // For retryable errors, you could implement retry logic here
-    throw new Error(classification.userMessage);
-  }
-
-  const createdOrder = (result.data as any)?.createOrder;
-
-  logger.info('Order created successfully', {
-    fileName,
-    orderId: createdOrder?.id,
-    orderRef: createdOrder?.ref,
-    status: createdOrder?.status,
-  });
-
-  stats.ordersCreated++;
-
-  // Step 5: Archive processed file
-  const archivePath = `${config.sftp.archivePath}/${new Date().toISOString().split('T')[0]}/${fileName}`;
-  logger.debug('Archiving file', { fileName, archivePath });
-
-  // Create archive directory if it doesn't exist
-  const archiveDir = archivePath.substring(0, archivePath.lastIndexOf('/'));
-  await sftpSource.createDirectory(archiveDir, true);
-
-  // Move file to archive
-  await sftpSource.moveFile(fileName, archivePath, false);
-
-  logger.info('File archived successfully', {
-    fileName,
-    archivePath,
-  });
-}
-
-// ============================================================================
-// MAIN EXECUTION LOOP
-// ============================================================================
-
-let isRunning = false;
-let shutdownRequested = false;
-
-async function runProcessingCycle() {
-  if (isRunning) {
-    logger.warn('Processing cycle already running, skipping...');
-    return;
-  }
-
-  isRunning = true;
-
-  try {
-    const stats = await processOrderFiles();
-
-    // Log summary
-    logger.info('Processing cycle summary', {
-      filesProcessed: stats.filesProcessed,
-      filesSucceeded: stats.filesSucceeded,
-      filesFailed: stats.filesFailed,
-      ordersCreated: stats.ordersCreated,
-      errorCount: stats.errors.length,
-    });
-
-    // Log errors if any
-    if (stats.errors.length > 0) {
-      logger.warn('Processing errors occurred', {
-        errors: stats.errors.slice(0, 5), // First 5 errors
-        totalErrors: stats.errors.length,
-      });
-    }
-  } catch (error: any) {
-    logger.error('Processing cycle failed', error);
-  } finally {
-    isRunning = false;
-  }
-}
-
-async function startPolling() {
-  logger.info('Starting polling loop', {
-    interval: config.processing.pollingInterval,
-    intervalSeconds: config.processing.pollingInterval / 1000,
-  });
-
-  // Run initial cycle
-  await runProcessingCycle();
-
-  // Set up polling interval
-  const intervalId = setInterval(async () => {
-    if (shutdownRequested) {
-      clearInterval(intervalId);
-      logger.info('Polling stopped due to shutdown request');
-      return;
-    }
-
-    await runProcessingCycle();
-  }, config.processing.pollingInterval);
-
-  // Handle graceful shutdown
-  const shutdown = async () => {
-    if (shutdownRequested) return;
-
-    shutdownRequested = true;
-    logger.info('Shutdown signal received, stopping gracefully...');
-
-    clearInterval(intervalId);
-
-    // Wait for current processing to complete
-    let waitCount = 0;
-    while (isRunning && waitCount < 30) {
-      logger.info('Waiting for current processing to complete...');
-      await new Promise(resolve => setTimeout(resolve, 1000));
-      waitCount++;
-    }
-
-    // Cleanup
-    await sftpSource.dispose();
-
-    logger.info('Shutdown complete');
-    process.exit(0);
-  };
-
-  process.on('SIGINT', shutdown);
-  process.on('SIGTERM', shutdown);
-}
-
-// ============================================================================
-// ENTRY POINT
-// ============================================================================
-
-async function main() {
-  try {
-    logger.info('SFTP XML Order Sync Starting...', {
-      sftpHost: config.sftp.host,
-      remotePath: config.sftp.remotePath,
-      fluentBaseUrl: config.fluent.baseUrl,
-      retailerId: config.fluent.retailerId,
-    });
-
-    // Validate configuration
-    if (!config.fluent.clientId || !config.fluent.clientSecret) {
-      throw new Error('Fluent OAuth2 credentials are required (FLUENT_CLIENT_ID, FLUENT_CLIENT_SECRET)');
-    }
-
-    if (!config.sftp.host || !config.sftp.username) {
-      throw new Error('SFTP connection details are required (SFTP_HOST, SFTP_USERNAME)');
-    }
-
-    if (!config.sftp.password && !config.sftp.privateKey) {
-      throw new Error('SFTP authentication required (SFTP_PASSWORD or SFTP_PRIVATE_KEY_PATH)');
-    }
-
-    // Initialize services
-    await initializeServices();
-
-    // Validate connections
-    logger.info('Validating SFTP connection...');
-    const sftpValid = await sftpSource.validateConnection();
-    if (!sftpValid) {
-      throw new Error('SFTP connection validation failed');
-    }
-    logger.info('SFTP connection validated');
-
-    // Start polling loop
-    await startPolling();
-  } catch (error: any) {
-    logger.error('Fatal error during startup', error);
-    process.exit(1);
-  }
-}
-
-// Run the script
-main();
-```
-
----
-
-## Key Patterns Explained
-
-### Pattern 1: SFTP Connection & File Operations
-
-**Connection Management:**
-
-```typescript
-const sftpSource = new SftpDataSource({
-  type: 'SFTP_XML',
-  connectionId: 'sftp-orders',
-  name: 'Order SFTP',
-  settings: {
-    host: config.sftp.host,
-    port: config.sftp.port,
-    username: config.sftp.username,
-    // Authentication: password OR private key
-    password: config.sftp.password,
-    privateKey: config.sftp.privateKey,
-    passphrase: config.sftp.passphrase,
-    remotePath: config.sftp.remotePath,
-    filePattern: config.sftp.filePattern,
-    connectionTimeout: 30000,
-    keepAliveInterval: 10000,
-  },
-}, logger);
-```
-
-**File Listing:**
-
-```typescript
-// List files matching pattern
-const files = await sftpSource.listFiles({
-  remotePath: '/orders/incoming',
-  filePattern: 'ORDER_*.xml',
-});
-
-// Filter by last modified time
-const files = await sftpSource.listFiles({
-  remotePath: '/orders/incoming',
-  filePattern: 'ORDER_*.xml',
-  lastProcessedTimestamp: '2024-01-01T00:00:00Z',
-});
-```
-
-**File Download:**
-
-```typescript
-// Download as string
-const xmlContent = await sftpSource.downloadFile(fileName, {
-  encoding: 'utf8'
-}) as string;
-
-// Download as buffer
-const buffer = await sftpSource.downloadFile(fileName, {
-  asBuffer: true
-}) as Buffer;
-```
-
-**File Archival:**
-
-```typescript
-// Create archive directory (recursive)
-await sftpSource.createDirectory(archiveDir, true);
-
-// Move file to archive
-await sftpSource.moveFile(
-  fileName,
-  archivePath,
-  false // overwrite
-);
-
-// Move to error folder
-await sftpSource.moveFile(
-  fileName,
-  errorPath,
-  true // overwrite
-);
-```
-
-### Pattern 2: XML Parsing & Validation
-
-**Basic XML Parsing:**
-
-```typescript
-const xmlParser = new XMLParserService();
-
-const parsedXml = await xmlParser.parse(xmlContent, {
-  includeAttributes: true,  // Parse @id, @type attributes
-  parseNumbers: true,       // Auto-convert "123" → 123
-  parseBooleans: true,      // Auto-convert "true" → true
-  normalizeWhitespace: true, // Collapse whitespace
-});
-```
-
-**XML with Namespaces:**
-
-```typescript
-const parsedXml = await xmlParser.parse(xmlContent, {
-  includeAttributes: true,
-  removeNamespacePrefix: true, // Remove ns: prefix
-});
-```
-
-**Array Element Handling:**
-
-```typescript
-const parsedXml = await xmlParser.parse(xmlContent, {
-  includeAttributes: true,
-  arrayElements: ['item', 'product'], // Force arrays
-});
-```
-
-**XML Structure Example:**
-
-```xml
-<order id="ORD-123" order-date="2024-01-15T10:30:00Z">
-  <customer>
-    <first-name>John</first-name>
-    <last-name>Doe</last-name>
-    <email>john@example.com</email>
-    <phone>+1-555-0123</phone>
-  </customer>
-  <shipping>
-    <name>John Doe</name>
-    <street>123 Main St</street>
-    <city>New York</city>
-    <state>NY</state>
-    <postcode>10001</postcode>
-    <country>US</country>
-  </shipping>
-  <items>
-    <item id="1">
-      <sku>PROD-001</sku>
-      <quantity>2</quantity>
-      <price>29.99</price>
-      <total-price>59.98</total-price>
-    </item>
-    <item id="2">
-      <sku>PROD-002</sku>
-      <quantity>1</quantity>
-      <price>49.99</price>
-      <total-price>49.99</total-price>
-    </item>
-  </items>
-  <totals>
-    <subtotal>109.97</subtotal>
-    <tax>10.00</tax>
-    <total>119.97</total>
-  </totals>
-</order>
-```
-
-**Parsed Result:**
-
-```javascript
-{
-  order: {
-    '@id': 'ORD-123',
-    '@order-date': '2024-01-15T10:30:00Z',
-    customer: {
-      'first-name': 'John',
-      'last-name': 'Doe',
-      email: 'john@example.com',
-      phone: '+1-555-0123'
-    },
-    shipping: { ... },
-    items: {
-      item: [
-        { '@id': '1', sku: 'PROD-001', quantity: 2, price: 29.99, ... },
-        { '@id': '2', sku: 'PROD-002', quantity: 1, price: 49.99, ... }
-      ]
-    },
-    totals: {
-      subtotal: 109.97,
-      tax: 10,
-      total: 119.97
-    }
-  }
-}
-```
-
-### Pattern 3: GraphQL Mutation Mapping
-
-**Mapping Configuration:**
-
-```typescript
-const mappingConfig: MappingConfig = {
-  version: '1.0',
-  mutation: 'createOrder',
-  sourceFormat: 'xml',
-  arguments: {
-    input: {
-      _type: 'CreateOrderInput!',
-
-      // Static value
-      type: {
-        value: 'HD',
-      },
-
-      // Source path
-      ref: {
-        source: 'order.@id',
-        required: true,
-      },
-
-      // Nested object
-      customer: {
-        firstName: {
-          source: 'order.customer.first-name',
-          transform: 'trim',
-        },
-        email: {
-          source: 'order.customer.email',
-          transform: 'toLowerCase',
-        },
-      },
-
-      // Array mapping
-      items: {
-        _array: true,
-        _autoWrap: true, // Single item → [item]
-        source: 'order.items.item',
-        ref: { source: '@id' },
-        productRef: { source: 'sku' },
-        quantity: {
-          source: 'quantity',
-          transform: 'parseInt',
-        },
-        price: {
-          source: 'price',
-          transform: 'parseFloat',
-        },
-      },
-    },
-  },
-  returnFields: [
-    'id',
-    'ref',
-    'status',
-    'customer { firstName lastName }',
-  ],
-};
-```
-
-**Built-in Transforms:**
-
-- `parseInt`, `parseFloat` - Number conversion
-- `toString` - String conversion
-- `toUpperCase`, `toLowerCase`, `trim` - String manipulation
-- `toBoolean` - Boolean conversion
-- `toISO8601`, `toDate` - Date formatting
-
-**Execute Mapping:**
-
-```typescript
-const mapper = new GraphQLMutationMapper(
-  mappingConfig,
-  fluentClient,
-  logger
-);
-
-// Use mapSafe() for error-safe mapping (recommended)
-const result = await mapper.mapSafe(parsedXml);
-if (!result.success) {
-  console.error('Mapping failed:', result.errors);
-  return;
-}
-// Result: { success: true, query: '...', variables: { ... } }
-```
-
-### Pattern 4: Custom Resolvers for Complex Logic
-
-**Custom Resolver Example:**
-
-```typescript
-const customResolvers = {
-  // Simple resolver
-  'custom.sourceFile': (value: any, context: any) => {
-    return fileName;
-  },
-
-  // Context-aware resolver
-  'custom.calculateTotal': (value: any, context: any) => {
-    const quantity = context.quantity || 1;
-    const price = context.price || 0;
-    return quantity * price;
-  },
-
-  // Async resolver (API call)
-  'custom.lookupCustomer': async (value: any, context: any, config: any, helpers: any) => {
-    const email = helpers.get(context, 'customer.email');
-    const query = `query GetCustomer($email: String!) {
-      customerByEmail(email: $email) {
-        id
-        ref
-      }
-    }`;
-    const result = await fluentClient.graphql({
-      query,
-      variables: { email },
-    });
-    return result.data?.customerByEmail?.id;
-  },
-
-  // Conditional logic
-  'custom.determineShippingMethod': (value: any, context: any) => {
-    const totalPrice = context.totalPrice || 0;
-    if (totalPrice > 100) {
-      return 'EXPRESS';
-    } else if (totalPrice > 50) {
-      return 'STANDARD';
-    } else {
-      return 'ECONOMY';
-    }
-  },
-};
-
-// ✅ CORRECT: Use mapWithNodes() when custom resolvers are defined
-const payload = await mapper.mapWithNodes(parsedXml, customResolvers, {
-  fluentClient: fluentClient as any,
-  config: {},
-  helpers: { fluentClient: fluentClient as any, logger },
-});
-
-// ❌ WRONG: map() does NOT accept custom resolvers
-// const payload = await mapper.map(parsedXml, customResolvers);
-```
-
-**Helper Functions Available:**
-
-```typescript
-// helpers.get - Extract nested value
-const email = helpers.get(context, 'customer.email');
-
-// helpers.logger - Logging
-helpers.logger.info('Processing order', { ref: orderRef });
-
-// helpers.ensureArray - Array conversion
-const items = helpers.ensureArray(context.items);
-```
-
-### Pattern 5: File Management (Archive/Error)
-
-**Archival Strategy:**
-
-```typescript
-// Date-based folder structure
-const today = new Date().toISOString().split('T')[0];
-const archivePath = `${config.sftp.archivePath}/${today}/${fileName}`;
-
-// Create directory if needed
-await sftpSource.createDirectory(
-  `${config.sftp.archivePath}/${today}`,
-  true // recursive
-);
-
-// Move file
-await sftpSource.moveFile(fileName, archivePath, false);
-```
-
-**Error Handling:**
-
-```typescript
-try {
-  await processOrderFile(fileName, stats);
-  // Success: Archive
-  await sftpSource.moveFile(fileName, archivePath, false);
-} catch (error: any) {
-  // Failure: Move to error folder
-  const errorPath = `${config.sftp.errorPath}/${fileName}`;
-  await sftpSource.moveFile(fileName, errorPath, true);
-
-  // Create error report
-  const errorReport = {
-    file: fileName,
-    error: error.message,
-    timestamp: new Date().toISOString(),
-  };
-  await sftpSource.uploadFile(null, 2, JSON.stringify(errorReport),
-    `${config.sftp.errorPath}/${fileName}.error.json`
-  );
-}
-```
-
----
-
-## Deployment Options
-
-### Option 1: Local Execution
-
-```bash
-# Development
-npm run dev
-
-# Production
-npm run build
-node dist/sftp-order-sync.js
-```
-
-### Option 2: Docker Container
-
-Create `Dockerfile`:
-
-```dockerfile
-FROM node:18-alpine
-
-WORKDIR /app
-
-# Install dependencies
-COPY package*.json ./
-RUN npm ci --only=production
-
-# Copy application
-COPY dist/ ./dist/
-COPY .env .env
-
-# Run
-CMD ["node", "dist/sftp-order-sync.js"]
-```
-
-Build and run:
-
-```bash
-docker build -t sftp-order-sync .
-docker run -d --name sftp-order-sync --env-file .env sftp-order-sync
-```
-
-### Option 3: Systemd Service
-
-Create `/etc/systemd/system/sftp-order-sync.service`:
-
-```ini
-[Unit]
-Description=SFTP Order Sync Service
-After=network.target
-
-[Service]
-Type=simple
-User=nodeapp
-WorkingDirectory=/opt/sftp-order-sync
-ExecStart=/usr/bin/node /opt/sftp-order-sync/dist/sftp-order-sync.js
-Restart=always
-RestartSec=10
-StandardOutput=journal
-StandardError=journal
-SyslogIdentifier=sftp-order-sync
-Environment=NODE_ENV=production
-
-[Install]
-WantedBy=multi-user.target
-```
-
-Enable and start:
-
-```bash
-sudo systemctl enable sftp-order-sync
-sudo systemctl start sftp-order-sync
-sudo journalctl -u sftp-order-sync -f
-```
-
-### Option 4: Cron Job
-
-Create `/opt/sftp-order-sync/run.sh`:
-
-```bash
-#!/bin/bash
-cd /opt/sftp-order-sync
-node dist/sftp-order-sync.js >> /var/log/sftp-order-sync.log 2>&1
-```
-
-Add to crontab:
-
-```bash
-# Run every 5 minutes
-*/5 * * * * /opt/sftp-order-sync/run.sh
-```
-
----
-
-## Testing
-
-### Test with Sample XML
-
-Create `test-order.xml`:
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<order id="TEST-001" order-date="2024-01-15T10:30:00Z">
-  <customer>
-    <first-name>John</first-name>
-    <last-name>Doe</last-name>
-    <email>john.doe@example.com</email>
-    <phone>+1-555-0123</phone>
-  </customer>
-  <shipping>
-    <name>John Doe</name>
-    <street>123 Main Street</street>
-    <city>New York</city>
-    <state>NY</state>
-    <postcode>10001</postcode>
-    <country>US</country>
-  </shipping>
-  <items>
-    <item id="1">
-      <sku>PROD-001</sku>
-      <quantity>2</quantity>
-      <price>29.99</price>
-      <total-price>59.98</total-price>
-    </item>
-    <item id="2">
-      <sku>PROD-002</sku>
-      <quantity>1</quantity>
-      <price>49.99</price>
-      <total-price>49.99</total-price>
-    </item>
-  </items>
-  <totals>
-    <subtotal>109.97</subtotal>
-    <tax>10.00</tax>
-    <total>119.97</total>
-  </totals>
-</order>
-```
-
-Upload to SFTP:
-
-```bash
-sftp user@sftp.example.com
-cd /orders/incoming
-put test-order.xml ORDER_TEST_001.xml
-```
-
-Monitor logs:
-
-```bash
-# Local
-npm run dev
-
-# Docker
-docker logs -f sftp-order-sync
-
-# Systemd
-sudo journalctl -u sftp-order-sync -f
-```
-
----
-
-## Common Issues
-
-### Issue 1: SFTP Connection Timeout
-
-**Symptoms:**
-
-```
-Error: SFTP connection timeout after 30000ms
-```
-
-**Solution:**
-
-```typescript
-// Increase timeout in SFTP config
-settings: {
-  connectionTimeout: 60000, // 60 seconds
-  keepAliveInterval: 10000, // 10 seconds
-}
-```
-
-### Issue 2: XML Parsing Fails for Attributes
-
-**Symptoms:**
-
-```
-Error: Cannot read property '@id' of undefined
-```
-
-**Solution:**
-
-```typescript
-// Ensure includeAttributes is enabled
-const parsedXml = await xmlParser.parse(xmlContent, {
-  includeAttributes: true, // REQUIRED for @attributes
-});
-```
-
-### Issue 3: Array Items Not Mapping
-
-**Symptoms:**
-
-```
-Error: Expected array at path 'order.items.item' but got object
-```
-
-**Solution:**
-
-```typescript
-// Enable auto-wrap for single items
-items: {
-  _array: true,
-  _autoWrap: true, // Convert single item to [item]
-  source: 'order.items.item',
-}
-```
-
-### Issue 4: GraphQL Mutation Fails
-
-**Symptoms:**
-
-```
-GraphQL errors: Field 'ref' is required but was null
-```
-
-**Solution:**
-
-```typescript
-// Check source path and add validation
-ref: {
-  source: 'order.@id', // Correct attribute path
-  required: true,      // Fail fast if missing
-}
-
-// Debug parsed XML structure
-logger.debug('Parsed XML structure', {
-  keys: Object.keys(parsedXml),
-  orderKeys: Object.keys(parsedXml.order || {}),
-});
-```
-
-### Issue 5: Files Not Archiving
-
-**Symptoms:**
-
-```
-Error: Directory does not exist: /orders/processed/2024-01-15
-```
-
-**Solution:**
-
-```typescript
-// Create directory before moving
-const archiveDir = archivePath.substring(0, archivePath.lastIndexOf('/'));
-await sftpSource.createDirectory(archiveDir, true); // recursive
-
-// Then move file
-await sftpSource.moveFile(fileName, archivePath, false);
-```
-
----
-
-## Related Guides
-
-- **[SFTP Credential Access & Security](../../02-CORE-GUIDES/data-sources/data-sources-sftp-credential-access-security.md)** - Comprehensive SFTP credential management guide
-- **[S3 CSV Inventory Sync](./s3-csv-batch-api.md)** - Similar pattern for S3 CSV files
-- **[GraphQL Query Export](./graphql-query-export.md)** - GraphQL extraction pattern
-- **[Field Mapping Pattern](../patterns/field-mapping-universal.md)** - Complete field mapping reference
-- **[Error Handling Pattern](../../02-CORE-GUIDES/advanced-services/advanced-services-readme.md)** - Comprehensive error strategies
-
----
-
-## Summary
-
-This guide demonstrates a production-ready SFTP XML to Fluent GraphQL integration with:
-
-- OAuth2 authentication
-- SFTP connection pooling
-- XML parsing with attribute support
-- GraphQL mutation mapping
-- Custom resolvers for complex logic
-- File archival and error handling
-- Graceful shutdown and retry logic
-
-The complete script is ~600 lines and includes all necessary error handling, logging, and deployment configurations for production use.
+# Standalone: SFTP XML → Fluent GraphQL
+
+**FC Connect SDK Use Case Guide**
+
+> **SDK**: [@fluentcommerce/fc-connect-sdk](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk)
+> **Version**: Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
+
+**Context**: Node.js script that reads XML order files from SFTP and creates orders in Fluent Commerce via GraphQL mutations
+
+**Complexity**: Medium
+
+**Runtime**: Node.js ≥18 / Deno
+
+**Estimated Lines**: ~600 lines
+
+## What You'll Build
+
+- Standalone Node.js/Deno script
+- OAuth2 authentication
+- SFTP connection and file operations
+- XML parsing with validation
+- GraphQL mutation mapping
+- Custom resolvers for transformations
+- File archival after processing
+- Error handling and logging
+
+## SDK Methods Used
+
+- `createClient({ config: { baseUrl, clientId, clientSecret, retailerId } })` - OAuth2 client
+- `SftpDataSource(config, logger)` - SFTP operations
+- `XMLParserService` - XML parsing
+- `GraphQLMutationMapper(config, logger, { fluentClient, customResolvers })` - Map XML to GraphQL
+- `mapper.mapSafe(xmlData)` - Transform data with error handling (recommended) OR `mapper.map(xmlData)` - Transform data (throws on error) OR `mapper.mapWithNodes(xmlData)` - Transform with custom resolvers
+- `client.graphql({ query, variables })` - Execute mutation
+
+---
+
+## SFTP Credential Configuration
+
+### For Standalone Scripts (Node.js/Deno)
+
+**Standalone environments** load SFTP credentials from environment variables or configuration files:
+
+```typescript
+import { SftpDataSource } from '@fluentcommerce/fc-connect-sdk';
+
+// Load from environment variables (recommended)
+const sftp = new SftpDataSource({
+  type: 'SFTP_XML',
+  connectionId: 'sftp-orders',
+  name: 'Order SFTP',
+  settings: {
+    host: process.env.SFTP_HOST || 'sftp.example.com',
+    port: parseInt(process.env.SFTP_PORT || '22'),
+    username: process.env.SFTP_USERNAME,
+
+    // Option 1: Password authentication
+    password: process.env.SFTP_PASSWORD,
+
+    // Option 2: SSH private key authentication (more secure)
+    // privateKey: fs.readFileSync(process.env.SFTP_KEY_PATH, 'utf8'),
+    // passphrase: process.env.SFTP_PASSPHRASE,
+  }
+}, logger);
+```
+
+**Environment Variable Setup:**
+
+```bash
+# .env file
+SFTP_HOST=sftp.example.com
+SFTP_PORT=22
+SFTP_USERNAME=your-username
+SFTP_PASSWORD=your-password
+
+# OR use SSH key
+# SFTP_PRIVATE_KEY_PATH=/path/to/private/key
+# SFTP_PASSPHRASE=key-passphrase
+```
+
+### For Versori Platform Deployments
+
+**Versori platform** uses connection-based credential management. See the comprehensive guide:
+
+- [SFTP Credential Access & Security](../../02-CORE-GUIDES/data-sources/data-sources-sftp-credential-access-security.md)
+
+**Key Differences:**
+
+| Aspect | Standalone (Node.js/Deno) | Versori Platform |
+|--------|---------------------------|------------------|
+| **Credential Storage** | Environment variables, files | Versori connections |
+| **Access Method** | Direct configuration | `connectionVariables`, `credentials()`, or `activation.connections` |
+| **Security** | Manual secret management | Platform-managed encryption |
+| **Rotation** | Manual updates | Centralized rotation |
+
+**Security Best Practices:**
+
+- Never hardcode credentials in source code
+- Use environment variables or secret management systems
+- Store SSH keys securely with appropriate file permissions
+- Rotate credentials regularly
+- Use SSH key authentication over passwords when possible
+
+---
+
+## Complete Working Script
+
+This standalone script demonstrates a complete SFTP-to-Fluent order integration workflow.
+
+### Step 1: Install Dependencies
+
+```bash
+npm install @fluentcommerce/fc-connect-sdk ssh2-sftp-client dotenv
+npm install --save-dev @types/ssh2-sftp-client @types/node typescript
+```
+
+### Step 2: Environment Configuration
+
+Create `.env` file:
+
+```bash
+# Fluent Commerce OAuth2
+FLUENT_BASE_URL=https://yourinstance.api.fluentcommerce.com
+FLUENT_CLIENT_ID=your-oauth-client-id
+FLUENT_CLIENT_SECRET=your-oauth-client-secret
+FLUENT_RETAILER_ID=your-retailer-id
+
+# SFTP Connection
+SFTP_HOST=sftp.example.com
+SFTP_PORT=22
+SFTP_USERNAME=sftp-user
+SFTP_PASSWORD=sftp-password
+
+# OR use SSH key
+# SFTP_PRIVATE_KEY_PATH=/path/to/private/key
+# SFTP_PASSPHRASE=key-passphrase
+
+# Processing Options
+SFTP_REMOTE_PATH=/orders/incoming
+SFTP_ARCHIVE_PATH=/orders/processed
+SFTP_ERROR_PATH=/orders/errors
+FILE_PATTERN=ORDER_*.xml
+POLLING_INTERVAL_MS=60000
+```
+
+### Step 3: Main Script Implementation
+
+Create `sftp-order-sync.ts`:
+
+```typescript
+import 'dotenv/config';
+
+// FC Connect SDK+
+// Install: npm install @fluentcommerce/fc-connect-sdk@latest
+// Docs: https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk
+// GitHub: https://github.com/fluentcommerce/fc-connect-sdk
+
+import {
+  createClient,
+  classifyErrors,
+  SftpDataSource,
+  XMLParserService,
+  GraphQLMutationMapper,
+  createConsoleLogger,
+  toStructuredLogger
+} from '@fluentcommerce/fc-connect-sdk';
+
+import type {
+  FluentClient,
+  StructuredLogger,
+  MappingConfig
+} from '@fluentcommerce/fc-connect-sdk';
+
+import { readFileSync } from 'fs';
+import { join } from 'path';
+
+// ============================================================================
+// CONFIGURATION
+// ============================================================================
+
+const config = {
+  fluent: {
+    baseUrl: process.env.FLUENT_BASE_URL!,
+    clientId: process.env.FLUENT_CLIENT_ID!,
+    clientSecret: process.env.FLUENT_CLIENT_SECRET!,
+    retailerId: process.env.FLUENT_RETAILER_ID!,
+  },
+  sftp: {
+    host: process.env.SFTP_HOST!,
+    port: parseInt(process.env.SFTP_PORT || '22'),
+    username: process.env.SFTP_USERNAME!,
+    password: process.env.SFTP_PASSWORD,
+    privateKey: process.env.SFTP_PRIVATE_KEY_PATH
+      ? readFileSync(process.env.SFTP_PRIVATE_KEY_PATH, 'utf8')
+      : undefined,
+    passphrase: process.env.SFTP_PASSPHRASE,
+    remotePath: process.env.SFTP_REMOTE_PATH || '/orders/incoming',
+    archivePath: process.env.SFTP_ARCHIVE_PATH || '/orders/processed',
+    errorPath: process.env.SFTP_ERROR_PATH || '/orders/errors',
+    filePattern: process.env.FILE_PATTERN || 'ORDER_*.xml',
+  },
+  processing: {
+    pollingInterval: parseInt(process.env.POLLING_INTERVAL_MS || '60000'),
+    batchSize: 100,
+  },
+};
+
+// ============================================================================
+// GRAPHQL MAPPING CONFIGURATION
+// ============================================================================
+
+const orderMappingConfig: MappingConfig = {
+  version: '1.0',
+  name: 'SFTP XML Order to Fluent',
+  mutation: 'createOrder',
+  sourceFormat: 'xml',
+  operationName: 'CreateOrderFromSFTP',
+  arguments: {
+    input: {
+      _type: 'CreateOrderInput!',
+      // Order reference
+      ref: {
+        source: 'order.@id',
+        required: true,
+      },
+      // Order type
+      type: {
+        value: 'HD', // Home delivery
+      },
+      // Retailer reference
+      retailer: {
+        id: {
+          value: config.fluent.retailerId,
+        },
+      },
+      // Customer information
+      customer: {
+        firstName: {
+          source: 'order.customer.first-name',
+          transform: 'trim',
+          required: true,
+        },
+        lastName: {
+          source: 'order.customer.last-name',
+          transform: 'trim',
+          required: true,
+        },
+        email: {
+          source: 'order.customer.email',
+          transform: 'toLowerCase',
+          required: true,
+        },
+        phone: {
+          source: 'order.customer.phone',
+          transform: 'trim',
+        },
+      },
+      // Delivery address
+      fulfilmentChoice: {
+        deliveryType: {
+          value: 'STANDARD',
+        },
+        deliveryAddress: {
+          name: {
+            source: 'order.shipping.name',
+          },
+          street: {
+            source: 'order.shipping.street',
+            required: true,
+          },
+          city: {
+            source: 'order.shipping.city',
+            required: true,
+          },
+          state: {
+            source: 'order.shipping.state',
+          },
+          postcode: {
+            source: 'order.shipping.postcode',
+            required: true,
+          },
+          country: {
+            source: 'order.shipping.country',
+            required: true,
+          },
+        },
+      },
+      // Order items array
+      items: {
+        _array: true,
+        _autoWrap: true, // Convert single item to array
+        source: 'order.items.item',
+        _validation: {
+          minItems: 1,
+        },
+        // Fields for each item
+        ref: {
+          source: '@id',
+          required: true,
+        },
+        productRef: {
+          source: 'sku',
+          required: true,
+        },
+        quantity: {
+          source: 'quantity',
+          transform: 'parseInt',
+          required: true,
+        },
+        price: {
+          source: 'price',
+          transform: 'parseFloat',
+          required: true,
+        },
+        totalPrice: {
+          source: 'total-price',
+          transform: 'parseFloat',
+          required: true,
+        },
+        currency: {
+          value: 'USD',
+        },
+      },
+      // Order totals
+      totalPrice: {
+        source: 'order.totals.subtotal',
+        transform: 'parseFloat',
+        required: true,
+      },
+      totalTaxPrice: {
+        source: 'order.totals.tax',
+        transform: 'parseFloat',
+        defaultValue: 0,
+      },
+      // Custom attributes
+      attributes: {
+        orderDate: {
+          source: 'order.@order-date',
+          transform: 'toISO8601',
+        },
+        externalSystem: {
+          value: 'SFTP_XML',
+        },
+        sourceFile: {
+          // This will be set by custom resolver
+        },
+      },
+    },
+  },
+  returnFields: [
+    'id',
+    'ref',
+    'status',
+    'createdOn',
+    'totalPrice',
+    'customer { firstName lastName email }',
+    'items { ref productRef quantity price }',
+  ],
+  customTransforms: {
+    // Add custom transform for phone number normalization
+    normalizePhone: (value: unknown) => {
+      if (!value || typeof value !== 'string') return value;
+      // Remove all non-digit characters
+      return value.replace(/\D/g, '');
+    },
+  },
+};
+
+// ============================================================================
+// LOGGING SETUP
+// ============================================================================
+
+const logger: StructuredLogger = toStructuredLogger(createConsoleLogger(), { logLevel: 'info' });
+
+// ============================================================================
+// INITIALIZE SERVICES
+// ============================================================================
+
+let fluentClient: FluentClient;
+let sftpSource: SftpDataSource;
+let xmlParser: XMLParserService;
+let mutationMapper: GraphQLMutationMapper;
+
+async function initializeServices() {
+  logger.info('Initializing services...');
+
+  // Create Fluent client with OAuth2
+  fluentClient = await createClient({ config: config.fluent });
+
+  // Create SFTP data source
+  sftpSource = new SftpDataSource({
+    type: 'SFTP_XML',
+    connectionId: 'sftp-orders',
+    name: 'Order SFTP',
+    settings: {
+      host: config.sftp.host,
+      port: config.sftp.port,
+      username: config.sftp.username,
+      password: config.sftp.password,
+      privateKey: config.sftp.privateKey,
+      passphrase: config.sftp.passphrase,
+      remotePath: config.sftp.remotePath,
+      filePattern: config.sftp.filePattern,
+      connectionTimeout: 30000,
+      keepAliveInterval: 10000,
+    },
+  }, logger);
+
+  // Create XML parser
+  xmlParser = new XMLParserService();
+
+  // Create GraphQL mutation mapper
+  mutationMapper = new GraphQLMutationMapper(orderMappingConfig, logger, { fluentClient: fluentClient });
+
+  logger.info('Services initialized successfully');
+}
+
+// ============================================================================
+// FILE PROCESSING
+// ============================================================================
+
+interface ProcessingStats {
+  filesProcessed: number;
+  filesSucceeded: number;
+  filesFailed: number;
+  ordersCreated: number;
+  errors: Array<{ file: string; error: string }>;
+}
+
+async function processOrderFiles(): Promise<ProcessingStats> {
+  const stats: ProcessingStats = {
+    filesProcessed: 0,
+    filesSucceeded: 0,
+    filesFailed: 0,
+    ordersCreated: 0,
+    errors: [],
+  };
+
+  try {
+    logger.info('Listing files from SFTP', {
+      path: config.sftp.remotePath,
+      pattern: config.sftp.filePattern,
+    });
+
+    // List files from SFTP
+    const files = await sftpSource.listFiles({
+      remotePath: config.sftp.remotePath,
+      filePattern: config.sftp.filePattern,
+    });
+
+    logger.info(`Found ${files.length} files to process`);
+
+    // Process each file
+    for (const file of files) {
+      stats.filesProcessed++;
+
+      try {
+        logger.info(`Processing file: ${file.name}`, {
+          size: file.size,
+          lastModified: file.lastModified,
+        });
+
+        await processOrderFile(file.name, stats);
+        stats.filesSucceeded++;
+      } catch (error: any) {
+        stats.filesFailed++;
+        stats.errors.push({
+          file: file.name,
+          error: error.message,
+        });
+
+        logger.error(`Failed to process file: ${file.name}`, error);
+
+        // Move to error folder
+        try {
+          const errorPath = `${config.sftp.errorPath}/${file.name}`;
+          await sftpSource.moveFile(file.path, errorPath, true); // Use file.path for source (full path)
+          logger.info(`Moved failed file to: ${errorPath}`);
+        } catch (moveError: any) {
+          logger.error('Failed to move file to error folder', moveError);
+        }
+      }
+    }
+
+    logger.info('Processing cycle completed', stats);
+  } catch (error: any) {
+    logger.error('Error during file listing', error);
+    throw error;
+  }
+
+  return stats;
+}
+
+async function processOrderFile(fileName: string, stats: ProcessingStats): Promise<void> {
+  // Step 1: Download XML file from SFTP
+  logger.debug('Downloading file from SFTP', { fileName });
+  const xmlContent = await sftpSource.downloadFile(fileName, { encoding: 'utf8' }) as string;
+  logger.debug('Downloaded file', {
+    fileName,
+    size: xmlContent.length,
+  });
+
+  // Step 2: Parse XML
+  logger.debug('Parsing XML', { fileName });
+  const parsedXml = await xmlParser.parse(xmlContent, {
+    includeAttributes: true,
+    parseNumbers: true,
+    parseBooleans: true,
+    normalizeWhitespace: true,
+  });
+
+  logger.debug('XML parsed successfully', {
+    fileName,
+    rootElements: Object.keys(parsedXml),
+  });
+
+  // Step 3: Map to GraphQL mutation using custom resolvers
+  logger.debug('Mapping XML to GraphQL mutation', { fileName });
+
+  const customResolvers = {
+    // Resolver to inject source file name into attributes
+    'custom.sourceFile': () => fileName,
+
+    // Resolver to calculate item total if not provided
+    'custom.calculateItemTotal': (value: any, context: any) => {
+      const quantity = context.quantity || 1;
+      const price = context.price || 0;
+      return quantity * price;
+    },
+  };
+
+  // Use mapSafe() for error-safe mapping (recommended for production)
+  const result = await mutationMapper.mapSafe(parsedXml, {
+    beforeMapping: async (data, ctx) => {
+      ctx.logger?.debug('Before mapping hook', {
+        hasOrder: !!data.order,
+      });
+      return data;
+    },
+    afterMapping: async (variables, ctx) => {
+      // Inject source file name via custom attribute
+      if (variables.input && typeof variables.input === 'object') {
+        const input = variables.input as any;
+        if (input.attributes) {
+          input.attributes.sourceFile = fileName;
+        }
+      }
+
+      ctx.logger?.debug('After mapping hook', {
+        ref: (variables.input as any)?.ref,
+        itemCount: (variables.input as any)?.items?.length,
+      });
+
+      return variables;
+    },
+  });
+
+  // Check for mapping errors
+  if (!result.success) {
+    logger.error('Mapping failed', {
+      fileName,
+      errors: result.errors,
+    });
+    return; // Skip this file
+  }
+
+  logger.debug('Mapping completed', {
+    fileName,
+    orderRef: (result.variables.input as any)?.ref,
+    itemCount: (result.variables.input as any)?.items?.length,
+  });
+
+  // Step 4: Execute GraphQL mutation
+  logger.info('Creating order in Fluent', {
+    fileName,
+    orderRef: (result.variables.input as any)?.ref,
+  });
+
+  const apiResult = await fluentClient.graphql({
+    query: result.query,
+    variables: result.variables,
+  });
+
+  if (apiResult.errors && apiResult.errors.length > 0) {
+    // Classify GraphQL errors to determine retry strategy
+    const classification = classifyErrors(apiResult.errors);
+    
+    logger.error('GraphQL errors', {
+      fileName,
+      errorCode: classification.errorCode,
+      retryable: classification.retryable,
+      action: classification.action,
+      message: classification.userMessage,
+      errors: apiResult.errors,
+    });
+    
+    // Don't retry non-retryable errors (e.g., order already exists)
+    if (!classification.retryable) {
+      throw new Error(classification.userMessage);
+    }
+    
+    // For retryable errors, you could implement retry logic here
+    throw new Error(classification.userMessage);
+  }
+
+  const createdOrder = (result.data as any)?.createOrder;
+
+  logger.info('Order created successfully', {
+    fileName,
+    orderId: createdOrder?.id,
+    orderRef: createdOrder?.ref,
+    status: createdOrder?.status,
+  });
+
+  stats.ordersCreated++;
+
+  // Step 5: Archive processed file
+  const archivePath = `${config.sftp.archivePath}/${new Date().toISOString().split('T')[0]}/${fileName}`;
+  logger.debug('Archiving file', { fileName, archivePath });
+
+  // Create archive directory if it doesn't exist
+  const archiveDir = archivePath.substring(0, archivePath.lastIndexOf('/'));
+  await sftpSource.createDirectory(archiveDir, true);
+
+  // Move file to archive
+  await sftpSource.moveFile(fileName, archivePath, false);
+
+  logger.info('File archived successfully', {
+    fileName,
+    archivePath,
+  });
+}
+
+// ============================================================================
+// MAIN EXECUTION LOOP
+// ============================================================================
+
+let isRunning = false;
+let shutdownRequested = false;
+
+async function runProcessingCycle() {
+  if (isRunning) {
+    logger.warn('Processing cycle already running, skipping...');
+    return;
+  }
+
+  isRunning = true;
+
+  try {
+    const stats = await processOrderFiles();
+
+    // Log summary
+    logger.info('Processing cycle summary', {
+      filesProcessed: stats.filesProcessed,
+      filesSucceeded: stats.filesSucceeded,
+      filesFailed: stats.filesFailed,
+      ordersCreated: stats.ordersCreated,
+      errorCount: stats.errors.length,
+    });
+
+    // Log errors if any
+    if (stats.errors.length > 0) {
+      logger.warn('Processing errors occurred', {
+        errors: stats.errors.slice(0, 5), // First 5 errors
+        totalErrors: stats.errors.length,
+      });
+    }
+  } catch (error: any) {
+    logger.error('Processing cycle failed', error);
+  } finally {
+    isRunning = false;
+  }
+}
+
+async function startPolling() {
+  logger.info('Starting polling loop', {
+    interval: config.processing.pollingInterval,
+    intervalSeconds: config.processing.pollingInterval / 1000,
+  });
+
+  // Run initial cycle
+  await runProcessingCycle();
+
+  // Set up polling interval
+  const intervalId = setInterval(async () => {
+    if (shutdownRequested) {
+      clearInterval(intervalId);
+      logger.info('Polling stopped due to shutdown request');
+      return;
+    }
+
+    await runProcessingCycle();
+  }, config.processing.pollingInterval);
+
+  // Handle graceful shutdown
+  const shutdown = async () => {
+    if (shutdownRequested) return;
+
+    shutdownRequested = true;
+    logger.info('Shutdown signal received, stopping gracefully...');
+
+    clearInterval(intervalId);
+
+    // Wait for current processing to complete
+    let waitCount = 0;
+    while (isRunning && waitCount < 30) {
+      logger.info('Waiting for current processing to complete...');
+      await new Promise(resolve => setTimeout(resolve, 1000));
+      waitCount++;
+    }
+
+    // Cleanup
+    await sftpSource.dispose();
+
+    logger.info('Shutdown complete');
+    process.exit(0);
+  };
+
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+}
+
+// ============================================================================
+// ENTRY POINT
+// ============================================================================
+
+async function main() {
+  try {
+    logger.info('SFTP XML Order Sync Starting...', {
+      sftpHost: config.sftp.host,
+      remotePath: config.sftp.remotePath,
+      fluentBaseUrl: config.fluent.baseUrl,
+      retailerId: config.fluent.retailerId,
+    });
+
+    // Validate configuration
+    if (!config.fluent.clientId || !config.fluent.clientSecret) {
+      throw new Error('Fluent OAuth2 credentials are required (FLUENT_CLIENT_ID, FLUENT_CLIENT_SECRET)');
+    }
+
+    if (!config.sftp.host || !config.sftp.username) {
+      throw new Error('SFTP connection details are required (SFTP_HOST, SFTP_USERNAME)');
+    }
+
+    if (!config.sftp.password && !config.sftp.privateKey) {
+      throw new Error('SFTP authentication required (SFTP_PASSWORD or SFTP_PRIVATE_KEY_PATH)');
+    }
+
+    // Initialize services
+    await initializeServices();
+
+    // Validate connections
+    logger.info('Validating SFTP connection...');
+    const sftpValid = await sftpSource.validateConnection();
+    if (!sftpValid) {
+      throw new Error('SFTP connection validation failed');
+    }
+    logger.info('SFTP connection validated');
+
+    // Start polling loop
+    await startPolling();
+  } catch (error: any) {
+    logger.error('Fatal error during startup', error);
+    process.exit(1);
+  }
+}
+
+// Run the script
+main();
+```
+
+---
+
+## Key Patterns Explained
+
+### Pattern 1: SFTP Connection & File Operations
+
+**Connection Management:**
+
+```typescript
+const sftpSource = new SftpDataSource({
+  type: 'SFTP_XML',
+  connectionId: 'sftp-orders',
+  name: 'Order SFTP',
+  settings: {
+    host: config.sftp.host,
+    port: config.sftp.port,
+    username: config.sftp.username,
+    // Authentication: password OR private key
+    password: config.sftp.password,
+    privateKey: config.sftp.privateKey,
+    passphrase: config.sftp.passphrase,
+    remotePath: config.sftp.remotePath,
+    filePattern: config.sftp.filePattern,
+    connectionTimeout: 30000,
+    keepAliveInterval: 10000,
+  },
+}, logger);
+```
+
+**File Listing:**
+
+```typescript
+// List files matching pattern
+const files = await sftpSource.listFiles({
+  remotePath: '/orders/incoming',
+  filePattern: 'ORDER_*.xml',
+});
+
+// Filter by last modified time
+const files = await sftpSource.listFiles({
+  remotePath: '/orders/incoming',
+  filePattern: 'ORDER_*.xml',
+  lastProcessedTimestamp: '2024-01-01T00:00:00Z',
+});
+```
+
+**File Download:**
+
+```typescript
+// Download as string
+const xmlContent = await sftpSource.downloadFile(fileName, {
+  encoding: 'utf8'
+}) as string;
+
+// Download as buffer
+const buffer = await sftpSource.downloadFile(fileName, {
+  asBuffer: true
+}) as Buffer;
+```
+
+**File Archival:**
+
+```typescript
+// Create archive directory (recursive)
+await sftpSource.createDirectory(archiveDir, true);
+
+// Move file to archive
+await sftpSource.moveFile(
+  fileName,
+  archivePath,
+  false // overwrite
+);
+
+// Move to error folder
+await sftpSource.moveFile(
+  fileName,
+  errorPath,
+  true // overwrite
+);
+```
+
+### Pattern 2: XML Parsing & Validation
+
+**Basic XML Parsing:**
+
+```typescript
+const xmlParser = new XMLParserService();
+
+const parsedXml = await xmlParser.parse(xmlContent, {
+  includeAttributes: true,  // Parse @id, @type attributes
+  parseNumbers: true,       // Auto-convert "123" → 123
+  parseBooleans: true,      // Auto-convert "true" → true
+  normalizeWhitespace: true, // Collapse whitespace
+});
+```
+
+**XML with Namespaces:**
+
+```typescript
+const parsedXml = await xmlParser.parse(xmlContent, {
+  includeAttributes: true,
+  removeNamespacePrefix: true, // Remove ns: prefix
+});
+```
+
+**Array Element Handling:**
+
+```typescript
+const parsedXml = await xmlParser.parse(xmlContent, {
+  includeAttributes: true,
+  arrayElements: ['item', 'product'], // Force arrays
+});
+```
+
+**XML Structure Example:**
+
+```xml
+<order id="ORD-123" order-date="2024-01-15T10:30:00Z">
+  <customer>
+    <first-name>John</first-name>
+    <last-name>Doe</last-name>
+    <email>john@example.com</email>
+    <phone>+1-555-0123</phone>
+  </customer>
+  <shipping>
+    <name>John Doe</name>
+    <street>123 Main St</street>
+    <city>New York</city>
+    <state>NY</state>
+    <postcode>10001</postcode>
+    <country>US</country>
+  </shipping>
+  <items>
+    <item id="1">
+      <sku>PROD-001</sku>
+      <quantity>2</quantity>
+      <price>29.99</price>
+      <total-price>59.98</total-price>
+    </item>
+    <item id="2">
+      <sku>PROD-002</sku>
+      <quantity>1</quantity>
+      <price>49.99</price>
+      <total-price>49.99</total-price>
+    </item>
+  </items>
+  <totals>
+    <subtotal>109.97</subtotal>
+    <tax>10.00</tax>
+    <total>119.97</total>
+  </totals>
+</order>
+```
+
+**Parsed Result:**
+
+```javascript
+{
+  order: {
+    '@id': 'ORD-123',
+    '@order-date': '2024-01-15T10:30:00Z',
+    customer: {
+      'first-name': 'John',
+      'last-name': 'Doe',
+      email: 'john@example.com',
+      phone: '+1-555-0123'
+    },
+    shipping: { ... },
+    items: {
+      item: [
+        { '@id': '1', sku: 'PROD-001', quantity: 2, price: 29.99, ... },
+        { '@id': '2', sku: 'PROD-002', quantity: 1, price: 49.99, ... }
+      ]
+    },
+    totals: {
+      subtotal: 109.97,
+      tax: 10,
+      total: 119.97
+    }
+  }
+}
+```
+
+### Pattern 3: GraphQL Mutation Mapping
+
+**Mapping Configuration:**
+
+```typescript
+const mappingConfig: MappingConfig = {
+  version: '1.0',
+  mutation: 'createOrder',
+  sourceFormat: 'xml',
+  arguments: {
+    input: {
+      _type: 'CreateOrderInput!',
+
+      // Static value
+      type: {
+        value: 'HD',
+      },
+
+      // Source path
+      ref: {
+        source: 'order.@id',
+        required: true,
+      },
+
+      // Nested object
+      customer: {
+        firstName: {
+          source: 'order.customer.first-name',
+          transform: 'trim',
+        },
+        email: {
+          source: 'order.customer.email',
+          transform: 'toLowerCase',
+        },
+      },
+
+      // Array mapping
+      items: {
+        _array: true,
+        _autoWrap: true, // Single item → [item]
+        source: 'order.items.item',
+        ref: { source: '@id' },
+        productRef: { source: 'sku' },
+        quantity: {
+          source: 'quantity',
+          transform: 'parseInt',
+        },
+        price: {
+          source: 'price',
+          transform: 'parseFloat',
+        },
+      },
+    },
+  },
+  returnFields: [
+    'id',
+    'ref',
+    'status',
+    'customer { firstName lastName }',
+  ],
+};
+```
+
+**Built-in Transforms:**
+
+- `parseInt`, `parseFloat` - Number conversion
+- `toString` - String conversion
+- `toUpperCase`, `toLowerCase`, `trim` - String manipulation
+- `toBoolean` - Boolean conversion
+- `toISO8601`, `toDate` - Date formatting
+
+**Execute Mapping:**
+
+```typescript
+const mapper = new GraphQLMutationMapper(
+  mappingConfig,
+  fluentClient,
+  logger
+);
+
+// Use mapSafe() for error-safe mapping (recommended)
+const result = await mapper.mapSafe(parsedXml);
+if (!result.success) {
+  console.error('Mapping failed:', result.errors);
+  return;
+}
+// Result: { success: true, query: '...', variables: { ... } }
+```
+
+### Pattern 4: Custom Resolvers for Complex Logic
+
+**Custom Resolver Example:**
+
+```typescript
+const customResolvers = {
+  // Simple resolver
+  'custom.sourceFile': (value: any, context: any) => {
+    return fileName;
+  },
+
+  // Context-aware resolver
+  'custom.calculateTotal': (value: any, context: any) => {
+    const quantity = context.quantity || 1;
+    const price = context.price || 0;
+    return quantity * price;
+  },
+
+  // Async resolver (API call)
+  'custom.lookupCustomer': async (value: any, context: any, config: any, helpers: any) => {
+    const email = helpers.get(context, 'customer.email');
+    const query = `query GetCustomer($email: String!) {
+      customerByEmail(email: $email) {
+        id
+        ref
+      }
+    }`;
+    const result = await fluentClient.graphql({
+      query,
+      variables: { email },
+    });
+    return result.data?.customerByEmail?.id;
+  },
+
+  // Conditional logic
+  'custom.determineShippingMethod': (value: any, context: any) => {
+    const totalPrice = context.totalPrice || 0;
+    if (totalPrice > 100) {
+      return 'EXPRESS';
+    } else if (totalPrice > 50) {
+      return 'STANDARD';
+    } else {
+      return 'ECONOMY';
+    }
+  },
+};
+
+// ✅ CORRECT: Use mapWithNodes() when custom resolvers are defined
+const payload = await mapper.mapWithNodes(parsedXml, customResolvers, {
+  fluentClient: fluentClient as any,
+  config: {},
+  helpers: { fluentClient: fluentClient as any, logger },
+});
+
+// ❌ WRONG: map() does NOT accept custom resolvers
+// const payload = await mapper.map(parsedXml, customResolvers);
+```
+
+**Helper Functions Available:**
+
+```typescript
+// helpers.get - Extract nested value
+const email = helpers.get(context, 'customer.email');
+
+// helpers.logger - Logging
+helpers.logger.info('Processing order', { ref: orderRef });
+
+// helpers.ensureArray - Array conversion
+const items = helpers.ensureArray(context.items);
+```
+
+### Pattern 5: File Management (Archive/Error)
+
+**Archival Strategy:**
+
+```typescript
+// Date-based folder structure
+const today = new Date().toISOString().split('T')[0];
+const archivePath = `${config.sftp.archivePath}/${today}/${fileName}`;
+
+// Create directory if needed
+await sftpSource.createDirectory(
+  `${config.sftp.archivePath}/${today}`,
+  true // recursive
+);
+
+// Move file
+await sftpSource.moveFile(fileName, archivePath, false);
+```
+
+**Error Handling:**
+
+```typescript
+try {
+  await processOrderFile(fileName, stats);
+  // Success: Archive
+  await sftpSource.moveFile(fileName, archivePath, false);
+} catch (error: any) {
+  // Failure: Move to error folder
+  const errorPath = `${config.sftp.errorPath}/${fileName}`;
+  await sftpSource.moveFile(fileName, errorPath, true);
+
+  // Create error report
+  const errorReport = {
+    file: fileName,
+    error: error.message,
+    timestamp: new Date().toISOString(),
+  };
+  await sftpSource.uploadFile(null, 2, JSON.stringify(errorReport),
+    `${config.sftp.errorPath}/${fileName}.error.json`
+  );
+}
+```
+
+---
+
+## Deployment Options
+
+### Option 1: Local Execution
+
+```bash
+# Development
+npm run dev
+
+# Production
+npm run build
+node dist/sftp-order-sync.js
+```
+
+### Option 2: Docker Container
+
+Create `Dockerfile`:
+
+```dockerfile
+FROM node:18-alpine
+
+WORKDIR /app
+
+# Install dependencies
+COPY package*.json ./
+RUN npm ci --only=production
+
+# Copy application
+COPY dist/ ./dist/
+COPY .env .env
+
+# Run
+CMD ["node", "dist/sftp-order-sync.js"]
+```
+
+Build and run:
+
+```bash
+docker build -t sftp-order-sync .
+docker run -d --name sftp-order-sync --env-file .env sftp-order-sync
+```
+
+### Option 3: Systemd Service
+
+Create `/etc/systemd/system/sftp-order-sync.service`:
+
+```ini
+[Unit]
+Description=SFTP Order Sync Service
+After=network.target
+
+[Service]
+Type=simple
+User=nodeapp
+WorkingDirectory=/opt/sftp-order-sync
+ExecStart=/usr/bin/node /opt/sftp-order-sync/dist/sftp-order-sync.js
+Restart=always
+RestartSec=10
+StandardOutput=journal
+StandardError=journal
+SyslogIdentifier=sftp-order-sync
+Environment=NODE_ENV=production
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Enable and start:
+
+```bash
+sudo systemctl enable sftp-order-sync
+sudo systemctl start sftp-order-sync
+sudo journalctl -u sftp-order-sync -f
+```
+
+### Option 4: Cron Job
+
+Create `/opt/sftp-order-sync/run.sh`:
+
+```bash
+#!/bin/bash
+cd /opt/sftp-order-sync
+node dist/sftp-order-sync.js >> /var/log/sftp-order-sync.log 2>&1
+```
+
+Add to crontab:
+
+```bash
+# Run every 5 minutes
+*/5 * * * * /opt/sftp-order-sync/run.sh
+```
+
+---
+
+## Testing
+
+### Test with Sample XML
+
+Create `test-order.xml`:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<order id="TEST-001" order-date="2024-01-15T10:30:00Z">
+  <customer>
+    <first-name>John</first-name>
+    <last-name>Doe</last-name>
+    <email>john.doe@example.com</email>
+    <phone>+1-555-0123</phone>
+  </customer>
+  <shipping>
+    <name>John Doe</name>
+    <street>123 Main Street</street>
+    <city>New York</city>
+    <state>NY</state>
+    <postcode>10001</postcode>
+    <country>US</country>
+  </shipping>
+  <items>
+    <item id="1">
+      <sku>PROD-001</sku>
+      <quantity>2</quantity>
+      <price>29.99</price>
+      <total-price>59.98</total-price>
+    </item>
+    <item id="2">
+      <sku>PROD-002</sku>
+      <quantity>1</quantity>
+      <price>49.99</price>
+      <total-price>49.99</total-price>
+    </item>
+  </items>
+  <totals>
+    <subtotal>109.97</subtotal>
+    <tax>10.00</tax>
+    <total>119.97</total>
+  </totals>
+</order>
+```
+
+Upload to SFTP:
+
+```bash
+sftp user@sftp.example.com
+cd /orders/incoming
+put test-order.xml ORDER_TEST_001.xml
+```
+
+Monitor logs:
+
+```bash
+# Local
+npm run dev
+
+# Docker
+docker logs -f sftp-order-sync
+
+# Systemd
+sudo journalctl -u sftp-order-sync -f
+```
+
+---
+
+## Common Issues
+
+### Issue 1: SFTP Connection Timeout
+
+**Symptoms:**
+
+```
+Error: SFTP connection timeout after 30000ms
+```
+
+**Solution:**
+
+```typescript
+// Increase timeout in SFTP config
+settings: {
+  connectionTimeout: 60000, // 60 seconds
+  keepAliveInterval: 10000, // 10 seconds
+}
+```
+
+### Issue 2: XML Parsing Fails for Attributes
+
+**Symptoms:**
+
+```
+Error: Cannot read property '@id' of undefined
+```
+
+**Solution:**
+
+```typescript
+// Ensure includeAttributes is enabled
+const parsedXml = await xmlParser.parse(xmlContent, {
+  includeAttributes: true, // REQUIRED for @attributes
+});
+```
+
+### Issue 3: Array Items Not Mapping
+
+**Symptoms:**
+
+```
+Error: Expected array at path 'order.items.item' but got object
+```
+
+**Solution:**
+
+```typescript
+// Enable auto-wrap for single items
+items: {
+  _array: true,
+  _autoWrap: true, // Convert single item to [item]
+  source: 'order.items.item',
+}
+```
+
+### Issue 4: GraphQL Mutation Fails
+
+**Symptoms:**
+
+```
+GraphQL errors: Field 'ref' is required but was null
+```
+
+**Solution:**
+
+```typescript
+// Check source path and add validation
+ref: {
+  source: 'order.@id', // Correct attribute path
+  required: true,      // Fail fast if missing
+}
+
+// Debug parsed XML structure
+logger.debug('Parsed XML structure', {
+  keys: Object.keys(parsedXml),
+  orderKeys: Object.keys(parsedXml.order || {}),
+});
+```
+
+### Issue 5: Files Not Archiving
+
+**Symptoms:**
+
+```
+Error: Directory does not exist: /orders/processed/2024-01-15
+```
+
+**Solution:**
+
+```typescript
+// Create directory before moving
+const archiveDir = archivePath.substring(0, archivePath.lastIndexOf('/'));
+await sftpSource.createDirectory(archiveDir, true); // recursive
+
+// Then move file
+await sftpSource.moveFile(fileName, archivePath, false);
+```
+
+---
+
+## Related Guides
+
+- **[SFTP Credential Access & Security](../../02-CORE-GUIDES/data-sources/data-sources-sftp-credential-access-security.md)** - Comprehensive SFTP credential management guide
+- **[S3 CSV Inventory Sync](./s3-csv-batch-api.md)** - Similar pattern for S3 CSV files
+- **[GraphQL Query Export](./graphql-query-export.md)** - GraphQL extraction pattern
+- **[Field Mapping Pattern](../patterns/field-mapping-universal.md)** - Complete field mapping reference
+- **[Error Handling Pattern](../../02-CORE-GUIDES/advanced-services/advanced-services-readme.md)** - Comprehensive error strategies
+
+---
+
+## Summary
+
+This guide demonstrates a production-ready SFTP XML to Fluent GraphQL integration with:
+
+- OAuth2 authentication
+- SFTP connection pooling
+- XML parsing with attribute support
+- GraphQL mutation mapping
+- Custom resolvers for complex logic
+- File archival and error handling
+- Graceful shutdown and retry logic
+
+The complete script is ~600 lines and includes all necessary error handling, logging, and deployment configurations for production use.