@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/03-PATTERN-GUIDES/file-operations/modules/file-operations-02-quick-start.md

@@ -1,484 +1,484 @@
-# Module 2: Quick Start
-
-**Level:** Beginner
-**Estimated Time:** 20 minutes
-
-## Overview
-
-This module provides working examples to get you started with file operations quickly. You'll see complete, runnable code for both S3 and SFTP operations.
-
-## Learning Objectives
-
-By the end of this module, you will:
-
-- ✅ Be able to set up S3DataSource and SftpDataSource
-- ✅ Perform basic file operations (list, read, write, move, delete)
-- ✅ Implement a simple Read-Process-Archive workflow
-- ✅ Understand error handling basics
-
-## Quick Start: S3 Operations
-
-### Step 1: Setup S3DataSource
-
-```typescript
-import {
-  S3DataSource,
-  createConsoleLogger,
-  toStructuredLogger
-} from '@fluentcommerce/fc-connect-sdk';
-
-const logger = createConsoleLogger();
-
-const s3 = new S3DataSource(
-  {
-    type: 'S3_CSV',
-    connectionId: 's3-quickstart',
-    name: 'S3 Quickstart',
-    s3Config: {
-      region: process.env.AWS_REGION || 'us-east-1',
-      bucket: process.env.S3_BUCKET || 'my-bucket',
-      accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
-      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
-    },
-  },
-  logger
-);
-```
-
-### Step 2: List Files
-
-```typescript
-// List all files
-const allFiles = await s3.listFiles();
-console.log(`Found ${allFiles.length} files`);
-
-// List with prefix filter
-const csvFiles = await s3.listFiles({
-  prefix: 'incoming/',
-  pattern: '*.csv',
-});
-console.log(`Found ${csvFiles.length} CSV files in incoming/`);
-
-// Examine file metadata
-csvFiles.forEach(file => {
-  console.log(`File: ${file.name}, Size: ${file.size} bytes`);
-});
-```
-
-### Step 3: Read a File
-
-```typescript
-try {
-  const content = await s3.downloadFile('incoming/orders.csv');
-  console.log(`Downloaded ${content.length} bytes`);
-
-  // Process the content
-  const lines = content.split('\n');
-  console.log(`File has ${lines.length} lines`);
-} catch (error) {
-  console.error('Failed to download file:', error);
-}
-```
-
-### Step 4: Write a File
-
-```typescript
-const data = {
-  timestamp: new Date().toISOString(),
-  records: 150,
-  status: 'processed',
-};
-
-const jsonContent = JSON.stringify(data, null, 2);
-
-await s3.uploadFile('output/results.json', jsonContent);
-console.log('File uploaded successfully');
-```
-
-### Step 5: Archive Processed Files
-
-```typescript
-// Move file to archive
-await s3.moveFile('incoming/orders.csv', 'archive/orders.csv');
-console.log('File archived');
-
-// Or with date-based path
-const today = new Date().toISOString().split('T')[0];
-await s3.moveFile('incoming/inventory.csv', `archive/${today}/inventory.csv`);
-console.log(`File archived to ${today} folder`);
-```
-
-### Complete S3 Example
-
-```typescript
-import {
-  S3DataSource,
-  createConsoleLogger,
-  toStructuredLogger
-} from '@fluentcommerce/fc-connect-sdk';
-
-async function processS3Files() {
-  const logger = createConsoleLogger();
-
-  const s3 = new S3DataSource(
-    {
-      type: 'S3_CSV',
-      connectionId: 's3-processor',
-      name: 'S3 File Processor',
-      s3Config: {
-        region: process.env.AWS_REGION!,
-        bucket: process.env.S3_BUCKET!,
-        accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
-        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
-      },
-    },
-    logger
-  );
-
-  try {
-    // List CSV files in incoming folder
-    const files = await s3.listFiles({
-      prefix: 'incoming/',
-      pattern: '*.csv',
-    });
-
-    logger.info(`Found ${files.length} files to process`);
-
-    for (const file of files) {
-      try {
-        // Read file
-        const content = await s3.downloadFile(file.name);
-        logger.info(`Processing ${file.name}: ${content.length} bytes`);
-
-        // Process data (your business logic)
-        const result = await processData(content);
-
-        // Write result
-        const outputKey = file.name.replace('incoming/', 'output/').replace('.csv', '.json');
-        await s3.uploadFile(outputKey, JSON.stringify(result));
-
-        // Archive source file
-        const archiveKey = file.name.replace('incoming/', 'archive/');
-        await s3.moveFile(file.name, archiveKey);
-
-        logger.info(`Successfully processed ${file.name}`);
-      } catch (error) {
-        logger.error(`Failed to process ${file.name}:`, error);
-        // Continue with next file
-      }
-    }
-
-    logger.info('Processing complete');
-  } catch (error) {
-    logger.error('S3 processing failed:', error);
-    throw error;
-  }
-}
-
-async function processData(csvContent: string): Promise<any> {
-  // Your transformation logic here
-  const lines = csvContent.split('\n');
-  return {
-    recordCount: lines.length - 1, // Exclude header
-    processedAt: new Date().toISOString(),
-  };
-}
-
-// Run the processor
-processS3Files().catch(console.error);
-```
-
-## Quick Start: SFTP Operations
-
-### Step 1: Setup SftpDataSource
-
-```typescript
-import {
-  SftpDataSource,
-  createConsoleLogger,
-  toStructuredLogger
-} from '@fluentcommerce/fc-connect-sdk';
-
-const logger = createConsoleLogger();
-
-const sftp = new SftpDataSource(
-  {
-    type: 'SFTP_CSV',
-    connectionId: 'sftp-quickstart',
-    name: 'SFTP Quickstart',
-    settings: {
-      host: process.env.SFTP_HOST!,
-      port: parseInt(process.env.SFTP_PORT || '22'),
-      username: process.env.SFTP_USERNAME!,
-      password: process.env.SFTP_PASSWORD!,
-    },
-  },
-  logger
-);
-
-// IMPORTANT: Always dispose when done!
-```
-
-### Step 2: List Files
-
-```typescript
-try {
-  const files = await sftp.listFiles();
-  console.log(`Found ${files.length} files matching pattern`);
-
-  files.forEach(file => {
-    console.log(`File: ${file.name}, Path: ${file.path}`);
-  });
-} finally {
-  await sftp.dispose(); // Always clean up!
-}
-```
-
-### Step 3: Read a File
-
-```typescript
-try {
-  const content = await sftp.downloadFile('/data/incoming/orders.csv');
-  console.log(`Downloaded ${content.length} bytes`);
-
-  // Process the content
-  const lines = content.split('\n');
-  console.log(`File has ${lines.length} lines`);
-} catch (error) {
-  console.error('Failed to download file:', error);
-} finally {
-  await sftp.dispose();
-}
-```
-
-### Step 4: Write a File
-
-```typescript
-try {
-  const data = {
-    timestamp: new Date().toISOString(),
-    status: 'completed',
-  };
-
-  await sftp.uploadFile('/data/outgoing/results.json', JSON.stringify(data));
-  console.log('File uploaded successfully');
-} finally {
-  await sftp.dispose();
-}
-```
-
-**Options parameter** (optional):
-```typescript
-await sftp.uploadFile('/data/outgoing/results.json', JSON.stringify(data), {
-  overwrite: true,           // Overwrite existing file (default: false)
-  createDirectories: true,   // Create parent directories (default: false)
-  permissions: '0644',       // File permissions (default: server default)
-  encoding: 'utf8'          // Content encoding (default: 'utf8')
-});
-```
-
-### Step 5: Archive Processed Files
-
-```typescript
-try {
-  // Move file to archive
-  await sftp.moveFile('/data/incoming/orders.csv', '/archive/orders.csv');
-  console.log('File archived');
-
-  // Or with date-based path
-  const today = new Date().toISOString().split('T')[0];
-  await sftp.moveFile('/data/incoming/inventory.csv', `/archive/${today}/inventory.csv`);
-  console.log(`File archived to ${today} folder`);
-} finally {
-  await sftp.dispose();
-}
-```
-
-### Complete SFTP Example
-
-```typescript
-import {
-  SftpDataSource,
-  createConsoleLogger,
-  toStructuredLogger
-} from '@fluentcommerce/fc-connect-sdk';
-
-async function processSftpFiles() {
-  const logger = createConsoleLogger();
-
-  const sftp = new SftpDataSource(
-    {
-      type: 'SFTP_CSV',
-      connectionId: 'sftp-processor',
-      name: 'SFTP File Processor',
-      settings: {
-        host: process.env.SFTP_HOST!,
-        port: parseInt(process.env.SFTP_PORT || '22'),
-        username: process.env.SFTP_USERNAME!,
-        password: process.env.SFTP_PASSWORD!,
-      },
-    },
-    logger
-  );
-
-  try {
-    // List CSV files matching pattern
-    const files = await sftp.listFiles();
-    logger.info(`Found ${files.length} files to process`);
-
-    for (const file of files) {
-      try {
-        // Read file
-        const content = await sftp.downloadFile(file.path);
-        logger.info(`Processing ${file.name}: ${content.length} bytes`);
-
-        // Process data (your business logic)
-        const result = await processData(content);
-
-        // Write result to outgoing folder
-        const outputPath = `/data/outgoing/${file.name.replace('.csv', '.json')}`;
-        await sftp.uploadFile(outputPath, JSON.stringify(result));
-
-        // Archive source file with date
-        const today = new Date().toISOString().split('T')[0];
-        const archivePath = `/archive/${today}/${file.name}`;
-        await sftp.moveFile(file.path, archivePath);
-
-        logger.info(`Successfully processed ${file.name}`);
-      } catch (error) {
-        logger.error(`Failed to process ${file.name}:`, error);
-        // Continue with next file
-      }
-    }
-
-    logger.info('Processing complete');
-  } catch (error) {
-    logger.error('SFTP processing failed:', error);
-    throw error;
-  } finally {
-    // Always dispose to clean up connection
-    await sftp.dispose();
-  }
-}
-
-async function processData(csvContent: string): Promise<any> {
-  // Your transformation logic here
-  const lines = csvContent.split('\n');
-  return {
-    recordCount: lines.length - 1, // Exclude header
-    processedAt: new Date().toISOString(),
-  };
-}
-
-// Run the processor
-processSftpFiles().catch(console.error);
-```
-
-## Environment Configuration
-
-Create a `.env` file with your credentials:
-
-```bash
-# S3 Configuration
-AWS_ACCESS_KEY_ID=your-access-key
-AWS_SECRET_ACCESS_KEY=your-secret-key
-AWS_REGION=us-east-1
-S3_BUCKET=my-bucket
-
-# SFTP Configuration
-SFTP_HOST=sftp.example.com
-SFTP_PORT=22
-SFTP_USERNAME=your-username
-SFTP_PASSWORD=your-password
-```
-
-## Error Handling Best Practices
-
-### S3 Error Handling
-
-```typescript
-try {
-  const content = await s3.downloadFile('file.csv');
-} catch (error: any) {
-  if (error.name === 'NoSuchKey') {
-    console.error('File not found');
-  } else if (error.name === 'AccessDenied') {
-    console.error('Permission denied - check IAM policy');
-  } else {
-    console.error('S3 error:', error.message);
-  }
-}
-```
-
-### SFTP Error Handling
-
-```typescript
-try {
-  const content = await sftp.downloadFile('/data/file.csv');
-} catch (error: any) {
-  if (error.message.includes('No such file')) {
-    console.error('File not found');
-  } else if (error.message.includes('Permission denied')) {
-    console.error('Permission denied - check SFTP permissions');
-  } else if (error.message.includes('Connection')) {
-    console.error('Connection error - check host/port/credentials');
-  } else {
-    console.error('SFTP error:', error.message);
-  }
-} finally {
-  await sftp.dispose(); // Always dispose!
-}
-```
-
-## Key Differences: S3 vs SFTP
-
-| Aspect                 | S3                                  | SFTP                               |
-| ---------------------- | ----------------------------------- | ---------------------------------- |
-| **Connection**         | Stateless (per-request)             | Stateful (persistent)              |
-| **Cleanup**            | Not needed                          | **Required** (`dispose()`)         |
-| **Path Format**        | No leading slash: `folder/file.csv` | Absolute paths: `/folder/file.csv` |
-| **Move Operation**     | Copy + Delete (2 operations)        | Native (1 operation)               |
-| **Directory Creation** | Automatic                           | Optional flag (`createDirs`)       |
-| **File Pattern**       | In `listFiles()` call               | In constructor config              |
-
-## Key Takeaways
-
-- 🎯 S3 and SFTP use the same method names but different setup patterns
-- 🎯 Always use `try/finally` with SFTP to ensure `dispose()` is called
-- 🎯 S3 paths don't have leading slashes, SFTP paths do
-- 🎯 The Read-Process-Archive pattern is common for data integration
-- 🎯 Error handling should account for "file not found" and "permission denied" scenarios
-
-## Practice Exercise
-
-Create a script that:
-
-1. Lists files from your chosen storage system
-2. Reads each file
-3. Counts the number of lines
-4. Writes a summary JSON file
-5. Archives the processed files
-
-<details>
-<summary>Solution Hint</summary>
-
-Use the complete examples above as templates. The main loop should:
-
-- `listFiles()` to get file list
-- `downloadFile()` to read each file
-- `content.split('\n').length` to count lines
-- `uploadFile()` to write summary
-- `moveFile()` to archive
-</details>
-
-## Next Steps
-
-Continue to [Module 3: S3 Operations](./file-operations-03-s3-operations.md) for deep dive into S3-specific features.
-
----
-
-**Related Resources:**
-
-- [Quick Reference](../../../02-CORE-GUIDES/advanced-services/advanced-services-quick-reference.md) - All operations cheat sheet
-- [Examples Directory](../examples/) - More complete examples
-- [Module 1: Foundations](./file-operations-01-foundations.md) - Core concepts
+# Module 2: Quick Start
+
+**Level:** Beginner
+**Estimated Time:** 20 minutes
+
+## Overview
+
+This module provides working examples to get you started with file operations quickly. You'll see complete, runnable code for both S3 and SFTP operations.
+
+## Learning Objectives
+
+By the end of this module, you will:
+
+- ✅ Be able to set up S3DataSource and SftpDataSource
+- ✅ Perform basic file operations (list, read, write, move, delete)
+- ✅ Implement a simple Read-Process-Archive workflow
+- ✅ Understand error handling basics
+
+## Quick Start: S3 Operations
+
+### Step 1: Setup S3DataSource
+
+```typescript
+import {
+  S3DataSource,
+  createConsoleLogger,
+  toStructuredLogger
+} from '@fluentcommerce/fc-connect-sdk';
+
+const logger = createConsoleLogger();
+
+const s3 = new S3DataSource(
+  {
+    type: 'S3_CSV',
+    connectionId: 's3-quickstart',
+    name: 'S3 Quickstart',
+    s3Config: {
+      region: process.env.AWS_REGION || 'us-east-1',
+      bucket: process.env.S3_BUCKET || 'my-bucket',
+      accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+    },
+  },
+  logger
+);
+```
+
+### Step 2: List Files
+
+```typescript
+// List all files
+const allFiles = await s3.listFiles();
+console.log(`Found ${allFiles.length} files`);
+
+// List with prefix filter
+const csvFiles = await s3.listFiles({
+  prefix: 'incoming/',
+  pattern: '*.csv',
+});
+console.log(`Found ${csvFiles.length} CSV files in incoming/`);
+
+// Examine file metadata
+csvFiles.forEach(file => {
+  console.log(`File: ${file.name}, Size: ${file.size} bytes`);
+});
+```
+
+### Step 3: Read a File
+
+```typescript
+try {
+  const content = await s3.downloadFile('incoming/orders.csv');
+  console.log(`Downloaded ${content.length} bytes`);
+
+  // Process the content
+  const lines = content.split('\n');
+  console.log(`File has ${lines.length} lines`);
+} catch (error) {
+  console.error('Failed to download file:', error);
+}
+```
+
+### Step 4: Write a File
+
+```typescript
+const data = {
+  timestamp: new Date().toISOString(),
+  records: 150,
+  status: 'processed',
+};
+
+const jsonContent = JSON.stringify(data, null, 2);
+
+await s3.uploadFile('output/results.json', jsonContent);
+console.log('File uploaded successfully');
+```
+
+### Step 5: Archive Processed Files
+
+```typescript
+// Move file to archive
+await s3.moveFile('incoming/orders.csv', 'archive/orders.csv');
+console.log('File archived');
+
+// Or with date-based path
+const today = new Date().toISOString().split('T')[0];
+await s3.moveFile('incoming/inventory.csv', `archive/${today}/inventory.csv`);
+console.log(`File archived to ${today} folder`);
+```
+
+### Complete S3 Example
+
+```typescript
+import {
+  S3DataSource,
+  createConsoleLogger,
+  toStructuredLogger
+} from '@fluentcommerce/fc-connect-sdk';
+
+async function processS3Files() {
+  const logger = createConsoleLogger();
+
+  const s3 = new S3DataSource(
+    {
+      type: 'S3_CSV',
+      connectionId: 's3-processor',
+      name: 'S3 File Processor',
+      s3Config: {
+        region: process.env.AWS_REGION!,
+        bucket: process.env.S3_BUCKET!,
+        accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+      },
+    },
+    logger
+  );
+
+  try {
+    // List CSV files in incoming folder
+    const files = await s3.listFiles({
+      prefix: 'incoming/',
+      pattern: '*.csv',
+    });
+
+    logger.info(`Found ${files.length} files to process`);
+
+    for (const file of files) {
+      try {
+        // Read file
+        const content = await s3.downloadFile(file.name);
+        logger.info(`Processing ${file.name}: ${content.length} bytes`);
+
+        // Process data (your business logic)
+        const result = await processData(content);
+
+        // Write result
+        const outputKey = file.name.replace('incoming/', 'output/').replace('.csv', '.json');
+        await s3.uploadFile(outputKey, JSON.stringify(result));
+
+        // Archive source file
+        const archiveKey = file.name.replace('incoming/', 'archive/');
+        await s3.moveFile(file.name, archiveKey);
+
+        logger.info(`Successfully processed ${file.name}`);
+      } catch (error) {
+        logger.error(`Failed to process ${file.name}:`, error);
+        // Continue with next file
+      }
+    }
+
+    logger.info('Processing complete');
+  } catch (error) {
+    logger.error('S3 processing failed:', error);
+    throw error;
+  }
+}
+
+async function processData(csvContent: string): Promise<any> {
+  // Your transformation logic here
+  const lines = csvContent.split('\n');
+  return {
+    recordCount: lines.length - 1, // Exclude header
+    processedAt: new Date().toISOString(),
+  };
+}
+
+// Run the processor
+processS3Files().catch(console.error);
+```
+
+## Quick Start: SFTP Operations
+
+### Step 1: Setup SftpDataSource
+
+```typescript
+import {
+  SftpDataSource,
+  createConsoleLogger,
+  toStructuredLogger
+} from '@fluentcommerce/fc-connect-sdk';
+
+const logger = createConsoleLogger();
+
+const sftp = new SftpDataSource(
+  {
+    type: 'SFTP_CSV',
+    connectionId: 'sftp-quickstart',
+    name: 'SFTP Quickstart',
+    settings: {
+      host: process.env.SFTP_HOST!,
+      port: parseInt(process.env.SFTP_PORT || '22'),
+      username: process.env.SFTP_USERNAME!,
+      password: process.env.SFTP_PASSWORD!,
+    },
+  },
+  logger
+);
+
+// IMPORTANT: Always dispose when done!
+```
+
+### Step 2: List Files
+
+```typescript
+try {
+  const files = await sftp.listFiles();
+  console.log(`Found ${files.length} files matching pattern`);
+
+  files.forEach(file => {
+    console.log(`File: ${file.name}, Path: ${file.path}`);
+  });
+} finally {
+  await sftp.dispose(); // Always clean up!
+}
+```
+
+### Step 3: Read a File
+
+```typescript
+try {
+  const content = await sftp.downloadFile('/data/incoming/orders.csv');
+  console.log(`Downloaded ${content.length} bytes`);
+
+  // Process the content
+  const lines = content.split('\n');
+  console.log(`File has ${lines.length} lines`);
+} catch (error) {
+  console.error('Failed to download file:', error);
+} finally {
+  await sftp.dispose();
+}
+```
+
+### Step 4: Write a File
+
+```typescript
+try {
+  const data = {
+    timestamp: new Date().toISOString(),
+    status: 'completed',
+  };
+
+  await sftp.uploadFile('/data/outgoing/results.json', JSON.stringify(data));
+  console.log('File uploaded successfully');
+} finally {
+  await sftp.dispose();
+}
+```
+
+**Options parameter** (optional):
+```typescript
+await sftp.uploadFile('/data/outgoing/results.json', JSON.stringify(data), {
+  overwrite: true,           // Overwrite existing file (default: false)
+  createDirectories: true,   // Create parent directories (default: false)
+  permissions: '0644',       // File permissions (default: server default)
+  encoding: 'utf8'          // Content encoding (default: 'utf8')
+});
+```
+
+### Step 5: Archive Processed Files
+
+```typescript
+try {
+  // Move file to archive
+  await sftp.moveFile('/data/incoming/orders.csv', '/archive/orders.csv');
+  console.log('File archived');
+
+  // Or with date-based path
+  const today = new Date().toISOString().split('T')[0];
+  await sftp.moveFile('/data/incoming/inventory.csv', `/archive/${today}/inventory.csv`);
+  console.log(`File archived to ${today} folder`);
+} finally {
+  await sftp.dispose();
+}
+```
+
+### Complete SFTP Example
+
+```typescript
+import {
+  SftpDataSource,
+  createConsoleLogger,
+  toStructuredLogger
+} from '@fluentcommerce/fc-connect-sdk';
+
+async function processSftpFiles() {
+  const logger = createConsoleLogger();
+
+  const sftp = new SftpDataSource(
+    {
+      type: 'SFTP_CSV',
+      connectionId: 'sftp-processor',
+      name: 'SFTP File Processor',
+      settings: {
+        host: process.env.SFTP_HOST!,
+        port: parseInt(process.env.SFTP_PORT || '22'),
+        username: process.env.SFTP_USERNAME!,
+        password: process.env.SFTP_PASSWORD!,
+      },
+    },
+    logger
+  );
+
+  try {
+    // List CSV files matching pattern
+    const files = await sftp.listFiles();
+    logger.info(`Found ${files.length} files to process`);
+
+    for (const file of files) {
+      try {
+        // Read file
+        const content = await sftp.downloadFile(file.path);
+        logger.info(`Processing ${file.name}: ${content.length} bytes`);
+
+        // Process data (your business logic)
+        const result = await processData(content);
+
+        // Write result to outgoing folder
+        const outputPath = `/data/outgoing/${file.name.replace('.csv', '.json')}`;
+        await sftp.uploadFile(outputPath, JSON.stringify(result));
+
+        // Archive source file with date
+        const today = new Date().toISOString().split('T')[0];
+        const archivePath = `/archive/${today}/${file.name}`;
+        await sftp.moveFile(file.path, archivePath);
+
+        logger.info(`Successfully processed ${file.name}`);
+      } catch (error) {
+        logger.error(`Failed to process ${file.name}:`, error);
+        // Continue with next file
+      }
+    }
+
+    logger.info('Processing complete');
+  } catch (error) {
+    logger.error('SFTP processing failed:', error);
+    throw error;
+  } finally {
+    // Always dispose to clean up connection
+    await sftp.dispose();
+  }
+}
+
+async function processData(csvContent: string): Promise<any> {
+  // Your transformation logic here
+  const lines = csvContent.split('\n');
+  return {
+    recordCount: lines.length - 1, // Exclude header
+    processedAt: new Date().toISOString(),
+  };
+}
+
+// Run the processor
+processSftpFiles().catch(console.error);
+```
+
+## Environment Configuration
+
+Create a `.env` file with your credentials:
+
+```bash
+# S3 Configuration
+AWS_ACCESS_KEY_ID=your-access-key
+AWS_SECRET_ACCESS_KEY=your-secret-key
+AWS_REGION=us-east-1
+S3_BUCKET=my-bucket
+
+# SFTP Configuration
+SFTP_HOST=sftp.example.com
+SFTP_PORT=22
+SFTP_USERNAME=your-username
+SFTP_PASSWORD=your-password
+```
+
+## Error Handling Best Practices
+
+### S3 Error Handling
+
+```typescript
+try {
+  const content = await s3.downloadFile('file.csv');
+} catch (error: any) {
+  if (error.name === 'NoSuchKey') {
+    console.error('File not found');
+  } else if (error.name === 'AccessDenied') {
+    console.error('Permission denied - check IAM policy');
+  } else {
+    console.error('S3 error:', error.message);
+  }
+}
+```
+
+### SFTP Error Handling
+
+```typescript
+try {
+  const content = await sftp.downloadFile('/data/file.csv');
+} catch (error: any) {
+  if (error.message.includes('No such file')) {
+    console.error('File not found');
+  } else if (error.message.includes('Permission denied')) {
+    console.error('Permission denied - check SFTP permissions');
+  } else if (error.message.includes('Connection')) {
+    console.error('Connection error - check host/port/credentials');
+  } else {
+    console.error('SFTP error:', error.message);
+  }
+} finally {
+  await sftp.dispose(); // Always dispose!
+}
+```
+
+## Key Differences: S3 vs SFTP
+
+| Aspect                 | S3                                  | SFTP                               |
+| ---------------------- | ----------------------------------- | ---------------------------------- |
+| **Connection**         | Stateless (per-request)             | Stateful (persistent)              |
+| **Cleanup**            | Not needed                          | **Required** (`dispose()`)         |
+| **Path Format**        | No leading slash: `folder/file.csv` | Absolute paths: `/folder/file.csv` |
+| **Move Operation**     | Copy + Delete (2 operations)        | Native (1 operation)               |
+| **Directory Creation** | Automatic                           | Optional flag (`createDirs`)       |
+| **File Pattern**       | In `listFiles()` call               | In constructor config              |
+
+## Key Takeaways
+
+- 🎯 S3 and SFTP use the same method names but different setup patterns
+- 🎯 Always use `try/finally` with SFTP to ensure `dispose()` is called
+- 🎯 S3 paths don't have leading slashes, SFTP paths do
+- 🎯 The Read-Process-Archive pattern is common for data integration
+- 🎯 Error handling should account for "file not found" and "permission denied" scenarios
+
+## Practice Exercise
+
+Create a script that:
+
+1. Lists files from your chosen storage system
+2. Reads each file
+3. Counts the number of lines
+4. Writes a summary JSON file
+5. Archives the processed files
+
+<details>
+<summary>Solution Hint</summary>
+
+Use the complete examples above as templates. The main loop should:
+
+- `listFiles()` to get file list
+- `downloadFile()` to read each file
+- `content.split('\n').length` to count lines
+- `uploadFile()` to write summary
+- `moveFile()` to archive
+</details>
+
+## Next Steps
+
+Continue to [Module 3: S3 Operations](./file-operations-03-s3-operations.md) for deep dive into S3-specific features.
+
+---
+
+**Related Resources:**
+
+- [Quick Reference](../../../02-CORE-GUIDES/advanced-services/advanced-services-quick-reference.md) - All operations cheat sheet
+- [Examples Directory](../examples/) - More complete examples
+- [Module 1: Foundations](./file-operations-01-foundations.md) - Core concepts