@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/02-CORE-GUIDES/parsers/modules/02-core-guides-parsers-02-csv-parser.md

@@ -1,772 +1,772 @@
-# Module 2: CSV Parser
-
-**Level:** Beginner
-**Estimated Time:** 20 minutes
-
-## Overview
-
-This module covers the CSV Parser (`CSVParserService`), the most common parser for inventory and product data feeds. You'll learn how to parse CSV files, validate data, handle large files with streaming, and integrate with SDK transformation services.
-
-## Learning Objectives
-
-By the end of this module, you will:
-- ✅ Parse CSV files into structured JavaScript objects
-- ✅ Configure parser options for different CSV formats
-- ✅ Stream large CSV files efficiently
-- ✅ Validate CSV structure and data types
-- ✅ Transform CSV data with UniversalMapper
-
-## What is CSV?
-
-**CSV (Comma-Separated Values)** is a simple tabular format where:
-- Each line represents a record
-- Fields are separated by commas (or other delimiters)
-- First line typically contains column headers
-- Text values may be quoted
-
-**Example:**
-```csv
-sku,name,qty,location
-SKU001,Wireless Mouse,100,WH-01
-SKU002,Keyboard,50,WH-01
-SKU003,Monitor,25,WH-02
-```
-
-## Basic CSV Parsing
-
-### Simple Parsing
-
-```typescript
-import { CSVParserService } from '@fluentcommerce/fc-connect-sdk';
-
-const csvParser = new CSVParserService();
-
-// Sample CSV data
-const csvContent = `sku,qty,location
-SKU001,100,WH-01
-SKU002,50,WH-01
-SKU003,75,WH-02`;
-
-// Parse CSV
-const records = await csvParser.parse(csvContent);
-
-console.log(records);
-// [
-//   { sku: 'SKU001', qty: '100', location: 'WH-01' },
-//   { sku: 'SKU002', qty: '50', location: 'WH-01' },
-//   { sku: 'SKU003', qty: '75', location: 'WH-02' }
-// ]
-```
-
-### Type Safety with TypeScript
-
-```typescript
-// Define your record structure
-interface InventoryRecord {
-  sku: string;
-  qty: string;
-  location: string;
-}
-
-// Parse with type assertion
-const records = await csvParser.parse<InventoryRecord>(csvContent);
-
-// Now you have full type safety
-records.forEach(record => {
-  console.log(`${record.sku}: ${record.qty} units at ${record.location}`);
-});
-```
-
-## Parser Configuration
-
-The CSV parser supports various options to handle different CSV formats:
-
-### Common Options
-
-```typescript
-import { CSVParserService } from '@fluentcommerce/fc-connect-sdk';
-import type { Options as CSVOptions } from 'csv-parse';
-
-const csvParser = new CSVParserService();
-
-const options: CSVOptions = {
-  // Column headers (default: true - first row is headers)
-  columns: true,
-
-  // Skip empty lines (default: true)
-  skip_empty_lines: true,
-
-  // Trim whitespace (default: true)
-  trim: true,
-
-  // Custom delimiter (default: ',')
-  delimiter: ',',
-
-  // Quote character (default: '"')
-  quote: '"',
-
-  // Escape character (default: '"')
-  escape: '"',
-
-  // Skip first N rows
-  from_line: 1
-};
-
-const records = await csvParser.parse(csvContent, options);
-```
-
-### Handling Different Delimiters
-
-```typescript
-// Tab-separated values (TSV)
-const tsvContent = `sku\tqty\tlocation
-SKU001\t100\tWH-01`;
-
-const tsvRecords = await csvParser.parse(tsvContent, {
-  delimiter: '\t'
-});
-
-// Pipe-separated values
-const pipeSeparated = `sku|qty|location
-SKU001|100|WH-01`;
-
-const pipeRecords = await csvParser.parse(pipeSeparated, {
-  delimiter: '|'
-});
-
-// Semicolon-separated (European format)
-const europeanCSV = `sku;qty;location
-SKU001;100;WH-01`;
-
-const records = await csvParser.parse(europeanCSV, {
-  delimiter: ';'
-});
-```
-
-### Custom Column Names
-
-```typescript
-// CSV without headers
-const noHeadersCSV = `SKU001,100,WH-01
-SKU002,50,WH-01`;
-
-// Provide custom column names
-const records = await csvParser.parse(noHeadersCSV, {
-  columns: ['sku', 'qty', 'location']
-});
-
-console.log(records);
-// [
-//   { sku: 'SKU001', qty: '100', location: 'WH-01' },
-//   { sku: 'SKU002', qty: '50', location: 'WH-01' }
-// ]
-```
-
-### Skipping Rows
-
-```typescript
-// Skip first 2 rows (e.g., title row + header row)
-const csvWithTitle = `Inventory Export - 2025-01-15
-sku,qty,location
-SKU001,100,WH-01
-SKU002,50,WH-01`;
-
-const records = await csvParser.parse(csvWithTitle, {
-  from_line: 2  // Start from line 2 (headers)
-});
-```
-
-## Streaming Large Files
-
-For large CSV files, use streaming to avoid memory issues:
-
-### Basic Streaming
-
-```typescript
-import { CSVParserService } from '@fluentcommerce/fc-connect-sdk';
-
-const csvParser = new CSVParserService();
-
-// Large CSV content (e.g., from S3)
-const largeCsvContent = `...`; // Thousands of rows
-
-// Process records one by one
-for await (const record of csvParser.parseStreaming(largeCsvContent)) {
-  console.log('Processing record:', record);
-  // Process each record individually
-}
-```
-
-### Batch Streaming
-
-Process records in batches for better performance:
-
-```typescript
-const batchSize = 100;
-
-// Process in batches of 100 records
-for await (const batch of csvParser.parseStreaming(largeCsvContent, {}, batchSize)) {
-  console.log(`Processing batch of ${batch.length} records`);
-
-  // Process batch (e.g., send to Fluent Batch API)
-  await processBatch(batch);
-}
-
-async function processBatch(records: any[]) {
-  // Transform and send to Fluent
-  console.log(`Batch processing ${records.length} records`);
-}
-```
-
-### Streaming with Progress Tracking
-
-```typescript
-async function streamWithProgress(csvContent: string) {
-  const csvParser = new CSVParserService();
-  const startTime = Date.now();
-  let recordCount = 0;
-  const batchSize = 500;
-
-  for await (const batch of csvParser.parseStreaming(csvContent, {}, batchSize)) {
-    recordCount += batch.length;
-
-    // Process batch
-    await processBatch(batch);
-
-    // Report progress every 1000 records
-    if (recordCount % 1000 === 0) {
-      const elapsed = (Date.now() - startTime) / 1000;
-      const rate = recordCount / elapsed;
-      console.log(`Processed ${recordCount} records (${rate.toFixed(2)} records/sec)`);
-    }
-  }
-
-  console.log(`Completed: ${recordCount} total records`);
-}
-```
-
-## Data Validation
-
-Validate CSV structure and data types:
-
-### Schema Validation
-
-```typescript
-import { CSVParserService, CSVValidationSchema } from '@fluentcommerce/fc-connect-sdk';
-
-const csvParser = new CSVParserService();
-
-// Define validation schema
-const schema: CSVValidationSchema = {
-  requiredColumns: ['sku', 'qty', 'location'],
-  columnTypes: {
-    sku: 'string',
-    qty: 'number',
-    location: 'string'
-  },
-  minRows: 1,
-  maxRows: 10000
-};
-
-// Validate CSV
-const validation = await csvParser.validate(csvContent, schema);
-
-if (validation.valid) {
-  console.log('CSV is valid');
-  const records = await csvParser.parse(csvContent);
-} else {
-  console.error('Validation errors:', validation.errors);
-  // ['Missing required column: sku', 'Column "qty" must be number']
-}
-```
-
-### Runtime Validation
-
-```typescript
-// Parse and validate each record
-const records = await csvParser.parse(csvContent);
-
-const validRecords = [];
-const errors = [];
-
-for (const record of records) {
-  // Validate required fields
-  if (!record.sku || !record.qty) {
-    errors.push({
-      record,
-      error: 'Missing required fields'
-    });
-    continue;
-  }
-
-  // Validate data types
-  const qty = parseInt(record.qty);
-  if (isNaN(qty) || qty < 0) {
-    errors.push({
-      record,
-      error: 'Invalid quantity'
-    });
-    continue;
-  }
-
-  validRecords.push(record);
-}
-
-console.log(`Valid: ${validRecords.length}, Errors: ${errors.length}`);
-```
-
-## Transformation with UniversalMapper
-
-Combine CSV parsing with field transformations:
-
-### Basic Transformation
-
-```typescript
-import { CSVParserService, UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-
-const csvParser = new CSVParserService();
-
-// CSV with different field names
-const csvContent = `product_code,stock_level,warehouse_id,last_update
-SKU001,100,WH-01,2025-01-15
-SKU002,50,WH-01,2025-01-15`;
-
-// Parse CSV
-const records = await csvParser.parse(csvContent);
-
-// Define field mapping
-const mapper = new UniversalMapper({
-  fields: {
-    ref: { source: 'product_code', required: true },
-    qty: { source: 'stock_level', resolver: 'sdk.parseInt' },
-    locationRef: { source: 'warehouse_id' },
-    updatedOn: { source: 'last_update', resolver: 'sdk.formatDate' }
-  }
-});
-
-// Transform records
-const result = await mapper.map(records);
-
-if (!result.success) {
-  console.error('Mapping errors:', result.errors);
-  throw new Error('Transformation failed');
-}
-
-console.log('Transformed data:', result.data);
-// [
-//   {
-//     ref: 'SKU001',
-//     qty: 100,
-//     locationRef: 'WH-01',
-//     updatedOn: '2025-01-15T00:00:00.000Z'
-//   },
-//   ...
-// ]
-```
-
-### Streaming + Transformation
-
-```typescript
-async function streamAndTransform(csvContent: string) {
-  const csvParser = new CSVParserService();
-  const mapper = new UniversalMapper(mappingConfig);
-
-  const batchSize = 500;
-  const transformedBatches = [];
-
-  // Stream CSV in batches
-  for await (const batch of csvParser.parseStreaming(csvContent, {}, batchSize)) {
-    // Transform each batch
-    const result = await mapper.map(batch);
-
-    if (result.success) {
-      transformedBatches.push(result.data);
-    } else {
-      console.error('Batch transformation failed:', result.errors);
-    }
-  }
-
-  return transformedBatches.flat();
-}
-```
-
-## Complete Integration Example
-
-Full workflow: CSV → Parse → Transform → Send to Fluent
-
-```typescript
-import {
-  createClient,
-  CSVParserService,
-  UniversalMapper
-} from '@fluentcommerce/fc-connect-sdk';
-
-async function processInventoryCSV(csvContent: string) {
-  // 1. Create client
-  const client = await createClient({
-    config: {
-      baseUrl: process.env.FLUENT_BASE_URL!,
-      clientId: process.env.FLUENT_CLIENT_ID!,
-      clientSecret: process.env.FLUENT_CLIENT_SECRET!,
-      retailerId: process.env.FLUENT_RETAILER_ID!
-    }
-  });
-
-  // 2. Parse CSV
-  const csvParser = new CSVParserService();
-  const records = await csvParser.parse(csvContent);
-
-  console.log(`Parsed ${records.length} records`);
-
-  // 3. Define field mapping
-  const mapper = new UniversalMapper({
-    fields: {
-      ref: { source: 'sku', required: true },
-      qty: { source: 'qty', resolver: 'sdk.parseInt' },
-      locationRef: { source: 'location' },
-      type: { value: 'LAST' }  // Static value
-    }
-  });
-
-  // 4. Transform data
-  const result = await mapper.map(records);
-
-  if (!result.success) {
-    throw new Error(`Mapping failed: ${result.errors.join(', ')}`);
-  }
-
-  console.log(`Transformed ${result.data.length} records`);
-
-  // 5. Send to Fluent Commerce (Batch API for INVENTORY only)
-  const job = await client.createJob({
-    name: 'csv-inventory-update',
-    retailerId: process.env.FLUENT_RETAILER_ID!
-  });
-
-  await client.sendBatch(job.id, {
-    entities: result.data
-  });
-
-  console.log(`✅ Successfully sent ${result.data.length} inventory positions to Fluent`);
-}
-```
-
-## Error Handling
-
-Handle common CSV parsing errors:
-
-```typescript
-import { CSVParserService } from '@fluentcommerce/fc-connect-sdk';
-
-async function robustCSVParsing(csvContent: string) {
-  const csvParser = new CSVParserService();
-
-  try {
-    // Validate first
-    const schema = {
-      requiredColumns: ['sku', 'qty'],
-      minRows: 1
-    };
-
-    const validation = await csvParser.validate(csvContent, schema);
-
-    if (!validation.valid) {
-      console.error('CSV validation failed:', validation.errors);
-      return null;
-    }
-
-    // Parse
-    const records = await csvParser.parse(csvContent);
-    return records;
-
-  } catch (error) {
-    if (error.message.includes('Invalid CSV')) {
-      console.error('Malformed CSV file');
-    } else if (error.message.includes('parse error')) {
-      console.error('CSV parsing error:', error.message);
-    } else {
-      console.error('Unexpected error:', error);
-    }
-
-    return null;
-  }
-}
-```
-
-## Performance Tips
-
-### 1. Use Streaming for Large Files
-
-```typescript
-// ❌ BAD: Load everything into memory
-const allRecords = await csvParser.parse(hugeCsvContent);
-
-// ✅ GOOD: Stream and process in batches
-for await (const batch of csvParser.parseStreaming(hugeCsvContent, {}, 500)) {
-  await processBatch(batch);
-}
-```
-
-### 2. Optimize Batch Size
-
-```typescript
-// Small batches (50-100): Complex transformations, API calls
-for await (const batch of csvParser.parseStreaming(csvContent, {}, 50)) {
-  await sendToExternalAPI(batch);
-}
-
-// Large batches (500-1000): Simple transformations, in-memory processing
-for await (const batch of csvParser.parseStreaming(csvContent, {}, 1000)) {
-  await simpleTransformation(batch);
-}
-```
-
-### 3. Parallel Processing
-
-```typescript
-async function parallelCSVProcessing(csvFiles: string[]) {
-  const csvParser = new CSVParserService();
-
-  // Process multiple CSV files in parallel
-  const promises = csvFiles.map(async (csvContent) => {
-    const records = await csvParser.parse(csvContent);
-    return transformRecords(records);
-  });
-
-  const results = await Promise.all(promises);
-  return results.flat();
-}
-```
-
-## CSV Generation (Writing)
-
-The CSV parser also supports converting JavaScript objects back to CSV format using the `stringify()` method.
-
-### CSVParserService.stringify()
-
-Convert array of records to CSV string.
-
-```typescript
-import { CSVParserService } from '@fluentcommerce/fc-connect-sdk';
-
-const csvParser = new CSVParserService();
-
-const records = [
-  { name: 'Alice', age: 30, city: 'NYC' },
-  { name: 'Bob', age: 25, city: 'LA' },
-  { name: 'Charlie', age: 35, city: 'Chicago' }
-];
-
-// Generate CSV with default options
-const csvString = csvParser.stringify(records, {
-  headers: true,        // Include header row
-  delimiter: ',',       // Field delimiter
-  quote: '"',          // Quote character
-  escape: '"'          // Escape character
-});
-
-console.log(csvString);
-// Output:
-// name,age,city
-// Alice,30,NYC
-// Bob,25,LA
-// Charlie,35,Chicago
-```
-
-### Stringify Options
-
-```typescript
-interface StringifyOptions {
-  headers?: boolean;        // Include header row (default: true)
-  delimiter?: string;       // Field delimiter (default: ',')
-  quote?: string;          // Quote character (default: '"')
-  escape?: string;         // Escape character (default: '"')
-}
-```
-
-### Different Delimiters
-
-```typescript
-// Tab-separated (TSV)
-const tsv = csvParser.stringify(records, {
-  delimiter: '\t',
-  headers: true
-});
-// Output: name\tage\tcity\nAlice\t30\tNYC...
-
-// Semicolon-separated (European format)
-const europeanCsv = csvParser.stringify(records, {
-  delimiter: ';',
-  headers: true
-});
-// Output: name;age;city\nAlice;30;NYC...
-
-// Pipe-separated
-const pipeCsv = csvParser.stringify(records, {
-  delimiter: '|',
-  headers: true
-});
-// Output: name|age|city\nAlice|30|NYC...
-```
-
-### Without Headers
-
-```typescript
-const csvNoHeaders = csvParser.stringify(records, {
-  headers: false  // Skip header row
-});
-
-console.log(csvNoHeaders);
-// Output:
-// Alice,30,NYC
-// Bob,25,LA
-// Charlie,35,Chicago
-```
-
-### Complete Round-Trip Example
-
-```typescript
-import { CSVParserService } from '@fluentcommerce/fc-connect-sdk';
-
-async function csvRoundTrip() {
-  const csvParser = new CSVParserService();
-
-  // Original CSV
-  const originalCsv = `sku,qty,location
-SKU001,100,WH-01
-SKU002,50,WH-02`;
-
-  // Parse
-  const records = await csvParser.parse(originalCsv);
-  console.log('Parsed:', records);
-
-  // Transform data (e.g., double quantities)
-  const transformed = records.map(r => ({
-    ...r,
-    qty: parseInt(r.qty) * 2
-  }));
-
-  // Convert back to CSV
-  const newCsv = csvParser.stringify(transformed, {
-    headers: true,
-    delimiter: ','
-  });
-
-  console.log('Generated CSV:');
-  console.log(newCsv);
-  // Output:
-  // sku,qty,location
-  // SKU001,200,WH-01
-  // SKU002,100,WH-02
-}
-```
-
-### Practical Use Case: Export to CSV File
-
-```typescript
-import { CSVParserService } from '@fluentcommerce/fc-connect-sdk';
-import * as fs from 'fs/promises';
-
-async function exportToCsv(data: any[], outputPath: string) {
-  const csvParser = new CSVParserService();
-
-  // Convert records to CSV
-  const csvContent = csvParser.stringify(data, {
-    headers: true,
-    delimiter: ','
-  });
-
-  // Write to file
-  await fs.writeFile(outputPath, csvContent, 'utf-8');
-
-  console.log(`✅ Exported ${data.length} records to ${outputPath}`);
-}
-
-// Usage
-const inventoryData = [
-  { sku: 'SKU001', qty: 100, location: 'WH-01' },
-  { sku: 'SKU002', qty: 50, location: 'WH-02' }
-];
-
-await exportToCsv(inventoryData, 'inventory-export.csv');
-```
-
-### Integration with S3
-
-```typescript
-import { CSVParserService, S3DataSource, createConsoleLogger, toStructuredLogger } from '@fluentcommerce/fc-connect-sdk';
-
-async function exportToS3(data: any[], s3Key: string) {
-  const logger = toStructuredLogger(createConsoleLogger(), { service: 'CSVExport' });
-  const csvParser = new CSVParserService();
-
-  // Convert to CSV
-  const csvContent = csvParser.stringify(data, { headers: true });
-
-  // Setup S3
-  const s3 = new S3DataSource(
-    {
-      type: 'S3_CSV',
-      connectionId: 's3-csv-export',
-      name: 'S3 CSV Export',
-      s3Config: {
-        bucket: process.env.S3_BUCKET!,
-        accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
-        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
-        region: process.env.AWS_REGION!
-      }
-    },
-    logger
-  );
-
-  // Upload to S3
-  await s3.uploadFile(s3Key, Buffer.from(csvContent), {
-    contentType: 'text/csv'
-  });
-
-  console.log(`✅ Exported to s3://${process.env.S3_BUCKET}/${s3Key}`);
-}
-
-// Usage
-await exportToS3(inventoryData, 'exports/inventory-2025-10-30.csv');
-```
-
----
-
-## Key Takeaways
-
-- 🎯 CSV Parser handles tabular data with headers
-- 🎯 Use `parse()` for small files, `parseStreaming()` for large files
-- 🎯 Use `stringify()` to convert objects back to CSV format
-- 🎯 Configure delimiter, quotes, and column options for different formats
-- 🎯 Validate structure with `validate()` before parsing
-- 🎯 Combine with `UniversalMapper` for field transformations
-- 🎯 Stream in batches for memory-efficient processing
-- 🎯 Handle errors gracefully with validation and try-catch
-
-## Practice Exercise
-
-**Challenge:** Parse this CSV and transform it for Fluent Commerce:
-
-```csv
-product_id,available_qty,warehouse,last_updated
-PROD-001,150,DC-EAST,2025-01-15T10:30:00Z
-PROD-002,75,DC-WEST,2025-01-15T11:00:00Z
-PROD-003,200,DC-CENTRAL,2025-01-15T11:30:00Z
-```
-
-**Requirements:**
-1. Parse the CSV
-2. Transform to Fluent format: `{ ref, qty, locationRef, updatedOn }`
-3. Validate that qty is a positive number
-4. Format the date properly
-
-**Solution:** See [CSV Examples](../examples/csv-parser-examples.ts)
-
-## Next Steps
-
-Continue to [Module 3: JSON Parser →](./02-core-guides-parsers-03-json-parser.md) to learn JSON and JSONL parsing.
-
----
-
-**Module 2 Complete!** ✅
+# Module 2: CSV Parser
+
+**Level:** Beginner
+**Estimated Time:** 20 minutes
+
+## Overview
+
+This module covers the CSV Parser (`CSVParserService`), the most common parser for inventory and product data feeds. You'll learn how to parse CSV files, validate data, handle large files with streaming, and integrate with SDK transformation services.
+
+## Learning Objectives
+
+By the end of this module, you will:
+- ✅ Parse CSV files into structured JavaScript objects
+- ✅ Configure parser options for different CSV formats
+- ✅ Stream large CSV files efficiently
+- ✅ Validate CSV structure and data types
+- ✅ Transform CSV data with UniversalMapper
+
+## What is CSV?
+
+**CSV (Comma-Separated Values)** is a simple tabular format where:
+- Each line represents a record
+- Fields are separated by commas (or other delimiters)
+- First line typically contains column headers
+- Text values may be quoted
+
+**Example:**
+```csv
+sku,name,qty,location
+SKU001,Wireless Mouse,100,WH-01
+SKU002,Keyboard,50,WH-01
+SKU003,Monitor,25,WH-02
+```
+
+## Basic CSV Parsing
+
+### Simple Parsing
+
+```typescript
+import { CSVParserService } from '@fluentcommerce/fc-connect-sdk';
+
+const csvParser = new CSVParserService();
+
+// Sample CSV data
+const csvContent = `sku,qty,location
+SKU001,100,WH-01
+SKU002,50,WH-01
+SKU003,75,WH-02`;
+
+// Parse CSV
+const records = await csvParser.parse(csvContent);
+
+console.log(records);
+// [
+//   { sku: 'SKU001', qty: '100', location: 'WH-01' },
+//   { sku: 'SKU002', qty: '50', location: 'WH-01' },
+//   { sku: 'SKU003', qty: '75', location: 'WH-02' }
+// ]
+```
+
+### Type Safety with TypeScript
+
+```typescript
+// Define your record structure
+interface InventoryRecord {
+  sku: string;
+  qty: string;
+  location: string;
+}
+
+// Parse with type assertion
+const records = await csvParser.parse<InventoryRecord>(csvContent);
+
+// Now you have full type safety
+records.forEach(record => {
+  console.log(`${record.sku}: ${record.qty} units at ${record.location}`);
+});
+```
+
+## Parser Configuration
+
+The CSV parser supports various options to handle different CSV formats:
+
+### Common Options
+
+```typescript
+import { CSVParserService } from '@fluentcommerce/fc-connect-sdk';
+import type { Options as CSVOptions } from 'csv-parse';
+
+const csvParser = new CSVParserService();
+
+const options: CSVOptions = {
+  // Column headers (default: true - first row is headers)
+  columns: true,
+
+  // Skip empty lines (default: true)
+  skip_empty_lines: true,
+
+  // Trim whitespace (default: true)
+  trim: true,
+
+  // Custom delimiter (default: ',')
+  delimiter: ',',
+
+  // Quote character (default: '"')
+  quote: '"',
+
+  // Escape character (default: '"')
+  escape: '"',
+
+  // Skip first N rows
+  from_line: 1
+};
+
+const records = await csvParser.parse(csvContent, options);
+```
+
+### Handling Different Delimiters
+
+```typescript
+// Tab-separated values (TSV)
+const tsvContent = `sku\tqty\tlocation
+SKU001\t100\tWH-01`;
+
+const tsvRecords = await csvParser.parse(tsvContent, {
+  delimiter: '\t'
+});
+
+// Pipe-separated values
+const pipeSeparated = `sku|qty|location
+SKU001|100|WH-01`;
+
+const pipeRecords = await csvParser.parse(pipeSeparated, {
+  delimiter: '|'
+});
+
+// Semicolon-separated (European format)
+const europeanCSV = `sku;qty;location
+SKU001;100;WH-01`;
+
+const records = await csvParser.parse(europeanCSV, {
+  delimiter: ';'
+});
+```
+
+### Custom Column Names
+
+```typescript
+// CSV without headers
+const noHeadersCSV = `SKU001,100,WH-01
+SKU002,50,WH-01`;
+
+// Provide custom column names
+const records = await csvParser.parse(noHeadersCSV, {
+  columns: ['sku', 'qty', 'location']
+});
+
+console.log(records);
+// [
+//   { sku: 'SKU001', qty: '100', location: 'WH-01' },
+//   { sku: 'SKU002', qty: '50', location: 'WH-01' }
+// ]
+```
+
+### Skipping Rows
+
+```typescript
+// Skip first 2 rows (e.g., title row + header row)
+const csvWithTitle = `Inventory Export - 2025-01-15
+sku,qty,location
+SKU001,100,WH-01
+SKU002,50,WH-01`;
+
+const records = await csvParser.parse(csvWithTitle, {
+  from_line: 2  // Start from line 2 (headers)
+});
+```
+
+## Streaming Large Files
+
+For large CSV files, use streaming to avoid memory issues:
+
+### Basic Streaming
+
+```typescript
+import { CSVParserService } from '@fluentcommerce/fc-connect-sdk';
+
+const csvParser = new CSVParserService();
+
+// Large CSV content (e.g., from S3)
+const largeCsvContent = `...`; // Thousands of rows
+
+// Process records one by one
+for await (const record of csvParser.parseStreaming(largeCsvContent)) {
+  console.log('Processing record:', record);
+  // Process each record individually
+}
+```
+
+### Batch Streaming
+
+Process records in batches for better performance:
+
+```typescript
+const batchSize = 100;
+
+// Process in batches of 100 records
+for await (const batch of csvParser.parseStreaming(largeCsvContent, {}, batchSize)) {
+  console.log(`Processing batch of ${batch.length} records`);
+
+  // Process batch (e.g., send to Fluent Batch API)
+  await processBatch(batch);
+}
+
+async function processBatch(records: any[]) {
+  // Transform and send to Fluent
+  console.log(`Batch processing ${records.length} records`);
+}
+```
+
+### Streaming with Progress Tracking
+
+```typescript
+async function streamWithProgress(csvContent: string) {
+  const csvParser = new CSVParserService();
+  const startTime = Date.now();
+  let recordCount = 0;
+  const batchSize = 500;
+
+  for await (const batch of csvParser.parseStreaming(csvContent, {}, batchSize)) {
+    recordCount += batch.length;
+
+    // Process batch
+    await processBatch(batch);
+
+    // Report progress every 1000 records
+    if (recordCount % 1000 === 0) {
+      const elapsed = (Date.now() - startTime) / 1000;
+      const rate = recordCount / elapsed;
+      console.log(`Processed ${recordCount} records (${rate.toFixed(2)} records/sec)`);
+    }
+  }
+
+  console.log(`Completed: ${recordCount} total records`);
+}
+```
+
+## Data Validation
+
+Validate CSV structure and data types:
+
+### Schema Validation
+
+```typescript
+import { CSVParserService, CSVValidationSchema } from '@fluentcommerce/fc-connect-sdk';
+
+const csvParser = new CSVParserService();
+
+// Define validation schema
+const schema: CSVValidationSchema = {
+  requiredColumns: ['sku', 'qty', 'location'],
+  columnTypes: {
+    sku: 'string',
+    qty: 'number',
+    location: 'string'
+  },
+  minRows: 1,
+  maxRows: 10000
+};
+
+// Validate CSV
+const validation = await csvParser.validate(csvContent, schema);
+
+if (validation.valid) {
+  console.log('CSV is valid');
+  const records = await csvParser.parse(csvContent);
+} else {
+  console.error('Validation errors:', validation.errors);
+  // ['Missing required column: sku', 'Column "qty" must be number']
+}
+```
+
+### Runtime Validation
+
+```typescript
+// Parse and validate each record
+const records = await csvParser.parse(csvContent);
+
+const validRecords = [];
+const errors = [];
+
+for (const record of records) {
+  // Validate required fields
+  if (!record.sku || !record.qty) {
+    errors.push({
+      record,
+      error: 'Missing required fields'
+    });
+    continue;
+  }
+
+  // Validate data types
+  const qty = parseInt(record.qty);
+  if (isNaN(qty) || qty < 0) {
+    errors.push({
+      record,
+      error: 'Invalid quantity'
+    });
+    continue;
+  }
+
+  validRecords.push(record);
+}
+
+console.log(`Valid: ${validRecords.length}, Errors: ${errors.length}`);
+```
+
+## Transformation with UniversalMapper
+
+Combine CSV parsing with field transformations:
+
+### Basic Transformation
+
+```typescript
+import { CSVParserService, UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+
+const csvParser = new CSVParserService();
+
+// CSV with different field names
+const csvContent = `product_code,stock_level,warehouse_id,last_update
+SKU001,100,WH-01,2025-01-15
+SKU002,50,WH-01,2025-01-15`;
+
+// Parse CSV
+const records = await csvParser.parse(csvContent);
+
+// Define field mapping
+const mapper = new UniversalMapper({
+  fields: {
+    ref: { source: 'product_code', required: true },
+    qty: { source: 'stock_level', resolver: 'sdk.parseInt' },
+    locationRef: { source: 'warehouse_id' },
+    updatedOn: { source: 'last_update', resolver: 'sdk.formatDate' }
+  }
+});
+
+// Transform records
+const result = await mapper.map(records);
+
+if (!result.success) {
+  console.error('Mapping errors:', result.errors);
+  throw new Error('Transformation failed');
+}
+
+console.log('Transformed data:', result.data);
+// [
+//   {
+//     ref: 'SKU001',
+//     qty: 100,
+//     locationRef: 'WH-01',
+//     updatedOn: '2025-01-15T00:00:00.000Z'
+//   },
+//   ...
+// ]
+```
+
+### Streaming + Transformation
+
+```typescript
+async function streamAndTransform(csvContent: string) {
+  const csvParser = new CSVParserService();
+  const mapper = new UniversalMapper(mappingConfig);
+
+  const batchSize = 500;
+  const transformedBatches = [];
+
+  // Stream CSV in batches
+  for await (const batch of csvParser.parseStreaming(csvContent, {}, batchSize)) {
+    // Transform each batch
+    const result = await mapper.map(batch);
+
+    if (result.success) {
+      transformedBatches.push(result.data);
+    } else {
+      console.error('Batch transformation failed:', result.errors);
+    }
+  }
+
+  return transformedBatches.flat();
+}
+```
+
+## Complete Integration Example
+
+Full workflow: CSV → Parse → Transform → Send to Fluent
+
+```typescript
+import {
+  createClient,
+  CSVParserService,
+  UniversalMapper
+} from '@fluentcommerce/fc-connect-sdk';
+
+async function processInventoryCSV(csvContent: string) {
+  // 1. Create client
+  const client = await createClient({
+    config: {
+      baseUrl: process.env.FLUENT_BASE_URL!,
+      clientId: process.env.FLUENT_CLIENT_ID!,
+      clientSecret: process.env.FLUENT_CLIENT_SECRET!,
+      retailerId: process.env.FLUENT_RETAILER_ID!
+    }
+  });
+
+  // 2. Parse CSV
+  const csvParser = new CSVParserService();
+  const records = await csvParser.parse(csvContent);
+
+  console.log(`Parsed ${records.length} records`);
+
+  // 3. Define field mapping
+  const mapper = new UniversalMapper({
+    fields: {
+      ref: { source: 'sku', required: true },
+      qty: { source: 'qty', resolver: 'sdk.parseInt' },
+      locationRef: { source: 'location' },
+      type: { value: 'LAST' }  // Static value
+    }
+  });
+
+  // 4. Transform data
+  const result = await mapper.map(records);
+
+  if (!result.success) {
+    throw new Error(`Mapping failed: ${result.errors.join(', ')}`);
+  }
+
+  console.log(`Transformed ${result.data.length} records`);
+
+  // 5. Send to Fluent Commerce (Batch API for INVENTORY only)
+  const job = await client.createJob({
+    name: 'csv-inventory-update',
+    retailerId: process.env.FLUENT_RETAILER_ID!
+  });
+
+  await client.sendBatch(job.id, {
+    entities: result.data
+  });
+
+  console.log(`✅ Successfully sent ${result.data.length} inventory positions to Fluent`);
+}
+```
+
+## Error Handling
+
+Handle common CSV parsing errors:
+
+```typescript
+import { CSVParserService } from '@fluentcommerce/fc-connect-sdk';
+
+async function robustCSVParsing(csvContent: string) {
+  const csvParser = new CSVParserService();
+
+  try {
+    // Validate first
+    const schema = {
+      requiredColumns: ['sku', 'qty'],
+      minRows: 1
+    };
+
+    const validation = await csvParser.validate(csvContent, schema);
+
+    if (!validation.valid) {
+      console.error('CSV validation failed:', validation.errors);
+      return null;
+    }
+
+    // Parse
+    const records = await csvParser.parse(csvContent);
+    return records;
+
+  } catch (error) {
+    if (error.message.includes('Invalid CSV')) {
+      console.error('Malformed CSV file');
+    } else if (error.message.includes('parse error')) {
+      console.error('CSV parsing error:', error.message);
+    } else {
+      console.error('Unexpected error:', error);
+    }
+
+    return null;
+  }
+}
+```
+
+## Performance Tips
+
+### 1. Use Streaming for Large Files
+
+```typescript
+// ❌ BAD: Load everything into memory
+const allRecords = await csvParser.parse(hugeCsvContent);
+
+// ✅ GOOD: Stream and process in batches
+for await (const batch of csvParser.parseStreaming(hugeCsvContent, {}, 500)) {
+  await processBatch(batch);
+}
+```
+
+### 2. Optimize Batch Size
+
+```typescript
+// Small batches (50-100): Complex transformations, API calls
+for await (const batch of csvParser.parseStreaming(csvContent, {}, 50)) {
+  await sendToExternalAPI(batch);
+}
+
+// Large batches (500-1000): Simple transformations, in-memory processing
+for await (const batch of csvParser.parseStreaming(csvContent, {}, 1000)) {
+  await simpleTransformation(batch);
+}
+```
+
+### 3. Parallel Processing
+
+```typescript
+async function parallelCSVProcessing(csvFiles: string[]) {
+  const csvParser = new CSVParserService();
+
+  // Process multiple CSV files in parallel
+  const promises = csvFiles.map(async (csvContent) => {
+    const records = await csvParser.parse(csvContent);
+    return transformRecords(records);
+  });
+
+  const results = await Promise.all(promises);
+  return results.flat();
+}
+```
+
+## CSV Generation (Writing)
+
+The CSV parser also supports converting JavaScript objects back to CSV format using the `stringify()` method.
+
+### CSVParserService.stringify()
+
+Convert array of records to CSV string.
+
+```typescript
+import { CSVParserService } from '@fluentcommerce/fc-connect-sdk';
+
+const csvParser = new CSVParserService();
+
+const records = [
+  { name: 'Alice', age: 30, city: 'NYC' },
+  { name: 'Bob', age: 25, city: 'LA' },
+  { name: 'Charlie', age: 35, city: 'Chicago' }
+];
+
+// Generate CSV with default options
+const csvString = csvParser.stringify(records, {
+  headers: true,        // Include header row
+  delimiter: ',',       // Field delimiter
+  quote: '"',          // Quote character
+  escape: '"'          // Escape character
+});
+
+console.log(csvString);
+// Output:
+// name,age,city
+// Alice,30,NYC
+// Bob,25,LA
+// Charlie,35,Chicago
+```
+
+### Stringify Options
+
+```typescript
+interface StringifyOptions {
+  headers?: boolean;        // Include header row (default: true)
+  delimiter?: string;       // Field delimiter (default: ',')
+  quote?: string;          // Quote character (default: '"')
+  escape?: string;         // Escape character (default: '"')
+}
+```
+
+### Different Delimiters
+
+```typescript
+// Tab-separated (TSV)
+const tsv = csvParser.stringify(records, {
+  delimiter: '\t',
+  headers: true
+});
+// Output: name\tage\tcity\nAlice\t30\tNYC...
+
+// Semicolon-separated (European format)
+const europeanCsv = csvParser.stringify(records, {
+  delimiter: ';',
+  headers: true
+});
+// Output: name;age;city\nAlice;30;NYC...
+
+// Pipe-separated
+const pipeCsv = csvParser.stringify(records, {
+  delimiter: '|',
+  headers: true
+});
+// Output: name|age|city\nAlice|30|NYC...
+```
+
+### Without Headers
+
+```typescript
+const csvNoHeaders = csvParser.stringify(records, {
+  headers: false  // Skip header row
+});
+
+console.log(csvNoHeaders);
+// Output:
+// Alice,30,NYC
+// Bob,25,LA
+// Charlie,35,Chicago
+```
+
+### Complete Round-Trip Example
+
+```typescript
+import { CSVParserService } from '@fluentcommerce/fc-connect-sdk';
+
+async function csvRoundTrip() {
+  const csvParser = new CSVParserService();
+
+  // Original CSV
+  const originalCsv = `sku,qty,location
+SKU001,100,WH-01
+SKU002,50,WH-02`;
+
+  // Parse
+  const records = await csvParser.parse(originalCsv);
+  console.log('Parsed:', records);
+
+  // Transform data (e.g., double quantities)
+  const transformed = records.map(r => ({
+    ...r,
+    qty: parseInt(r.qty) * 2
+  }));
+
+  // Convert back to CSV
+  const newCsv = csvParser.stringify(transformed, {
+    headers: true,
+    delimiter: ','
+  });
+
+  console.log('Generated CSV:');
+  console.log(newCsv);
+  // Output:
+  // sku,qty,location
+  // SKU001,200,WH-01
+  // SKU002,100,WH-02
+}
+```
+
+### Practical Use Case: Export to CSV File
+
+```typescript
+import { CSVParserService } from '@fluentcommerce/fc-connect-sdk';
+import * as fs from 'fs/promises';
+
+async function exportToCsv(data: any[], outputPath: string) {
+  const csvParser = new CSVParserService();
+
+  // Convert records to CSV
+  const csvContent = csvParser.stringify(data, {
+    headers: true,
+    delimiter: ','
+  });
+
+  // Write to file
+  await fs.writeFile(outputPath, csvContent, 'utf-8');
+
+  console.log(`✅ Exported ${data.length} records to ${outputPath}`);
+}
+
+// Usage
+const inventoryData = [
+  { sku: 'SKU001', qty: 100, location: 'WH-01' },
+  { sku: 'SKU002', qty: 50, location: 'WH-02' }
+];
+
+await exportToCsv(inventoryData, 'inventory-export.csv');
+```
+
+### Integration with S3
+
+```typescript
+import { CSVParserService, S3DataSource, createConsoleLogger, toStructuredLogger } from '@fluentcommerce/fc-connect-sdk';
+
+async function exportToS3(data: any[], s3Key: string) {
+  const logger = toStructuredLogger(createConsoleLogger(), { service: 'CSVExport' });
+  const csvParser = new CSVParserService();
+
+  // Convert to CSV
+  const csvContent = csvParser.stringify(data, { headers: true });
+
+  // Setup S3
+  const s3 = new S3DataSource(
+    {
+      type: 'S3_CSV',
+      connectionId: 's3-csv-export',
+      name: 'S3 CSV Export',
+      s3Config: {
+        bucket: process.env.S3_BUCKET!,
+        accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+        region: process.env.AWS_REGION!
+      }
+    },
+    logger
+  );
+
+  // Upload to S3
+  await s3.uploadFile(s3Key, Buffer.from(csvContent), {
+    contentType: 'text/csv'
+  });
+
+  console.log(`✅ Exported to s3://${process.env.S3_BUCKET}/${s3Key}`);
+}
+
+// Usage
+await exportToS3(inventoryData, 'exports/inventory-2025-10-30.csv');
+```
+
+---
+
+## Key Takeaways
+
+- 🎯 CSV Parser handles tabular data with headers
+- 🎯 Use `parse()` for small files, `parseStreaming()` for large files
+- 🎯 Use `stringify()` to convert objects back to CSV format
+- 🎯 Configure delimiter, quotes, and column options for different formats
+- 🎯 Validate structure with `validate()` before parsing
+- 🎯 Combine with `UniversalMapper` for field transformations
+- 🎯 Stream in batches for memory-efficient processing
+- 🎯 Handle errors gracefully with validation and try-catch
+
+## Practice Exercise
+
+**Challenge:** Parse this CSV and transform it for Fluent Commerce:
+
+```csv
+product_id,available_qty,warehouse,last_updated
+PROD-001,150,DC-EAST,2025-01-15T10:30:00Z
+PROD-002,75,DC-WEST,2025-01-15T11:00:00Z
+PROD-003,200,DC-CENTRAL,2025-01-15T11:30:00Z
+```
+
+**Requirements:**
+1. Parse the CSV
+2. Transform to Fluent format: `{ ref, qty, locationRef, updatedOn }`
+3. Validate that qty is a positive number
+4. Format the date properly
+
+**Solution:** See [CSV Examples](../examples/csv-parser-examples.ts)
+
+## Next Steps
+
+Continue to [Module 3: JSON Parser →](./02-core-guides-parsers-03-json-parser.md) to learn JSON and JSONL parsing.
+
+---
+
+**Module 2 Complete!** ✅