@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/01-TEMPLATES/standalone/standalone-asn-inbound-processing.md

@@ -1,1209 +1,1209 @@
-# Standalone: ASN Inbound Processing (WMS/3PL Integration)
-
-**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 processes Advanced Ship Notices (ASNs) from WMS/3PL systems via SFTP, creating expected receipts in Fluent Commerce and confirming actual receipts
-
-**Complexity**: Medium
-
-**Runtime**: Node.js ≥18 / Deno
-
-**Estimated Lines**: ~900 lines
-
-**Volume**: 10-100 ASNs/day, 100-5000 units per ASN
-
-**Latency**: Near real-time (< 5 min)
-
-**Pattern**: SFTP polling → EDI/XML parsing → GraphQL mutation
-
-## What You'll Build
-
-- Standalone Node.js/Deno script (no Versori)
-- SFTP integration for ASN file polling
-- EDI 856 (X12) and XML ASN format parsing
-- Container hierarchy mapping (shipment → pallet → case → item)
-- Expected receipt creation in Fluent Commerce
-- Actual receipt confirmation with variance handling
-- Cross-dock scenario support (direct to customer)
-- Email alerts for significant variances (> 5%)
-- State management to prevent duplicate processing
-- Comprehensive error handling and logging
-
-## SDK Methods Used
-
-- `createClient({ config: { baseUrl, clientId, clientSecret, retailerId } })` - OAuth2 client
-- `SftpDataSource(config, logger)` - SFTP operations
-- `XMLParserService` - XML ASN parsing
-- `GraphQLMutationMapper` - ASN → Fluent GraphQL mutations
-- `VersoriFileTracker` (adapted for standalone) - Deduplication
-- `client.graphql(payload)` - Execute mutations
-- Custom EDI 856 parser for X12 format
-
----
-
-## Complete Working Implementation
-
-### 1. Project Setup
-
-```bash
-# Create project directory
-mkdir asn-inbound-processor
-cd asn-inbound-processor
-
-# Initialize Node.js project
-npm init -y
-
-# Install dependencies
-npm install @fluentcommerce/fc-connect-sdk dotenv nodemailer
-```
-
-### 2. Environment Configuration
-
-Create `.env` file:
-
-```env
-# Fluent Commerce Configuration
-FLUENT_BASE_URL=https://api.fluentcommerce.com
-FLUENT_CLIENT_ID=your-oauth2-client-id
-FLUENT_CLIENT_SECRET=your-oauth2-client-secret
-FLUENT_RETAILER_ID=your-retailer-id
-
-# SFTP Configuration
-SFTP_HOST=sftp.3pl-provider.com
-SFTP_PORT=22
-SFTP_USERNAME=your-username
-SFTP_PASSWORD=your-password
-# OR use private key authentication
-# SFTP_PRIVATE_KEY=/path/to/private_key
-# SFTP_PASSPHRASE=key-passphrase
-
-# SFTP Paths
-SFTP_INBOUND_PATH=/inbound/asn
-SFTP_PROCESSED_PATH=/processed/asn
-SFTP_ERROR_PATH=/errors/asn
-SFTP_FILE_PATTERN=*.{xml,edi,856}
-
-# Processing Configuration
-ASN_FORMAT=xml# Options: xml, edi856
-ENABLE_ACTUAL_RECEIPT_CONFIRMATION=true
-VARIANCE_ALERT_THRESHOLD=0.05# 5% threshold for email alerts
-
-# Email Alerts (for variances)
-SMTP_HOST=smtp.gmail.com
-SMTP_PORT=587
-SMTP_USER=alerts@yourcompany.com
-SMTP_PASSWORD=your-smtp-password
-ALERT_EMAIL_TO=warehouse-mgr@yourcompany.com
-
-# State Management
-STATE_STORAGE_PATH=./data/asn-state.json
-
-# Optional: Cross-dock support
-ENABLE_CROSS_DOCK=true
-CROSS_DOCK_LOCATION_PREFIX=CUSTOMER_
-
-# Logging
-LOG_LEVEL=info# Options: debug, info, warn, error
-```
-
-### 3. Main Script Implementation (src/asn-processor.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,
-  SftpDataSource,
-  XMLParserService,
-  GraphQLMutationMapper,
-  type FluentClient,
-  type StructuredLogger,
-  createConsoleLogger,
-  toStructuredLogger
-} from '@fluentcommerce/fc-connect-sdk';
-
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
-import { join, dirname } from 'path';
-import nodemailer from 'nodemailer';
-
-// ============================================================================
-// TYPES & INTERFACES
-// ============================================================================
-
-interface AsnDocument {
-  asnNumber: string;
-  shipmentDate: string;
-  expectedDeliveryDate: string;
-  carrier: string;
-  trackingNumber?: string;
-  origin: {
-    locationRef: string;
-    name: string;
-    address?: string;
-  };
-  destination: {
-    locationRef: string;
-    name: string;
-    address?: string;
-  };
-  containers: Container[];
-  totalQuantity: number;
-}
-
-interface Container {
-  id: string;
-  type: 'PALLET' | 'CASE' | 'CARTON';
-  sscc?: string;
-  items: AsnItem[];
-  children?: Container[];
-}
-
-interface AsnItem {
-  sku: string;
-  productName?: string;
-  expectedQuantity: number;
-  actualQuantity?: number;
-  uom: string;
-  lotNumber?: string;
-  serialNumbers?: string[];
-  expiryDate?: string;
-}
-
-interface ProcessingState {
-  processedFiles: Record<string, {
-    timestamp: string;
-    asnNumber: string;
-    status: 'success' | 'failed';
-    receiptId?: string;
-  }>;
-}
-
-// ============================================================================
-// 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
-      ? readFileSync(process.env.SFTP_PRIVATE_KEY, 'utf8')
-      : undefined,
-    passphrase: process.env.SFTP_PASSPHRASE,
-    inboundPath: process.env.SFTP_INBOUND_PATH || '/inbound/asn',
-    processedPath: process.env.SFTP_PROCESSED_PATH || '/processed/asn',
-    errorPath: process.env.SFTP_ERROR_PATH || '/errors/asn',
-    filePattern: process.env.SFTP_FILE_PATTERN || '*.{xml,edi,856}',
-  },
-  processing: {
-    asnFormat: process.env.ASN_FORMAT || 'xml',
-    enableActualReceipt: process.env.ENABLE_ACTUAL_RECEIPT_CONFIRMATION === 'true',
-    varianceThreshold: parseFloat(process.env.VARIANCE_ALERT_THRESHOLD || '0.05'),
-    enableCrossDock: process.env.ENABLE_CROSS_DOCK === 'true',
-    crossDockLocationPrefix: process.env.CROSS_DOCK_LOCATION_PREFIX || 'CUSTOMER_',
-  },
-  email: {
-    smtpHost: process.env.SMTP_HOST,
-    smtpPort: parseInt(process.env.SMTP_PORT || '587'),
-    smtpUser: process.env.SMTP_USER,
-    smtpPassword: process.env.SMTP_PASSWORD,
-    alertEmailTo: process.env.ALERT_EMAIL_TO,
-  },
-  state: {
-    storagePath: process.env.STATE_STORAGE_PATH || './data/asn-state.json',
-  },
-};
-
-// ============================================================================
-// STATE MANAGEMENT
-// ============================================================================
-
-class StateManager {
-  private state: ProcessingState;
-  private storagePath: string;
-
-  constructor(storagePath: string) {
-    this.storagePath = storagePath;
-    this.state = this.loadState();
-  }
-
-  private loadState(): ProcessingState {
-    try {
-      if (existsSync(this.storagePath)) {
-        const data = readFileSync(this.storagePath, 'utf8');
-        return JSON.parse(data);
-      }
-    } catch (error) {
-      console.warn('Failed to load state, starting fresh', error);
-    }
-    return { processedFiles: {} };
-  }
-
-  private saveState(): void {
-    try {
-      const dir = dirname(this.storagePath);
-      if (!existsSync(dir)) {
-        mkdirSync(dir, { recursive: true });
-      }
-      writeFileSync(this.storagePath, JSON.stringify(this.state, null, 2));
-    } catch (error) {
-      console.error('Failed to save state', error);
-    }
-  }
-
-  isFileProcessed(fileName: string): boolean {
-    return !!this.state.processedFiles[fileName];
-  }
-
-  markFileProcessed(fileName: string, asnNumber: string, receiptId?: string): void {
-    this.state.processedFiles[fileName] = {
-      timestamp: new Date().toISOString(),
-      asnNumber,
-      status: 'success',
-      receiptId,
-    };
-    this.saveState();
-  }
-
-  markFileFailed(fileName: string, asnNumber: string): void {
-    this.state.processedFiles[fileName] = {
-      timestamp: new Date().toISOString(),
-      asnNumber,
-      status: 'failed',
-    };
-    this.saveState();
-  }
-}
-
-// ============================================================================
-// EMAIL ALERTS
-// ============================================================================
-
-class EmailAlerter {
-  private transporter: any;
-  private enabled: boolean;
-
-  constructor(config: typeof config.email) {
-    this.enabled = !!(config.smtpHost && config.smtpUser && config.alertEmailTo);
-
-    if (this.enabled) {
-      this.transporter = nodemailer.createTransport({
-        host: config.smtpHost,
-        port: config.smtpPort,
-        secure: config.smtpPort === 465,
-        auth: {
-          user: config.smtpUser,
-          pass: config.smtpPassword,
-        },
-      });
-    }
-  }
-
-  async sendVarianceAlert(asnNumber: string, variances: any[]): Promise<void> {
-    if (!this.enabled) return;
-
-    const html = `
-      <h2>ASN Variance Alert: ${asnNumber}</h2>
-      <p>Significant variances detected during receipt confirmation:</p>
-      <table border="1" cellpadding="5">
-        <tr>
-          <th>SKU</th>
-          <th>Expected</th>
-          <th>Actual</th>
-          <th>Variance</th>
-          <th>%</th>
-        </tr>
-        ${variances.map(v => `
-          <tr>
-            <td>${v.sku}</td>
-            <td>${v.expected}</td>
-            <td>${v.actual}</td>
-            <td style="color: ${v.variance < 0 ? 'red' : 'orange'}">${v.variance > 0 ? '+' : ''}${v.variance}</td>
-            <td>${(v.variancePercent * 100).toFixed(1)}%</td>
-          </tr>
-        `).join('')}
-      </table>
-      <p><strong>Action Required:</strong> Review and investigate variances.</p>
-    `;
-
-    try {
-      await this.transporter.sendMail({
-        from: config.email.smtpUser,
-        to: config.email.alertEmailTo,
-        subject: `⚠️ ASN Variance Alert: ${asnNumber}`,
-        html,
-      });
-    } catch (error) {
-      console.error('Failed to send email alert', error);
-    }
-  }
-}
-
-// ============================================================================
-// ASN PROCESSOR
-// ============================================================================
-
-class AsnProcessor {
-  private client: FluentClient;
-  private sftpSource: SftpDataSource;
-  private xmlParser: XMLParserService;
-  private logger: StructuredLogger;
-  private stateManager: StateManager;
-  private emailAlerter: EmailAlerter;
-
-  constructor() {
-    this.logger = toStructuredLogger(createConsoleLogger(), { logLevel: 'info' });
-  }
-
-  async initialize(): Promise<void> {
-    this.logger.info('Initializing ASN processor...');
-
-    // Initialize Fluent client
-    this.client = await createClient({ config: config.fluent });
-
-    // Initialize SFTP data source
-    this.sftpSource = new SftpDataSource({
-      type: 'SFTP_XML',
-      connectionId: 'asn-sftp',
-      name: 'ASN 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,
-      },
-    }, this.logger);
-
-    // Initialize XML parser
-    this.xmlParser = new XMLParserService();
-
-    // Initialize state manager
-    this.stateManager = new StateManager(config.state.storagePath);
-
-    // Initialize email alerter
-    this.emailAlerter = new EmailAlerter(config.email);
-
-    // Validate SFTP connection
-    const isConnected = await this.sftpSource.validateConnection();
-    if (!isConnected) {
-      throw new Error('SFTP connection validation failed');
-    }
-
-    this.logger.info('ASN processor initialized successfully');
-  }
-
-  async processFiles(): Promise<void> {
-    this.logger.info('Starting ASN file processing cycle');
-
-    try {
-      // List files from SFTP
-      const files = await this.sftpSource.listFiles({
-        remotePath: config.sftp.inboundPath,
-        filePattern: config.sftp.filePattern,
-      });
-
-      this.logger.info(`Found ${files.length} ASN files`);
-
-      for (const file of files) {
-        // Skip already processed files
-        if (this.stateManager.isFileProcessed(file.name)) {
-          this.logger.debug(`Skipping already processed file: ${file.name}`);
-          continue;
-        }
-
-        try {
-          await this.processAsnFile(file.name);
-        } catch (error: any) {
-          this.logger.error(`Failed to process ASN file: ${file.name}`, error);
-
-          // Move to error folder
-          const errorPath = `${config.sftp.errorPath}/${file.name}`;
-          await this.sftpSource.moveFile(file.path, errorPath, true); // Use file.path for source (full path)
-        }
-      }
-
-      this.logger.info('ASN processing cycle completed');
-    } catch (error: any) {
-      this.logger.error('ASN processing cycle failed', error);
-      throw error;
-    }
-  }
-
-  private async processAsnFile(fileName: string): Promise<void> {
-    this.logger.info(`Processing ASN file: ${fileName}`);
-
-    // Download file
-    const content = await this.sftpSource.downloadFile(fileName, {
-      encoding: 'utf8'
-    }) as string;
-
-    // Parse based on format
-    let asnDoc: AsnDocument;
-    if (config.processing.asnFormat === 'edi856') {
-      asnDoc = this.parseEdi856(content);
-    } else {
-      asnDoc = await this.parseXmlAsn(content);
-    }
-
-    this.logger.info(`Parsed ASN: ${asnDoc.asnNumber}`, {
-      containers: asnDoc.containers.length,
-      totalQuantity: asnDoc.totalQuantity,
-    });
-
-    // Create expected receipt in Fluent
-    const receiptId = await this.createExpectedReceipt(asnDoc);
-    this.logger.info(`Created expected receipt: ${receiptId}`);
-
-    // If actual receipt confirmation is enabled, process it
-    if (config.processing.enableActualReceipt) {
-      await this.confirmActualReceipt(asnDoc, receiptId);
-    }
-
-    // Mark as processed
-    this.stateManager.markFileProcessed(fileName, asnDoc.asnNumber, receiptId);
-
-    // Archive file
-    const archivePath = `${config.sftp.processedPath}/${new Date().toISOString().split('T')[0]}/${fileName}`;
-    await this.sftpSource.createDirectory(dirname(archivePath), true);
-    await this.sftpSource.moveFile(fileName, archivePath, false);
-
-    this.logger.info(`ASN file processed successfully: ${fileName}`);
-  }
-
-  private parseEdi856(ediContent: string): AsnDocument {
-    // Simplified EDI 856 parser - implement full parser based on your needs
-    const segments = ediContent.split('~').map(s => s.trim()).filter(Boolean);
-
-    const asnDoc: AsnDocument = {
-      asnNumber: '',
-      shipmentDate: '',
-      expectedDeliveryDate: '',
-      carrier: '',
-      origin: { locationRef: '', name: '' },
-      destination: { locationRef: '', name: '' },
-      containers: [],
-      totalQuantity: 0,
-    };
-
-    for (const segment of segments) {
-      const elements = segment.split('*');
-      const segmentId = elements[0];
-
-      if (segmentId === 'BSN') {
-        // Beginning Segment for Ship Notice
-        asnDoc.asnNumber = elements[2];
-        asnDoc.shipmentDate = elements[3];
-      } else if (segmentId === 'LIN') {
-        // Item Identification
-        // Parse item details...
-      }
-      // Add more segment parsing as needed
-    }
-
-    return asnDoc;
-  }
-
-  private async parseXmlAsn(xmlContent: string): Promise<AsnDocument> {
-    const parsed = await this.xmlParser.parse(xmlContent, {
-      includeAttributes: true,
-      parseNumbers: true,
-    });
-
-    const asn = parsed.asn || parsed.shipmentNotice;
-
-    return {
-      asnNumber: asn['@number'] || asn.asnNumber,
-      shipmentDate: asn.shipmentDate || asn['@shipmentDate'],
-      expectedDeliveryDate: asn.expectedDeliveryDate,
-      carrier: asn.carrier?.name || asn['@carrier'],
-      trackingNumber: asn.trackingNumber,
-      origin: {
-        locationRef: asn.origin?.locationRef || asn.origin?.['@ref'],
-        name: asn.origin?.name || '',
-        address: asn.origin?.address,
-      },
-      destination: {
-        locationRef: asn.destination?.locationRef || asn.destination?.['@ref'],
-        name: asn.destination?.name || '',
-        address: asn.destination?.address,
-      },
-      containers: this.parseContainers(asn.containers?.container || []),
-      totalQuantity: parseInt(asn.totalQuantity || '0'),
-    };
-  }
-
-  private parseContainers(containers: any[]): Container[] {
-    if (!Array.isArray(containers)) {
-      containers = [containers];
-    }
-
-    return containers.map(c => ({
-      id: c['@id'] || c.containerId,
-      type: (c['@type'] || c.type || 'CARTON').toUpperCase() as any,
-      sscc: c.sscc || c['@sscc'],
-      items: this.parseItems(c.items?.item || []),
-      children: c.children ? this.parseContainers(c.children.container) : undefined,
-    }));
-  }
-
-  private parseItems(items: any[]): AsnItem[] {
-    if (!Array.isArray(items)) {
-      items = [items];
-    }
-
-    return items.map(item => ({
-      sku: item.sku || item['@sku'],
-      productName: item.productName || item.description,
-      expectedQuantity: parseInt(item.expectedQuantity || item.quantity || '0'),
-      uom: item.uom || 'EA',
-      lotNumber: item.lotNumber,
-      serialNumbers: item.serialNumbers ?
-        (Array.isArray(item.serialNumbers.serial) ?
-          item.serialNumbers.serial : [item.serialNumbers.serial]) :
-        undefined,
-      expiryDate: item.expiryDate,
-    }));
-  }
-
-  private async createExpectedReceipt(asnDoc: AsnDocument): Promise<string> {
-    const mutation = `
-      mutation CreateExpectedReceipt($input: CreateReceiptInput!) {
-        createReceipt(input: $input) {
-          id
-          ref
-          status
-          type
-        }
-      }
-    `;
-
-    const variables = {
-      input: {
-        ref: asnDoc.asnNumber,
-        type: 'EXPECTED',
-        retailerId: config.fluent.retailerId,
-        locationRef: asnDoc.destination.locationRef,
-        expectedOn: asnDoc.expectedDeliveryDate,
-        carrier: asnDoc.carrier,
-        trackingNumber: asnDoc.trackingNumber,
-        items: this.flattenItems(asnDoc.containers),
-        attributes: {
-          asnNumber: asnDoc.asnNumber,
-          originLocation: asnDoc.origin.locationRef,
-          containerCount: asnDoc.containers.length,
-          totalQuantity: asnDoc.totalQuantity.toString(),
-        },
-      },
-    };
-
-    const result = await this.client.graphql({ query: mutation, variables });
-
-    if (result.errors) {
-      throw new Error(`GraphQL errors: ${JSON.stringify(result.errors)}`);
-    }
-
-    return (result.data as any).createReceipt.id;
-  }
-
-  private flattenItems(containers: Container[]): any[] {
-    const items: any[] = [];
-
-    for (const container of containers) {
-      for (const item of container.items) {
-        items.push({
-          productRef: item.sku,
-          expectedQuantity: item.expectedQuantity,
-          uom: item.uom,
-          lotNumber: item.lotNumber,
-          expiryDate: item.expiryDate,
-          serialNumbers: item.serialNumbers,
-        });
-      }
-
-      if (container.children) {
-        items.push(...this.flattenItems(container.children));
-      }
-    }
-
-    return items;
-  }
-
-  private async confirmActualReceipt(asnDoc: AsnDocument, receiptId: string): Promise<void> {
-    // In a real scenario, actual quantities would come from a separate file
-    // or WMS system. For demo, we assume expected = actual with potential variances
-
-    const mutation = `
-      mutation ConfirmReceipt($input: ConfirmReceiptInput!) {
-        confirmReceipt(input: $input) {
-          id
-          status
-          variances {
-            productRef
-            expectedQuantity
-            actualQuantity
-            variance
-          }
-        }
-      }
-    `;
-
-    const items = this.flattenItems(asnDoc.containers);
-    const variances: any[] = [];
-
-    // Simulate actual quantities (in production, these come from WMS)
-    const actualItems = items.map(item => {
-      const actualQty = item.expectedQuantity; // Replace with actual scanned quantity
-      const variance = actualQty - item.expectedQuantity;
-      const variancePercent = Math.abs(variance / item.expectedQuantity);
-
-      if (variancePercent > config.processing.varianceThreshold) {
-        variances.push({
-          sku: item.productRef,
-          expected: item.expectedQuantity,
-          actual: actualQty,
-          variance,
-          variancePercent,
-        });
-      }
-
-      return {
-        ...item,
-        actualQuantity: actualQty,
-      };
-    });
-
-    const variables = {
-      input: {
-        receiptId,
-        items: actualItems,
-        confirmedBy: 'ASN_PROCESSOR',
-      },
-    };
-
-    const result = await this.client.graphql({ query: mutation, variables });
-
-    if (result.errors) {
-      throw new Error(`GraphQL errors: ${JSON.stringify(result.errors)}`);
-    }
-
-    // Send variance alerts if needed
-    if (variances.length > 0) {
-      this.logger.warn(`Variances detected for ASN ${asnDoc.asnNumber}`, {
-        count: variances.length,
-      });
-      await this.emailAlerter.sendVarianceAlert(asnDoc.asnNumber, variances);
-    }
-  }
-}
-
-// ============================================================================
-// MAIN ENTRY POINT
-// ============================================================================
-
-async function main() {
-  const processor = new AsnProcessor();
-
-  try {
-    await processor.initialize();
-    await processor.processFiles();
-
-    console.log('ASN processing completed successfully');
-    process.exit(0);
-  } catch (error: any) {
-    console.error('Fatal error:', error);
-    process.exit(1);
-  }
-}
-
-// Run if executed directly
-if (require.main === module) {
-  main();
-}
-
-export { AsnProcessor };
-```
-
-### 4. Key Patterns Explained
-
-## Pattern 1: EDI 856 Parsing
-
-**Purpose**: Parse X12 EDI 856 format into structured data
-
-**Implementation**:
-
-```typescript
-class Edi856Parser {
-  parse(ediContent: string): AsnDocument {
-    // Split into segments (~ delimiter)
-    const segments = ediContent.split('~');
-
-    // Extract header info
-    const asnNumber = this.findSegmentValue(segments, 'BSN', 2);
-    const poNumber = this.findSegmentValue(segments, 'REF', 2, 'PO');
-
-    // Parse hierarchical levels (HL segments)
-    const containers = this.parseHierarchy(segments);
-
-    return { asnNumber, poNumber, containers, ... };
-  }
-}
-```
-
-**Key Points**:
-- EDI segments end with `~` delimiter
-- Fields within segments separated by `*`
-- Hierarchical levels (HL) define container structure
-- Qualifiers identify reference types (PO, BOL, etc.)
-
-**EDI 856 Hierarchy**:
-- S = Shipment (top level)
-- O = Order (PO reference)
-- P = Pack (pallet/case)
-- I = Item (SKU)
-
-## Pattern 2: Container Hierarchy Mapping
-
-**Purpose**: Map nested container structures (shipment → pallet → case → item)
-
-**Implementation**:
-
-```typescript
-interface AsnContainer {
-  containerId: string;
-  containerType: 'PALLET' | 'CASE' | 'TOTE';
-  parentContainerId?: string; // For nested containers
-  items: AsnItem[];
-}
-
-// Flatten containers into Fluent format
-const consignmentArticles = asn.containers.flatMap(container =>
-  container.items.map(item => ({
-    ref: `${asn.asnNumber}-${item.sku}`,
-    skuRef: item.sku,
-    requestedQuantity: item.quantity,
-    containerId: container.containerId,
-    containerType: container.containerType,
-  }))
-);
-```
-
-**Key Points**:
-- Containers can be nested (pallet contains cases)
-- Each item references its container
-- flatMap creates flat array for Fluent API
-- Container IDs track physical units
-
-## Pattern 3: Expected vs Actual Receipt Reconciliation
-
-**Purpose**: Compare expected quantities with actual received quantities
-
-**Implementation**:
-
-```typescript
-interface ActualReceipt {
-  items: {
-    sku: string;
-    expectedQty: number;
-    receivedQty: number;
-    variance: number;
-    variancePercent: number;
-    damageQty?: number;
-    shortQty?: number;
-    overQty?: number;
-  }[];
-  totalVariance: number;
-}
-
-// Calculate variance
-const variance = receivedQty - expectedQty;
-const variancePercent = (variance / expectedQty) * 100;
-
-// Alert if above threshold
-if (Math.abs(variancePercent) > VARIANCE_THRESHOLD) {
-  await sendVarianceAlert(asn, actualReceipt);
-}
-```
-
-**Variance Categories**:
-- **Shortage**: receivedQty < expectedQty (negative variance)
-- **Overage**: receivedQty > expectedQty (positive variance)
-- **Damage**: Items received damaged (separate count)
-- **Perfect**: receivedQty === expectedQty (no variance)
-
-**Best Practices**:
-- Set reasonable variance threshold (3-5%)
-- Separate damage from shortage
-- Track variance reasons (code required by some WMS)
-- Escalate variances > 10% to management
-
-## Pattern 4: Cross-Dock Support
-
-**Purpose**: Route shipments directly to customers (bypass warehouse)
-
-**Implementation**:
-
-```typescript
-// Detect cross-dock from ASN
-const isCrossDock = asn.header.isCrossDock === 'true';
-const customerOrderRef = asn.header.customerOrderRef;
-
-// Set destination to customer location
-const destinationLocation = isCrossDock
-  ? `${CROSS_DOCK_PREFIX}${customerOrderRef}`
-  : asn.destinationLocation;
-
-// Create consignment with cross-dock flag
-const input = {
-  ref: asn.asnNumber,
-  destinationLocation: { ref: destinationLocation },
-  isCrossDock,
-  customerOrderRef,
-  ...
-};
-```
-
-**Cross-Dock Scenarios**:
-1. **Direct-to-Customer**: Bypass warehouse entirely
-2. **Fast-Track**: Minimal warehouse touch (receive → pack → ship)
-3. **Bulk-Break**: Receive pallet, ship cases to multiple customers
-
-**Key Points**:
-- Destination location is customer address
-- Skip put-away workflow
-- Immediate allocation to customer order
-- Faster delivery times
-
-## Pattern 5: State Management & Deduplication
-
-**Purpose**: Prevent duplicate processing of ASN files
-
-**Implementation**:
-
-```typescript
-class StateManager {
-  private state: { processedFiles: Record<string, { hash: string, ... }> };
-
-  isFileProcessed(fileName: string, fileHash: string): boolean {
-    const record = this.state.processedFiles[fileName];
-    if (!record) return false;
-
-    // Reprocess if file content changed
-    if (record.hash !== fileHash) return false;
-
-    return record.status === 'SUCCESS';
-  }
-
-  markFileProcessed(fileName: string, fileHash: string, ...): void {
-    this.state.processedFiles[fileName] = {
-      hash: fileHash,
-      processedAt: new Date().toISOString(),
-      status: 'SUCCESS',
-    };
-    this.saveState();
-  }
-}
-```
-
-**Key Points**:
-- File name + content hash for deduplication
-- Reprocess if file content changed (hash mismatch)
-- Persist state to JSON file (or Redis/DB)
-- Track success/error status
-
-**State Storage Options**:
-- **JSON File**: Simple, local filesystem (this implementation)
-- **Redis**: Distributed, faster lookup
-- **PostgreSQL**: Relational, queryable history
-- **DynamoDB**: AWS-native, serverless
-
----
-
-## Testing
-
-### Local Testing
-
-```bash
-# 1. Upload test EDI file to SFTP
-sftp user@sftp.example.com
-put test-data/sample-asn.edi /inbound/asn/
-
-# 2. Run processor
-npm run process
-
-# 3. Check logs
-tail -f logs/asn-processor.log
-
-# 4. Verify in Fluent Commerce
-# - Check consignment created
-# - Verify expected quantities
-# - Check container references
-```
-
-### Integration Testing
-
-```bash
-# Test EDI parsing
-npm test -- edi856-parser.test.ts
-
-# Test XML parsing
-npm test -- xml-asn-parser.test.ts
-
-# Test variance calculation
-npm test -- variance-calculator.test.ts
-
-# Test state management
-npm test -- state-manager.test.ts
-```
-
----
-
-## Common Issues
-
-### Issue 1: EDI Segment Parsing Errors
-
-**Symptom**: `Failed to parse EDI 856: Invalid segment`
-
-**Cause**: Non-standard EDI format or line ending issues
-
-**Solution**:
-
-```typescript
-// Normalize line endings before parsing
-const normalizedContent = ediContent
-  .replace(/\r\n/g, '\n')
-  .replace(/\r/g, '\n')
-  .replace(/\n+/g, '~'); // Ensure ~ delimiter
-```
-
-### Issue 2: Container Hierarchy Missing
-
-**Symptom**: Items not associated with containers
-
-**Cause**: XML parser not handling nested structures correctly
-
-**Solution**:
-
-```typescript
-// Force array elements for consistent parsing
-const parsed = await xmlParser.parse(xmlContent, {
-  includeAttributes: true,
-  arrayElements: ['container', 'item', 'serialNumber'],
-});
-```
-
-### Issue 3: Variance Alerts Not Sending
-
-**Symptom**: No email alerts despite variances > threshold
-
-**Cause**: SMTP authentication failure or missing configuration
-
-**Solution**:
-
-```bash
-# Test SMTP connection
-npm install -g nodemailer-smtp-transport
-node -e "require('nodemailer').createTransport({host:'smtp.gmail.com',port:587,auth:{user:'test',pass:'test'}}).verify((e,s)=>console.log(e||'OK'))"
-
-# Enable app-specific password for Gmail
-# https://myaccount.google.com/apppasswords
-```
-
-### Issue 4: Duplicate ASN Processing
-
-**Symptom**: Same ASN processed multiple times
-
-**Cause**: State file not persisting or file hash not matching
-
-**Solution**:
-
-```typescript
-// Ensure state directory exists
-const stateDir = path.dirname(config.state.storagePath);
-if (!fs.existsSync(stateDir)) {
-  fs.mkdirSync(stateDir, { recursive: true });
-}
-
-// Use consistent hash algorithm
-const fileHash = crypto.createHash('sha256').update(content).digest('hex');
-```
-
-### Issue 5: SFTP Connection Timeout
-
-**Symptom**: `SFTP connection timeout after 30 seconds`
-
-**Cause**: Firewall blocking port 22 or network latency
-
-**Solution**:
-
-```typescript
-// Increase connection timeout
-const sftpSource = new SftpDataSource({
-  settings: {
-    ...config.sftp,
-    connectionTimeout: 60000, // 60 seconds
-    keepAliveInterval: 10000, // 10 seconds
-  },
-}, logger);
-```
-
----
-
-## Sample EDI 856 File
-
-Create `test-data/sample-asn.edi`:
-
-```
-ISA*00*          *00*          *ZZ*SENDER         *ZZ*RECEIVER       *240115*1200*U*00401*000000001*0*P*>~
-GS*SH*SENDER*RECEIVER*20240115*1200*1*X*004010~
-ST*856*0001~
-BSN*00*ASN-12345*20240115*120000~
-HL*1**S~
-TD5****UPS*GROUND~
-REF*PO*PO-67890~
-REF*BM*SHIP-001~
-DTM*011*20240116~
-N1*SF*SUPPLIER WAREHOUSE~
-N1*ST*DESTINATION WAREHOUSE~
-HL*2*1*O~
-PRF*PO-67890~
-HL*3*2*P~
-MAN*GM*PALLET-001~
-HL*4*3*I~
-LIN**SK*SKU-001~
-SN1**100*EA~
-HL*5*3*I~
-LIN**SK*SKU-002~
-SN1**50*EA~
-HL*6*2*P~
-MAN*GM*PALLET-002~
-HL*7*6*I~
-LIN**SK*SKU-003~
-SN1**25*EA~
-SE*20*0001~
-GE*1*1~
-IEA*1*000000001~
-```
-
-## Sample XML ASN File
-
-Create `test-data/sample-asn.xml`:
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<asn>
-  <header>
-    <asnNumber>ASN-12345</asnNumber>
-    <poNumber>PO-67890</poNumber>
-    <shipmentId>SHIP-001</shipmentId>
-    <carrier>UPS Ground</carrier>
-    <trackingNumber>1Z999AA10123456784</trackingNumber>
-    <scheduledDeliveryDate>2024-01-16T10:00:00Z</scheduledDeliveryDate>
-    <originLocation>SUPPLIER-WAREHOUSE</originLocation>
-    <destinationLocation>DC-EAST</destinationLocation>
-    <isCrossDock>false</isCrossDock>
-    <notes>Handle with care - fragile items</notes>
-  </header>
-  <containers>
-    <container>
-      <containerId>PALLET-001</containerId>
-      <containerType>PALLET</containerType>
-      <items>
-        <item>
-          <sku>SKU-001</sku>
-          <description>Widget A</description>
-          <quantity>100</quantity>
-          <uom>EA</uom>
-          <lotNumber>LOT-2024-001</lotNumber>
-          <expirationDate>2024-12-31</expirationDate>
-        </item>
-        <item>
-          <sku>SKU-002</sku>
-          <description>Widget B</description>
-          <quantity>50</quantity>
-          <uom>EA</uom>
-          <lotNumber>LOT-2024-002</lotNumber>
-        </item>
-      </items>
-    </container>
-    <container>
-      <containerId>PALLET-002</containerId>
-      <containerType>PALLET</containerType>
-      <items>
-        <item>
-          <sku>SKU-003</sku>
-          <description>Gadget X</description>
-          <quantity>25</quantity>
-          <uom>EA</uom>
-        </item>
-      </items>
-    </container>
-  </containers>
-</asn>
-```
-
----
-
-## Related Guides
-
-- **SDK Reference**: `../../readme.md` - Core SDK documentation
-- **SFTP Data Source**: `../../02-CORE-GUIDES/data-sources/readme.md` - SFTP operations
-- **XML Parser**: `../../02-CORE-GUIDES/parsers/readme.md` - XML parsing options
-- **GraphQL Mutation Mapper**: `../../02-CORE-GUIDES/mapping/graphql-mutation-mapping/` - ASN → Fluent mutations
-- **State Management**: `../../02-CORE-GUIDES/ingestion/modules/07-state-management.md` - Deduplication patterns
-- **Error Handling**: `../../03-PATTERN-GUIDES/error-handling/readme.md` - Error patterns
-
----
-
-## Production Checklist
-
-Before deploying to production:
-
-- [ ] EDI 856 format validated with 3PL provider
-- [ ] XML schema aligned with WMS export format
-- [ ] SFTP credentials secured (vault, secrets manager)
-- [ ] Variance threshold tuned based on historical data
-- [ ] Email alerts tested with actual SMTP server
-- [ ] State storage configured for persistence (Redis/DB)
-- [ ] Monitoring dashboard setup (ASN success rate, avg variance)
-- [ ] Cross-dock routing logic tested with real orders
-- [ ] Container hierarchy validated (pallet → case → item)
-- [ ] Error alerting configured (PagerDuty, Slack)
-- [ ] Retry logic tested (network failures, API errors)
-- [ ] SFTP connection pooling configured
-- [ ] Health check endpoint added
-- [ ] Disaster recovery tested (reprocess from archive)
-
----
-
-**Next Steps**:
-
-1. Configure SFTP connection with your 3PL provider
-2. Obtain sample EDI 856 or XML ASN files
-3. Customize field mappings for your ASN format
-4. Test variance calculation with historical data
-5. Set up monitoring and alerting
-6. Deploy to cron or Lambda for automated processing
-
-**Support**:
-
-- SDK Issues: https://github.com/fluentcommerce/fc-connect-sdk/issues
-- Fluent Commerce API: https://docs.fluentcommerce.com
-- EDI 856 Spec: https://www.x12.org/examples/004010/856/
-- Community: https://community.fluentcommerce.com
+# Standalone: ASN Inbound Processing (WMS/3PL Integration)
+
+**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 processes Advanced Ship Notices (ASNs) from WMS/3PL systems via SFTP, creating expected receipts in Fluent Commerce and confirming actual receipts
+
+**Complexity**: Medium
+
+**Runtime**: Node.js ≥18 / Deno
+
+**Estimated Lines**: ~900 lines
+
+**Volume**: 10-100 ASNs/day, 100-5000 units per ASN
+
+**Latency**: Near real-time (< 5 min)
+
+**Pattern**: SFTP polling → EDI/XML parsing → GraphQL mutation
+
+## What You'll Build
+
+- Standalone Node.js/Deno script (no Versori)
+- SFTP integration for ASN file polling
+- EDI 856 (X12) and XML ASN format parsing
+- Container hierarchy mapping (shipment → pallet → case → item)
+- Expected receipt creation in Fluent Commerce
+- Actual receipt confirmation with variance handling
+- Cross-dock scenario support (direct to customer)
+- Email alerts for significant variances (> 5%)
+- State management to prevent duplicate processing
+- Comprehensive error handling and logging
+
+## SDK Methods Used
+
+- `createClient({ config: { baseUrl, clientId, clientSecret, retailerId } })` - OAuth2 client
+- `SftpDataSource(config, logger)` - SFTP operations
+- `XMLParserService` - XML ASN parsing
+- `GraphQLMutationMapper` - ASN → Fluent GraphQL mutations
+- `VersoriFileTracker` (adapted for standalone) - Deduplication
+- `client.graphql(payload)` - Execute mutations
+- Custom EDI 856 parser for X12 format
+
+---
+
+## Complete Working Implementation
+
+### 1. Project Setup
+
+```bash
+# Create project directory
+mkdir asn-inbound-processor
+cd asn-inbound-processor
+
+# Initialize Node.js project
+npm init -y
+
+# Install dependencies
+npm install @fluentcommerce/fc-connect-sdk dotenv nodemailer
+```
+
+### 2. Environment Configuration
+
+Create `.env` file:
+
+```env
+# Fluent Commerce Configuration
+FLUENT_BASE_URL=https://api.fluentcommerce.com
+FLUENT_CLIENT_ID=your-oauth2-client-id
+FLUENT_CLIENT_SECRET=your-oauth2-client-secret
+FLUENT_RETAILER_ID=your-retailer-id
+
+# SFTP Configuration
+SFTP_HOST=sftp.3pl-provider.com
+SFTP_PORT=22
+SFTP_USERNAME=your-username
+SFTP_PASSWORD=your-password
+# OR use private key authentication
+# SFTP_PRIVATE_KEY=/path/to/private_key
+# SFTP_PASSPHRASE=key-passphrase
+
+# SFTP Paths
+SFTP_INBOUND_PATH=/inbound/asn
+SFTP_PROCESSED_PATH=/processed/asn
+SFTP_ERROR_PATH=/errors/asn
+SFTP_FILE_PATTERN=*.{xml,edi,856}
+
+# Processing Configuration
+ASN_FORMAT=xml# Options: xml, edi856
+ENABLE_ACTUAL_RECEIPT_CONFIRMATION=true
+VARIANCE_ALERT_THRESHOLD=0.05# 5% threshold for email alerts
+
+# Email Alerts (for variances)
+SMTP_HOST=smtp.gmail.com
+SMTP_PORT=587
+SMTP_USER=alerts@yourcompany.com
+SMTP_PASSWORD=your-smtp-password
+ALERT_EMAIL_TO=warehouse-mgr@yourcompany.com
+
+# State Management
+STATE_STORAGE_PATH=./data/asn-state.json
+
+# Optional: Cross-dock support
+ENABLE_CROSS_DOCK=true
+CROSS_DOCK_LOCATION_PREFIX=CUSTOMER_
+
+# Logging
+LOG_LEVEL=info# Options: debug, info, warn, error
+```
+
+### 3. Main Script Implementation (src/asn-processor.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,
+  SftpDataSource,
+  XMLParserService,
+  GraphQLMutationMapper,
+  type FluentClient,
+  type StructuredLogger,
+  createConsoleLogger,
+  toStructuredLogger
+} from '@fluentcommerce/fc-connect-sdk';
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+import nodemailer from 'nodemailer';
+
+// ============================================================================
+// TYPES & INTERFACES
+// ============================================================================
+
+interface AsnDocument {
+  asnNumber: string;
+  shipmentDate: string;
+  expectedDeliveryDate: string;
+  carrier: string;
+  trackingNumber?: string;
+  origin: {
+    locationRef: string;
+    name: string;
+    address?: string;
+  };
+  destination: {
+    locationRef: string;
+    name: string;
+    address?: string;
+  };
+  containers: Container[];
+  totalQuantity: number;
+}
+
+interface Container {
+  id: string;
+  type: 'PALLET' | 'CASE' | 'CARTON';
+  sscc?: string;
+  items: AsnItem[];
+  children?: Container[];
+}
+
+interface AsnItem {
+  sku: string;
+  productName?: string;
+  expectedQuantity: number;
+  actualQuantity?: number;
+  uom: string;
+  lotNumber?: string;
+  serialNumbers?: string[];
+  expiryDate?: string;
+}
+
+interface ProcessingState {
+  processedFiles: Record<string, {
+    timestamp: string;
+    asnNumber: string;
+    status: 'success' | 'failed';
+    receiptId?: string;
+  }>;
+}
+
+// ============================================================================
+// 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
+      ? readFileSync(process.env.SFTP_PRIVATE_KEY, 'utf8')
+      : undefined,
+    passphrase: process.env.SFTP_PASSPHRASE,
+    inboundPath: process.env.SFTP_INBOUND_PATH || '/inbound/asn',
+    processedPath: process.env.SFTP_PROCESSED_PATH || '/processed/asn',
+    errorPath: process.env.SFTP_ERROR_PATH || '/errors/asn',
+    filePattern: process.env.SFTP_FILE_PATTERN || '*.{xml,edi,856}',
+  },
+  processing: {
+    asnFormat: process.env.ASN_FORMAT || 'xml',
+    enableActualReceipt: process.env.ENABLE_ACTUAL_RECEIPT_CONFIRMATION === 'true',
+    varianceThreshold: parseFloat(process.env.VARIANCE_ALERT_THRESHOLD || '0.05'),
+    enableCrossDock: process.env.ENABLE_CROSS_DOCK === 'true',
+    crossDockLocationPrefix: process.env.CROSS_DOCK_LOCATION_PREFIX || 'CUSTOMER_',
+  },
+  email: {
+    smtpHost: process.env.SMTP_HOST,
+    smtpPort: parseInt(process.env.SMTP_PORT || '587'),
+    smtpUser: process.env.SMTP_USER,
+    smtpPassword: process.env.SMTP_PASSWORD,
+    alertEmailTo: process.env.ALERT_EMAIL_TO,
+  },
+  state: {
+    storagePath: process.env.STATE_STORAGE_PATH || './data/asn-state.json',
+  },
+};
+
+// ============================================================================
+// STATE MANAGEMENT
+// ============================================================================
+
+class StateManager {
+  private state: ProcessingState;
+  private storagePath: string;
+
+  constructor(storagePath: string) {
+    this.storagePath = storagePath;
+    this.state = this.loadState();
+  }
+
+  private loadState(): ProcessingState {
+    try {
+      if (existsSync(this.storagePath)) {
+        const data = readFileSync(this.storagePath, 'utf8');
+        return JSON.parse(data);
+      }
+    } catch (error) {
+      console.warn('Failed to load state, starting fresh', error);
+    }
+    return { processedFiles: {} };
+  }
+
+  private saveState(): void {
+    try {
+      const dir = dirname(this.storagePath);
+      if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+      }
+      writeFileSync(this.storagePath, JSON.stringify(this.state, null, 2));
+    } catch (error) {
+      console.error('Failed to save state', error);
+    }
+  }
+
+  isFileProcessed(fileName: string): boolean {
+    return !!this.state.processedFiles[fileName];
+  }
+
+  markFileProcessed(fileName: string, asnNumber: string, receiptId?: string): void {
+    this.state.processedFiles[fileName] = {
+      timestamp: new Date().toISOString(),
+      asnNumber,
+      status: 'success',
+      receiptId,
+    };
+    this.saveState();
+  }
+
+  markFileFailed(fileName: string, asnNumber: string): void {
+    this.state.processedFiles[fileName] = {
+      timestamp: new Date().toISOString(),
+      asnNumber,
+      status: 'failed',
+    };
+    this.saveState();
+  }
+}
+
+// ============================================================================
+// EMAIL ALERTS
+// ============================================================================
+
+class EmailAlerter {
+  private transporter: any;
+  private enabled: boolean;
+
+  constructor(config: typeof config.email) {
+    this.enabled = !!(config.smtpHost && config.smtpUser && config.alertEmailTo);
+
+    if (this.enabled) {
+      this.transporter = nodemailer.createTransport({
+        host: config.smtpHost,
+        port: config.smtpPort,
+        secure: config.smtpPort === 465,
+        auth: {
+          user: config.smtpUser,
+          pass: config.smtpPassword,
+        },
+      });
+    }
+  }
+
+  async sendVarianceAlert(asnNumber: string, variances: any[]): Promise<void> {
+    if (!this.enabled) return;
+
+    const html = `
+      <h2>ASN Variance Alert: ${asnNumber}</h2>
+      <p>Significant variances detected during receipt confirmation:</p>
+      <table border="1" cellpadding="5">
+        <tr>
+          <th>SKU</th>
+          <th>Expected</th>
+          <th>Actual</th>
+          <th>Variance</th>
+          <th>%</th>
+        </tr>
+        ${variances.map(v => `
+          <tr>
+            <td>${v.sku}</td>
+            <td>${v.expected}</td>
+            <td>${v.actual}</td>
+            <td style="color: ${v.variance < 0 ? 'red' : 'orange'}">${v.variance > 0 ? '+' : ''}${v.variance}</td>
+            <td>${(v.variancePercent * 100).toFixed(1)}%</td>
+          </tr>
+        `).join('')}
+      </table>
+      <p><strong>Action Required:</strong> Review and investigate variances.</p>
+    `;
+
+    try {
+      await this.transporter.sendMail({
+        from: config.email.smtpUser,
+        to: config.email.alertEmailTo,
+        subject: `⚠️ ASN Variance Alert: ${asnNumber}`,
+        html,
+      });
+    } catch (error) {
+      console.error('Failed to send email alert', error);
+    }
+  }
+}
+
+// ============================================================================
+// ASN PROCESSOR
+// ============================================================================
+
+class AsnProcessor {
+  private client: FluentClient;
+  private sftpSource: SftpDataSource;
+  private xmlParser: XMLParserService;
+  private logger: StructuredLogger;
+  private stateManager: StateManager;
+  private emailAlerter: EmailAlerter;
+
+  constructor() {
+    this.logger = toStructuredLogger(createConsoleLogger(), { logLevel: 'info' });
+  }
+
+  async initialize(): Promise<void> {
+    this.logger.info('Initializing ASN processor...');
+
+    // Initialize Fluent client
+    this.client = await createClient({ config: config.fluent });
+
+    // Initialize SFTP data source
+    this.sftpSource = new SftpDataSource({
+      type: 'SFTP_XML',
+      connectionId: 'asn-sftp',
+      name: 'ASN 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,
+      },
+    }, this.logger);
+
+    // Initialize XML parser
+    this.xmlParser = new XMLParserService();
+
+    // Initialize state manager
+    this.stateManager = new StateManager(config.state.storagePath);
+
+    // Initialize email alerter
+    this.emailAlerter = new EmailAlerter(config.email);
+
+    // Validate SFTP connection
+    const isConnected = await this.sftpSource.validateConnection();
+    if (!isConnected) {
+      throw new Error('SFTP connection validation failed');
+    }
+
+    this.logger.info('ASN processor initialized successfully');
+  }
+
+  async processFiles(): Promise<void> {
+    this.logger.info('Starting ASN file processing cycle');
+
+    try {
+      // List files from SFTP
+      const files = await this.sftpSource.listFiles({
+        remotePath: config.sftp.inboundPath,
+        filePattern: config.sftp.filePattern,
+      });
+
+      this.logger.info(`Found ${files.length} ASN files`);
+
+      for (const file of files) {
+        // Skip already processed files
+        if (this.stateManager.isFileProcessed(file.name)) {
+          this.logger.debug(`Skipping already processed file: ${file.name}`);
+          continue;
+        }
+
+        try {
+          await this.processAsnFile(file.name);
+        } catch (error: any) {
+          this.logger.error(`Failed to process ASN file: ${file.name}`, error);
+
+          // Move to error folder
+          const errorPath = `${config.sftp.errorPath}/${file.name}`;
+          await this.sftpSource.moveFile(file.path, errorPath, true); // Use file.path for source (full path)
+        }
+      }
+
+      this.logger.info('ASN processing cycle completed');
+    } catch (error: any) {
+      this.logger.error('ASN processing cycle failed', error);
+      throw error;
+    }
+  }
+
+  private async processAsnFile(fileName: string): Promise<void> {
+    this.logger.info(`Processing ASN file: ${fileName}`);
+
+    // Download file
+    const content = await this.sftpSource.downloadFile(fileName, {
+      encoding: 'utf8'
+    }) as string;
+
+    // Parse based on format
+    let asnDoc: AsnDocument;
+    if (config.processing.asnFormat === 'edi856') {
+      asnDoc = this.parseEdi856(content);
+    } else {
+      asnDoc = await this.parseXmlAsn(content);
+    }
+
+    this.logger.info(`Parsed ASN: ${asnDoc.asnNumber}`, {
+      containers: asnDoc.containers.length,
+      totalQuantity: asnDoc.totalQuantity,
+    });
+
+    // Create expected receipt in Fluent
+    const receiptId = await this.createExpectedReceipt(asnDoc);
+    this.logger.info(`Created expected receipt: ${receiptId}`);
+
+    // If actual receipt confirmation is enabled, process it
+    if (config.processing.enableActualReceipt) {
+      await this.confirmActualReceipt(asnDoc, receiptId);
+    }
+
+    // Mark as processed
+    this.stateManager.markFileProcessed(fileName, asnDoc.asnNumber, receiptId);
+
+    // Archive file
+    const archivePath = `${config.sftp.processedPath}/${new Date().toISOString().split('T')[0]}/${fileName}`;
+    await this.sftpSource.createDirectory(dirname(archivePath), true);
+    await this.sftpSource.moveFile(fileName, archivePath, false);
+
+    this.logger.info(`ASN file processed successfully: ${fileName}`);
+  }
+
+  private parseEdi856(ediContent: string): AsnDocument {
+    // Simplified EDI 856 parser - implement full parser based on your needs
+    const segments = ediContent.split('~').map(s => s.trim()).filter(Boolean);
+
+    const asnDoc: AsnDocument = {
+      asnNumber: '',
+      shipmentDate: '',
+      expectedDeliveryDate: '',
+      carrier: '',
+      origin: { locationRef: '', name: '' },
+      destination: { locationRef: '', name: '' },
+      containers: [],
+      totalQuantity: 0,
+    };
+
+    for (const segment of segments) {
+      const elements = segment.split('*');
+      const segmentId = elements[0];
+
+      if (segmentId === 'BSN') {
+        // Beginning Segment for Ship Notice
+        asnDoc.asnNumber = elements[2];
+        asnDoc.shipmentDate = elements[3];
+      } else if (segmentId === 'LIN') {
+        // Item Identification
+        // Parse item details...
+      }
+      // Add more segment parsing as needed
+    }
+
+    return asnDoc;
+  }
+
+  private async parseXmlAsn(xmlContent: string): Promise<AsnDocument> {
+    const parsed = await this.xmlParser.parse(xmlContent, {
+      includeAttributes: true,
+      parseNumbers: true,
+    });
+
+    const asn = parsed.asn || parsed.shipmentNotice;
+
+    return {
+      asnNumber: asn['@number'] || asn.asnNumber,
+      shipmentDate: asn.shipmentDate || asn['@shipmentDate'],
+      expectedDeliveryDate: asn.expectedDeliveryDate,
+      carrier: asn.carrier?.name || asn['@carrier'],
+      trackingNumber: asn.trackingNumber,
+      origin: {
+        locationRef: asn.origin?.locationRef || asn.origin?.['@ref'],
+        name: asn.origin?.name || '',
+        address: asn.origin?.address,
+      },
+      destination: {
+        locationRef: asn.destination?.locationRef || asn.destination?.['@ref'],
+        name: asn.destination?.name || '',
+        address: asn.destination?.address,
+      },
+      containers: this.parseContainers(asn.containers?.container || []),
+      totalQuantity: parseInt(asn.totalQuantity || '0'),
+    };
+  }
+
+  private parseContainers(containers: any[]): Container[] {
+    if (!Array.isArray(containers)) {
+      containers = [containers];
+    }
+
+    return containers.map(c => ({
+      id: c['@id'] || c.containerId,
+      type: (c['@type'] || c.type || 'CARTON').toUpperCase() as any,
+      sscc: c.sscc || c['@sscc'],
+      items: this.parseItems(c.items?.item || []),
+      children: c.children ? this.parseContainers(c.children.container) : undefined,
+    }));
+  }
+
+  private parseItems(items: any[]): AsnItem[] {
+    if (!Array.isArray(items)) {
+      items = [items];
+    }
+
+    return items.map(item => ({
+      sku: item.sku || item['@sku'],
+      productName: item.productName || item.description,
+      expectedQuantity: parseInt(item.expectedQuantity || item.quantity || '0'),
+      uom: item.uom || 'EA',
+      lotNumber: item.lotNumber,
+      serialNumbers: item.serialNumbers ?
+        (Array.isArray(item.serialNumbers.serial) ?
+          item.serialNumbers.serial : [item.serialNumbers.serial]) :
+        undefined,
+      expiryDate: item.expiryDate,
+    }));
+  }
+
+  private async createExpectedReceipt(asnDoc: AsnDocument): Promise<string> {
+    const mutation = `
+      mutation CreateExpectedReceipt($input: CreateReceiptInput!) {
+        createReceipt(input: $input) {
+          id
+          ref
+          status
+          type
+        }
+      }
+    `;
+
+    const variables = {
+      input: {
+        ref: asnDoc.asnNumber,
+        type: 'EXPECTED',
+        retailerId: config.fluent.retailerId,
+        locationRef: asnDoc.destination.locationRef,
+        expectedOn: asnDoc.expectedDeliveryDate,
+        carrier: asnDoc.carrier,
+        trackingNumber: asnDoc.trackingNumber,
+        items: this.flattenItems(asnDoc.containers),
+        attributes: {
+          asnNumber: asnDoc.asnNumber,
+          originLocation: asnDoc.origin.locationRef,
+          containerCount: asnDoc.containers.length,
+          totalQuantity: asnDoc.totalQuantity.toString(),
+        },
+      },
+    };
+
+    const result = await this.client.graphql({ query: mutation, variables });
+
+    if (result.errors) {
+      throw new Error(`GraphQL errors: ${JSON.stringify(result.errors)}`);
+    }
+
+    return (result.data as any).createReceipt.id;
+  }
+
+  private flattenItems(containers: Container[]): any[] {
+    const items: any[] = [];
+
+    for (const container of containers) {
+      for (const item of container.items) {
+        items.push({
+          productRef: item.sku,
+          expectedQuantity: item.expectedQuantity,
+          uom: item.uom,
+          lotNumber: item.lotNumber,
+          expiryDate: item.expiryDate,
+          serialNumbers: item.serialNumbers,
+        });
+      }
+
+      if (container.children) {
+        items.push(...this.flattenItems(container.children));
+      }
+    }
+
+    return items;
+  }
+
+  private async confirmActualReceipt(asnDoc: AsnDocument, receiptId: string): Promise<void> {
+    // In a real scenario, actual quantities would come from a separate file
+    // or WMS system. For demo, we assume expected = actual with potential variances
+
+    const mutation = `
+      mutation ConfirmReceipt($input: ConfirmReceiptInput!) {
+        confirmReceipt(input: $input) {
+          id
+          status
+          variances {
+            productRef
+            expectedQuantity
+            actualQuantity
+            variance
+          }
+        }
+      }
+    `;
+
+    const items = this.flattenItems(asnDoc.containers);
+    const variances: any[] = [];
+
+    // Simulate actual quantities (in production, these come from WMS)
+    const actualItems = items.map(item => {
+      const actualQty = item.expectedQuantity; // Replace with actual scanned quantity
+      const variance = actualQty - item.expectedQuantity;
+      const variancePercent = Math.abs(variance / item.expectedQuantity);
+
+      if (variancePercent > config.processing.varianceThreshold) {
+        variances.push({
+          sku: item.productRef,
+          expected: item.expectedQuantity,
+          actual: actualQty,
+          variance,
+          variancePercent,
+        });
+      }
+
+      return {
+        ...item,
+        actualQuantity: actualQty,
+      };
+    });
+
+    const variables = {
+      input: {
+        receiptId,
+        items: actualItems,
+        confirmedBy: 'ASN_PROCESSOR',
+      },
+    };
+
+    const result = await this.client.graphql({ query: mutation, variables });
+
+    if (result.errors) {
+      throw new Error(`GraphQL errors: ${JSON.stringify(result.errors)}`);
+    }
+
+    // Send variance alerts if needed
+    if (variances.length > 0) {
+      this.logger.warn(`Variances detected for ASN ${asnDoc.asnNumber}`, {
+        count: variances.length,
+      });
+      await this.emailAlerter.sendVarianceAlert(asnDoc.asnNumber, variances);
+    }
+  }
+}
+
+// ============================================================================
+// MAIN ENTRY POINT
+// ============================================================================
+
+async function main() {
+  const processor = new AsnProcessor();
+
+  try {
+    await processor.initialize();
+    await processor.processFiles();
+
+    console.log('ASN processing completed successfully');
+    process.exit(0);
+  } catch (error: any) {
+    console.error('Fatal error:', error);
+    process.exit(1);
+  }
+}
+
+// Run if executed directly
+if (require.main === module) {
+  main();
+}
+
+export { AsnProcessor };
+```
+
+### 4. Key Patterns Explained
+
+## Pattern 1: EDI 856 Parsing
+
+**Purpose**: Parse X12 EDI 856 format into structured data
+
+**Implementation**:
+
+```typescript
+class Edi856Parser {
+  parse(ediContent: string): AsnDocument {
+    // Split into segments (~ delimiter)
+    const segments = ediContent.split('~');
+
+    // Extract header info
+    const asnNumber = this.findSegmentValue(segments, 'BSN', 2);
+    const poNumber = this.findSegmentValue(segments, 'REF', 2, 'PO');
+
+    // Parse hierarchical levels (HL segments)
+    const containers = this.parseHierarchy(segments);
+
+    return { asnNumber, poNumber, containers, ... };
+  }
+}
+```
+
+**Key Points**:
+- EDI segments end with `~` delimiter
+- Fields within segments separated by `*`
+- Hierarchical levels (HL) define container structure
+- Qualifiers identify reference types (PO, BOL, etc.)
+
+**EDI 856 Hierarchy**:
+- S = Shipment (top level)
+- O = Order (PO reference)
+- P = Pack (pallet/case)
+- I = Item (SKU)
+
+## Pattern 2: Container Hierarchy Mapping
+
+**Purpose**: Map nested container structures (shipment → pallet → case → item)
+
+**Implementation**:
+
+```typescript
+interface AsnContainer {
+  containerId: string;
+  containerType: 'PALLET' | 'CASE' | 'TOTE';
+  parentContainerId?: string; // For nested containers
+  items: AsnItem[];
+}
+
+// Flatten containers into Fluent format
+const consignmentArticles = asn.containers.flatMap(container =>
+  container.items.map(item => ({
+    ref: `${asn.asnNumber}-${item.sku}`,
+    skuRef: item.sku,
+    requestedQuantity: item.quantity,
+    containerId: container.containerId,
+    containerType: container.containerType,
+  }))
+);
+```
+
+**Key Points**:
+- Containers can be nested (pallet contains cases)
+- Each item references its container
+- flatMap creates flat array for Fluent API
+- Container IDs track physical units
+
+## Pattern 3: Expected vs Actual Receipt Reconciliation
+
+**Purpose**: Compare expected quantities with actual received quantities
+
+**Implementation**:
+
+```typescript
+interface ActualReceipt {
+  items: {
+    sku: string;
+    expectedQty: number;
+    receivedQty: number;
+    variance: number;
+    variancePercent: number;
+    damageQty?: number;
+    shortQty?: number;
+    overQty?: number;
+  }[];
+  totalVariance: number;
+}
+
+// Calculate variance
+const variance = receivedQty - expectedQty;
+const variancePercent = (variance / expectedQty) * 100;
+
+// Alert if above threshold
+if (Math.abs(variancePercent) > VARIANCE_THRESHOLD) {
+  await sendVarianceAlert(asn, actualReceipt);
+}
+```
+
+**Variance Categories**:
+- **Shortage**: receivedQty < expectedQty (negative variance)
+- **Overage**: receivedQty > expectedQty (positive variance)
+- **Damage**: Items received damaged (separate count)
+- **Perfect**: receivedQty === expectedQty (no variance)
+
+**Best Practices**:
+- Set reasonable variance threshold (3-5%)
+- Separate damage from shortage
+- Track variance reasons (code required by some WMS)
+- Escalate variances > 10% to management
+
+## Pattern 4: Cross-Dock Support
+
+**Purpose**: Route shipments directly to customers (bypass warehouse)
+
+**Implementation**:
+
+```typescript
+// Detect cross-dock from ASN
+const isCrossDock = asn.header.isCrossDock === 'true';
+const customerOrderRef = asn.header.customerOrderRef;
+
+// Set destination to customer location
+const destinationLocation = isCrossDock
+  ? `${CROSS_DOCK_PREFIX}${customerOrderRef}`
+  : asn.destinationLocation;
+
+// Create consignment with cross-dock flag
+const input = {
+  ref: asn.asnNumber,
+  destinationLocation: { ref: destinationLocation },
+  isCrossDock,
+  customerOrderRef,
+  ...
+};
+```
+
+**Cross-Dock Scenarios**:
+1. **Direct-to-Customer**: Bypass warehouse entirely
+2. **Fast-Track**: Minimal warehouse touch (receive → pack → ship)
+3. **Bulk-Break**: Receive pallet, ship cases to multiple customers
+
+**Key Points**:
+- Destination location is customer address
+- Skip put-away workflow
+- Immediate allocation to customer order
+- Faster delivery times
+
+## Pattern 5: State Management & Deduplication
+
+**Purpose**: Prevent duplicate processing of ASN files
+
+**Implementation**:
+
+```typescript
+class StateManager {
+  private state: { processedFiles: Record<string, { hash: string, ... }> };
+
+  isFileProcessed(fileName: string, fileHash: string): boolean {
+    const record = this.state.processedFiles[fileName];
+    if (!record) return false;
+
+    // Reprocess if file content changed
+    if (record.hash !== fileHash) return false;
+
+    return record.status === 'SUCCESS';
+  }
+
+  markFileProcessed(fileName: string, fileHash: string, ...): void {
+    this.state.processedFiles[fileName] = {
+      hash: fileHash,
+      processedAt: new Date().toISOString(),
+      status: 'SUCCESS',
+    };
+    this.saveState();
+  }
+}
+```
+
+**Key Points**:
+- File name + content hash for deduplication
+- Reprocess if file content changed (hash mismatch)
+- Persist state to JSON file (or Redis/DB)
+- Track success/error status
+
+**State Storage Options**:
+- **JSON File**: Simple, local filesystem (this implementation)
+- **Redis**: Distributed, faster lookup
+- **PostgreSQL**: Relational, queryable history
+- **DynamoDB**: AWS-native, serverless
+
+---
+
+## Testing
+
+### Local Testing
+
+```bash
+# 1. Upload test EDI file to SFTP
+sftp user@sftp.example.com
+put test-data/sample-asn.edi /inbound/asn/
+
+# 2. Run processor
+npm run process
+
+# 3. Check logs
+tail -f logs/asn-processor.log
+
+# 4. Verify in Fluent Commerce
+# - Check consignment created
+# - Verify expected quantities
+# - Check container references
+```
+
+### Integration Testing
+
+```bash
+# Test EDI parsing
+npm test -- edi856-parser.test.ts
+
+# Test XML parsing
+npm test -- xml-asn-parser.test.ts
+
+# Test variance calculation
+npm test -- variance-calculator.test.ts
+
+# Test state management
+npm test -- state-manager.test.ts
+```
+
+---
+
+## Common Issues
+
+### Issue 1: EDI Segment Parsing Errors
+
+**Symptom**: `Failed to parse EDI 856: Invalid segment`
+
+**Cause**: Non-standard EDI format or line ending issues
+
+**Solution**:
+
+```typescript
+// Normalize line endings before parsing
+const normalizedContent = ediContent
+  .replace(/\r\n/g, '\n')
+  .replace(/\r/g, '\n')
+  .replace(/\n+/g, '~'); // Ensure ~ delimiter
+```
+
+### Issue 2: Container Hierarchy Missing
+
+**Symptom**: Items not associated with containers
+
+**Cause**: XML parser not handling nested structures correctly
+
+**Solution**:
+
+```typescript
+// Force array elements for consistent parsing
+const parsed = await xmlParser.parse(xmlContent, {
+  includeAttributes: true,
+  arrayElements: ['container', 'item', 'serialNumber'],
+});
+```
+
+### Issue 3: Variance Alerts Not Sending
+
+**Symptom**: No email alerts despite variances > threshold
+
+**Cause**: SMTP authentication failure or missing configuration
+
+**Solution**:
+
+```bash
+# Test SMTP connection
+npm install -g nodemailer-smtp-transport
+node -e "require('nodemailer').createTransport({host:'smtp.gmail.com',port:587,auth:{user:'test',pass:'test'}}).verify((e,s)=>console.log(e||'OK'))"
+
+# Enable app-specific password for Gmail
+# https://myaccount.google.com/apppasswords
+```
+
+### Issue 4: Duplicate ASN Processing
+
+**Symptom**: Same ASN processed multiple times
+
+**Cause**: State file not persisting or file hash not matching
+
+**Solution**:
+
+```typescript
+// Ensure state directory exists
+const stateDir = path.dirname(config.state.storagePath);
+if (!fs.existsSync(stateDir)) {
+  fs.mkdirSync(stateDir, { recursive: true });
+}
+
+// Use consistent hash algorithm
+const fileHash = crypto.createHash('sha256').update(content).digest('hex');
+```
+
+### Issue 5: SFTP Connection Timeout
+
+**Symptom**: `SFTP connection timeout after 30 seconds`
+
+**Cause**: Firewall blocking port 22 or network latency
+
+**Solution**:
+
+```typescript
+// Increase connection timeout
+const sftpSource = new SftpDataSource({
+  settings: {
+    ...config.sftp,
+    connectionTimeout: 60000, // 60 seconds
+    keepAliveInterval: 10000, // 10 seconds
+  },
+}, logger);
+```
+
+---
+
+## Sample EDI 856 File
+
+Create `test-data/sample-asn.edi`:
+
+```
+ISA*00*          *00*          *ZZ*SENDER         *ZZ*RECEIVER       *240115*1200*U*00401*000000001*0*P*>~
+GS*SH*SENDER*RECEIVER*20240115*1200*1*X*004010~
+ST*856*0001~
+BSN*00*ASN-12345*20240115*120000~
+HL*1**S~
+TD5****UPS*GROUND~
+REF*PO*PO-67890~
+REF*BM*SHIP-001~
+DTM*011*20240116~
+N1*SF*SUPPLIER WAREHOUSE~
+N1*ST*DESTINATION WAREHOUSE~
+HL*2*1*O~
+PRF*PO-67890~
+HL*3*2*P~
+MAN*GM*PALLET-001~
+HL*4*3*I~
+LIN**SK*SKU-001~
+SN1**100*EA~
+HL*5*3*I~
+LIN**SK*SKU-002~
+SN1**50*EA~
+HL*6*2*P~
+MAN*GM*PALLET-002~
+HL*7*6*I~
+LIN**SK*SKU-003~
+SN1**25*EA~
+SE*20*0001~
+GE*1*1~
+IEA*1*000000001~
+```
+
+## Sample XML ASN File
+
+Create `test-data/sample-asn.xml`:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<asn>
+  <header>
+    <asnNumber>ASN-12345</asnNumber>
+    <poNumber>PO-67890</poNumber>
+    <shipmentId>SHIP-001</shipmentId>
+    <carrier>UPS Ground</carrier>
+    <trackingNumber>1Z999AA10123456784</trackingNumber>
+    <scheduledDeliveryDate>2024-01-16T10:00:00Z</scheduledDeliveryDate>
+    <originLocation>SUPPLIER-WAREHOUSE</originLocation>
+    <destinationLocation>DC-EAST</destinationLocation>
+    <isCrossDock>false</isCrossDock>
+    <notes>Handle with care - fragile items</notes>
+  </header>
+  <containers>
+    <container>
+      <containerId>PALLET-001</containerId>
+      <containerType>PALLET</containerType>
+      <items>
+        <item>
+          <sku>SKU-001</sku>
+          <description>Widget A</description>
+          <quantity>100</quantity>
+          <uom>EA</uom>
+          <lotNumber>LOT-2024-001</lotNumber>
+          <expirationDate>2024-12-31</expirationDate>
+        </item>
+        <item>
+          <sku>SKU-002</sku>
+          <description>Widget B</description>
+          <quantity>50</quantity>
+          <uom>EA</uom>
+          <lotNumber>LOT-2024-002</lotNumber>
+        </item>
+      </items>
+    </container>
+    <container>
+      <containerId>PALLET-002</containerId>
+      <containerType>PALLET</containerType>
+      <items>
+        <item>
+          <sku>SKU-003</sku>
+          <description>Gadget X</description>
+          <quantity>25</quantity>
+          <uom>EA</uom>
+        </item>
+      </items>
+    </container>
+  </containers>
+</asn>
+```
+
+---
+
+## Related Guides
+
+- **SDK Reference**: `../../readme.md` - Core SDK documentation
+- **SFTP Data Source**: `../../02-CORE-GUIDES/data-sources/readme.md` - SFTP operations
+- **XML Parser**: `../../02-CORE-GUIDES/parsers/readme.md` - XML parsing options
+- **GraphQL Mutation Mapper**: `../../02-CORE-GUIDES/mapping/graphql-mutation-mapping/` - ASN → Fluent mutations
+- **State Management**: `../../02-CORE-GUIDES/ingestion/modules/07-state-management.md` - Deduplication patterns
+- **Error Handling**: `../../03-PATTERN-GUIDES/error-handling/readme.md` - Error patterns
+
+---
+
+## Production Checklist
+
+Before deploying to production:
+
+- [ ] EDI 856 format validated with 3PL provider
+- [ ] XML schema aligned with WMS export format
+- [ ] SFTP credentials secured (vault, secrets manager)
+- [ ] Variance threshold tuned based on historical data
+- [ ] Email alerts tested with actual SMTP server
+- [ ] State storage configured for persistence (Redis/DB)
+- [ ] Monitoring dashboard setup (ASN success rate, avg variance)
+- [ ] Cross-dock routing logic tested with real orders
+- [ ] Container hierarchy validated (pallet → case → item)
+- [ ] Error alerting configured (PagerDuty, Slack)
+- [ ] Retry logic tested (network failures, API errors)
+- [ ] SFTP connection pooling configured
+- [ ] Health check endpoint added
+- [ ] Disaster recovery tested (reprocess from archive)
+
+---
+
+**Next Steps**:
+
+1. Configure SFTP connection with your 3PL provider
+2. Obtain sample EDI 856 or XML ASN files
+3. Customize field mappings for your ASN format
+4. Test variance calculation with historical data
+5. Set up monitoring and alerting
+6. Deploy to cron or Lambda for automated processing
+
+**Support**:
+
+- SDK Issues: https://github.com/fluentcommerce/fc-connect-sdk/issues
+- Fluent Commerce API: https://docs.fluentcommerce.com
+- EDI 856 Spec: https://www.x12.org/examples/004010/856/
+- Community: https://community.fluentcommerce.com