@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/01-TEMPLATES/standalone/standalone-s3-csv-batch-api.md

@@ -1,1390 +1,1390 @@
-# Standalone: S3 CSV → Fluent Batch API
-
-**FC Connect SDK Use Case Guide**
-
-> **SDK**: [@fluentcommerce/fc-connect-sdk](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk)
-> **Version**: Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
-
-**Context**: Node.js script that reads CSV inventory files from S3 and updates Fluent Commerce inventory via Batch API
-
-**Complexity**: Medium
-
-**Runtime**: Node.js ≥18 / Deno
-
-**Estimated Lines**: ~500 lines
-
-## What You'll Build
-
-- Standalone Node.js/Deno script (no Versori)
-- OAuth2 authentication with Fluent Commerce
-- S3 file listing and download with AWS SDK
-- CSV parsing with validation
-- UniversalMapper for field transformations
-- Batch API processing with job management
-- Error handling and logging
-- Optional: Schedule with cron or AWS EventBridge
-
-## SDK Methods Used
-
-- `createClient({ config: { baseUrl, clientId, clientSecret, retailerId } })` - OAuth2 client
-- `S3DataSource(config, logger)` - S3 operations
-- `CSVParserService` - CSV parsing
-- `UniversalMapper(mappingConfig)` - Field mapping
-- `client.createJob({ name, retailerId })` - Create Batch job
-- `client.sendBatch(jobId, { entities })` - Send inventory batch
-- `client.getJobStatus(jobId)` - Check status
-
----
-
-## Complete Working Implementation
-
-### 1. Project Setup
-
-```bash
-# Create project directory
-mkdir inventory-sync-standalone
-cd inventory-sync-standalone
-
-# Initialize Node.js project
-npm init -y
-
-# Install dependencies
-npm install @fluentcommerce/fc-connect-sdk dotenv
-```
-
-### Method selection (SDK)
-
-- Queries → `client.graphql`
-- Mutations → `client.graphql`
-- Advanced needs (pagination/telemetry) → `client.graphql` with pagination options
-
-```typescript
-// Query (use graphql for both queries and mutations)
-const products = await client.graphql({ query, variables });
-
-// Mutation (use graphql for both queries and mutations)
-const result = await client.graphql({ query: mutation, variables });
-
-// Advanced pagination
-const res = await client.graphql({ query, variables, pagination: { maxPages: 50 } });
-```
-
-### 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
-
-# AWS S3 Configuration
-AWS_ACCESS_KEY_ID=your-aws-access-key
-AWS_SECRET_ACCESS_KEY=your-aws-secret-key
-AWS_REGION=us-east-1
-AWS_BUCKET_NAME=your-inventory-bucket
-AWS_FILE_PREFIX=inventory/updates/
-
-# Processing Configuration
-BATCH_SIZE=100
-JOB_NAME_PREFIX=S3-CSV-Inventory-Update
-ARCHIVE_PREFIX=inventory/archive/
-ERROR_PREFIX=inventory/errors/
-
-# Optional: Scheduling
-ENABLE_SCHEDULING=false
-CRON_SCHEDULE=0 */4 * * *
-```
-
-### 3. Main Script Implementation
-
-Create `src/inventory-sync.ts`:
-
-```typescript
-import 'dotenv/config';
-// FC Connect SDK+
-// Install: npm install @fluentcommerce/fc-connect-sdk@latest
-// Docs: https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk
-// GitHub: https://github.com/fluentcommerce/fc-connect-sdk
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-import { S3DataSource } from '@fluentcommerce/fc-connect-sdk';
-import { CSVParserService } from '@fluentcommerce/fc-connect-sdk';
-import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-
-/**
- * ARCHITECTURE:
- *
- * This standalone script implements a complete inventory sync workflow:
- * 1. List CSV files from S3 bucket
- * 2. Download and parse CSV files
- * 3. Map CSV fields to Fluent inventory format
- * 4. Create Batch API job
- * 5. Send inventory updates in batches
- * 6. Poll job status until complete
- * 7. Archive successful files, move errors
- *
- * ERROR HANDLING STRATEGY:
- * - File-level errors: Move to error folder, continue with other files
- * - Batch errors: Log and continue (Fluent API provides detailed error reports)
- * - Fatal errors: Exit with error code for monitoring/alerting
- *
- * STATE MANAGEMENT:
- * - No state tracking in this basic version (processes all files)
- * - Advanced: Use S3 metadata or external DB to track processed files
- */
-
-// ============================================================================
-// CONFIGURATION & SETUP
-// ============================================================================
-
-interface SyncConfig {
-  fluent: {
-    baseUrl: string;
-    clientId: string;
-    clientSecret: string;
-    retailerId: string;
-  };
-  s3: {
-    accessKeyId: string;
-    secretAccessKey: string;
-    region: string;
-    bucket: string;
-    prefix: string;
-  };
-  processing: {
-    batchSize: number;
-    jobNamePrefix: string;
-    archivePrefix: string;
-    errorPrefix: string;
-  };
-}
-
-/**
- * Load configuration from environment variables
- * Validates all required config before proceeding
- */
-function loadConfig(): SyncConfig {
-  const requiredEnvVars = [
-    'FLUENT_BASE_URL',
-    'FLUENT_CLIENT_ID',
-    'FLUENT_CLIENT_SECRET',
-    'FLUENT_RETAILER_ID',
-    'AWS_ACCESS_KEY_ID',
-    'AWS_SECRET_ACCESS_KEY',
-    'AWS_REGION',
-    'AWS_BUCKET_NAME',
-  ];
-
-  // Validate all required environment variables are present
-  const missing = requiredEnvVars.filter(v => !process.env[v]);
-  if (missing.length > 0) {
-    throw new Error(`Missing required environment variables: ${missing.join(', ')}`);
-  }
-
-  return {
-    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!,
-    },
-    s3: {
-      accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
-      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
-      region: process.env.AWS_REGION!,
-      bucket: process.env.AWS_BUCKET_NAME!,
-      prefix: process.env.AWS_FILE_PREFIX || 'inventory/updates/',
-    },
-    processing: {
-      batchSize: parseInt(process.env.BATCH_SIZE || '100'),
-      jobNamePrefix: process.env.JOB_NAME_PREFIX || 'S3-CSV-Inventory-Update',
-      archivePrefix: process.env.ARCHIVE_PREFIX || 'inventory/archive/',
-      errorPrefix: process.env.ERROR_PREFIX || 'inventory/errors/',
-    },
-  };
-}
-
-// ============================================================================
-// FIELD MAPPING CONFIGURATION
-// ============================================================================
-
-/**
- * UniversalMapper configuration for CSV → Fluent Batch API transformation
- *
- * FIELD MAPPING RULES:
- * - ref: Product SKU (required) - uppercase transformation
- * - locationRef: Location code (required) - prefix with "LOC:"
- * - qty: Quantity (required) - parse as integer, default to 0
- * - type: Inventory type (required) - defaults to "ADJUSTMENT"
- * - status: Inventory status (optional) - defaults to "ACTIVE"
- *
- * SDK RESOLVERS USED:
- * - sdk.uppercase: Convert SKU to uppercase for consistency
- * - sdk.parseInt: Parse quantity string to integer
- * - sdk.trim: Remove whitespace from location codes
- * - sdk.defaultTo: Provide fallback values
- */
-const inventoryMappingConfig = {
-  version: '1.0.0',
-  description: 'S3 CSV to Fluent Commerce Inventory Mapping',
-  fields: {
-    // Product SKU (required field)
-    ref: {
-      source: 'sku',
-      resolver: 'sdk.uppercase', // Normalize to uppercase
-      required: true,
-    },
-    // Location reference (required field)
-    locationRef: {
-      source: 'location',
-      resolver: 'sdk.trim', // Remove whitespace
-      required: true,
-    },
-    // Quantity (required field)
-    qty: {
-      source: 'quantity',
-      resolver: 'sdk.parseInt', // Parse as integer
-      required: true,
-    },
-    // Inventory type (defaults to ADJUSTMENT)
-    type: {
-      value: 'ADJUSTMENT', // Static value
-    },
-    // Inventory status (optional, with default)
-    status: {
-      source: 'status',
-      resolver: 'sdk.uppercase',
-      defaultValue: 'ACTIVE', // Fallback if not provided
-    },
-    // Expected date (optional)
-    expectedOn: {
-      source: 'expected_date',
-      resolver: 'sdk.formatDate', // Convert to ISO date format
-    },
-  },
-};
-
-// ============================================================================
-// LOGGER IMPLEMENTATION
-// ============================================================================
-
-/**
- * Simple console logger with timestamp and log levels
- * Production: Replace with Winston, Bunyan, or Pino
- */
-const logger = {
-  debug: (message: string, meta?: any) => {
-    if (process.env.LOG_LEVEL === 'debug') {
-      console.log(`[${new Date().toISOString()}] DEBUG: ${message}`, meta || '');
-    }
-  },
-  info: (message: string, meta?: any) => {
-    console.log(`[${new Date().toISOString()}] INFO: ${message}`, meta || '');
-  },
-  warn: (message: string, meta?: any) => {
-    console.warn(`[${new Date().toISOString()}] WARN: ${message}`, meta || '');
-  },
-  error: (message: string, error?: Error, meta?: any) => {
-    console.error(
-      `[${new Date().toISOString()}] ERROR: ${message}`,
-      error?.message || '',
-      meta || ''
-    );
-  },
-};
-
-// ============================================================================
-// MAIN SYNC ORCHESTRATION
-// ============================================================================
-
-/**
- * Main inventory sync function
- *
- * ALGORITHM:
- * 1. Initialize SDK clients (Fluent, S3, CSV parser, mapper)
- * 2. List CSV files from S3 prefix
- * 3. For each file:
- *    a. Download file content
- *    b. Parse CSV to records
- *    c. Validate records (skip invalid)
- *    d. Map records using UniversalMapper
- *    e. Create Batch API job
- *    f. Send batches (chunked by batch size)
- *    g. Poll job status until complete
- *    h. Archive successful files OR move to error folder
- * 4. Return summary statistics
- */
-async function syncInventory(): Promise<{
-  filesProcessed: number;
-  filesSucceeded: number;
-  filesFailed: number;
-  totalRecordsProcessed: number;
-  totalRecordsFailed: number;
-}> {
-  const startTime = Date.now();
-  logger.info('='.repeat(80));
-  logger.info('Starting S3 CSV → Fluent Batch API inventory sync');
-  logger.info('='.repeat(80));
-
-  // Load configuration
-  const config = loadConfig();
-  logger.info('Configuration loaded', {
-    s3Bucket: config.s3.bucket,
-    s3Prefix: config.s3.prefix,
-    batchSize: config.processing.batchSize,
-  });
-
-  // ───────────────────────────────────────────────────────────────────────────
-  // STEP 1: Initialize SDK Clients
-  // ───────────────────────────────────────────────────────────────────────────
-
-  // Initialize Fluent Client with OAuth2
-  logger.info('Initializing Fluent Commerce client...');
-  const fluentClient = await createClient({
-    config: {
-      baseUrl: config.fluent.baseUrl,
-      clientId: config.fluent.clientId,
-      clientSecret: config.fluent.clientSecret,
-      retailerId: config.fluent.retailerId,
-    },
-  });
-
-  // Initialize S3 Data Source
-  logger.info('Initializing S3 data source...');
-  const s3Source = new S3DataSource(
-    {
-      type: 'S3_CSV',
-      connectionId: 'inventory-s3',
-      name: 'Inventory S3 Source',
-      s3Config: {
-        bucket: config.s3.bucket,
-        region: config.s3.region,
-        accessKeyId: config.s3.accessKeyId,
-        secretAccessKey: config.s3.secretAccessKey,
-      },
-    },
-    logger
-  );
-
-  // Initialize CSV Parser
-  const csvParser = new CSVParserService();
-
-  // Initialize Universal Mapper
-  const mapper = new UniversalMapper(inventoryMappingConfig, {
-    logger,
-    fluentClient,
-  });
-
-  // Validate S3 connection
-  logger.info('Validating S3 connection...');
-  const s3Connected = await s3Source.validateConnection();
-  if (!s3Connected) {
-    throw new Error('Failed to connect to S3 bucket');
-  }
-  logger.info('S3 connection validated successfully');
-
-  // ───────────────────────────────────────────────────────────────────────────
-  // STEP 2: List CSV Files from S3
-  // ───────────────────────────────────────────────────────────────────────────
-
-  logger.info(`Listing CSV files from S3 prefix: ${config.s3.prefix}`);
-  const files = await s3Source.listFiles({
-    prefix: config.s3.prefix,
-    maxKeys: 1000,
-  });
-
-  // Filter for CSV files only
-  // NOTE: S3 doesn't support glob patterns, so manual filtering is required
-  // IMPORTANT: Use .endsWith('.csv') NOT .endsWith('*.csv')
-  //   ✓ Correct:  f.name.endsWith('.csv')
-  //   ✗ Wrong:    f.name.endsWith('*.csv')  // Would never match!
-  const csvFiles = files.filter(f => f.name.toLowerCase().endsWith('.csv'));
-
-  logger.info(`Found ${csvFiles.length} CSV files to process`, {
-    totalFiles: files.length,
-    csvFiles: csvFiles.length,
-  });
-
-  if (csvFiles.length === 0) {
-    logger.info('No CSV files found. Exiting.');
-    return {
-      filesProcessed: 0,
-      filesSucceeded: 0,
-      filesFailed: 0,
-      totalRecordsProcessed: 0,
-      totalRecordsFailed: 0,
-    };
-  }
-
-  // ───────────────────────────────────────────────────────────────────────────
-  // STEP 3: Process Each CSV File
-  // ───────────────────────────────────────────────────────────────────────────
-
-  let filesSucceeded = 0;
-  let filesFailed = 0;
-  let totalRecordsProcessed = 0;
-  let totalRecordsFailed = 0;
-
-  for (const file of csvFiles) {
-    logger.info('-'.repeat(80));
-    logger.info(`Processing file: ${file.name}`, {
-      size: file.size,
-      lastModified: file.lastModified,
-    });
-
-    try {
-      // ─────────────────────────────────────────────────────────────────────
-      // STEP 3a: Download CSV File
-      // ─────────────────────────────────────────────────────────────────────
-      logger.info(`Downloading file: ${file.path}`);
-      const csvContent = await s3Source.downloadFile(file.path);
-      logger.info(
-        `Downloaded ${typeof csvContent === 'string' ? csvContent.length : csvContent.length} bytes`
-      );
-
-      // ─────────────────────────────────────────────────────────────────────
-      // STEP 3b: Parse CSV to Records
-      // ─────────────────────────────────────────────────────────────────────
-      logger.info('Parsing CSV content...');
-      const records = await csvParser.parse(csvContent as string);
-      logger.info(`Parsed ${records.length} records from CSV`);
-
-      if (records.length === 0) {
-        logger.warn('CSV file is empty, skipping');
-        continue;
-      }
-
-      // ─────────────────────────────────────────────────────────────────────
-      // STEP 3c: Validate Records (Basic Validation)
-      // ─────────────────────────────────────────────────────────────────────
-      logger.info('Validating records...');
-      const validRecords = records.filter((record: any, index: number) => {
-        // Check for required fields
-        if (!record.sku || !record.location || record.quantity === undefined) {
-          logger.warn(`Record ${index + 1} missing required fields, skipping`, {
-            record,
-          });
-          totalRecordsFailed++;
-          return false;
-        }
-
-        // Validate quantity is numeric
-        if (isNaN(Number(record.quantity))) {
-          logger.warn(`Record ${index + 1} has invalid quantity, skipping`, {
-            record,
-          });
-          totalRecordsFailed++;
-          return false;
-        }
-
-        return true;
-      });
-
-      logger.info(
-        `Validation complete: ${validRecords.length} valid, ${records.length - validRecords.length} invalid`
-      );
-
-      if (validRecords.length === 0) {
-        logger.warn('No valid records found in file, skipping');
-        continue;
-      }
-
-      // ─────────────────────────────────────────────────────────────────────
-      // STEP 3d: Map Records Using UniversalMapper
-      // ─────────────────────────────────────────────────────────────────────
-      logger.info('Mapping records using UniversalMapper...');
-      const mappedRecords: any[] = [];
-      const mappingErrors: string[] = [];
-
-      for (let i = 0; i < validRecords.length; i++) {
-        const record = validRecords[i];
-        const result = await mapper.map(record);
-
-        if (result.success) {
-          mappedRecords.push(result.data);
-        } else {
-          logger.warn(`Record ${i + 1} mapping failed`, {
-            errors: result.errors,
-            record,
-          });
-          mappingErrors.push(`Record ${i + 1}: ${result.errors?.join(', ')}`);
-          totalRecordsFailed++;
-        }
-      }
-
-      logger.info(
-        `Mapping complete: ${mappedRecords.length} mapped, ${mappingErrors.length} failed`
-      );
-
-      if (mappedRecords.length === 0) {
-        logger.warn('No records successfully mapped, skipping file');
-        continue;
-      }
-
-      // ─────────────────────────────────────────────────────────────────────
-      // STEP 3e: Create Batch API Job
-      // ─────────────────────────────────────────────────────────────────────
-      const jobName = `${config.processing.jobNamePrefix} - ${file.name} - ${new Date().toISOString()}`;
-      logger.info(`Creating Batch API job: ${jobName}`);
-
-      const job = await fluentClient.createJob({
-        name: jobName,
-        retailerId: config.fluent.retailerId,
-      });
-
-      logger.info(`Job created successfully`, {
-        jobId: job.id,
-        status: job.status,
-      });
-
-      // ─────────────────────────────────────────────────────────────────────
-      // STEP 3f: Send Batches (Chunked by Batch Size)
-      // ─────────────────────────────────────────────────────────────────────
-      logger.info(
-        `Sending ${mappedRecords.length} records in batches of ${config.processing.batchSize}`
-      );
-      const batches = chunk(mappedRecords, config.processing.batchSize);
-
-      for (let i = 0; i < batches.length; i++) {
-        const batch = batches[i];
-        logger.info(`Sending batch ${i + 1}/${batches.length} (${batch.length} records)`);
-
-        const batchResponse = await fluentClient.sendBatch(job.id, {
-          entities: batch,
-        });
-
-        logger.info(`Batch ${i + 1} sent successfully`, {
-          batchId: batchResponse.id,
-          status: batchResponse.status,
-        });
-      }
-
-      // ─────────────────────────────────────────────────────────────────────
-      // STEP 3g: Poll Job Status Until Complete
-      // ─────────────────────────────────────────────────────────────────────
-      logger.info('Polling job status...');
-      const finalStatus = await pollJobStatus(fluentClient, job.id, logger);
-
-      logger.info(`Job completed with status: ${finalStatus.status}`, {
-        jobId: job.id,
-        status: finalStatus.status,
-      });
-
-      // Check if job succeeded
-      if (finalStatus.status === 'COMPLETE') {
-        totalRecordsProcessed += mappedRecords.length;
-        filesSucceeded++;
-
-        // ───────────────────────────────────────────────────────────────────
-        // STEP 3h: Archive Successful File
-        // ───────────────────────────────────────────────────────────────────
-        const archivePath = `${config.processing.archivePrefix}${new Date().toISOString().split('T')[0]}/${file.name}`;
-        logger.info(`Archiving file to: ${archivePath}`);
-        await s3Source.moveFile(file.path, archivePath);
-        logger.info('File archived successfully');
-      } else {
-        // Job failed or has errors
-        logger.error('Job failed or has errors', undefined, {
-          jobId: job.id,
-          status: finalStatus.status,
-        });
-
-        // Move to error folder
-        const errorPath = `${config.processing.errorPrefix}${new Date().toISOString().split('T')[0]}/${file.name}`;
-        logger.info(`Moving file to error folder: ${errorPath}`);
-        await s3Source.moveFile(file.path, errorPath);
-        logger.info('File moved to error folder');
-
-        filesFailed++;
-      }
-    } catch (error) {
-      // File processing error
-      logger.error(`Failed to process file: ${file.name}`, error as Error);
-      filesFailed++;
-
-      try {
-        // Move to error folder
-        const errorPath = `${config.processing.errorPrefix}${new Date().toISOString().split('T')[0]}/${file.name}`;
-        await s3Source.moveFile(file.path, errorPath);
-        logger.info('File moved to error folder after processing error');
-      } catch (moveError) {
-        logger.error('Failed to move file to error folder', moveError as Error);
-      }
-    }
-  }
-
-  // ───────────────────────────────────────────────────────────────────────────
-  // STEP 4: Summary Statistics
-  // ───────────────────────────────────────────────────────────────────────────
-
-  const duration = Date.now() - startTime;
-  logger.info('='.repeat(80));
-  logger.info('Inventory sync completed', {
-    duration: `${(duration / 1000).toFixed(2)}s`,
-    filesProcessed: csvFiles.length,
-    filesSucceeded,
-    filesFailed,
-    totalRecordsProcessed,
-    totalRecordsFailed,
-  });
-  logger.info('='.repeat(80));
-
-  return {
-    filesProcessed: csvFiles.length,
-    filesSucceeded,
-    filesFailed,
-    totalRecordsProcessed,
-    totalRecordsFailed,
-  };
-}
-
-// ============================================================================
-// HELPER FUNCTIONS
-// ============================================================================
-
-/**
- * Poll Batch API job status until completion
- *
- * POLLING STRATEGY:
- * - Initial delay: 2 seconds
- * - Max delay: 30 seconds
- * - Exponential backoff with 1.5x multiplier
- * - Timeout: 30 minutes
- *
- * TERMINAL STATES:
- * - COMPLETE: Job succeeded
- * - FAILED: Job failed (API error, validation errors, etc.)
- * - Other statuses: Continue polling
- */
-async function pollJobStatus(client: any, jobId: string, logger: any): Promise<any> {
-  let delay = 2000; // Start with 2 second delay
-  const maxDelay = 30000; // Cap at 30 seconds
-  const timeout = 30 * 60 * 1000; // 30 minutes
-  const startTime = Date.now();
-
-  while (true) {
-    // Check timeout
-    if (Date.now() - startTime > timeout) {
-      throw new Error('Job status polling timeout (30 minutes)');
-    }
-
-    // Get job status
-    const status = await client.getJobStatus(jobId);
-    logger.debug(`Job status: ${status.status}`, {
-      jobId,
-      status: status.status,
-    });
-
-    // Check terminal states
-    if (status.status === 'COMPLETE' || status.status === 'FAILED') {
-      return status;
-    }
-
-    // Wait before next poll
-    await sleep(delay);
-
-    // Increase delay with exponential backoff (1.5x multiplier)
-    delay = Math.min(delay * 1.5, maxDelay);
-  }
-}
-
-/**
- * Sleep helper function
- */
-function sleep(ms: number): Promise<void> {
-  return new Promise(resolve => setTimeout(resolve, ms));
-}
-
-/**
- * Chunk array into smaller arrays
- */
-function chunk<T>(array: T[], size: number): T[][] {
-  const chunks: T[][] = [];
-  for (let i = 0; i < array.length; i += size) {
-    chunks.push(array.slice(i, i + size));
-  }
-  return chunks;
-}
-
-// ============================================================================
-// ENTRY POINT
-// ============================================================================
-
-/**
- * Main entry point with error handling
- */
-async function main() {
-  try {
-    const result = await syncInventory();
-
-    // Exit with success code if no files failed
-    if (result.filesFailed === 0) {
-      logger.info('All files processed successfully');
-      process.exit(0);
-    } else {
-      logger.warn('Some files failed to process');
-      process.exit(1);
-    }
-  } catch (error) {
-    logger.error('Fatal error during inventory sync', error as Error);
-    process.exit(1);
-  }
-}
-
-// Run the sync
-main();
-```
-
-### 4. Package.json Configuration
-
-```json
-{
-  "name": "inventory-sync-standalone",
-  "version": "1.0.0",
-  "description": "Standalone S3 CSV to Fluent Commerce inventory sync",
-  "main": "dist/inventory-sync.js",
-  "type": "module",
-  "scripts": {
-    "build": "tsc",
-    "start": "node dist/inventory-sync.js",
-    "dev": "tsx src/inventory-sync.ts",
-    "sync": "npm run dev",
-    "lint": "eslint src --ext .ts",
-    "type-check": "tsc --noEmit"
-  },
-  "keywords": ["fluent-commerce", "inventory", "s3", "batch-api"],
-  "author": "",
-  "license": "MIT",
-  "dependencies": {
-    "@fluentcommerce/fc-connect-sdk": "^0.1.39",
-    "dotenv": "^16.0.0"
-  },
-  "devDependencies": {
-    "@types/node": "^18.0.0",
-    "tsx": "^4.0.0",
-    "typescript": "^5.0.0"
-  }
-}
-```
-
-### 5. TypeScript Configuration
-
-Create `tsconfig.json`:
-
-```json
-{
-  "compilerOptions": {
-    "module": "ES2022",
-    "target": "ES2024",
-    "moduleResolution": "node"
-  }
-}
-```
-
----
-
-## Key Patterns Explained
-
-### Pattern 1: OAuth2 Authentication
-
-**Purpose**: Authenticate with Fluent Commerce without Versori connection
-
-**Implementation**:
-
-```typescript
-const fluentClient = await createClient({
-  config: {
-    baseUrl: 'https://api.fluentcommerce.com',
-    clientId: process.env.FLUENT_CLIENT_ID,
-    clientSecret: process.env.FLUENT_CLIENT_SECRET,
-    retailerId: process.env.FLUENT_RETAILER_ID,
-  },
-});
-```
-
-**Key Points**:
-
-- Uses client credentials OAuth2 grant type
-- Token automatically cached and refreshed by SDK
-- No manual token management needed
-- Token expires after ~1 hour, SDK handles refresh transparently
-
-**When to Use**:
-
-- Standalone Node.js/Deno scripts
-- Background jobs/cron tasks
-- CI/CD pipelines
-- Local development
-
-### Pattern 2: S3 File Operations
-
-**Purpose**: List, download, and move files in S3 bucket
-
-**Implementation**:
-
-```typescript
-// Initialize S3 Data Source
-const s3Source = new S3DataSource(
-  {
-    type: 'S3_CSV',
-    connectionId: 'inventory-s3',
-    name: 'Inventory S3 Source',
-    s3Config: {
-      bucket: 'my-bucket',
-      region: 'us-east-1',
-      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
-      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
-    },
-  },
-  logger
-);
-
-// List files with prefix filter
-const files = await s3Source.listFiles({
-  prefix: 'inventory/updates/',
-  maxKeys: 1000,
-});
-
-// Download file content
-const content = await s3Source.downloadFile(file.path);
-
-// Move file (copy + delete)
-await s3Source.moveFile(sourcePath, destPath);
-```
-
-**Key Points**:
-
-- Uses presigned URLs (no AWS SDK required)
-- Automatic retry logic for transient failures
-- Streaming support for large files
-- Cross-bucket move support
-
-**Best Practices**:
-
-- Always use prefix filtering to limit results
-- Move files to archive/error folders (don't delete)
-- Use date-based folder structure for archiving
-- Validate S3 connection before processing
-
-### Pattern 3: CSV Parsing & Validation
-
-**Purpose**: Parse CSV files and validate data quality
-
-**Implementation**:
-
-```typescript
-// Initialize CSV Parser
-const csvParser = new CSVParserService();
-
-// Parse CSV content (returns array of objects)
-const records = await csvParser.parse(csvContent);
-
-// Validate records
-const validRecords = records.filter(record => {
-  // Required field validation
-  if (!record.sku || !record.location || record.quantity === undefined) {
-    logger.warn('Missing required fields', { record });
-    return false;
-  }
-
-  // Type validation
-  if (isNaN(Number(record.quantity))) {
-    logger.warn('Invalid quantity', { record });
-    return false;
-  }
-
-  return true;
-});
-```
-
-**Key Points**:
-
-- CSV parser auto-detects headers by default
-- Trims whitespace and skips empty lines
-- Returns array of objects (header → value mapping)
-- Validation happens before mapping (fail fast)
-
-**Validation Strategies**:
-
-1. **Required Fields**: Check for null/undefined/empty
-2. **Type Validation**: Ensure numeric fields are numbers
-3. **Format Validation**: Regex for SKU, email, phone, etc.
-4. **Business Rules**: Range checks, valid enum values
-5. **Cross-field Validation**: Relationships between fields
-
-### Pattern 4: Batch API Workflow
-
-**Purpose**: Send large datasets to Fluent Commerce efficiently
-
-**Implementation**:
-
-```typescript
-// STEP 1: Create Job
-const job = await fluentClient.createJob({
-  name: 'Inventory Update - file.csv',
-  retailerId: 'my-retailer',
-});
-
-// STEP 2: Send Batches (chunked)
-const batchSize = 100;
-for (let i = 0; i < records.length; i += batchSize) {
-  const batch = records.slice(i, i + batchSize);
-  await fluentClient.sendBatch(job.id, {
-    entities: batch,
-  });
-}
-
-// STEP 3: Poll Job Status
-let status = await fluentClient.getJobStatus(job.id);
-while (status.status !== 'COMPLETE' && status.status !== 'FAILED') {
-  await sleep(5000); // Wait 5 seconds
-  status = await fluentClient.getJobStatus(job.id);
-}
-
-// STEP 4: Check Results
-if (status.status === 'COMPLETE') {
-  console.log('Job succeeded!');
-} else {
-  console.error('Job failed:', status);
-}
-```
-
-**Key Points**:
-
-- One job per file (easier tracking)
-- Batch size 50-500 records (100 recommended)
-- Poll with exponential backoff
-- Handle both COMPLETE and FAILED states
-
-**Batch Size Guidelines**:
-
-- Small records (<10 fields): 200-500 per batch
-- Medium records (10-30 fields): 100-200 per batch
-- Large records (>30 fields): 50-100 per batch
-- API limit: Usually 1000 records per batch
-
-### Pattern 5: Error Handling & Retry
-
-**Purpose**: Graceful degradation and recovery from failures
-
-**Implementation**:
-
-```typescript
-// File-level try-catch
-for (const file of files) {
-  try {
-    await processFile(file);
-    filesSucceeded++;
-  } catch (error) {
-    logger.error('File processing failed', error);
-    filesFailed++;
-
-    // Move to error folder
-    try {
-      await s3Source.moveFile(file.path, errorPath);
-    } catch (moveError) {
-      logger.error('Failed to move error file', moveError);
-    }
-  }
-}
-
-// Automatic retry with exponential backoff
-async function retryWithBackoff<T>(fn: () => Promise<T>, maxRetries: number = 3): Promise<T> {
-  let lastError: Error;
-  for (let attempt = 0; attempt < maxRetries; attempt++) {
-    try {
-      return await fn();
-    } catch (error) {
-      lastError = error as Error;
-      if (attempt < maxRetries - 1) {
-        const delay = Math.pow(2, attempt) * 1000;
-        await sleep(delay);
-      }
-    }
-  }
-  throw lastError!;
-}
-```
-
-**Error Categories**:
-
-1. **Network Errors**: Retry with exponential backoff
-2. **4xx Client Errors**: Don't retry (bad request)
-3. **5xx Server Errors**: Retry (transient failure)
-4. **Validation Errors**: Skip record, continue processing
-5. **Fatal Errors**: Exit with error code
-
-**Retry Best Practices**:
-
-- Max 3-5 retry attempts
-- Exponential backoff (1s, 2s, 4s, 8s, ...)
-- Jitter to prevent thundering herd
-- Log each retry attempt
-- Give up after max retries
-
----
-
-## Deployment Options
-
-### Option 1: Local Execution
-
-```bash
-# One-time sync
-npm run sync
-
-# With debug logging
-LOG_LEVEL=debug npm run sync
-```
-
-### Option 2: Docker Container
-
-Create `Dockerfile`:
-
-```dockerfile
-FROM node:18-alpine
-WORKDIR /app
-
-# Copy package files
-COPY package*.json ./
-
-# Install dependencies
-RUN npm ci --only=production
-
-# Copy application code
-COPY dist ./dist
-
-# Run the sync
-CMD ["node", "dist/inventory-sync.js"]
-```
-
-Build and run:
-
-```bash
-# Build image
-docker build -t inventory-sync .
-
-# Run container
-docker run --env-file .env inventory-sync
-```
-
-### Option 3: AWS Lambda
-
-Create `lambda-handler.ts`:
-
-```typescript
-import { syncInventory } from './inventory-sync';
-
-export const handler = async (event: any, context: any) => {
-  try {
-    const result = await syncInventory();
-    return {
-      statusCode: 200,
-      body: JSON.stringify(result),
-    };
-  } catch (error) {
-    console.error('Lambda error:', error);
-    return {
-      statusCode: 500,
-      body: JSON.stringify({ error: (error as Error).message }),
-    };
-  }
-};
-```
-
-Deploy:
-
-```bash
-# Package for Lambda
-npm run build
-zip -r function.zip dist node_modules
-
-# Deploy with AWS CLI
-aws lambda create-function \
-  --function-name inventory-sync \
-  --runtime nodejs18.x \
-  --handler dist/lambda-handler.handler \
-  --zip-file fileb://function.zip \
-  --role arn:aws:iam::123456789:role/lambda-execution \
-  --timeout 900 \
-  --memory-size 512
-```
-
-### Option 4: Cron Scheduling
-
-**Linux/Mac cron**:
-
-```bash
-# Edit crontab
-crontab -e
-
-# Run every 4 hours
-0 */4 * * * cd /path/to/inventory-sync && npm run sync >> /var/log/inventory-sync.log 2>&1
-```
-
-**Node.js cron**:
-
-Install: `npm install node-cron`
-
-```typescript
-import cron from 'node-cron';
-
-// Run every 4 hours
-cron.schedule('0 */4 * * *', async () => {
-  logger.info('Starting scheduled inventory sync');
-  await syncInventory();
-});
-
-logger.info('Cron scheduler started (every 4 hours)');
-```
-
-**AWS EventBridge**:
-
-```bash
-# Create rule
-aws events put-rule \
-  --name inventory-sync-schedule \
-  --schedule-expression "rate(4 hours)"
-
-# Add Lambda target
-aws events put-targets \
-  --rule inventory-sync-schedule \
-  --targets "Id"="1","Arn"="arn:aws:lambda:us-east-1:123:function:inventory-sync"
-```
-
----
-
-## Testing
-
-### Local Testing
-
-```bash
-# 1. Create test CSV file
-cat > test-inventory.csv << EOF
-sku,location,quantity,status,expected_date
-TEST-SKU-001,WAREHOUSE-A,100,ACTIVE,2024-01-15
-TEST-SKU-002,WAREHOUSE-B,50,ACTIVE,2024-01-15
-TEST-SKU-003,STORE-001,25,ACTIVE,2024-01-16
-EOF
-
-# 2. Upload to S3
-aws s3 cp test-inventory.csv s3://your-bucket/inventory/updates/
-
-# 3. Run sync
-npm run sync
-
-# 4. Check logs
-cat logs/inventory-sync.log
-
-# 5. Verify in Fluent Commerce
-# - Check job status in admin portal
-# - Query inventory positions via GraphQL
-```
-
-### Integration Testing
-
-Create `tests/integration.test.ts`:
-
-```typescript
-import { describe, it, expect, beforeAll } from '@jest/globals';
-import { syncInventory } from '../src/inventory-sync';
-
-describe('Inventory Sync Integration', () => {
-  beforeAll(async () => {
-    // Setup test environment
-  });
-
-  it('should process valid CSV file', async () => {
-    // Upload test file to S3
-    // Run sync
-    const result = await syncInventory();
-
-    // Assertions
-    expect(result.filesSucceeded).toBe(1);
-    expect(result.filesFailed).toBe(0);
-    expect(result.totalRecordsProcessed).toBeGreaterThan(0);
-  });
-
-  it('should handle invalid records gracefully', async () => {
-    // Upload CSV with invalid records
-    // Run sync
-    const result = await syncInventory();
-
-    // Should still succeed but skip invalid records
-    expect(result.filesSucceeded).toBe(1);
-    expect(result.totalRecordsFailed).toBeGreaterThan(0);
-  });
-
-  it('should move failed files to error folder', async () => {
-    // Upload malformed CSV
-    // Run sync
-    const result = await syncInventory();
-
-    // File should be in error folder
-    expect(result.filesFailed).toBe(1);
-    // Check S3 error folder
-  });
-});
-```
-
-Run tests:
-
-```bash
-npm install --save-dev jest @jest/globals @types/jest ts-jest
-npm test
-```
-
----
-
-## Common Issues
-
-### Issue 1: OAuth2 Token Expired
-
-**Symptom**: `401 Unauthorized` errors
-
-**Cause**: Token expired and SDK failed to refresh
-
-**Solution**:
-
-```typescript
-// SDK handles refresh automatically, but you can force refresh
-const client = await createClient({
-  config: {
-    baseUrl: 'https://api.fluentcommerce.com',
-    clientId: process.env.FLUENT_CLIENT_ID,
-    clientSecret: process.env.FLUENT_CLIENT_SECRET,
-    retailerId: process.env.FLUENT_RETAILER_ID,
-    retryAttempts: 3,
-  },
-});
-```
-
-### Issue 2: S3 Permission Denied
-
-**Symptom**: `AccessDenied` errors when listing/downloading files
-
-**Cause**: IAM policy missing required permissions
-
-**Solution**:
-
-```json
-{
-  "Version": "2012-10-17",
-  "Statement": [
-    {
-      "Effect": "Allow",
-      "Action": ["s3:ListBucket", "s3:GetObject", "s3:PutObject", "s3:DeleteObject"],
-      "Resource": ["arn:aws:s3:::your-bucket", "arn:aws:s3:::your-bucket/*"]
-    }
-  ]
-}
-```
-
-### Issue 3: CSV Parsing Errors
-
-**Symptom**: `CSV parse error: Invalid record`
-
-**Cause**: Malformed CSV (unescaped quotes, inconsistent columns)
-
-**Solution**:
-
-```typescript
-// Use more lenient CSV parser options
-const csvParser = CSVParserService.create({
-  columns: true,
-  skip_empty_lines: true,
-  trim: true,
-  relax_column_count: true, // Allow inconsistent column counts
-  quote: '"',
-  escape: '"',
-  delimiter: ',',
-});
-```
-
-### Issue 4: Batch API Timeout
-
-**Symptom**: Job stays in `PENDING` state indefinitely
-
-**Cause**: Fluent API processing delay or large batch size
-
-**Solution**:
-
-```typescript
-// Reduce batch size
-const batchSize = 50; // Instead of 100
-
-// Increase polling timeout
-const timeout = 60 * 60 * 1000; // 1 hour instead of 30 minutes
-
-// Add more aggressive polling
-let delay = 1000; // Start with 1 second
-const maxDelay = 15000; // Cap at 15 seconds
-```
-
-### Issue 5: Memory Exhaustion
-
-**Symptom**: `JavaScript heap out of memory` error
-
-**Cause**: Loading entire large CSV file into memory
-
-**Solution**:
-
-```typescript
-// Use streaming CSV parsing instead
-for await (const record of csvParser.parseStreaming(csvContent, {}, 100)) {
-  // Process records in batches of 100
-  const mappedBatch = await Promise.all(record.map(r => mapper.map(r)));
-
-  // Send batch immediately (don't accumulate)
-  await fluentClient.sendBatch(jobId, {
-    entities: mappedBatch.filter(r => r.success).map(r => r.data),
-  });
-}
-```
-
----
-
-## Related Guides
-
-- **SDK Reference**: `../../readme.md` - Core SDK documentation
-- **Universal Mapping Guide**: `../../02-CORE-GUIDES/mapping/readme.md` - Field mapping patterns
-- **Batch API Guide**: `../../02-CORE-GUIDES/api-reference/modules/03-batch-processing.md` - Batch API details
-- **S3 Data Source**: `../../02-CORE-GUIDES/data-sources/readme.md` - S3 operations
-- **CSV Parser**: `../../02-CORE-GUIDES/parsers/readme.md` - CSV parsing options
-- **Error Handling**: `../../03-PATTERN-GUIDES/error-handling/readme.md` - Error patterns
-
----
-
-## Production Checklist
-
-Before deploying to production:
-
-- [ ] Environment variables secured (AWS Secrets Manager, vault, etc.)
-- [ ] Logging configured (Winston, CloudWatch, Datadog, etc.)
-- [ ] Error alerting setup (PagerDuty, Slack, email)
-- [ ] Monitoring dashboard (metrics, job success rate, duration)
-- [ ] Retry logic tested (network failures, API errors)
-- [ ] Batch size optimized (tested with production file sizes)
-- [ ] Memory profiling done (no leaks)
-- [ ] S3 lifecycle policies configured (archive old files)
-- [ ] IAM permissions minimized (least privilege)
-- [ ] Health check endpoint added (for orchestration tools)
-- [ ] Documentation updated (runbook, troubleshooting)
-- [ ] Disaster recovery tested (restore from archive)
-
----
-
-**Next Steps**:
-
-1. Customize field mappings for your inventory data structure
-2. Add custom validation rules for your business logic
-3. Implement state tracking to prevent duplicate processing
-4. Set up monitoring and alerting
-5. Deploy to your preferred environment (Lambda, ECS, K8s, etc.)
-
-**Support**:
-
-- SDK Issues: https://github.com/fluentcommerce/fc-connect-sdk/issues
-- Fluent Commerce API: https://docs.fluentcommerce.com
-- Community: https://community.fluentcommerce.com
+# Standalone: S3 CSV → Fluent Batch API
+
+**FC Connect SDK Use Case Guide**
+
+> **SDK**: [@fluentcommerce/fc-connect-sdk](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk)
+> **Version**: Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
+
+**Context**: Node.js script that reads CSV inventory files from S3 and updates Fluent Commerce inventory via Batch API
+
+**Complexity**: Medium
+
+**Runtime**: Node.js ≥18 / Deno
+
+**Estimated Lines**: ~500 lines
+
+## What You'll Build
+
+- Standalone Node.js/Deno script (no Versori)
+- OAuth2 authentication with Fluent Commerce
+- S3 file listing and download with AWS SDK
+- CSV parsing with validation
+- UniversalMapper for field transformations
+- Batch API processing with job management
+- Error handling and logging
+- Optional: Schedule with cron or AWS EventBridge
+
+## SDK Methods Used
+
+- `createClient({ config: { baseUrl, clientId, clientSecret, retailerId } })` - OAuth2 client
+- `S3DataSource(config, logger)` - S3 operations
+- `CSVParserService` - CSV parsing
+- `UniversalMapper(mappingConfig)` - Field mapping
+- `client.createJob({ name, retailerId })` - Create Batch job
+- `client.sendBatch(jobId, { entities })` - Send inventory batch
+- `client.getJobStatus(jobId)` - Check status
+
+---
+
+## Complete Working Implementation
+
+### 1. Project Setup
+
+```bash
+# Create project directory
+mkdir inventory-sync-standalone
+cd inventory-sync-standalone
+
+# Initialize Node.js project
+npm init -y
+
+# Install dependencies
+npm install @fluentcommerce/fc-connect-sdk dotenv
+```
+
+### Method selection (SDK)
+
+- Queries → `client.graphql`
+- Mutations → `client.graphql`
+- Advanced needs (pagination/telemetry) → `client.graphql` with pagination options
+
+```typescript
+// Query (use graphql for both queries and mutations)
+const products = await client.graphql({ query, variables });
+
+// Mutation (use graphql for both queries and mutations)
+const result = await client.graphql({ query: mutation, variables });
+
+// Advanced pagination
+const res = await client.graphql({ query, variables, pagination: { maxPages: 50 } });
+```
+
+### 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
+
+# AWS S3 Configuration
+AWS_ACCESS_KEY_ID=your-aws-access-key
+AWS_SECRET_ACCESS_KEY=your-aws-secret-key
+AWS_REGION=us-east-1
+AWS_BUCKET_NAME=your-inventory-bucket
+AWS_FILE_PREFIX=inventory/updates/
+
+# Processing Configuration
+BATCH_SIZE=100
+JOB_NAME_PREFIX=S3-CSV-Inventory-Update
+ARCHIVE_PREFIX=inventory/archive/
+ERROR_PREFIX=inventory/errors/
+
+# Optional: Scheduling
+ENABLE_SCHEDULING=false
+CRON_SCHEDULE=0 */4 * * *
+```
+
+### 3. Main Script Implementation
+
+Create `src/inventory-sync.ts`:
+
+```typescript
+import 'dotenv/config';
+// FC Connect SDK+
+// Install: npm install @fluentcommerce/fc-connect-sdk@latest
+// Docs: https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk
+// GitHub: https://github.com/fluentcommerce/fc-connect-sdk
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+import { S3DataSource } from '@fluentcommerce/fc-connect-sdk';
+import { CSVParserService } from '@fluentcommerce/fc-connect-sdk';
+import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+
+/**
+ * ARCHITECTURE:
+ *
+ * This standalone script implements a complete inventory sync workflow:
+ * 1. List CSV files from S3 bucket
+ * 2. Download and parse CSV files
+ * 3. Map CSV fields to Fluent inventory format
+ * 4. Create Batch API job
+ * 5. Send inventory updates in batches
+ * 6. Poll job status until complete
+ * 7. Archive successful files, move errors
+ *
+ * ERROR HANDLING STRATEGY:
+ * - File-level errors: Move to error folder, continue with other files
+ * - Batch errors: Log and continue (Fluent API provides detailed error reports)
+ * - Fatal errors: Exit with error code for monitoring/alerting
+ *
+ * STATE MANAGEMENT:
+ * - No state tracking in this basic version (processes all files)
+ * - Advanced: Use S3 metadata or external DB to track processed files
+ */
+
+// ============================================================================
+// CONFIGURATION & SETUP
+// ============================================================================
+
+interface SyncConfig {
+  fluent: {
+    baseUrl: string;
+    clientId: string;
+    clientSecret: string;
+    retailerId: string;
+  };
+  s3: {
+    accessKeyId: string;
+    secretAccessKey: string;
+    region: string;
+    bucket: string;
+    prefix: string;
+  };
+  processing: {
+    batchSize: number;
+    jobNamePrefix: string;
+    archivePrefix: string;
+    errorPrefix: string;
+  };
+}
+
+/**
+ * Load configuration from environment variables
+ * Validates all required config before proceeding
+ */
+function loadConfig(): SyncConfig {
+  const requiredEnvVars = [
+    'FLUENT_BASE_URL',
+    'FLUENT_CLIENT_ID',
+    'FLUENT_CLIENT_SECRET',
+    'FLUENT_RETAILER_ID',
+    'AWS_ACCESS_KEY_ID',
+    'AWS_SECRET_ACCESS_KEY',
+    'AWS_REGION',
+    'AWS_BUCKET_NAME',
+  ];
+
+  // Validate all required environment variables are present
+  const missing = requiredEnvVars.filter(v => !process.env[v]);
+  if (missing.length > 0) {
+    throw new Error(`Missing required environment variables: ${missing.join(', ')}`);
+  }
+
+  return {
+    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!,
+    },
+    s3: {
+      accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+      region: process.env.AWS_REGION!,
+      bucket: process.env.AWS_BUCKET_NAME!,
+      prefix: process.env.AWS_FILE_PREFIX || 'inventory/updates/',
+    },
+    processing: {
+      batchSize: parseInt(process.env.BATCH_SIZE || '100'),
+      jobNamePrefix: process.env.JOB_NAME_PREFIX || 'S3-CSV-Inventory-Update',
+      archivePrefix: process.env.ARCHIVE_PREFIX || 'inventory/archive/',
+      errorPrefix: process.env.ERROR_PREFIX || 'inventory/errors/',
+    },
+  };
+}
+
+// ============================================================================
+// FIELD MAPPING CONFIGURATION
+// ============================================================================
+
+/**
+ * UniversalMapper configuration for CSV → Fluent Batch API transformation
+ *
+ * FIELD MAPPING RULES:
+ * - ref: Product SKU (required) - uppercase transformation
+ * - locationRef: Location code (required) - prefix with "LOC:"
+ * - qty: Quantity (required) - parse as integer, default to 0
+ * - type: Inventory type (required) - defaults to "ADJUSTMENT"
+ * - status: Inventory status (optional) - defaults to "ACTIVE"
+ *
+ * SDK RESOLVERS USED:
+ * - sdk.uppercase: Convert SKU to uppercase for consistency
+ * - sdk.parseInt: Parse quantity string to integer
+ * - sdk.trim: Remove whitespace from location codes
+ * - sdk.defaultTo: Provide fallback values
+ */
+const inventoryMappingConfig = {
+  version: '1.0.0',
+  description: 'S3 CSV to Fluent Commerce Inventory Mapping',
+  fields: {
+    // Product SKU (required field)
+    ref: {
+      source: 'sku',
+      resolver: 'sdk.uppercase', // Normalize to uppercase
+      required: true,
+    },
+    // Location reference (required field)
+    locationRef: {
+      source: 'location',
+      resolver: 'sdk.trim', // Remove whitespace
+      required: true,
+    },
+    // Quantity (required field)
+    qty: {
+      source: 'quantity',
+      resolver: 'sdk.parseInt', // Parse as integer
+      required: true,
+    },
+    // Inventory type (defaults to ADJUSTMENT)
+    type: {
+      value: 'ADJUSTMENT', // Static value
+    },
+    // Inventory status (optional, with default)
+    status: {
+      source: 'status',
+      resolver: 'sdk.uppercase',
+      defaultValue: 'ACTIVE', // Fallback if not provided
+    },
+    // Expected date (optional)
+    expectedOn: {
+      source: 'expected_date',
+      resolver: 'sdk.formatDate', // Convert to ISO date format
+    },
+  },
+};
+
+// ============================================================================
+// LOGGER IMPLEMENTATION
+// ============================================================================
+
+/**
+ * Simple console logger with timestamp and log levels
+ * Production: Replace with Winston, Bunyan, or Pino
+ */
+const logger = {
+  debug: (message: string, meta?: any) => {
+    if (process.env.LOG_LEVEL === 'debug') {
+      console.log(`[${new Date().toISOString()}] DEBUG: ${message}`, meta || '');
+    }
+  },
+  info: (message: string, meta?: any) => {
+    console.log(`[${new Date().toISOString()}] INFO: ${message}`, meta || '');
+  },
+  warn: (message: string, meta?: any) => {
+    console.warn(`[${new Date().toISOString()}] WARN: ${message}`, meta || '');
+  },
+  error: (message: string, error?: Error, meta?: any) => {
+    console.error(
+      `[${new Date().toISOString()}] ERROR: ${message}`,
+      error?.message || '',
+      meta || ''
+    );
+  },
+};
+
+// ============================================================================
+// MAIN SYNC ORCHESTRATION
+// ============================================================================
+
+/**
+ * Main inventory sync function
+ *
+ * ALGORITHM:
+ * 1. Initialize SDK clients (Fluent, S3, CSV parser, mapper)
+ * 2. List CSV files from S3 prefix
+ * 3. For each file:
+ *    a. Download file content
+ *    b. Parse CSV to records
+ *    c. Validate records (skip invalid)
+ *    d. Map records using UniversalMapper
+ *    e. Create Batch API job
+ *    f. Send batches (chunked by batch size)
+ *    g. Poll job status until complete
+ *    h. Archive successful files OR move to error folder
+ * 4. Return summary statistics
+ */
+async function syncInventory(): Promise<{
+  filesProcessed: number;
+  filesSucceeded: number;
+  filesFailed: number;
+  totalRecordsProcessed: number;
+  totalRecordsFailed: number;
+}> {
+  const startTime = Date.now();
+  logger.info('='.repeat(80));
+  logger.info('Starting S3 CSV → Fluent Batch API inventory sync');
+  logger.info('='.repeat(80));
+
+  // Load configuration
+  const config = loadConfig();
+  logger.info('Configuration loaded', {
+    s3Bucket: config.s3.bucket,
+    s3Prefix: config.s3.prefix,
+    batchSize: config.processing.batchSize,
+  });
+
+  // ───────────────────────────────────────────────────────────────────────────
+  // STEP 1: Initialize SDK Clients
+  // ───────────────────────────────────────────────────────────────────────────
+
+  // Initialize Fluent Client with OAuth2
+  logger.info('Initializing Fluent Commerce client...');
+  const fluentClient = await createClient({
+    config: {
+      baseUrl: config.fluent.baseUrl,
+      clientId: config.fluent.clientId,
+      clientSecret: config.fluent.clientSecret,
+      retailerId: config.fluent.retailerId,
+    },
+  });
+
+  // Initialize S3 Data Source
+  logger.info('Initializing S3 data source...');
+  const s3Source = new S3DataSource(
+    {
+      type: 'S3_CSV',
+      connectionId: 'inventory-s3',
+      name: 'Inventory S3 Source',
+      s3Config: {
+        bucket: config.s3.bucket,
+        region: config.s3.region,
+        accessKeyId: config.s3.accessKeyId,
+        secretAccessKey: config.s3.secretAccessKey,
+      },
+    },
+    logger
+  );
+
+  // Initialize CSV Parser
+  const csvParser = new CSVParserService();
+
+  // Initialize Universal Mapper
+  const mapper = new UniversalMapper(inventoryMappingConfig, {
+    logger,
+    fluentClient,
+  });
+
+  // Validate S3 connection
+  logger.info('Validating S3 connection...');
+  const s3Connected = await s3Source.validateConnection();
+  if (!s3Connected) {
+    throw new Error('Failed to connect to S3 bucket');
+  }
+  logger.info('S3 connection validated successfully');
+
+  // ───────────────────────────────────────────────────────────────────────────
+  // STEP 2: List CSV Files from S3
+  // ───────────────────────────────────────────────────────────────────────────
+
+  logger.info(`Listing CSV files from S3 prefix: ${config.s3.prefix}`);
+  const files = await s3Source.listFiles({
+    prefix: config.s3.prefix,
+    maxKeys: 1000,
+  });
+
+  // Filter for CSV files only
+  // NOTE: S3 doesn't support glob patterns, so manual filtering is required
+  // IMPORTANT: Use .endsWith('.csv') NOT .endsWith('*.csv')
+  //   ✓ Correct:  f.name.endsWith('.csv')
+  //   ✗ Wrong:    f.name.endsWith('*.csv')  // Would never match!
+  const csvFiles = files.filter(f => f.name.toLowerCase().endsWith('.csv'));
+
+  logger.info(`Found ${csvFiles.length} CSV files to process`, {
+    totalFiles: files.length,
+    csvFiles: csvFiles.length,
+  });
+
+  if (csvFiles.length === 0) {
+    logger.info('No CSV files found. Exiting.');
+    return {
+      filesProcessed: 0,
+      filesSucceeded: 0,
+      filesFailed: 0,
+      totalRecordsProcessed: 0,
+      totalRecordsFailed: 0,
+    };
+  }
+
+  // ───────────────────────────────────────────────────────────────────────────
+  // STEP 3: Process Each CSV File
+  // ───────────────────────────────────────────────────────────────────────────
+
+  let filesSucceeded = 0;
+  let filesFailed = 0;
+  let totalRecordsProcessed = 0;
+  let totalRecordsFailed = 0;
+
+  for (const file of csvFiles) {
+    logger.info('-'.repeat(80));
+    logger.info(`Processing file: ${file.name}`, {
+      size: file.size,
+      lastModified: file.lastModified,
+    });
+
+    try {
+      // ─────────────────────────────────────────────────────────────────────
+      // STEP 3a: Download CSV File
+      // ─────────────────────────────────────────────────────────────────────
+      logger.info(`Downloading file: ${file.path}`);
+      const csvContent = await s3Source.downloadFile(file.path);
+      logger.info(
+        `Downloaded ${typeof csvContent === 'string' ? csvContent.length : csvContent.length} bytes`
+      );
+
+      // ─────────────────────────────────────────────────────────────────────
+      // STEP 3b: Parse CSV to Records
+      // ─────────────────────────────────────────────────────────────────────
+      logger.info('Parsing CSV content...');
+      const records = await csvParser.parse(csvContent as string);
+      logger.info(`Parsed ${records.length} records from CSV`);
+
+      if (records.length === 0) {
+        logger.warn('CSV file is empty, skipping');
+        continue;
+      }
+
+      // ─────────────────────────────────────────────────────────────────────
+      // STEP 3c: Validate Records (Basic Validation)
+      // ─────────────────────────────────────────────────────────────────────
+      logger.info('Validating records...');
+      const validRecords = records.filter((record: any, index: number) => {
+        // Check for required fields
+        if (!record.sku || !record.location || record.quantity === undefined) {
+          logger.warn(`Record ${index + 1} missing required fields, skipping`, {
+            record,
+          });
+          totalRecordsFailed++;
+          return false;
+        }
+
+        // Validate quantity is numeric
+        if (isNaN(Number(record.quantity))) {
+          logger.warn(`Record ${index + 1} has invalid quantity, skipping`, {
+            record,
+          });
+          totalRecordsFailed++;
+          return false;
+        }
+
+        return true;
+      });
+
+      logger.info(
+        `Validation complete: ${validRecords.length} valid, ${records.length - validRecords.length} invalid`
+      );
+
+      if (validRecords.length === 0) {
+        logger.warn('No valid records found in file, skipping');
+        continue;
+      }
+
+      // ─────────────────────────────────────────────────────────────────────
+      // STEP 3d: Map Records Using UniversalMapper
+      // ─────────────────────────────────────────────────────────────────────
+      logger.info('Mapping records using UniversalMapper...');
+      const mappedRecords: any[] = [];
+      const mappingErrors: string[] = [];
+
+      for (let i = 0; i < validRecords.length; i++) {
+        const record = validRecords[i];
+        const result = await mapper.map(record);
+
+        if (result.success) {
+          mappedRecords.push(result.data);
+        } else {
+          logger.warn(`Record ${i + 1} mapping failed`, {
+            errors: result.errors,
+            record,
+          });
+          mappingErrors.push(`Record ${i + 1}: ${result.errors?.join(', ')}`);
+          totalRecordsFailed++;
+        }
+      }
+
+      logger.info(
+        `Mapping complete: ${mappedRecords.length} mapped, ${mappingErrors.length} failed`
+      );
+
+      if (mappedRecords.length === 0) {
+        logger.warn('No records successfully mapped, skipping file');
+        continue;
+      }
+
+      // ─────────────────────────────────────────────────────────────────────
+      // STEP 3e: Create Batch API Job
+      // ─────────────────────────────────────────────────────────────────────
+      const jobName = `${config.processing.jobNamePrefix} - ${file.name} - ${new Date().toISOString()}`;
+      logger.info(`Creating Batch API job: ${jobName}`);
+
+      const job = await fluentClient.createJob({
+        name: jobName,
+        retailerId: config.fluent.retailerId,
+      });
+
+      logger.info(`Job created successfully`, {
+        jobId: job.id,
+        status: job.status,
+      });
+
+      // ─────────────────────────────────────────────────────────────────────
+      // STEP 3f: Send Batches (Chunked by Batch Size)
+      // ─────────────────────────────────────────────────────────────────────
+      logger.info(
+        `Sending ${mappedRecords.length} records in batches of ${config.processing.batchSize}`
+      );
+      const batches = chunk(mappedRecords, config.processing.batchSize);
+
+      for (let i = 0; i < batches.length; i++) {
+        const batch = batches[i];
+        logger.info(`Sending batch ${i + 1}/${batches.length} (${batch.length} records)`);
+
+        const batchResponse = await fluentClient.sendBatch(job.id, {
+          entities: batch,
+        });
+
+        logger.info(`Batch ${i + 1} sent successfully`, {
+          batchId: batchResponse.id,
+          status: batchResponse.status,
+        });
+      }
+
+      // ─────────────────────────────────────────────────────────────────────
+      // STEP 3g: Poll Job Status Until Complete
+      // ─────────────────────────────────────────────────────────────────────
+      logger.info('Polling job status...');
+      const finalStatus = await pollJobStatus(fluentClient, job.id, logger);
+
+      logger.info(`Job completed with status: ${finalStatus.status}`, {
+        jobId: job.id,
+        status: finalStatus.status,
+      });
+
+      // Check if job succeeded
+      if (finalStatus.status === 'COMPLETE') {
+        totalRecordsProcessed += mappedRecords.length;
+        filesSucceeded++;
+
+        // ───────────────────────────────────────────────────────────────────
+        // STEP 3h: Archive Successful File
+        // ───────────────────────────────────────────────────────────────────
+        const archivePath = `${config.processing.archivePrefix}${new Date().toISOString().split('T')[0]}/${file.name}`;
+        logger.info(`Archiving file to: ${archivePath}`);
+        await s3Source.moveFile(file.path, archivePath);
+        logger.info('File archived successfully');
+      } else {
+        // Job failed or has errors
+        logger.error('Job failed or has errors', undefined, {
+          jobId: job.id,
+          status: finalStatus.status,
+        });
+
+        // Move to error folder
+        const errorPath = `${config.processing.errorPrefix}${new Date().toISOString().split('T')[0]}/${file.name}`;
+        logger.info(`Moving file to error folder: ${errorPath}`);
+        await s3Source.moveFile(file.path, errorPath);
+        logger.info('File moved to error folder');
+
+        filesFailed++;
+      }
+    } catch (error) {
+      // File processing error
+      logger.error(`Failed to process file: ${file.name}`, error as Error);
+      filesFailed++;
+
+      try {
+        // Move to error folder
+        const errorPath = `${config.processing.errorPrefix}${new Date().toISOString().split('T')[0]}/${file.name}`;
+        await s3Source.moveFile(file.path, errorPath);
+        logger.info('File moved to error folder after processing error');
+      } catch (moveError) {
+        logger.error('Failed to move file to error folder', moveError as Error);
+      }
+    }
+  }
+
+  // ───────────────────────────────────────────────────────────────────────────
+  // STEP 4: Summary Statistics
+  // ───────────────────────────────────────────────────────────────────────────
+
+  const duration = Date.now() - startTime;
+  logger.info('='.repeat(80));
+  logger.info('Inventory sync completed', {
+    duration: `${(duration / 1000).toFixed(2)}s`,
+    filesProcessed: csvFiles.length,
+    filesSucceeded,
+    filesFailed,
+    totalRecordsProcessed,
+    totalRecordsFailed,
+  });
+  logger.info('='.repeat(80));
+
+  return {
+    filesProcessed: csvFiles.length,
+    filesSucceeded,
+    filesFailed,
+    totalRecordsProcessed,
+    totalRecordsFailed,
+  };
+}
+
+// ============================================================================
+// HELPER FUNCTIONS
+// ============================================================================
+
+/**
+ * Poll Batch API job status until completion
+ *
+ * POLLING STRATEGY:
+ * - Initial delay: 2 seconds
+ * - Max delay: 30 seconds
+ * - Exponential backoff with 1.5x multiplier
+ * - Timeout: 30 minutes
+ *
+ * TERMINAL STATES:
+ * - COMPLETE: Job succeeded
+ * - FAILED: Job failed (API error, validation errors, etc.)
+ * - Other statuses: Continue polling
+ */
+async function pollJobStatus(client: any, jobId: string, logger: any): Promise<any> {
+  let delay = 2000; // Start with 2 second delay
+  const maxDelay = 30000; // Cap at 30 seconds
+  const timeout = 30 * 60 * 1000; // 30 minutes
+  const startTime = Date.now();
+
+  while (true) {
+    // Check timeout
+    if (Date.now() - startTime > timeout) {
+      throw new Error('Job status polling timeout (30 minutes)');
+    }
+
+    // Get job status
+    const status = await client.getJobStatus(jobId);
+    logger.debug(`Job status: ${status.status}`, {
+      jobId,
+      status: status.status,
+    });
+
+    // Check terminal states
+    if (status.status === 'COMPLETE' || status.status === 'FAILED') {
+      return status;
+    }
+
+    // Wait before next poll
+    await sleep(delay);
+
+    // Increase delay with exponential backoff (1.5x multiplier)
+    delay = Math.min(delay * 1.5, maxDelay);
+  }
+}
+
+/**
+ * Sleep helper function
+ */
+function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Chunk array into smaller arrays
+ */
+function chunk<T>(array: T[], size: number): T[][] {
+  const chunks: T[][] = [];
+  for (let i = 0; i < array.length; i += size) {
+    chunks.push(array.slice(i, i + size));
+  }
+  return chunks;
+}
+
+// ============================================================================
+// ENTRY POINT
+// ============================================================================
+
+/**
+ * Main entry point with error handling
+ */
+async function main() {
+  try {
+    const result = await syncInventory();
+
+    // Exit with success code if no files failed
+    if (result.filesFailed === 0) {
+      logger.info('All files processed successfully');
+      process.exit(0);
+    } else {
+      logger.warn('Some files failed to process');
+      process.exit(1);
+    }
+  } catch (error) {
+    logger.error('Fatal error during inventory sync', error as Error);
+    process.exit(1);
+  }
+}
+
+// Run the sync
+main();
+```
+
+### 4. Package.json Configuration
+
+```json
+{
+  "name": "inventory-sync-standalone",
+  "version": "1.0.0",
+  "description": "Standalone S3 CSV to Fluent Commerce inventory sync",
+  "main": "dist/inventory-sync.js",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/inventory-sync.js",
+    "dev": "tsx src/inventory-sync.ts",
+    "sync": "npm run dev",
+    "lint": "eslint src --ext .ts",
+    "type-check": "tsc --noEmit"
+  },
+  "keywords": ["fluent-commerce", "inventory", "s3", "batch-api"],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@fluentcommerce/fc-connect-sdk": "^0.1.39",
+    "dotenv": "^16.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^18.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  }
+}
+```
+
+### 5. TypeScript Configuration
+
+Create `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "module": "ES2022",
+    "target": "ES2024",
+    "moduleResolution": "node"
+  }
+}
+```
+
+---
+
+## Key Patterns Explained
+
+### Pattern 1: OAuth2 Authentication
+
+**Purpose**: Authenticate with Fluent Commerce without Versori connection
+
+**Implementation**:
+
+```typescript
+const fluentClient = await createClient({
+  config: {
+    baseUrl: 'https://api.fluentcommerce.com',
+    clientId: process.env.FLUENT_CLIENT_ID,
+    clientSecret: process.env.FLUENT_CLIENT_SECRET,
+    retailerId: process.env.FLUENT_RETAILER_ID,
+  },
+});
+```
+
+**Key Points**:
+
+- Uses client credentials OAuth2 grant type
+- Token automatically cached and refreshed by SDK
+- No manual token management needed
+- Token expires after ~1 hour, SDK handles refresh transparently
+
+**When to Use**:
+
+- Standalone Node.js/Deno scripts
+- Background jobs/cron tasks
+- CI/CD pipelines
+- Local development
+
+### Pattern 2: S3 File Operations
+
+**Purpose**: List, download, and move files in S3 bucket
+
+**Implementation**:
+
+```typescript
+// Initialize S3 Data Source
+const s3Source = new S3DataSource(
+  {
+    type: 'S3_CSV',
+    connectionId: 'inventory-s3',
+    name: 'Inventory S3 Source',
+    s3Config: {
+      bucket: 'my-bucket',
+      region: 'us-east-1',
+      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+    },
+  },
+  logger
+);
+
+// List files with prefix filter
+const files = await s3Source.listFiles({
+  prefix: 'inventory/updates/',
+  maxKeys: 1000,
+});
+
+// Download file content
+const content = await s3Source.downloadFile(file.path);
+
+// Move file (copy + delete)
+await s3Source.moveFile(sourcePath, destPath);
+```
+
+**Key Points**:
+
+- Uses presigned URLs (no AWS SDK required)
+- Automatic retry logic for transient failures
+- Streaming support for large files
+- Cross-bucket move support
+
+**Best Practices**:
+
+- Always use prefix filtering to limit results
+- Move files to archive/error folders (don't delete)
+- Use date-based folder structure for archiving
+- Validate S3 connection before processing
+
+### Pattern 3: CSV Parsing & Validation
+
+**Purpose**: Parse CSV files and validate data quality
+
+**Implementation**:
+
+```typescript
+// Initialize CSV Parser
+const csvParser = new CSVParserService();
+
+// Parse CSV content (returns array of objects)
+const records = await csvParser.parse(csvContent);
+
+// Validate records
+const validRecords = records.filter(record => {
+  // Required field validation
+  if (!record.sku || !record.location || record.quantity === undefined) {
+    logger.warn('Missing required fields', { record });
+    return false;
+  }
+
+  // Type validation
+  if (isNaN(Number(record.quantity))) {
+    logger.warn('Invalid quantity', { record });
+    return false;
+  }
+
+  return true;
+});
+```
+
+**Key Points**:
+
+- CSV parser auto-detects headers by default
+- Trims whitespace and skips empty lines
+- Returns array of objects (header → value mapping)
+- Validation happens before mapping (fail fast)
+
+**Validation Strategies**:
+
+1. **Required Fields**: Check for null/undefined/empty
+2. **Type Validation**: Ensure numeric fields are numbers
+3. **Format Validation**: Regex for SKU, email, phone, etc.
+4. **Business Rules**: Range checks, valid enum values
+5. **Cross-field Validation**: Relationships between fields
+
+### Pattern 4: Batch API Workflow
+
+**Purpose**: Send large datasets to Fluent Commerce efficiently
+
+**Implementation**:
+
+```typescript
+// STEP 1: Create Job
+const job = await fluentClient.createJob({
+  name: 'Inventory Update - file.csv',
+  retailerId: 'my-retailer',
+});
+
+// STEP 2: Send Batches (chunked)
+const batchSize = 100;
+for (let i = 0; i < records.length; i += batchSize) {
+  const batch = records.slice(i, i + batchSize);
+  await fluentClient.sendBatch(job.id, {
+    entities: batch,
+  });
+}
+
+// STEP 3: Poll Job Status
+let status = await fluentClient.getJobStatus(job.id);
+while (status.status !== 'COMPLETE' && status.status !== 'FAILED') {
+  await sleep(5000); // Wait 5 seconds
+  status = await fluentClient.getJobStatus(job.id);
+}
+
+// STEP 4: Check Results
+if (status.status === 'COMPLETE') {
+  console.log('Job succeeded!');
+} else {
+  console.error('Job failed:', status);
+}
+```
+
+**Key Points**:
+
+- One job per file (easier tracking)
+- Batch size 50-500 records (100 recommended)
+- Poll with exponential backoff
+- Handle both COMPLETE and FAILED states
+
+**Batch Size Guidelines**:
+
+- Small records (<10 fields): 200-500 per batch
+- Medium records (10-30 fields): 100-200 per batch
+- Large records (>30 fields): 50-100 per batch
+- API limit: Usually 1000 records per batch
+
+### Pattern 5: Error Handling & Retry
+
+**Purpose**: Graceful degradation and recovery from failures
+
+**Implementation**:
+
+```typescript
+// File-level try-catch
+for (const file of files) {
+  try {
+    await processFile(file);
+    filesSucceeded++;
+  } catch (error) {
+    logger.error('File processing failed', error);
+    filesFailed++;
+
+    // Move to error folder
+    try {
+      await s3Source.moveFile(file.path, errorPath);
+    } catch (moveError) {
+      logger.error('Failed to move error file', moveError);
+    }
+  }
+}
+
+// Automatic retry with exponential backoff
+async function retryWithBackoff<T>(fn: () => Promise<T>, maxRetries: number = 3): Promise<T> {
+  let lastError: Error;
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error as Error;
+      if (attempt < maxRetries - 1) {
+        const delay = Math.pow(2, attempt) * 1000;
+        await sleep(delay);
+      }
+    }
+  }
+  throw lastError!;
+}
+```
+
+**Error Categories**:
+
+1. **Network Errors**: Retry with exponential backoff
+2. **4xx Client Errors**: Don't retry (bad request)
+3. **5xx Server Errors**: Retry (transient failure)
+4. **Validation Errors**: Skip record, continue processing
+5. **Fatal Errors**: Exit with error code
+
+**Retry Best Practices**:
+
+- Max 3-5 retry attempts
+- Exponential backoff (1s, 2s, 4s, 8s, ...)
+- Jitter to prevent thundering herd
+- Log each retry attempt
+- Give up after max retries
+
+---
+
+## Deployment Options
+
+### Option 1: Local Execution
+
+```bash
+# One-time sync
+npm run sync
+
+# With debug logging
+LOG_LEVEL=debug npm run sync
+```
+
+### Option 2: Docker Container
+
+Create `Dockerfile`:
+
+```dockerfile
+FROM node:18-alpine
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+
+# Install dependencies
+RUN npm ci --only=production
+
+# Copy application code
+COPY dist ./dist
+
+# Run the sync
+CMD ["node", "dist/inventory-sync.js"]
+```
+
+Build and run:
+
+```bash
+# Build image
+docker build -t inventory-sync .
+
+# Run container
+docker run --env-file .env inventory-sync
+```
+
+### Option 3: AWS Lambda
+
+Create `lambda-handler.ts`:
+
+```typescript
+import { syncInventory } from './inventory-sync';
+
+export const handler = async (event: any, context: any) => {
+  try {
+    const result = await syncInventory();
+    return {
+      statusCode: 200,
+      body: JSON.stringify(result),
+    };
+  } catch (error) {
+    console.error('Lambda error:', error);
+    return {
+      statusCode: 500,
+      body: JSON.stringify({ error: (error as Error).message }),
+    };
+  }
+};
+```
+
+Deploy:
+
+```bash
+# Package for Lambda
+npm run build
+zip -r function.zip dist node_modules
+
+# Deploy with AWS CLI
+aws lambda create-function \
+  --function-name inventory-sync \
+  --runtime nodejs18.x \
+  --handler dist/lambda-handler.handler \
+  --zip-file fileb://function.zip \
+  --role arn:aws:iam::123456789:role/lambda-execution \
+  --timeout 900 \
+  --memory-size 512
+```
+
+### Option 4: Cron Scheduling
+
+**Linux/Mac cron**:
+
+```bash
+# Edit crontab
+crontab -e
+
+# Run every 4 hours
+0 */4 * * * cd /path/to/inventory-sync && npm run sync >> /var/log/inventory-sync.log 2>&1
+```
+
+**Node.js cron**:
+
+Install: `npm install node-cron`
+
+```typescript
+import cron from 'node-cron';
+
+// Run every 4 hours
+cron.schedule('0 */4 * * *', async () => {
+  logger.info('Starting scheduled inventory sync');
+  await syncInventory();
+});
+
+logger.info('Cron scheduler started (every 4 hours)');
+```
+
+**AWS EventBridge**:
+
+```bash
+# Create rule
+aws events put-rule \
+  --name inventory-sync-schedule \
+  --schedule-expression "rate(4 hours)"
+
+# Add Lambda target
+aws events put-targets \
+  --rule inventory-sync-schedule \
+  --targets "Id"="1","Arn"="arn:aws:lambda:us-east-1:123:function:inventory-sync"
+```
+
+---
+
+## Testing
+
+### Local Testing
+
+```bash
+# 1. Create test CSV file
+cat > test-inventory.csv << EOF
+sku,location,quantity,status,expected_date
+TEST-SKU-001,WAREHOUSE-A,100,ACTIVE,2024-01-15
+TEST-SKU-002,WAREHOUSE-B,50,ACTIVE,2024-01-15
+TEST-SKU-003,STORE-001,25,ACTIVE,2024-01-16
+EOF
+
+# 2. Upload to S3
+aws s3 cp test-inventory.csv s3://your-bucket/inventory/updates/
+
+# 3. Run sync
+npm run sync
+
+# 4. Check logs
+cat logs/inventory-sync.log
+
+# 5. Verify in Fluent Commerce
+# - Check job status in admin portal
+# - Query inventory positions via GraphQL
+```
+
+### Integration Testing
+
+Create `tests/integration.test.ts`:
+
+```typescript
+import { describe, it, expect, beforeAll } from '@jest/globals';
+import { syncInventory } from '../src/inventory-sync';
+
+describe('Inventory Sync Integration', () => {
+  beforeAll(async () => {
+    // Setup test environment
+  });
+
+  it('should process valid CSV file', async () => {
+    // Upload test file to S3
+    // Run sync
+    const result = await syncInventory();
+
+    // Assertions
+    expect(result.filesSucceeded).toBe(1);
+    expect(result.filesFailed).toBe(0);
+    expect(result.totalRecordsProcessed).toBeGreaterThan(0);
+  });
+
+  it('should handle invalid records gracefully', async () => {
+    // Upload CSV with invalid records
+    // Run sync
+    const result = await syncInventory();
+
+    // Should still succeed but skip invalid records
+    expect(result.filesSucceeded).toBe(1);
+    expect(result.totalRecordsFailed).toBeGreaterThan(0);
+  });
+
+  it('should move failed files to error folder', async () => {
+    // Upload malformed CSV
+    // Run sync
+    const result = await syncInventory();
+
+    // File should be in error folder
+    expect(result.filesFailed).toBe(1);
+    // Check S3 error folder
+  });
+});
+```
+
+Run tests:
+
+```bash
+npm install --save-dev jest @jest/globals @types/jest ts-jest
+npm test
+```
+
+---
+
+## Common Issues
+
+### Issue 1: OAuth2 Token Expired
+
+**Symptom**: `401 Unauthorized` errors
+
+**Cause**: Token expired and SDK failed to refresh
+
+**Solution**:
+
+```typescript
+// SDK handles refresh automatically, but you can force refresh
+const client = await createClient({
+  config: {
+    baseUrl: 'https://api.fluentcommerce.com',
+    clientId: process.env.FLUENT_CLIENT_ID,
+    clientSecret: process.env.FLUENT_CLIENT_SECRET,
+    retailerId: process.env.FLUENT_RETAILER_ID,
+    retryAttempts: 3,
+  },
+});
+```
+
+### Issue 2: S3 Permission Denied
+
+**Symptom**: `AccessDenied` errors when listing/downloading files
+
+**Cause**: IAM policy missing required permissions
+
+**Solution**:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": ["s3:ListBucket", "s3:GetObject", "s3:PutObject", "s3:DeleteObject"],
+      "Resource": ["arn:aws:s3:::your-bucket", "arn:aws:s3:::your-bucket/*"]
+    }
+  ]
+}
+```
+
+### Issue 3: CSV Parsing Errors
+
+**Symptom**: `CSV parse error: Invalid record`
+
+**Cause**: Malformed CSV (unescaped quotes, inconsistent columns)
+
+**Solution**:
+
+```typescript
+// Use more lenient CSV parser options
+const csvParser = CSVParserService.create({
+  columns: true,
+  skip_empty_lines: true,
+  trim: true,
+  relax_column_count: true, // Allow inconsistent column counts
+  quote: '"',
+  escape: '"',
+  delimiter: ',',
+});
+```
+
+### Issue 4: Batch API Timeout
+
+**Symptom**: Job stays in `PENDING` state indefinitely
+
+**Cause**: Fluent API processing delay or large batch size
+
+**Solution**:
+
+```typescript
+// Reduce batch size
+const batchSize = 50; // Instead of 100
+
+// Increase polling timeout
+const timeout = 60 * 60 * 1000; // 1 hour instead of 30 minutes
+
+// Add more aggressive polling
+let delay = 1000; // Start with 1 second
+const maxDelay = 15000; // Cap at 15 seconds
+```
+
+### Issue 5: Memory Exhaustion
+
+**Symptom**: `JavaScript heap out of memory` error
+
+**Cause**: Loading entire large CSV file into memory
+
+**Solution**:
+
+```typescript
+// Use streaming CSV parsing instead
+for await (const record of csvParser.parseStreaming(csvContent, {}, 100)) {
+  // Process records in batches of 100
+  const mappedBatch = await Promise.all(record.map(r => mapper.map(r)));
+
+  // Send batch immediately (don't accumulate)
+  await fluentClient.sendBatch(jobId, {
+    entities: mappedBatch.filter(r => r.success).map(r => r.data),
+  });
+}
+```
+
+---
+
+## Related Guides
+
+- **SDK Reference**: `../../readme.md` - Core SDK documentation
+- **Universal Mapping Guide**: `../../02-CORE-GUIDES/mapping/readme.md` - Field mapping patterns
+- **Batch API Guide**: `../../02-CORE-GUIDES/api-reference/modules/03-batch-processing.md` - Batch API details
+- **S3 Data Source**: `../../02-CORE-GUIDES/data-sources/readme.md` - S3 operations
+- **CSV Parser**: `../../02-CORE-GUIDES/parsers/readme.md` - CSV parsing options
+- **Error Handling**: `../../03-PATTERN-GUIDES/error-handling/readme.md` - Error patterns
+
+---
+
+## Production Checklist
+
+Before deploying to production:
+
+- [ ] Environment variables secured (AWS Secrets Manager, vault, etc.)
+- [ ] Logging configured (Winston, CloudWatch, Datadog, etc.)
+- [ ] Error alerting setup (PagerDuty, Slack, email)
+- [ ] Monitoring dashboard (metrics, job success rate, duration)
+- [ ] Retry logic tested (network failures, API errors)
+- [ ] Batch size optimized (tested with production file sizes)
+- [ ] Memory profiling done (no leaks)
+- [ ] S3 lifecycle policies configured (archive old files)
+- [ ] IAM permissions minimized (least privilege)
+- [ ] Health check endpoint added (for orchestration tools)
+- [ ] Documentation updated (runbook, troubleshooting)
+- [ ] Disaster recovery tested (restore from archive)
+
+---
+
+**Next Steps**:
+
+1. Customize field mappings for your inventory data structure
+2. Add custom validation rules for your business logic
+3. Implement state tracking to prevent duplicate processing
+4. Set up monitoring and alerting
+5. Deploy to your preferred environment (Lambda, ECS, K8s, etc.)
+
+**Support**:
+
+- SDK Issues: https://github.com/fluentcommerce/fc-connect-sdk/issues
+- Fluent Commerce API: https://docs.fluentcommerce.com
+- Community: https://community.fluentcommerce.com