@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/01-TEMPLATES/standalone/standalone-multi-source-aggregation.md

@@ -1,1462 +1,1462 @@
-# Standalone: Multi-Source Inventory Aggregation
-
-**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 aggregates inventory from SFTP + S3, reconciles with Fluent Commerce, and updates differences
-
-**Complexity**: High
-
-**Runtime**: Node.js ≥18
-
-**Estimated Lines**: ~800 lines
-
-## What You'll Build
-
-- Multi-source data collection (SFTP CSV + S3 JSON)
-- Data aggregation and deduplication using Map-based algorithm
-- Reconciliation with Fluent Commerce current state
-- Difference calculation (delta detection)
-- GraphQL mutation execution for inventory updates
-- Comprehensive logging and metrics tracking
-- Reconciliation report generation
-- Error handling and recovery
-
-## SDK Methods Used
-
-- `createClient(...)` - OAuth2 client creation
-- `SftpDataSource(...)` - SFTP file operations
-- `S3DataSource(...)` - S3 file operations
-- `CSVParserService` - Parse SFTP CSV files
-- `client.graphql({ query, variables })` - Query current Fluent inventory
-- `client.graphqlMutation(mutation, variables)` - Execute inventory updates
-- `UniversalMapper(...)` - Transform aggregated data
-
-## Complete Working Code
-
-### 1. Environment Configuration
-
-Create `.env` file:
-
-```bash
-# Fluent Commerce OAuth2
-FLUENT_BASE_URL=https://api.fluentcommerce.com
-FLUENT_CLIENT_ID=your-oauth2-client-id
-FLUENT_CLIENT_SECRET=your-oauth2-client-secret
-FLUENT_USERNAME=your-username
-FLUENT_PASSWORD=your-password
-FLUENT_RETAILER_ID=your-retailer-id
-
-# Warehouse SFTP Source
-WAREHOUSE_SFTP_HOST=warehouse-sftp.example.com
-WAREHOUSE_SFTP_PORT=22
-WAREHOUSE_SFTP_USER=warehouse-user
-WAREHOUSE_SFTP_PASSWORD=warehouse-password
-WAREHOUSE_SFTP_PATH=/inventory/updates
-
-# Store S3 Source
-STORE_S3_BUCKET=store-inventory
-STORE_S3_REGION=us-east-1
-STORE_AWS_ACCESS_KEY_ID=your-aws-access-key
-STORE_AWS_SECRET_ACCESS_KEY=your-aws-secret-key
-STORE_S3_PREFIX=stores/inventory/
-
-# Reporting S3 Destination
-REPORT_S3_BUCKET=inventory-reports
-REPORT_S3_REGION=us-east-1
-REPORT_AWS_ACCESS_KEY_ID=your-aws-access-key
-REPORT_AWS_SECRET_ACCESS_KEY=your-aws-secret-key
-```
-
-### 2. Package Configuration
-
-Create `package.json`:
-
-```json
-{
-  "name": "multi-source-inventory-aggregation",
-  "version": "1.0.0",
-  "type": "module",
-  "description": "Multi-source inventory aggregation with Fluent Commerce",
-  "main": "src/index.js",
-  "scripts": {
-    "start": "node src/index.js",
-    "dev": "node --watch src/index.js",
-    "aggregation:once": "node src/index.js",
-    "aggregation:schedule": "node src/scheduler.js"
-  },
-  "dependencies": {
-    "@fluentcommerce/fc-connect-sdk": "^0.1.39",
-    "dotenv": "^16.0.0",
-    "node-cron": "^3.0.0"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  }
-}
-```
-
-### 3. Main Aggregation Script
-
-Create `src/index.js`:
-
-```javascript
-// 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,
-  S3DataSource,
-  CSVParserService,
-  UniversalMapper,
-  createConsoleLogger,
-  toStructuredLogger,
-} from '@fluentcommerce/fc-connect-sdk';
-import dotenv from 'dotenv';
-import { fileURLToPath } from 'url';
-import { dirname, join } from 'path';
-
-// Load environment variables
-dotenv.config();
-
-// Get current directory (ESM equivalent of __dirname)
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-/**
- * MULTI-SOURCE INVENTORY AGGREGATION SYSTEM
- *
- * This script implements a sophisticated inventory aggregation workflow:
- *
- * 1. Data Collection: Gather inventory from multiple sources (SFTP + S3)
- * 2. Aggregation: Combine data using Map-based deduplication
- * 3. Reconciliation: Compare with Fluent Commerce current state
- * 4. Update: Send only differences to Fluent via GraphQL mutations
- * 5. Reporting: Generate comprehensive reconciliation report
- *
- * DESIGN DECISIONS:
- * - Map-based aggregation: O(n) complexity for deduplication
- * - Delta-only updates: Minimize API calls by updating only differences
- * - Source tracking: Maintain provenance for debugging
- * - Location granularity: Track inventory per SKU per location
- * - Error recovery: Continue processing after non-critical failures
- */
-
-/**
- * Aggregated Inventory Item Structure
- *
- * This represents a single SKU's inventory across all locations.
- * The Map structure provides O(1) lookup for deduplication.
- *
- * @typedef {Object} AggregatedItem
- * @property {string} sku - Product SKU (unique identifier)
- * @property {Map<string, number>} locations - Location ID -> quantity mapping
- * @property {Set<string>} sources - Data sources that contributed to this item
- */
-
-/**
- * Initialize Logger
- */
-const logger = toStructuredLogger(createConsoleLogger(), {
-  service: 'multi-source-aggregation',
-  version: '1.0.0',
-});
-
-/**
- * Configuration Object
- *
- * Centralizes all configuration to make the script easily testable
- * and configurable without code changes.
- */
-const config = {
-  // Fluent Commerce
-  fluent: {
-    baseUrl: process.env.FLUENT_BASE_URL,
-    clientId: process.env.FLUENT_CLIENT_ID,
-    clientSecret: process.env.FLUENT_CLIENT_SECRET,
-    username: process.env.FLUENT_USERNAME,
-    password: process.env.FLUENT_PASSWORD,
-    retailerId: process.env.FLUENT_RETAILER_ID,
-  },
-
-  // Warehouse SFTP Source
-  warehouseSftp: {
-    host: process.env.WAREHOUSE_SFTP_HOST,
-    port: parseInt(process.env.WAREHOUSE_SFTP_PORT || '22'),
-    username: process.env.WAREHOUSE_SFTP_USER,
-    password: process.env.WAREHOUSE_SFTP_PASSWORD,
-    remotePath: process.env.WAREHOUSE_SFTP_PATH || '/inventory/updates',
-    filePattern: '*.csv',
-  },
-
-  // Store S3 Source
-  storeS3: {
-    bucket: process.env.STORE_S3_BUCKET,
-    region: process.env.STORE_S3_REGION || 'us-east-1',
-    accessKeyId: process.env.STORE_AWS_ACCESS_KEY_ID,
-    secretAccessKey: process.env.STORE_AWS_SECRET_ACCESS_KEY,
-    prefix: process.env.STORE_S3_PREFIX || 'stores/inventory/',
-  },
-
-  // Reporting S3 Destination
-  reportS3: {
-    bucket: process.env.REPORT_S3_BUCKET,
-    region: process.env.REPORT_S3_REGION || 'us-east-1',
-    accessKeyId: process.env.REPORT_AWS_ACCESS_KEY_ID,
-    secretAccessKey: process.env.REPORT_AWS_SECRET_ACCESS_KEY,
-  },
-
-  // Processing options
-  processing: {
-    batchSize: 100, // Number of records to process in one GraphQL mutation
-    maxRetries: 3,
-    retryDelay: 1000, // milliseconds
-  },
-};
-
-/**
- * Validate Configuration
- *
- * Ensures all required environment variables are set before proceeding.
- * Fails fast with clear error messages to prevent runtime issues.
- */
-function validateConfig() {
-  const required = [
-    'FLUENT_BASE_URL',
-    'FLUENT_CLIENT_ID',
-    'FLUENT_CLIENT_SECRET',
-    'FLUENT_USERNAME',
-    'FLUENT_PASSWORD',
-    'FLUENT_RETAILER_ID',
-    'WAREHOUSE_SFTP_HOST',
-    'WAREHOUSE_SFTP_USER',
-    'WAREHOUSE_SFTP_PASSWORD',
-    'STORE_S3_BUCKET',
-    'STORE_AWS_ACCESS_KEY_ID',
-    'STORE_AWS_SECRET_ACCESS_KEY',
-  ];
-
-  const missing = required.filter(key => !process.env[key]);
-
-  if (missing.length > 0) {
-    throw new Error(`Missing required environment variables: ${missing.join(', ')}`);
-  }
-
-  logger.info('Configuration validated successfully');
-}
-
-/**
- * Initialize Data Sources
- *
- * Creates SFTP and S3 data source instances for reading inventory files.
- * Each source is configured with connection parameters and file patterns.
- *
- * @returns {Object} Data source instances
- */
-function initializeDataSources() {
-  logger.info('Initializing data sources');
-
-  // SFTP Data Source for warehouse inventory (CSV format)
-  const sftpSource = new SftpDataSource(
-    {
-      type: 'SFTP_CSV',
-      connectionId: 'warehouse-sftp',
-      name: 'Warehouse SFTP',
-      settings: {
-        ...config.warehouseSftp,
-        csvDelimiter: ',',
-        csvHeaders: ['sku', 'location', 'quantity', 'status'],
-        csvSkipEmptyLines: true,
-        csvTrimValues: true,
-      },
-    },
-    logger
-  );
-
-  // S3 Data Source for store inventory (JSON format)
-  const s3Source = new S3DataSource(
-    {
-      type: 'S3_CSV',
-      connectionId: 'store-s3',
-      name: 'Store Inventory S3',
-      s3Config: config.storeS3,
-    },
-    logger
-  );
-
-  // S3 Data Source for reporting (write destination)
-  const reportS3Source = new S3DataSource(
-    {
-      type: 'S3_CSV',
-      connectionId: 'report-s3',
-      name: 'Report S3',
-      s3Config: config.reportS3,
-    },
-    logger
-  );
-
-  logger.info('Data sources initialized successfully');
-
-  return { sftpSource, s3Source, reportS3Source };
-}
-
-/**
- * Collect Inventory from SFTP Source
- *
- * WAREHOUSE INVENTORY COLLECTION
- *
- * Algorithm:
- * 1. List CSV files from SFTP remote path
- * 2. Download each CSV file
- * 3. Parse CSV using CSVParserService
- * 4. Aggregate data into Map structure (SKU -> locations -> quantity)
- * 5. Track source provenance (WAREHOUSE_SFTP)
- *
- * CSV Format Expected:
- * sku,location,quantity,status
- * PROD-001,WH-01,150,AVAILABLE
- * PROD-002,WH-01,75,AVAILABLE
- *
- * @param {SftpDataSource} sftpSource - SFTP data source instance
- * @param {Map<string, AggregatedItem>} inventoryMap - Aggregation map
- * @returns {Promise<number>} Number of files processed
- */
-async function collectSftpInventory(sftpSource, inventoryMap) {
-  logger.info('Collecting inventory from SFTP (warehouse)');
-
-  try {
-    // List CSV files from SFTP server
-    const files = await sftpSource.listFiles({
-      filePattern: config.warehouseSftp.filePattern,
-    });
-
-    logger.info(`Found ${files.length} CSV files in SFTP`);
-
-    if (files.length === 0) {
-      logger.warn('No files found in SFTP source');
-      return 0;
-    }
-
-    // Process each CSV file
-    for (const file of files) {
-      logger.info(`Processing SFTP file: ${file.name}`);
-
-      try {
-        // Download file content
-        const content = await sftpSource.downloadFile(file.name);
-
-        // Parse CSV content
-        const csvParser = new CSVParserService();
-        const records = await csvParser.parse(content);
-
-        logger.info(`Parsed ${records.length} records from ${file.name}`);
-
-        // Aggregate records into inventory map
-        for (const record of records) {
-          const sku = record.sku;
-          const location = record.location;
-          const quantity = parseInt(record.quantity) || 0;
-
-          // Skip invalid records
-          if (!sku || !location) {
-            logger.warn('Skipping record with missing SKU or location', { record });
-            continue;
-          }
-
-          // Get or create aggregated item
-          if (!inventoryMap.has(sku)) {
-            inventoryMap.set(sku, {
-              sku: sku,
-              locations: new Map(),
-              sources: new Set(),
-            });
-          }
-
-          const item = inventoryMap.get(sku);
-
-          // Aggregate quantity by location
-          // If SKU+location exists from another source, ADD quantities
-          const currentQty = item.locations.get(location) || 0;
-          item.locations.set(location, currentQty + quantity);
-
-          // Track source
-          item.sources.add('WAREHOUSE_SFTP');
-        }
-      } catch (fileError) {
-        logger.error(`Failed to process SFTP file: ${file.name}`, fileError);
-        // Continue processing other files
-      }
-    }
-
-    logger.info(`SFTP collection complete: ${inventoryMap.size} unique SKUs aggregated`);
-    return files.length;
-  } catch (error) {
-    logger.error('Failed to collect inventory from SFTP', error);
-    throw error;
-  }
-}
-
-/**
- * Collect Inventory from S3 Source
- *
- * STORE INVENTORY COLLECTION
- *
- * Algorithm:
- * 1. List JSON files from S3 bucket/prefix
- * 2. Download each JSON file
- * 3. Parse JSON (expected structure: { inventory: [...] })
- * 4. Aggregate data into Map structure
- * 5. Track source provenance (STORE_S3)
- *
- * JSON Format Expected:
- * {
- *   "storeId": "STORE-001",
- *   "timestamp": "2024-01-15T10:30:00Z",
- *   "inventory": [
- *     { "productId": "PROD-001", "storeId": "STORE-001", "availableQty": 25 },
- *     { "productId": "PROD-002", "storeId": "STORE-001", "availableQty": 50 }
- *   ]
- * }
- *
- * @param {S3DataSource} s3Source - S3 data source instance
- * @param {Map<string, AggregatedItem>} inventoryMap - Aggregation map
- * @returns {Promise<number>} Number of files processed
- */
-async function collectS3Inventory(s3Source, inventoryMap) {
-  logger.info('Collecting inventory from S3 (stores)');
-
-  try {
-    // List JSON files from S3
-    const files = await s3Source.listFiles({
-      prefix: config.storeS3.prefix,
-    });
-
-    // Filter only JSON files
-    const jsonFiles = files.filter(file => file.name.toLowerCase().endsWith('.json'));
-
-    logger.info(`Found ${jsonFiles.length} JSON files in S3`);
-
-    if (jsonFiles.length === 0) {
-      logger.warn('No JSON files found in S3 source');
-      return 0;
-    }
-
-    // Process each JSON file
-    for (const file of jsonFiles) {
-      logger.info(`Processing S3 file: ${file.path}`);
-
-      try {
-        // Download file content
-        const content = await s3Source.downloadFile(file.path);
-
-        // Parse JSON
-        const storeData = JSON.parse(content);
-
-        if (!storeData.inventory || !Array.isArray(storeData.inventory)) {
-          logger.warn(`Invalid JSON structure in ${file.path}: missing 'inventory' array`);
-          continue;
-        }
-
-        logger.info(`Parsed ${storeData.inventory.length} records from ${file.path}`);
-
-        // Aggregate records into inventory map
-        for (const record of storeData.inventory) {
-          const sku = record.productId;
-          const location = record.storeId;
-          const quantity = parseInt(record.availableQty) || 0;
-
-          // Skip invalid records
-          if (!sku || !location) {
-            logger.warn('Skipping record with missing productId or storeId', { record });
-            continue;
-          }
-
-          // Get or create aggregated item
-          if (!inventoryMap.has(sku)) {
-            inventoryMap.set(sku, {
-              sku: sku,
-              locations: new Map(),
-              sources: new Set(),
-            });
-          }
-
-          const item = inventoryMap.get(sku);
-
-          // Aggregate quantity by location
-          const currentQty = item.locations.get(location) || 0;
-          item.locations.set(location, currentQty + quantity);
-
-          // Track source
-          item.sources.add('STORE_S3');
-        }
-      } catch (fileError) {
-        logger.error(`Failed to process S3 file: ${file.path}`, fileError);
-        // Continue processing other files
-      }
-    }
-
-    logger.info(`S3 collection complete: ${inventoryMap.size} unique SKUs aggregated`);
-    return jsonFiles.length;
-  } catch (error) {
-    logger.error('Failed to collect inventory from S3', error);
-    throw error;
-  }
-}
-
-/**
- * Query Current Fluent Inventory
- *
- * CURRENT STATE RETRIEVAL
- *
- * Queries Fluent Commerce to get the current inventory state.
- * This is necessary for reconciliation (comparing aggregated vs. current).
- *
- * GraphQL Query Pattern:
- * - Uses pagination (first: 1000) to handle large inventories
- * - Returns: ref, productRef, locationRef, qty, availableQty
- * - Maps to SKU+Location structure for comparison
- *
- * @param {FluentClient} fluentClient - Fluent Commerce API client
- * @returns {Promise<Map>} Map of "SKU:LOCATION" -> { qty, availableQty }
- */
-async function queryCurrentInventory(fluentClient) {
-  logger.info('Querying current inventory from Fluent Commerce');
-
-  const query = `
-    query GetCurrentInventory($retailerId: ID!, $first: Int!, $after: String) {
-      inventoryPositions(
-        retailerId: $retailerId,
-        first: $first,
-        after: $after
-      ) {
-        edges {
-          cursor
-          node {
-            ref
-            productRef
-            locationRef
-            qty
-            availableQty
-            status
-            updatedOn
-          }
-        }
-        pageInfo {
-          hasNextPage
-        }
-      }
-    }
-  `;
-
-  try {
-    // Query with pagination support
-    const result = await fluentClient.graphql({
-      query,
-      variables: {
-        retailerId: config.fluent.retailerId,
-        first: 1000, // Adjust based on expected inventory size
-      },
-    });
-
-    if (!result.data || !result.data.inventoryPositions) {
-      throw new Error('Invalid GraphQL response structure');
-    }
-
-    const edges = result.data.inventoryPositions.edges || [];
-    logger.info(`Retrieved ${edges.length} inventory positions from Fluent`);
-
-    // Build lookup map: "SKU:LOCATION" -> inventory data
-    const currentInventory = new Map();
-
-    for (const edge of edges) {
-      const node = edge.node;
-      const key = `${node.productRef}:${node.locationRef}`;
-
-      currentInventory.set(key, {
-        ref: node.ref,
-        productRef: node.productRef,
-        locationRef: node.locationRef,
-        qty: node.qty,
-        availableQty: node.availableQty,
-        status: node.status,
-        updatedOn: node.updatedOn,
-      });
-    }
-
-    logger.info(`Current inventory indexed: ${currentInventory.size} positions`);
-    return currentInventory;
-  } catch (error) {
-    logger.error('Failed to query current inventory', error);
-    throw error;
-  }
-}
-
-/**
- * Reconcile Inventory Differences
- *
- * RECONCILIATION ALGORITHM
- *
- * Compares aggregated inventory (from SFTP + S3) with Fluent current state.
- * Identifies differences and generates update commands.
- *
- * Algorithm:
- * 1. Iterate through aggregated inventory Map
- * 2. For each SKU+Location, compare aggregated qty vs. Fluent qty
- * 3. If difference exists (newQty !== currentQty), create update record
- * 4. Calculate adjustment type (RECEIPT if increase, DISPATCH if decrease)
- * 5. Build reconciliation report with detailed differences
- *
- * Update Decision Logic:
- * - No Fluent record: CREATE (new inventory position)
- * - Qty unchanged: SKIP (no update needed)
- * - Qty increased: RECEIPT adjustment
- * - Qty decreased: DISPATCH adjustment
- *
- * @param {Map<string, AggregatedItem>} inventoryMap - Aggregated inventory
- * @param {Map} currentInventory - Current Fluent inventory
- * @returns {Object} { updates: [], report: [] }
- */
-function reconcileInventory(inventoryMap, currentInventory) {
-  logger.info('Reconciling inventory differences');
-
-  const updates = [];
-  const reconciliationReport = [];
-  let createCount = 0;
-  let updateCount = 0;
-  let skipCount = 0;
-
-  // Iterate through aggregated inventory
-  for (const [sku, aggregated] of inventoryMap.entries()) {
-    for (const [location, newQty] of aggregated.locations.entries()) {
-      const key = `${sku}:${location}`;
-
-      // Look up current inventory position
-      const current = currentInventory.get(key);
-      const currentQty = current ? current.qty : 0;
-      const difference = newQty - currentQty;
-
-      // Skip if no change
-      if (difference === 0 && current) {
-        skipCount++;
-        continue;
-      }
-
-      // Determine operation type
-      let operation;
-      if (!current) {
-        operation = 'CREATE';
-        createCount++;
-      } else if (difference > 0) {
-        operation = 'RECEIPT';
-        updateCount++;
-      } else {
-        operation = 'DISPATCH';
-        updateCount++;
-      }
-
-      // Create update record
-      updates.push({
-        ref: current ? current.ref : `${sku}-${location}`,
-        productRef: sku,
-        locationRef: location,
-        qty: newQty,
-        type: operation === 'CREATE' ? 'ADJUSTMENT' : operation,
-        adjustmentQty: Math.abs(difference),
-        reason: 'MULTI_SOURCE_SYNC',
-        attributes: {
-          sources: Array.from(aggregated.sources).join(','),
-          previousQty: currentQty,
-          newQty: newQty,
-          difference: difference,
-          syncedAt: new Date().toISOString(),
-        },
-      });
-
-      // Add to reconciliation report
-      reconciliationReport.push({
-        sku,
-        location,
-        operation,
-        previousQty: currentQty,
-        newQty: newQty,
-        difference,
-        sources: Array.from(aggregated.sources),
-        timestamp: new Date().toISOString(),
-      });
-    }
-  }
-
-  logger.info('Reconciliation complete', {
-    totalDifferences: updates.length,
-    creates: createCount,
-    updates: updateCount,
-    skipped: skipCount,
-  });
-
-  return { updates, reconciliationReport };
-}
-
-/**
- * Execute Inventory Updates
- *
- * BATCH UPDATE EXECUTION
- *
- * Sends inventory updates to Fluent Commerce via GraphQL mutations.
- * Processes updates in batches to avoid API limits.
- *
- * Mutation Pattern:
- * - Uses adjustInventory mutation for updates
- * - Batches of 100 records per mutation
- * - Tracks success/failure per batch
- * - Logs errors for retry/debugging
- *
- * @param {FluentClient} fluentClient - Fluent Commerce API client
- * @param {Array} updates - Array of update records
- * @returns {Promise<Object>} { success: number, failed: number, errors: [] }
- */
-async function executeUpdates(fluentClient, updates) {
-  logger.info(`Executing ${updates.length} inventory updates`);
-
-  if (updates.length === 0) {
-    logger.info('No updates to execute');
-    return { success: 0, failed: 0, errors: [] };
-  }
-
-  const batchSize = config.processing.batchSize;
-  let successCount = 0;
-  let failedCount = 0;
-  const errors = [];
-
-  // Process in batches
-  for (let i = 0; i < updates.length; i += batchSize) {
-    const batch = updates.slice(i, i + batchSize);
-    const batchNumber = Math.floor(i / batchSize) + 1;
-    const totalBatches = Math.ceil(updates.length / batchSize);
-
-    logger.info(`Processing batch ${batchNumber}/${totalBatches} (${batch.length} records)`);
-
-    try {
-      // GraphQL mutation for inventory adjustment
-      const mutation = `
-        mutation AdjustInventory($updates: [InventoryAdjustmentInput]!) {
-          adjustInventory(input: $updates) {
-            success
-            failed
-            errors {
-              ref
-              message
-              code
-            }
-          }
-        }
-      `;
-
-      const result = await fluentClient.graphqlMutation(mutation, {
-        updates: batch,
-      });
-
-      if (result.data && result.data.adjustInventory) {
-        const batchResult = result.data.adjustInventory;
-        successCount += batchResult.success || 0;
-        failedCount += batchResult.failed || 0;
-
-        if (batchResult.errors && batchResult.errors.length > 0) {
-          errors.push(...batchResult.errors);
-          logger.warn(`Batch ${batchNumber} had ${batchResult.errors.length} errors`, {
-            errors: batchResult.errors.slice(0, 5), // Log first 5 errors
-          });
-        }
-
-        logger.info(
-          `Batch ${batchNumber} complete: ${batchResult.success} success, ${batchResult.failed} failed`
-        );
-      }
-    } catch (batchError) {
-      logger.error(`Batch ${batchNumber} failed completely`, batchError);
-      failedCount += batch.length;
-      errors.push({
-        batch: batchNumber,
-        message: batchError.message,
-        records: batch.length,
-      });
-    }
-  }
-
-  logger.info('Update execution complete', {
-    totalUpdates: updates.length,
-    success: successCount,
-    failed: failedCount,
-    errors: errors.length,
-  });
-
-  return { success: successCount, failed: failedCount, errors };
-}
-
-/**
- * Generate Reconciliation Report
- *
- * COMPREHENSIVE REPORTING
- *
- * Creates a detailed JSON report of the reconciliation process.
- * Includes statistics, detailed changes, and errors.
- * Uploads report to S3 for auditing and monitoring.
- *
- * Report Structure:
- * - timestamp: When reconciliation ran
- * - sourcesProcessed: Files processed per source
- * - statistics: Summary counts
- * - reconciliation: Detailed changes (first 1000)
- * - errors: Any errors encountered
- *
- * @param {S3DataSource} reportS3Source - S3 data source for report upload
- * @param {Object} stats - Statistics object
- * @returns {Promise<string>} Report S3 key
- */
-async function generateReconciliationReport(reportS3Source, stats) {
-  logger.info('Generating reconciliation report');
-
-  const timestamp = new Date().toISOString();
-  const reportKey = `reconciliation/report-${timestamp.replace(/[:.]/g, '-')}.json`;
-
-  const report = {
-    timestamp,
-    version: '1.0.0',
-    sourcesProcessed: {
-      sftpFiles: stats.sftpFiles,
-      s3Files: stats.s3Files,
-    },
-    statistics: {
-      totalSKUs: stats.totalSKUs,
-      totalLocations: stats.totalLocations,
-      totalUpdates: stats.totalUpdates,
-      creates: stats.creates,
-      receipts: stats.receipts,
-      dispatches: stats.dispatches,
-      skipped: stats.skipped,
-      success: stats.success,
-      failed: stats.failed,
-    },
-    reconciliation: stats.reconciliationDetails.slice(0, 1000), // Limit to first 1000 for report size
-    errors: stats.errors || [],
-  };
-
-  // Upload report to S3
-  try {
-    await reportS3Source.uploadFile(reportKey, JSON.stringify(report, null, 2), {
-      contentType: 'application/json',
-    });
-
-    logger.info(`Reconciliation report uploaded: ${reportKey}`);
-    return reportKey;
-  } catch (error) {
-    logger.error('Failed to upload reconciliation report', error);
-    throw error;
-  }
-}
-
-/**
- * Main Aggregation Function
- *
- * ORCHESTRATION ENTRY POINT
- *
- * Coordinates the entire multi-source aggregation workflow:
- * 1. Validate configuration
- * 2. Initialize data sources and Fluent client
- * 3. Collect inventory from SFTP + S3
- * 4. Query current Fluent inventory
- * 5. Reconcile differences
- * 6. Execute updates
- * 7. Generate report
- *
- * Error Handling Strategy:
- * - Configuration errors: Fail immediately
- * - Source collection errors: Continue with other sources
- * - Reconciliation errors: Fail (cannot proceed without comparison)
- * - Update errors: Track failures but continue batch processing
- *
- * @returns {Promise<Object>} Final statistics
- */
-async function aggregateInventory() {
-  const startTime = Date.now();
-
-  logger.info('='.repeat(80));
-  logger.info('MULTI-SOURCE INVENTORY AGGREGATION - START');
-  logger.info('='.repeat(80));
-
-  try {
-    // Step 1: Validate configuration
-    validateConfig();
-
-    // Step 2: Initialize data sources
-    const { sftpSource, s3Source, reportS3Source } = initializeDataSources();
-
-    // Step 3: Create Fluent client
-    logger.info('Creating Fluent Commerce client');
-    const fluentClient = await createClient(config.fluent);
-    logger.info('Fluent client created successfully');
-
-    // Step 4: Initialize aggregation map
-    // Map structure: SKU -> { sku, locations: Map<location, qty>, sources: Set<source> }
-    const inventoryMap = new Map();
-
-    // Step 5: Collect inventory from SFTP (warehouses)
-    logger.info('-'.repeat(80));
-    logger.info('PHASE 1: SFTP Collection');
-    logger.info('-'.repeat(80));
-    const sftpFiles = await collectSftpInventory(sftpSource, inventoryMap);
-
-    // Step 6: Collect inventory from S3 (stores)
-    logger.info('-'.repeat(80));
-    logger.info('PHASE 2: S3 Collection');
-    logger.info('-'.repeat(80));
-    const s3Files = await collectS3Inventory(s3Source, inventoryMap);
-
-    logger.info('-'.repeat(80));
-    logger.info('AGGREGATION COMPLETE');
-    logger.info('-'.repeat(80));
-    logger.info(`Total unique SKUs: ${inventoryMap.size}`);
-
-    // Calculate total locations
-    let totalLocations = 0;
-    for (const item of inventoryMap.values()) {
-      totalLocations += item.locations.size;
-    }
-    logger.info(`Total locations: ${totalLocations}`);
-
-    // Step 7: Query current Fluent inventory
-    logger.info('-'.repeat(80));
-    logger.info('PHASE 3: Current State Query');
-    logger.info('-'.repeat(80));
-    const currentInventory = await queryCurrentInventory(fluentClient);
-
-    // Step 8: Reconcile differences
-    logger.info('-'.repeat(80));
-    logger.info('PHASE 4: Reconciliation');
-    logger.info('-'.repeat(80));
-    const { updates, reconciliationReport } = reconcileInventory(inventoryMap, currentInventory);
-
-    // Step 9: Execute updates
-    logger.info('-'.repeat(80));
-    logger.info('PHASE 5: Update Execution');
-    logger.info('-'.repeat(80));
-    const updateResult = await executeUpdates(fluentClient, updates);
-
-    // Step 10: Generate report
-    logger.info('-'.repeat(80));
-    logger.info('PHASE 6: Report Generation');
-    logger.info('-'.repeat(80));
-
-    const stats = {
-      sftpFiles,
-      s3Files,
-      totalSKUs: inventoryMap.size,
-      totalLocations,
-      totalUpdates: updates.length,
-      creates: updates.filter(u => u.type === 'ADJUSTMENT').length,
-      receipts: updates.filter(u => u.type === 'RECEIPT').length,
-      dispatches: updates.filter(u => u.type === 'DISPATCH').length,
-      skipped: totalLocations - updates.length,
-      success: updateResult.success,
-      failed: updateResult.failed,
-      errors: updateResult.errors,
-      reconciliationDetails: reconciliationReport,
-    };
-
-    const reportKey = await generateReconciliationReport(reportS3Source, stats);
-
-    // Step 11: Final summary
-    const duration = Math.round((Date.now() - startTime) / 1000);
-
-    logger.info('='.repeat(80));
-    logger.info('MULTI-SOURCE INVENTORY AGGREGATION - COMPLETE');
-    logger.info('='.repeat(80));
-    logger.info(`Duration: ${duration} seconds`);
-    logger.info(`Sources processed: ${sftpFiles} SFTP files, ${s3Files} S3 files`);
-    logger.info(`Total SKUs: ${stats.totalSKUs}`);
-    logger.info(
-      `Total updates: ${stats.totalUpdates} (${stats.success} success, ${stats.failed} failed)`
-    );
-    logger.info(`Report: ${reportKey}`);
-    logger.info('='.repeat(80));
-
-    return stats;
-  } catch (error) {
-    logger.error('Multi-source aggregation failed', error);
-    throw error;
-  }
-}
-
-// Execute if run directly
-if (import.meta.url === `file://${process.argv[1]}`) {
-  aggregateInventory()
-    .then(() => {
-      logger.info('Aggregation completed successfully');
-      process.exit(0);
-    })
-    .catch(error => {
-      logger.error('Aggregation failed with error', error);
-      process.exit(1);
-    });
-}
-
-export { aggregateInventory, config };
-```
-
-### 4. Scheduler (Optional)
-
-Create `src/scheduler.js` for scheduled execution:
-
-```javascript
-import cron from 'node-cron';
-import { aggregateInventory } from './index.js';
-
-/**
- * SCHEDULED AGGREGATION
- *
- * Runs aggregation on a schedule using cron syntax.
- * Default: Hourly at minute 0 (e.g., 1:00, 2:00, 3:00)
- *
- * Cron Pattern: '0 * * * *'
- * - Minute: 0 (at the top of the hour)
- * - Hour: * (every hour)
- * - Day of Month: * (every day)
- * - Month: * (every month)
- * - Day of Week: * (every day of week)
- */
-
-console.log('Multi-Source Inventory Aggregation Scheduler');
-console.log('Schedule: Hourly at minute 0');
-console.log('Press Ctrl+C to stop');
-
-// Schedule task
-cron.schedule('0 * * * *', async () => {
-  console.log(`\n${'='.repeat(80)}`);
-  console.log(`Scheduled aggregation triggered: ${new Date().toISOString()}`);
-  console.log('='.repeat(80));
-
-  try {
-    await aggregateInventory();
-    console.log('Scheduled aggregation completed successfully');
-  } catch (error) {
-    console.error('Scheduled aggregation failed:', error);
-  }
-});
-
-// Run immediately on startup (optional)
-if (process.env.RUN_ON_STARTUP === 'true') {
-  console.log('Running initial aggregation on startup...');
-  aggregateInventory()
-    .then(() => console.log('Initial aggregation complete'))
-    .catch(error => console.error('Initial aggregation failed:', error));
-}
-```
-
-## Key Patterns Explained
-
-### Pattern 1: Multi-Source Data Collection
-
-**Challenge**: Collecting inventory from heterogeneous sources (CSV from SFTP, JSON from S3)
-
-**Solution**: Source-specific collection functions with unified aggregation structure
-
-```javascript
-// Each source has its own collection function
-await collectSftpInventory(sftpSource, inventoryMap); // CSV → Map
-await collectS3Inventory(s3Source, inventoryMap); // JSON → Map
-
-// Both populate the same Map structure:
-// Map<SKU, { locations: Map<location, qty>, sources: Set<source> }>
-```
-
-**Why This Works**:
-
-- Abstraction: Each source function handles its own format
-- Unified Structure: All sources aggregate into the same Map
-- Source Tracking: Set tracks which sources contributed to each SKU
-- Deduplication: Map automatically handles duplicate SKU+location combinations
-
-### Pattern 2: Map-Based Aggregation & Deduplication
-
-**Challenge**: Combine inventory from multiple sources, handling duplicates and quantities
-
-**Solution**: Nested Map structure with additive aggregation
-
-```javascript
-// Aggregation data structure
-const inventoryMap = new Map(); // SKU -> AggregatedItem
-
-// AggregatedItem structure:
-{
-  sku: 'PROD-001',
-  locations: Map<string, number>,  // location -> quantity
-  sources: Set<string>              // ['WAREHOUSE_SFTP', 'STORE_S3']
-}
-
-// Aggregation algorithm (additive for duplicates)
-if (!inventoryMap.has(sku)) {
-  inventoryMap.set(sku, {
-    sku: sku,
-    locations: new Map(),
-    sources: new Set()
-  });
-}
-
-const item = inventoryMap.get(sku);
-const currentQty = item.locations.get(location) || 0;
-item.locations.set(location, currentQty + quantity);  // ADD quantities
-item.sources.add(sourceName);
-```
-
-**Why This Works**:
-
-- O(1) lookup: Map provides fast SKU lookup
-- O(1) duplicate detection: Map automatically handles duplicates
-- Additive logic: Quantities from different sources are summed
-- Source provenance: Track which sources contributed (debugging/auditing)
-
-### Pattern 3: Reconciliation Algorithm
-
-**Challenge**: Compare aggregated inventory with Fluent current state to find differences
-
-**Solution**: Key-based lookup with delta calculation
-
-```javascript
-// Build lookup key: "SKU:LOCATION"
-const key = `${sku}:${location}`;
-
-// Look up current state
-const current = currentInventory.get(key);
-const currentQty = current ? current.qty : 0;
-
-// Calculate delta
-const difference = newQty - currentQty;
-
-// Determine operation
-if (difference === 0) {
-  operation = 'SKIP'; // No change
-} else if (!current) {
-  operation = 'CREATE'; // New inventory position
-} else if (difference > 0) {
-  operation = 'RECEIPT'; // Increase
-} else {
-  operation = 'DISPATCH'; // Decrease
-}
-```
-
-**Why This Works**:
-
-- Key-based comparison: Fast O(1) lookup for each SKU+location
-- Delta detection: Only send changes (minimizes API calls)
-- Operation classification: Clear intent (CREATE/RECEIPT/DISPATCH)
-- Skip optimization: Avoid unnecessary updates when qty unchanged
-
-### Pattern 4: Batch Update Execution
-
-**Challenge**: Send thousands of inventory updates without hitting API limits
-
-**Solution**: Batch processing with error tracking
-
-```javascript
-const batchSize = 100;
-
-for (let i = 0; i < updates.length; i += batchSize) {
-  const batch = updates.slice(i, i + batchSize);
-
-  try {
-    const result = await fluentClient.graphqlMutation(mutation, {
-      updates: batch,
-    });
-
-    // Track success/failure per batch
-    successCount += result.data.adjustInventory.success;
-    failedCount += result.data.adjustInventory.failed;
-  } catch (batchError) {
-    // Log error but continue processing other batches
-    logger.error(`Batch ${batchNumber} failed`, batchError);
-    failedCount += batch.length;
-  }
-}
-```
-
-**Why This Works**:
-
-- Batch optimization: Reduces API calls (1000 updates → 10 API calls at batch size 100)
-- Error isolation: One batch failure doesn't stop other batches
-- Progress tracking: Log after each batch for monitoring
-- Retry-friendly: Failed batches can be retried individually
-
-### Pattern 5: Comprehensive Report Generation
-
-**Challenge**: Provide audit trail and debugging information for reconciliation
-
-**Solution**: Structured JSON report with statistics and details
-
-```javascript
-const report = {
-  timestamp: new Date().toISOString(),
-  version: '1.0.0',
-
-  // Source processing statistics
-  sourcesProcessed: {
-    sftpFiles: 5,
-    s3Files: 20,
-  },
-
-  // Aggregate statistics
-  statistics: {
-    totalSKUs: 1250,
-    totalLocations: 3400,
-    totalUpdates: 450,
-    creates: 50,
-    receipts: 200,
-    dispatches: 200,
-    skipped: 2950,
-    success: 445,
-    failed: 5,
-  },
-
-  // Detailed changes (first 1000)
-  reconciliation: [
-    {
-      sku: 'PROD-001',
-      location: 'WH-01',
-      operation: 'RECEIPT',
-      previousQty: 100,
-      newQty: 150,
-      difference: 50,
-      sources: ['WAREHOUSE_SFTP'],
-      timestamp: '2024-01-15T10:30:00Z',
-    },
-  ],
-
-  // Errors encountered
-  errors: [],
-};
-
-// Upload to S3 for persistence
-await reportS3Source.uploadFile(reportKey, JSON.stringify(report, null, 2));
-```
-
-**Why This Works**:
-
-- Audit trail: Permanent record of what was updated
-- Debugging: Detailed information for troubleshooting failures
-- Monitoring: Statistics for dashboards and alerts
-- Compliance: Provenance tracking (which sources contributed)
-
-## Deployment Options
-
-### Option 1: Scheduled Execution (Hourly)
-
-Run aggregation every hour using cron:
-
-```bash
-# Install dependencies
-npm install
-
-# Run scheduler (stays running, executes hourly)
-npm run aggregation:schedule
-```
-
-**Use Case**: Regular inventory synchronization from multiple sources
-
-### Option 2: Manual Execution (On-Demand)
-
-Run aggregation once, manually triggered:
-
-```bash
-# Single execution
-npm run aggregation:once
-```
-
-**Use Case**: Testing, troubleshooting, or ad-hoc reconciliation
-
-### Option 3: Containerized Deployment
-
-Create `Dockerfile`:
-
-```dockerfile
-FROM node:18-alpine
-
-WORKDIR /app
-
-COPY package*.json ./
-RUN npm ci --production
-
-COPY src/ ./src/
-
-CMD ["node", "src/scheduler.js"]
-```
-
-Build and run:
-
-```bash
-# Build Docker image
-docker build -t multi-source-aggregation .
-
-# Run container
-docker run -d \
-  --name inventory-aggregation \
-  --env-file .env \
-  --restart unless-stopped \
-  multi-source-aggregation
-```
-
-**Use Case**: Production deployment with container orchestration (Kubernetes, ECS)
-
-## Testing
-
-### Test with Mock Data
-
-Create `tests/test-aggregation.js`:
-
-```javascript
-import { aggregateInventory, config } from '../src/index.js';
-
-// Override config for testing
-config.processing.batchSize = 10;
-
-// Mock environment variables
-process.env.FLUENT_BASE_URL = 'https://api.fluentcommerce.com';
-process.env.FLUENT_CLIENT_ID = 'test-client-id';
-// ... (other test env vars)
-
-// Run aggregation
-aggregateInventory()
-  .then(stats => {
-    console.log('Test completed successfully');
-    console.log(JSON.stringify(stats, null, 2));
-  })
-  .catch(error => {
-    console.error('Test failed:', error);
-    process.exit(1);
-  });
-```
-
-Run test:
-
-```bash
-node tests/test-aggregation.js
-```
-
-## Common Issues
-
-### Issue 1: SFTP Connection Timeout
-
-**Symptom**: `Error: Connection timeout after 30s`
-
-**Solution**:
-
-```bash
-# Increase timeout in .env
-WAREHOUSE_SFTP_TIMEOUT=60000
-
-# Or in code (src/index.js):
-settings: {
-  ...config.warehouseSftp,
-  connectionTimeout: 60000  // 60 seconds
-}
-```
-
-### Issue 2: S3 Access Denied
-
-**Symptom**: `Error: AccessDenied: User is not authorized`
-
-**Solution**:
-
-- Verify AWS credentials are correct
-- Check IAM policy includes:
-  - `s3:GetObject` on source bucket
-  - `s3:PutObject` on report bucket
-  - `s3:ListBucket` on both buckets
-
-```json
-{
-  "Version": "2012-10-17",
-  "Statement": [
-    {
-      "Effect": "Allow",
-      "Action": ["s3:GetObject", "s3:ListBucket"],
-      "Resource": ["arn:aws:s3:::store-inventory", "arn:aws:s3:::store-inventory/*"]
-    },
-    {
-      "Effect": "Allow",
-      "Action": ["s3:PutObject"],
-      "Resource": ["arn:aws:s3:::inventory-reports/*"]
-    }
-  ]
-}
-```
-
-### Issue 3: Fluent GraphQL Errors
-
-**Symptom**: `Error: adjustInventory mutation failed`
-
-**Solution**:
-
-- Check Fluent API credentials
-- Verify retailerId is correct
-- Ensure inventory positions exist (or use CREATE operation)
-- Check mutation input format matches Fluent schema
-
-### Issue 4: Memory Issues with Large Datasets
-
-**Symptom**: `JavaScript heap out of memory`
-
-**Solution**:
-
-```bash
-# Increase Node.js heap size
-node --max-old-space-size=4096 src/index.js
-
-# Or reduce batch size in config
-config.processing.batchSize = 50;
-```
-
-### Issue 5: Duplicate SKUs from Multiple Sources
-
-**Symptom**: Quantities are doubled or incorrect
-
-**Solution**:
-
-- **Intended behavior**: Quantities are ADDED from multiple sources
-- If you need OVERRIDE behavior (last source wins), modify aggregation:
-
-```javascript
-// OVERRIDE mode (replace instead of add)
-item.locations.set(location, quantity); // Don't add, just set
-```
-
-### Issue 6: Report Upload Failures
-
-**Symptom**: `Failed to upload reconciliation report`
-
-**Solution**:
-
-- Check report S3 bucket exists
-- Verify write permissions
-- Check S3 region matches configuration
-- Ensure network connectivity to S3
-
-## Related Guides
-
-- **[Simple CSV Ingestion](./s3-csv-batch-api.md)** - Single source ingestion pattern
-- **[SFTP to Fluent](../../02-CORE-GUIDES/ingestion/ingestion-readme.md)** - SFTP-specific workflows (see Versori templates)
-- **[S3 Parquet Extraction](./graphql-query-export.md)** - S3 and Parquet handling
-- **[Connector Scenarios](../../02-CORE-GUIDES/advanced-services/advanced-services-readme.md)** - Multi-source patterns
-- **[Universal Mapping Guide](../../02-CORE-GUIDES/advanced-services/advanced-services-readme.md)** - Field transformation
-- **[SDK Resolvers](../../02-CORE-GUIDES/mapping/resolvers/mapping-resolvers-resolver-guide.md)** - Built-in transformations
-
-## Next Steps
-
-1. **Add Custom Transformations**: Use UniversalMapper for complex field mappings
-2. **Implement Retry Logic**: Add exponential backoff for transient failures
-3. **Add Monitoring**: Integrate with CloudWatch, Datadog, or other monitoring
-4. **Implement Alerting**: Send notifications on failures or reconciliation anomalies
-5. **Add State Management**: Track processed files to avoid reprocessing
-6. **Optimize Performance**: Implement parallel processing for large datasets
+# Standalone: Multi-Source Inventory Aggregation
+
+**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 aggregates inventory from SFTP + S3, reconciles with Fluent Commerce, and updates differences
+
+**Complexity**: High
+
+**Runtime**: Node.js ≥18
+
+**Estimated Lines**: ~800 lines
+
+## What You'll Build
+
+- Multi-source data collection (SFTP CSV + S3 JSON)
+- Data aggregation and deduplication using Map-based algorithm
+- Reconciliation with Fluent Commerce current state
+- Difference calculation (delta detection)
+- GraphQL mutation execution for inventory updates
+- Comprehensive logging and metrics tracking
+- Reconciliation report generation
+- Error handling and recovery
+
+## SDK Methods Used
+
+- `createClient(...)` - OAuth2 client creation
+- `SftpDataSource(...)` - SFTP file operations
+- `S3DataSource(...)` - S3 file operations
+- `CSVParserService` - Parse SFTP CSV files
+- `client.graphql({ query, variables })` - Query current Fluent inventory
+- `client.graphqlMutation(mutation, variables)` - Execute inventory updates
+- `UniversalMapper(...)` - Transform aggregated data
+
+## Complete Working Code
+
+### 1. Environment Configuration
+
+Create `.env` file:
+
+```bash
+# Fluent Commerce OAuth2
+FLUENT_BASE_URL=https://api.fluentcommerce.com
+FLUENT_CLIENT_ID=your-oauth2-client-id
+FLUENT_CLIENT_SECRET=your-oauth2-client-secret
+FLUENT_USERNAME=your-username
+FLUENT_PASSWORD=your-password
+FLUENT_RETAILER_ID=your-retailer-id
+
+# Warehouse SFTP Source
+WAREHOUSE_SFTP_HOST=warehouse-sftp.example.com
+WAREHOUSE_SFTP_PORT=22
+WAREHOUSE_SFTP_USER=warehouse-user
+WAREHOUSE_SFTP_PASSWORD=warehouse-password
+WAREHOUSE_SFTP_PATH=/inventory/updates
+
+# Store S3 Source
+STORE_S3_BUCKET=store-inventory
+STORE_S3_REGION=us-east-1
+STORE_AWS_ACCESS_KEY_ID=your-aws-access-key
+STORE_AWS_SECRET_ACCESS_KEY=your-aws-secret-key
+STORE_S3_PREFIX=stores/inventory/
+
+# Reporting S3 Destination
+REPORT_S3_BUCKET=inventory-reports
+REPORT_S3_REGION=us-east-1
+REPORT_AWS_ACCESS_KEY_ID=your-aws-access-key
+REPORT_AWS_SECRET_ACCESS_KEY=your-aws-secret-key
+```
+
+### 2. Package Configuration
+
+Create `package.json`:
+
+```json
+{
+  "name": "multi-source-inventory-aggregation",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Multi-source inventory aggregation with Fluent Commerce",
+  "main": "src/index.js",
+  "scripts": {
+    "start": "node src/index.js",
+    "dev": "node --watch src/index.js",
+    "aggregation:once": "node src/index.js",
+    "aggregation:schedule": "node src/scheduler.js"
+  },
+  "dependencies": {
+    "@fluentcommerce/fc-connect-sdk": "^0.1.39",
+    "dotenv": "^16.0.0",
+    "node-cron": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}
+```
+
+### 3. Main Aggregation Script
+
+Create `src/index.js`:
+
+```javascript
+// 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,
+  S3DataSource,
+  CSVParserService,
+  UniversalMapper,
+  createConsoleLogger,
+  toStructuredLogger,
+} from '@fluentcommerce/fc-connect-sdk';
+import dotenv from 'dotenv';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+// Load environment variables
+dotenv.config();
+
+// Get current directory (ESM equivalent of __dirname)
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * MULTI-SOURCE INVENTORY AGGREGATION SYSTEM
+ *
+ * This script implements a sophisticated inventory aggregation workflow:
+ *
+ * 1. Data Collection: Gather inventory from multiple sources (SFTP + S3)
+ * 2. Aggregation: Combine data using Map-based deduplication
+ * 3. Reconciliation: Compare with Fluent Commerce current state
+ * 4. Update: Send only differences to Fluent via GraphQL mutations
+ * 5. Reporting: Generate comprehensive reconciliation report
+ *
+ * DESIGN DECISIONS:
+ * - Map-based aggregation: O(n) complexity for deduplication
+ * - Delta-only updates: Minimize API calls by updating only differences
+ * - Source tracking: Maintain provenance for debugging
+ * - Location granularity: Track inventory per SKU per location
+ * - Error recovery: Continue processing after non-critical failures
+ */
+
+/**
+ * Aggregated Inventory Item Structure
+ *
+ * This represents a single SKU's inventory across all locations.
+ * The Map structure provides O(1) lookup for deduplication.
+ *
+ * @typedef {Object} AggregatedItem
+ * @property {string} sku - Product SKU (unique identifier)
+ * @property {Map<string, number>} locations - Location ID -> quantity mapping
+ * @property {Set<string>} sources - Data sources that contributed to this item
+ */
+
+/**
+ * Initialize Logger
+ */
+const logger = toStructuredLogger(createConsoleLogger(), {
+  service: 'multi-source-aggregation',
+  version: '1.0.0',
+});
+
+/**
+ * Configuration Object
+ *
+ * Centralizes all configuration to make the script easily testable
+ * and configurable without code changes.
+ */
+const config = {
+  // Fluent Commerce
+  fluent: {
+    baseUrl: process.env.FLUENT_BASE_URL,
+    clientId: process.env.FLUENT_CLIENT_ID,
+    clientSecret: process.env.FLUENT_CLIENT_SECRET,
+    username: process.env.FLUENT_USERNAME,
+    password: process.env.FLUENT_PASSWORD,
+    retailerId: process.env.FLUENT_RETAILER_ID,
+  },
+
+  // Warehouse SFTP Source
+  warehouseSftp: {
+    host: process.env.WAREHOUSE_SFTP_HOST,
+    port: parseInt(process.env.WAREHOUSE_SFTP_PORT || '22'),
+    username: process.env.WAREHOUSE_SFTP_USER,
+    password: process.env.WAREHOUSE_SFTP_PASSWORD,
+    remotePath: process.env.WAREHOUSE_SFTP_PATH || '/inventory/updates',
+    filePattern: '*.csv',
+  },
+
+  // Store S3 Source
+  storeS3: {
+    bucket: process.env.STORE_S3_BUCKET,
+    region: process.env.STORE_S3_REGION || 'us-east-1',
+    accessKeyId: process.env.STORE_AWS_ACCESS_KEY_ID,
+    secretAccessKey: process.env.STORE_AWS_SECRET_ACCESS_KEY,
+    prefix: process.env.STORE_S3_PREFIX || 'stores/inventory/',
+  },
+
+  // Reporting S3 Destination
+  reportS3: {
+    bucket: process.env.REPORT_S3_BUCKET,
+    region: process.env.REPORT_S3_REGION || 'us-east-1',
+    accessKeyId: process.env.REPORT_AWS_ACCESS_KEY_ID,
+    secretAccessKey: process.env.REPORT_AWS_SECRET_ACCESS_KEY,
+  },
+
+  // Processing options
+  processing: {
+    batchSize: 100, // Number of records to process in one GraphQL mutation
+    maxRetries: 3,
+    retryDelay: 1000, // milliseconds
+  },
+};
+
+/**
+ * Validate Configuration
+ *
+ * Ensures all required environment variables are set before proceeding.
+ * Fails fast with clear error messages to prevent runtime issues.
+ */
+function validateConfig() {
+  const required = [
+    'FLUENT_BASE_URL',
+    'FLUENT_CLIENT_ID',
+    'FLUENT_CLIENT_SECRET',
+    'FLUENT_USERNAME',
+    'FLUENT_PASSWORD',
+    'FLUENT_RETAILER_ID',
+    'WAREHOUSE_SFTP_HOST',
+    'WAREHOUSE_SFTP_USER',
+    'WAREHOUSE_SFTP_PASSWORD',
+    'STORE_S3_BUCKET',
+    'STORE_AWS_ACCESS_KEY_ID',
+    'STORE_AWS_SECRET_ACCESS_KEY',
+  ];
+
+  const missing = required.filter(key => !process.env[key]);
+
+  if (missing.length > 0) {
+    throw new Error(`Missing required environment variables: ${missing.join(', ')}`);
+  }
+
+  logger.info('Configuration validated successfully');
+}
+
+/**
+ * Initialize Data Sources
+ *
+ * Creates SFTP and S3 data source instances for reading inventory files.
+ * Each source is configured with connection parameters and file patterns.
+ *
+ * @returns {Object} Data source instances
+ */
+function initializeDataSources() {
+  logger.info('Initializing data sources');
+
+  // SFTP Data Source for warehouse inventory (CSV format)
+  const sftpSource = new SftpDataSource(
+    {
+      type: 'SFTP_CSV',
+      connectionId: 'warehouse-sftp',
+      name: 'Warehouse SFTP',
+      settings: {
+        ...config.warehouseSftp,
+        csvDelimiter: ',',
+        csvHeaders: ['sku', 'location', 'quantity', 'status'],
+        csvSkipEmptyLines: true,
+        csvTrimValues: true,
+      },
+    },
+    logger
+  );
+
+  // S3 Data Source for store inventory (JSON format)
+  const s3Source = new S3DataSource(
+    {
+      type: 'S3_CSV',
+      connectionId: 'store-s3',
+      name: 'Store Inventory S3',
+      s3Config: config.storeS3,
+    },
+    logger
+  );
+
+  // S3 Data Source for reporting (write destination)
+  const reportS3Source = new S3DataSource(
+    {
+      type: 'S3_CSV',
+      connectionId: 'report-s3',
+      name: 'Report S3',
+      s3Config: config.reportS3,
+    },
+    logger
+  );
+
+  logger.info('Data sources initialized successfully');
+
+  return { sftpSource, s3Source, reportS3Source };
+}
+
+/**
+ * Collect Inventory from SFTP Source
+ *
+ * WAREHOUSE INVENTORY COLLECTION
+ *
+ * Algorithm:
+ * 1. List CSV files from SFTP remote path
+ * 2. Download each CSV file
+ * 3. Parse CSV using CSVParserService
+ * 4. Aggregate data into Map structure (SKU -> locations -> quantity)
+ * 5. Track source provenance (WAREHOUSE_SFTP)
+ *
+ * CSV Format Expected:
+ * sku,location,quantity,status
+ * PROD-001,WH-01,150,AVAILABLE
+ * PROD-002,WH-01,75,AVAILABLE
+ *
+ * @param {SftpDataSource} sftpSource - SFTP data source instance
+ * @param {Map<string, AggregatedItem>} inventoryMap - Aggregation map
+ * @returns {Promise<number>} Number of files processed
+ */
+async function collectSftpInventory(sftpSource, inventoryMap) {
+  logger.info('Collecting inventory from SFTP (warehouse)');
+
+  try {
+    // List CSV files from SFTP server
+    const files = await sftpSource.listFiles({
+      filePattern: config.warehouseSftp.filePattern,
+    });
+
+    logger.info(`Found ${files.length} CSV files in SFTP`);
+
+    if (files.length === 0) {
+      logger.warn('No files found in SFTP source');
+      return 0;
+    }
+
+    // Process each CSV file
+    for (const file of files) {
+      logger.info(`Processing SFTP file: ${file.name}`);
+
+      try {
+        // Download file content
+        const content = await sftpSource.downloadFile(file.name);
+
+        // Parse CSV content
+        const csvParser = new CSVParserService();
+        const records = await csvParser.parse(content);
+
+        logger.info(`Parsed ${records.length} records from ${file.name}`);
+
+        // Aggregate records into inventory map
+        for (const record of records) {
+          const sku = record.sku;
+          const location = record.location;
+          const quantity = parseInt(record.quantity) || 0;
+
+          // Skip invalid records
+          if (!sku || !location) {
+            logger.warn('Skipping record with missing SKU or location', { record });
+            continue;
+          }
+
+          // Get or create aggregated item
+          if (!inventoryMap.has(sku)) {
+            inventoryMap.set(sku, {
+              sku: sku,
+              locations: new Map(),
+              sources: new Set(),
+            });
+          }
+
+          const item = inventoryMap.get(sku);
+
+          // Aggregate quantity by location
+          // If SKU+location exists from another source, ADD quantities
+          const currentQty = item.locations.get(location) || 0;
+          item.locations.set(location, currentQty + quantity);
+
+          // Track source
+          item.sources.add('WAREHOUSE_SFTP');
+        }
+      } catch (fileError) {
+        logger.error(`Failed to process SFTP file: ${file.name}`, fileError);
+        // Continue processing other files
+      }
+    }
+
+    logger.info(`SFTP collection complete: ${inventoryMap.size} unique SKUs aggregated`);
+    return files.length;
+  } catch (error) {
+    logger.error('Failed to collect inventory from SFTP', error);
+    throw error;
+  }
+}
+
+/**
+ * Collect Inventory from S3 Source
+ *
+ * STORE INVENTORY COLLECTION
+ *
+ * Algorithm:
+ * 1. List JSON files from S3 bucket/prefix
+ * 2. Download each JSON file
+ * 3. Parse JSON (expected structure: { inventory: [...] })
+ * 4. Aggregate data into Map structure
+ * 5. Track source provenance (STORE_S3)
+ *
+ * JSON Format Expected:
+ * {
+ *   "storeId": "STORE-001",
+ *   "timestamp": "2024-01-15T10:30:00Z",
+ *   "inventory": [
+ *     { "productId": "PROD-001", "storeId": "STORE-001", "availableQty": 25 },
+ *     { "productId": "PROD-002", "storeId": "STORE-001", "availableQty": 50 }
+ *   ]
+ * }
+ *
+ * @param {S3DataSource} s3Source - S3 data source instance
+ * @param {Map<string, AggregatedItem>} inventoryMap - Aggregation map
+ * @returns {Promise<number>} Number of files processed
+ */
+async function collectS3Inventory(s3Source, inventoryMap) {
+  logger.info('Collecting inventory from S3 (stores)');
+
+  try {
+    // List JSON files from S3
+    const files = await s3Source.listFiles({
+      prefix: config.storeS3.prefix,
+    });
+
+    // Filter only JSON files
+    const jsonFiles = files.filter(file => file.name.toLowerCase().endsWith('.json'));
+
+    logger.info(`Found ${jsonFiles.length} JSON files in S3`);
+
+    if (jsonFiles.length === 0) {
+      logger.warn('No JSON files found in S3 source');
+      return 0;
+    }
+
+    // Process each JSON file
+    for (const file of jsonFiles) {
+      logger.info(`Processing S3 file: ${file.path}`);
+
+      try {
+        // Download file content
+        const content = await s3Source.downloadFile(file.path);
+
+        // Parse JSON
+        const storeData = JSON.parse(content);
+
+        if (!storeData.inventory || !Array.isArray(storeData.inventory)) {
+          logger.warn(`Invalid JSON structure in ${file.path}: missing 'inventory' array`);
+          continue;
+        }
+
+        logger.info(`Parsed ${storeData.inventory.length} records from ${file.path}`);
+
+        // Aggregate records into inventory map
+        for (const record of storeData.inventory) {
+          const sku = record.productId;
+          const location = record.storeId;
+          const quantity = parseInt(record.availableQty) || 0;
+
+          // Skip invalid records
+          if (!sku || !location) {
+            logger.warn('Skipping record with missing productId or storeId', { record });
+            continue;
+          }
+
+          // Get or create aggregated item
+          if (!inventoryMap.has(sku)) {
+            inventoryMap.set(sku, {
+              sku: sku,
+              locations: new Map(),
+              sources: new Set(),
+            });
+          }
+
+          const item = inventoryMap.get(sku);
+
+          // Aggregate quantity by location
+          const currentQty = item.locations.get(location) || 0;
+          item.locations.set(location, currentQty + quantity);
+
+          // Track source
+          item.sources.add('STORE_S3');
+        }
+      } catch (fileError) {
+        logger.error(`Failed to process S3 file: ${file.path}`, fileError);
+        // Continue processing other files
+      }
+    }
+
+    logger.info(`S3 collection complete: ${inventoryMap.size} unique SKUs aggregated`);
+    return jsonFiles.length;
+  } catch (error) {
+    logger.error('Failed to collect inventory from S3', error);
+    throw error;
+  }
+}
+
+/**
+ * Query Current Fluent Inventory
+ *
+ * CURRENT STATE RETRIEVAL
+ *
+ * Queries Fluent Commerce to get the current inventory state.
+ * This is necessary for reconciliation (comparing aggregated vs. current).
+ *
+ * GraphQL Query Pattern:
+ * - Uses pagination (first: 1000) to handle large inventories
+ * - Returns: ref, productRef, locationRef, qty, availableQty
+ * - Maps to SKU+Location structure for comparison
+ *
+ * @param {FluentClient} fluentClient - Fluent Commerce API client
+ * @returns {Promise<Map>} Map of "SKU:LOCATION" -> { qty, availableQty }
+ */
+async function queryCurrentInventory(fluentClient) {
+  logger.info('Querying current inventory from Fluent Commerce');
+
+  const query = `
+    query GetCurrentInventory($retailerId: ID!, $first: Int!, $after: String) {
+      inventoryPositions(
+        retailerId: $retailerId,
+        first: $first,
+        after: $after
+      ) {
+        edges {
+          cursor
+          node {
+            ref
+            productRef
+            locationRef
+            qty
+            availableQty
+            status
+            updatedOn
+          }
+        }
+        pageInfo {
+          hasNextPage
+        }
+      }
+    }
+  `;
+
+  try {
+    // Query with pagination support
+    const result = await fluentClient.graphql({
+      query,
+      variables: {
+        retailerId: config.fluent.retailerId,
+        first: 1000, // Adjust based on expected inventory size
+      },
+    });
+
+    if (!result.data || !result.data.inventoryPositions) {
+      throw new Error('Invalid GraphQL response structure');
+    }
+
+    const edges = result.data.inventoryPositions.edges || [];
+    logger.info(`Retrieved ${edges.length} inventory positions from Fluent`);
+
+    // Build lookup map: "SKU:LOCATION" -> inventory data
+    const currentInventory = new Map();
+
+    for (const edge of edges) {
+      const node = edge.node;
+      const key = `${node.productRef}:${node.locationRef}`;
+
+      currentInventory.set(key, {
+        ref: node.ref,
+        productRef: node.productRef,
+        locationRef: node.locationRef,
+        qty: node.qty,
+        availableQty: node.availableQty,
+        status: node.status,
+        updatedOn: node.updatedOn,
+      });
+    }
+
+    logger.info(`Current inventory indexed: ${currentInventory.size} positions`);
+    return currentInventory;
+  } catch (error) {
+    logger.error('Failed to query current inventory', error);
+    throw error;
+  }
+}
+
+/**
+ * Reconcile Inventory Differences
+ *
+ * RECONCILIATION ALGORITHM
+ *
+ * Compares aggregated inventory (from SFTP + S3) with Fluent current state.
+ * Identifies differences and generates update commands.
+ *
+ * Algorithm:
+ * 1. Iterate through aggregated inventory Map
+ * 2. For each SKU+Location, compare aggregated qty vs. Fluent qty
+ * 3. If difference exists (newQty !== currentQty), create update record
+ * 4. Calculate adjustment type (RECEIPT if increase, DISPATCH if decrease)
+ * 5. Build reconciliation report with detailed differences
+ *
+ * Update Decision Logic:
+ * - No Fluent record: CREATE (new inventory position)
+ * - Qty unchanged: SKIP (no update needed)
+ * - Qty increased: RECEIPT adjustment
+ * - Qty decreased: DISPATCH adjustment
+ *
+ * @param {Map<string, AggregatedItem>} inventoryMap - Aggregated inventory
+ * @param {Map} currentInventory - Current Fluent inventory
+ * @returns {Object} { updates: [], report: [] }
+ */
+function reconcileInventory(inventoryMap, currentInventory) {
+  logger.info('Reconciling inventory differences');
+
+  const updates = [];
+  const reconciliationReport = [];
+  let createCount = 0;
+  let updateCount = 0;
+  let skipCount = 0;
+
+  // Iterate through aggregated inventory
+  for (const [sku, aggregated] of inventoryMap.entries()) {
+    for (const [location, newQty] of aggregated.locations.entries()) {
+      const key = `${sku}:${location}`;
+
+      // Look up current inventory position
+      const current = currentInventory.get(key);
+      const currentQty = current ? current.qty : 0;
+      const difference = newQty - currentQty;
+
+      // Skip if no change
+      if (difference === 0 && current) {
+        skipCount++;
+        continue;
+      }
+
+      // Determine operation type
+      let operation;
+      if (!current) {
+        operation = 'CREATE';
+        createCount++;
+      } else if (difference > 0) {
+        operation = 'RECEIPT';
+        updateCount++;
+      } else {
+        operation = 'DISPATCH';
+        updateCount++;
+      }
+
+      // Create update record
+      updates.push({
+        ref: current ? current.ref : `${sku}-${location}`,
+        productRef: sku,
+        locationRef: location,
+        qty: newQty,
+        type: operation === 'CREATE' ? 'ADJUSTMENT' : operation,
+        adjustmentQty: Math.abs(difference),
+        reason: 'MULTI_SOURCE_SYNC',
+        attributes: {
+          sources: Array.from(aggregated.sources).join(','),
+          previousQty: currentQty,
+          newQty: newQty,
+          difference: difference,
+          syncedAt: new Date().toISOString(),
+        },
+      });
+
+      // Add to reconciliation report
+      reconciliationReport.push({
+        sku,
+        location,
+        operation,
+        previousQty: currentQty,
+        newQty: newQty,
+        difference,
+        sources: Array.from(aggregated.sources),
+        timestamp: new Date().toISOString(),
+      });
+    }
+  }
+
+  logger.info('Reconciliation complete', {
+    totalDifferences: updates.length,
+    creates: createCount,
+    updates: updateCount,
+    skipped: skipCount,
+  });
+
+  return { updates, reconciliationReport };
+}
+
+/**
+ * Execute Inventory Updates
+ *
+ * BATCH UPDATE EXECUTION
+ *
+ * Sends inventory updates to Fluent Commerce via GraphQL mutations.
+ * Processes updates in batches to avoid API limits.
+ *
+ * Mutation Pattern:
+ * - Uses adjustInventory mutation for updates
+ * - Batches of 100 records per mutation
+ * - Tracks success/failure per batch
+ * - Logs errors for retry/debugging
+ *
+ * @param {FluentClient} fluentClient - Fluent Commerce API client
+ * @param {Array} updates - Array of update records
+ * @returns {Promise<Object>} { success: number, failed: number, errors: [] }
+ */
+async function executeUpdates(fluentClient, updates) {
+  logger.info(`Executing ${updates.length} inventory updates`);
+
+  if (updates.length === 0) {
+    logger.info('No updates to execute');
+    return { success: 0, failed: 0, errors: [] };
+  }
+
+  const batchSize = config.processing.batchSize;
+  let successCount = 0;
+  let failedCount = 0;
+  const errors = [];
+
+  // Process in batches
+  for (let i = 0; i < updates.length; i += batchSize) {
+    const batch = updates.slice(i, i + batchSize);
+    const batchNumber = Math.floor(i / batchSize) + 1;
+    const totalBatches = Math.ceil(updates.length / batchSize);
+
+    logger.info(`Processing batch ${batchNumber}/${totalBatches} (${batch.length} records)`);
+
+    try {
+      // GraphQL mutation for inventory adjustment
+      const mutation = `
+        mutation AdjustInventory($updates: [InventoryAdjustmentInput]!) {
+          adjustInventory(input: $updates) {
+            success
+            failed
+            errors {
+              ref
+              message
+              code
+            }
+          }
+        }
+      `;
+
+      const result = await fluentClient.graphqlMutation(mutation, {
+        updates: batch,
+      });
+
+      if (result.data && result.data.adjustInventory) {
+        const batchResult = result.data.adjustInventory;
+        successCount += batchResult.success || 0;
+        failedCount += batchResult.failed || 0;
+
+        if (batchResult.errors && batchResult.errors.length > 0) {
+          errors.push(...batchResult.errors);
+          logger.warn(`Batch ${batchNumber} had ${batchResult.errors.length} errors`, {
+            errors: batchResult.errors.slice(0, 5), // Log first 5 errors
+          });
+        }
+
+        logger.info(
+          `Batch ${batchNumber} complete: ${batchResult.success} success, ${batchResult.failed} failed`
+        );
+      }
+    } catch (batchError) {
+      logger.error(`Batch ${batchNumber} failed completely`, batchError);
+      failedCount += batch.length;
+      errors.push({
+        batch: batchNumber,
+        message: batchError.message,
+        records: batch.length,
+      });
+    }
+  }
+
+  logger.info('Update execution complete', {
+    totalUpdates: updates.length,
+    success: successCount,
+    failed: failedCount,
+    errors: errors.length,
+  });
+
+  return { success: successCount, failed: failedCount, errors };
+}
+
+/**
+ * Generate Reconciliation Report
+ *
+ * COMPREHENSIVE REPORTING
+ *
+ * Creates a detailed JSON report of the reconciliation process.
+ * Includes statistics, detailed changes, and errors.
+ * Uploads report to S3 for auditing and monitoring.
+ *
+ * Report Structure:
+ * - timestamp: When reconciliation ran
+ * - sourcesProcessed: Files processed per source
+ * - statistics: Summary counts
+ * - reconciliation: Detailed changes (first 1000)
+ * - errors: Any errors encountered
+ *
+ * @param {S3DataSource} reportS3Source - S3 data source for report upload
+ * @param {Object} stats - Statistics object
+ * @returns {Promise<string>} Report S3 key
+ */
+async function generateReconciliationReport(reportS3Source, stats) {
+  logger.info('Generating reconciliation report');
+
+  const timestamp = new Date().toISOString();
+  const reportKey = `reconciliation/report-${timestamp.replace(/[:.]/g, '-')}.json`;
+
+  const report = {
+    timestamp,
+    version: '1.0.0',
+    sourcesProcessed: {
+      sftpFiles: stats.sftpFiles,
+      s3Files: stats.s3Files,
+    },
+    statistics: {
+      totalSKUs: stats.totalSKUs,
+      totalLocations: stats.totalLocations,
+      totalUpdates: stats.totalUpdates,
+      creates: stats.creates,
+      receipts: stats.receipts,
+      dispatches: stats.dispatches,
+      skipped: stats.skipped,
+      success: stats.success,
+      failed: stats.failed,
+    },
+    reconciliation: stats.reconciliationDetails.slice(0, 1000), // Limit to first 1000 for report size
+    errors: stats.errors || [],
+  };
+
+  // Upload report to S3
+  try {
+    await reportS3Source.uploadFile(reportKey, JSON.stringify(report, null, 2), {
+      contentType: 'application/json',
+    });
+
+    logger.info(`Reconciliation report uploaded: ${reportKey}`);
+    return reportKey;
+  } catch (error) {
+    logger.error('Failed to upload reconciliation report', error);
+    throw error;
+  }
+}
+
+/**
+ * Main Aggregation Function
+ *
+ * ORCHESTRATION ENTRY POINT
+ *
+ * Coordinates the entire multi-source aggregation workflow:
+ * 1. Validate configuration
+ * 2. Initialize data sources and Fluent client
+ * 3. Collect inventory from SFTP + S3
+ * 4. Query current Fluent inventory
+ * 5. Reconcile differences
+ * 6. Execute updates
+ * 7. Generate report
+ *
+ * Error Handling Strategy:
+ * - Configuration errors: Fail immediately
+ * - Source collection errors: Continue with other sources
+ * - Reconciliation errors: Fail (cannot proceed without comparison)
+ * - Update errors: Track failures but continue batch processing
+ *
+ * @returns {Promise<Object>} Final statistics
+ */
+async function aggregateInventory() {
+  const startTime = Date.now();
+
+  logger.info('='.repeat(80));
+  logger.info('MULTI-SOURCE INVENTORY AGGREGATION - START');
+  logger.info('='.repeat(80));
+
+  try {
+    // Step 1: Validate configuration
+    validateConfig();
+
+    // Step 2: Initialize data sources
+    const { sftpSource, s3Source, reportS3Source } = initializeDataSources();
+
+    // Step 3: Create Fluent client
+    logger.info('Creating Fluent Commerce client');
+    const fluentClient = await createClient(config.fluent);
+    logger.info('Fluent client created successfully');
+
+    // Step 4: Initialize aggregation map
+    // Map structure: SKU -> { sku, locations: Map<location, qty>, sources: Set<source> }
+    const inventoryMap = new Map();
+
+    // Step 5: Collect inventory from SFTP (warehouses)
+    logger.info('-'.repeat(80));
+    logger.info('PHASE 1: SFTP Collection');
+    logger.info('-'.repeat(80));
+    const sftpFiles = await collectSftpInventory(sftpSource, inventoryMap);
+
+    // Step 6: Collect inventory from S3 (stores)
+    logger.info('-'.repeat(80));
+    logger.info('PHASE 2: S3 Collection');
+    logger.info('-'.repeat(80));
+    const s3Files = await collectS3Inventory(s3Source, inventoryMap);
+
+    logger.info('-'.repeat(80));
+    logger.info('AGGREGATION COMPLETE');
+    logger.info('-'.repeat(80));
+    logger.info(`Total unique SKUs: ${inventoryMap.size}`);
+
+    // Calculate total locations
+    let totalLocations = 0;
+    for (const item of inventoryMap.values()) {
+      totalLocations += item.locations.size;
+    }
+    logger.info(`Total locations: ${totalLocations}`);
+
+    // Step 7: Query current Fluent inventory
+    logger.info('-'.repeat(80));
+    logger.info('PHASE 3: Current State Query');
+    logger.info('-'.repeat(80));
+    const currentInventory = await queryCurrentInventory(fluentClient);
+
+    // Step 8: Reconcile differences
+    logger.info('-'.repeat(80));
+    logger.info('PHASE 4: Reconciliation');
+    logger.info('-'.repeat(80));
+    const { updates, reconciliationReport } = reconcileInventory(inventoryMap, currentInventory);
+
+    // Step 9: Execute updates
+    logger.info('-'.repeat(80));
+    logger.info('PHASE 5: Update Execution');
+    logger.info('-'.repeat(80));
+    const updateResult = await executeUpdates(fluentClient, updates);
+
+    // Step 10: Generate report
+    logger.info('-'.repeat(80));
+    logger.info('PHASE 6: Report Generation');
+    logger.info('-'.repeat(80));
+
+    const stats = {
+      sftpFiles,
+      s3Files,
+      totalSKUs: inventoryMap.size,
+      totalLocations,
+      totalUpdates: updates.length,
+      creates: updates.filter(u => u.type === 'ADJUSTMENT').length,
+      receipts: updates.filter(u => u.type === 'RECEIPT').length,
+      dispatches: updates.filter(u => u.type === 'DISPATCH').length,
+      skipped: totalLocations - updates.length,
+      success: updateResult.success,
+      failed: updateResult.failed,
+      errors: updateResult.errors,
+      reconciliationDetails: reconciliationReport,
+    };
+
+    const reportKey = await generateReconciliationReport(reportS3Source, stats);
+
+    // Step 11: Final summary
+    const duration = Math.round((Date.now() - startTime) / 1000);
+
+    logger.info('='.repeat(80));
+    logger.info('MULTI-SOURCE INVENTORY AGGREGATION - COMPLETE');
+    logger.info('='.repeat(80));
+    logger.info(`Duration: ${duration} seconds`);
+    logger.info(`Sources processed: ${sftpFiles} SFTP files, ${s3Files} S3 files`);
+    logger.info(`Total SKUs: ${stats.totalSKUs}`);
+    logger.info(
+      `Total updates: ${stats.totalUpdates} (${stats.success} success, ${stats.failed} failed)`
+    );
+    logger.info(`Report: ${reportKey}`);
+    logger.info('='.repeat(80));
+
+    return stats;
+  } catch (error) {
+    logger.error('Multi-source aggregation failed', error);
+    throw error;
+  }
+}
+
+// Execute if run directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  aggregateInventory()
+    .then(() => {
+      logger.info('Aggregation completed successfully');
+      process.exit(0);
+    })
+    .catch(error => {
+      logger.error('Aggregation failed with error', error);
+      process.exit(1);
+    });
+}
+
+export { aggregateInventory, config };
+```
+
+### 4. Scheduler (Optional)
+
+Create `src/scheduler.js` for scheduled execution:
+
+```javascript
+import cron from 'node-cron';
+import { aggregateInventory } from './index.js';
+
+/**
+ * SCHEDULED AGGREGATION
+ *
+ * Runs aggregation on a schedule using cron syntax.
+ * Default: Hourly at minute 0 (e.g., 1:00, 2:00, 3:00)
+ *
+ * Cron Pattern: '0 * * * *'
+ * - Minute: 0 (at the top of the hour)
+ * - Hour: * (every hour)
+ * - Day of Month: * (every day)
+ * - Month: * (every month)
+ * - Day of Week: * (every day of week)
+ */
+
+console.log('Multi-Source Inventory Aggregation Scheduler');
+console.log('Schedule: Hourly at minute 0');
+console.log('Press Ctrl+C to stop');
+
+// Schedule task
+cron.schedule('0 * * * *', async () => {
+  console.log(`\n${'='.repeat(80)}`);
+  console.log(`Scheduled aggregation triggered: ${new Date().toISOString()}`);
+  console.log('='.repeat(80));
+
+  try {
+    await aggregateInventory();
+    console.log('Scheduled aggregation completed successfully');
+  } catch (error) {
+    console.error('Scheduled aggregation failed:', error);
+  }
+});
+
+// Run immediately on startup (optional)
+if (process.env.RUN_ON_STARTUP === 'true') {
+  console.log('Running initial aggregation on startup...');
+  aggregateInventory()
+    .then(() => console.log('Initial aggregation complete'))
+    .catch(error => console.error('Initial aggregation failed:', error));
+}
+```
+
+## Key Patterns Explained
+
+### Pattern 1: Multi-Source Data Collection
+
+**Challenge**: Collecting inventory from heterogeneous sources (CSV from SFTP, JSON from S3)
+
+**Solution**: Source-specific collection functions with unified aggregation structure
+
+```javascript
+// Each source has its own collection function
+await collectSftpInventory(sftpSource, inventoryMap); // CSV → Map
+await collectS3Inventory(s3Source, inventoryMap); // JSON → Map
+
+// Both populate the same Map structure:
+// Map<SKU, { locations: Map<location, qty>, sources: Set<source> }>
+```
+
+**Why This Works**:
+
+- Abstraction: Each source function handles its own format
+- Unified Structure: All sources aggregate into the same Map
+- Source Tracking: Set tracks which sources contributed to each SKU
+- Deduplication: Map automatically handles duplicate SKU+location combinations
+
+### Pattern 2: Map-Based Aggregation & Deduplication
+
+**Challenge**: Combine inventory from multiple sources, handling duplicates and quantities
+
+**Solution**: Nested Map structure with additive aggregation
+
+```javascript
+// Aggregation data structure
+const inventoryMap = new Map(); // SKU -> AggregatedItem
+
+// AggregatedItem structure:
+{
+  sku: 'PROD-001',
+  locations: Map<string, number>,  // location -> quantity
+  sources: Set<string>              // ['WAREHOUSE_SFTP', 'STORE_S3']
+}
+
+// Aggregation algorithm (additive for duplicates)
+if (!inventoryMap.has(sku)) {
+  inventoryMap.set(sku, {
+    sku: sku,
+    locations: new Map(),
+    sources: new Set()
+  });
+}
+
+const item = inventoryMap.get(sku);
+const currentQty = item.locations.get(location) || 0;
+item.locations.set(location, currentQty + quantity);  // ADD quantities
+item.sources.add(sourceName);
+```
+
+**Why This Works**:
+
+- O(1) lookup: Map provides fast SKU lookup
+- O(1) duplicate detection: Map automatically handles duplicates
+- Additive logic: Quantities from different sources are summed
+- Source provenance: Track which sources contributed (debugging/auditing)
+
+### Pattern 3: Reconciliation Algorithm
+
+**Challenge**: Compare aggregated inventory with Fluent current state to find differences
+
+**Solution**: Key-based lookup with delta calculation
+
+```javascript
+// Build lookup key: "SKU:LOCATION"
+const key = `${sku}:${location}`;
+
+// Look up current state
+const current = currentInventory.get(key);
+const currentQty = current ? current.qty : 0;
+
+// Calculate delta
+const difference = newQty - currentQty;
+
+// Determine operation
+if (difference === 0) {
+  operation = 'SKIP'; // No change
+} else if (!current) {
+  operation = 'CREATE'; // New inventory position
+} else if (difference > 0) {
+  operation = 'RECEIPT'; // Increase
+} else {
+  operation = 'DISPATCH'; // Decrease
+}
+```
+
+**Why This Works**:
+
+- Key-based comparison: Fast O(1) lookup for each SKU+location
+- Delta detection: Only send changes (minimizes API calls)
+- Operation classification: Clear intent (CREATE/RECEIPT/DISPATCH)
+- Skip optimization: Avoid unnecessary updates when qty unchanged
+
+### Pattern 4: Batch Update Execution
+
+**Challenge**: Send thousands of inventory updates without hitting API limits
+
+**Solution**: Batch processing with error tracking
+
+```javascript
+const batchSize = 100;
+
+for (let i = 0; i < updates.length; i += batchSize) {
+  const batch = updates.slice(i, i + batchSize);
+
+  try {
+    const result = await fluentClient.graphqlMutation(mutation, {
+      updates: batch,
+    });
+
+    // Track success/failure per batch
+    successCount += result.data.adjustInventory.success;
+    failedCount += result.data.adjustInventory.failed;
+  } catch (batchError) {
+    // Log error but continue processing other batches
+    logger.error(`Batch ${batchNumber} failed`, batchError);
+    failedCount += batch.length;
+  }
+}
+```
+
+**Why This Works**:
+
+- Batch optimization: Reduces API calls (1000 updates → 10 API calls at batch size 100)
+- Error isolation: One batch failure doesn't stop other batches
+- Progress tracking: Log after each batch for monitoring
+- Retry-friendly: Failed batches can be retried individually
+
+### Pattern 5: Comprehensive Report Generation
+
+**Challenge**: Provide audit trail and debugging information for reconciliation
+
+**Solution**: Structured JSON report with statistics and details
+
+```javascript
+const report = {
+  timestamp: new Date().toISOString(),
+  version: '1.0.0',
+
+  // Source processing statistics
+  sourcesProcessed: {
+    sftpFiles: 5,
+    s3Files: 20,
+  },
+
+  // Aggregate statistics
+  statistics: {
+    totalSKUs: 1250,
+    totalLocations: 3400,
+    totalUpdates: 450,
+    creates: 50,
+    receipts: 200,
+    dispatches: 200,
+    skipped: 2950,
+    success: 445,
+    failed: 5,
+  },
+
+  // Detailed changes (first 1000)
+  reconciliation: [
+    {
+      sku: 'PROD-001',
+      location: 'WH-01',
+      operation: 'RECEIPT',
+      previousQty: 100,
+      newQty: 150,
+      difference: 50,
+      sources: ['WAREHOUSE_SFTP'],
+      timestamp: '2024-01-15T10:30:00Z',
+    },
+  ],
+
+  // Errors encountered
+  errors: [],
+};
+
+// Upload to S3 for persistence
+await reportS3Source.uploadFile(reportKey, JSON.stringify(report, null, 2));
+```
+
+**Why This Works**:
+
+- Audit trail: Permanent record of what was updated
+- Debugging: Detailed information for troubleshooting failures
+- Monitoring: Statistics for dashboards and alerts
+- Compliance: Provenance tracking (which sources contributed)
+
+## Deployment Options
+
+### Option 1: Scheduled Execution (Hourly)
+
+Run aggregation every hour using cron:
+
+```bash
+# Install dependencies
+npm install
+
+# Run scheduler (stays running, executes hourly)
+npm run aggregation:schedule
+```
+
+**Use Case**: Regular inventory synchronization from multiple sources
+
+### Option 2: Manual Execution (On-Demand)
+
+Run aggregation once, manually triggered:
+
+```bash
+# Single execution
+npm run aggregation:once
+```
+
+**Use Case**: Testing, troubleshooting, or ad-hoc reconciliation
+
+### Option 3: Containerized Deployment
+
+Create `Dockerfile`:
+
+```dockerfile
+FROM node:18-alpine
+
+WORKDIR /app
+
+COPY package*.json ./
+RUN npm ci --production
+
+COPY src/ ./src/
+
+CMD ["node", "src/scheduler.js"]
+```
+
+Build and run:
+
+```bash
+# Build Docker image
+docker build -t multi-source-aggregation .
+
+# Run container
+docker run -d \
+  --name inventory-aggregation \
+  --env-file .env \
+  --restart unless-stopped \
+  multi-source-aggregation
+```
+
+**Use Case**: Production deployment with container orchestration (Kubernetes, ECS)
+
+## Testing
+
+### Test with Mock Data
+
+Create `tests/test-aggregation.js`:
+
+```javascript
+import { aggregateInventory, config } from '../src/index.js';
+
+// Override config for testing
+config.processing.batchSize = 10;
+
+// Mock environment variables
+process.env.FLUENT_BASE_URL = 'https://api.fluentcommerce.com';
+process.env.FLUENT_CLIENT_ID = 'test-client-id';
+// ... (other test env vars)
+
+// Run aggregation
+aggregateInventory()
+  .then(stats => {
+    console.log('Test completed successfully');
+    console.log(JSON.stringify(stats, null, 2));
+  })
+  .catch(error => {
+    console.error('Test failed:', error);
+    process.exit(1);
+  });
+```
+
+Run test:
+
+```bash
+node tests/test-aggregation.js
+```
+
+## Common Issues
+
+### Issue 1: SFTP Connection Timeout
+
+**Symptom**: `Error: Connection timeout after 30s`
+
+**Solution**:
+
+```bash
+# Increase timeout in .env
+WAREHOUSE_SFTP_TIMEOUT=60000
+
+# Or in code (src/index.js):
+settings: {
+  ...config.warehouseSftp,
+  connectionTimeout: 60000  // 60 seconds
+}
+```
+
+### Issue 2: S3 Access Denied
+
+**Symptom**: `Error: AccessDenied: User is not authorized`
+
+**Solution**:
+
+- Verify AWS credentials are correct
+- Check IAM policy includes:
+  - `s3:GetObject` on source bucket
+  - `s3:PutObject` on report bucket
+  - `s3:ListBucket` on both buckets
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": ["s3:GetObject", "s3:ListBucket"],
+      "Resource": ["arn:aws:s3:::store-inventory", "arn:aws:s3:::store-inventory/*"]
+    },
+    {
+      "Effect": "Allow",
+      "Action": ["s3:PutObject"],
+      "Resource": ["arn:aws:s3:::inventory-reports/*"]
+    }
+  ]
+}
+```
+
+### Issue 3: Fluent GraphQL Errors
+
+**Symptom**: `Error: adjustInventory mutation failed`
+
+**Solution**:
+
+- Check Fluent API credentials
+- Verify retailerId is correct
+- Ensure inventory positions exist (or use CREATE operation)
+- Check mutation input format matches Fluent schema
+
+### Issue 4: Memory Issues with Large Datasets
+
+**Symptom**: `JavaScript heap out of memory`
+
+**Solution**:
+
+```bash
+# Increase Node.js heap size
+node --max-old-space-size=4096 src/index.js
+
+# Or reduce batch size in config
+config.processing.batchSize = 50;
+```
+
+### Issue 5: Duplicate SKUs from Multiple Sources
+
+**Symptom**: Quantities are doubled or incorrect
+
+**Solution**:
+
+- **Intended behavior**: Quantities are ADDED from multiple sources
+- If you need OVERRIDE behavior (last source wins), modify aggregation:
+
+```javascript
+// OVERRIDE mode (replace instead of add)
+item.locations.set(location, quantity); // Don't add, just set
+```
+
+### Issue 6: Report Upload Failures
+
+**Symptom**: `Failed to upload reconciliation report`
+
+**Solution**:
+
+- Check report S3 bucket exists
+- Verify write permissions
+- Check S3 region matches configuration
+- Ensure network connectivity to S3
+
+## Related Guides
+
+- **[Simple CSV Ingestion](./s3-csv-batch-api.md)** - Single source ingestion pattern
+- **[SFTP to Fluent](../../02-CORE-GUIDES/ingestion/ingestion-readme.md)** - SFTP-specific workflows (see Versori templates)
+- **[S3 Parquet Extraction](./graphql-query-export.md)** - S3 and Parquet handling
+- **[Connector Scenarios](../../02-CORE-GUIDES/advanced-services/advanced-services-readme.md)** - Multi-source patterns
+- **[Universal Mapping Guide](../../02-CORE-GUIDES/advanced-services/advanced-services-readme.md)** - Field transformation
+- **[SDK Resolvers](../../02-CORE-GUIDES/mapping/resolvers/mapping-resolvers-resolver-guide.md)** - Built-in transformations
+
+## Next Steps
+
+1. **Add Custom Transformations**: Use UniversalMapper for complex field mappings
+2. **Implement Retry Logic**: Add exponential backoff for transient failures
+3. **Add Monitoring**: Integrate with CloudWatch, Datadog, or other monitoring
+4. **Implement Alerting**: Send notifications on failures or reconciliation anomalies
+5. **Add State Management**: Track processed files to avoid reprocessing
+6. **Optimize Performance**: Implement parallel processing for large datasets