@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

package/docs/03-PATTERN-GUIDES/file-operations/modules/file-operations-03-s3-operations.md

@@ -1,507 +1,507 @@
-# Module 3: S3 Operations
-
-**Level:** Intermediate
-**Estimated Time:** 25 minutes
-
-## Overview
-
-Complete guide to S3-specific file operations, including presigned URLs, batch operations, and S3-specific features.
-
-## Learning Objectives
-
-By the end of this module, you will:
-- ✅ Master all S3 file operations (list, read, write, move, copy, delete)
-- ✅ Understand S3-specific concepts (buckets, keys, regions)
-- ✅ Learn presigned URL generation for temporary access
-- ✅ Implement efficient batch operations
-- ✅ Handle S3-specific errors
-
-## S3 Concepts
-
-### Buckets and Keys
-
-```typescript
-// Bucket: Top-level container
-const bucketName = 'my-data-bucket';
-
-// Key: Object path within bucket (no leading slash!)
-const key = 'incoming/orders/2025-01-15.csv';
-//           └─ prefix ─┘ └──── file ────┘
-
-// Full S3 URL: s3://my-data-bucket/incoming/orders/2025-01-15.csv
-```
-
-### Regions
-
-```typescript
-const s3 = new S3DataSource({
-  type: 'S3_CSV',
-  connectionId: 's3-operations',
-  name: 'S3 Operations',
-  s3Config: {
-    region: 'us-east-1',  // Must match bucket region
-    bucket: 'my-bucket',
-    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
-    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!
-  }
-}, logger);
-```
-
-## All S3 Operations
-
-### List Files
-
-```typescript
-// List all files
-const allFiles = await s3.listFiles();
-
-// List with prefix
-const incomingFiles = await s3.listFiles({ prefix: 'incoming/' });
-
-// List with maxKeys for pagination
-const csvFiles = await s3.listFiles({ prefix: 'incoming/', maxKeys: 100 });
-
-// List with delimiter for folder structure
-const folders = await s3.listFiles({ prefix: 'incoming/', delimiter: '/' });
-
-// Examine metadata
-files.forEach(file => {
-  console.log(`Name: ${file.name}`);
-  console.log(`Path: ${file.path}`);
-  console.log(`Size: ${file.size} bytes`);
-  console.log(`Source: ${file.source}`); // 'S3'
-  if (file.lastModified) {
-    console.log(`Modified: ${file.lastModified}`); // ISO string
-  }
-});
-```
-
-### Download Files
-
-```typescript
-// Download as string
-const csvContent = await s3.downloadFile('data/orders.csv');
-
-// Handle large files
-try {
-  const content = await s3.downloadFile('large-file.csv');
-  console.log(`Downloaded ${content.length} bytes`);
-} catch (error: any) {
-  if (error.name === 'NoSuchKey') {
-    console.error('File does not exist');
-  } else {
-    console.error('Download failed:', error);
-  }
-}
-```
-
-### Upload Files
-
-```typescript
-import { Buffer } from 'node:buffer'; // Required for Deno/Versori runtime
-
-// Upload string content
-const data = JSON.stringify({ status: 'processed' });
-await s3.uploadFile('output/results.json', data);
-
-// Upload buffer
-const buffer = Buffer.from('Hello, S3!');
-await s3.uploadFile('messages/greeting.txt', buffer);
-
-// Upload with error handling
-try {
-  await s3.uploadFile('output/data.csv', csvContent);
-  console.log('Upload successful');
-} catch (error: any) {
-  if (error.name === 'AccessDenied') {
-    console.error('No write permission');
-  } else {
-    console.error('Upload failed:', error);
-  }
-}
-```
-
-### Move Files
-
-```typescript
-// Move (copy + delete source - DEFAULT BEHAVIOR)
-await s3.moveFile('incoming/file.csv', 'processed/file.csv');
-// Source file is DELETED by default
-
-// Move without deleting source
-await s3.moveFile('incoming/file.csv', 'processed/file.csv', false);
-// Source file is preserved
-
-// Move to date-based archive
-const today = new Date().toISOString().split('T')[0];
-await s3.moveFile(
-  'incoming/orders.csv',
-  `archive/${today}/orders.csv`
-);
-
-// Move with error handling
-try {
-  await s3.moveFile(sourceKey, destKey);
-  console.log('File moved successfully');
-} catch (error: any) {
-  if (error.name === 'NoSuchKey') {
-    console.error('Source file not found');
-  } else {
-    console.error('Move failed:', error);
-  }
-}
-```
-
-### Copy Files
-
-```typescript
-// Copy to backup
-await s3.copyFile('important/data.csv', 'backup/data.csv');
-
-// Copy with metadata
-await s3.copyFile('source/file.txt', 'dest/file.txt', {
-  metadata: { processedBy: 'sdk' }
-});
-
-// Copy from different bucket
-await s3.copyFile('source/file.txt', 'dest/file.txt', {
-  sourceBucket: 'other-bucket'
-});
-```
-
-### Delete Files
-
-```typescript
-// Delete single file
-await s3.deleteFile('temp/old-file.csv');
-
-// Delete with confirmation
-const fileToDelete = 'archive/old/data.csv';
-const exists = await s3.fileExists(fileToDelete);
-if (exists) {
-  await s3.deleteFile(fileToDelete);
-  console.log('File deleted');
-}
-```
-
-### Check File Existence
-
-```typescript
-// Check if file exists
-const exists = await s3.fileExists('incoming/orders.csv');
-console.log(`File exists: ${exists}`);
-
-// Conditional processing
-if (await s3.fileExists('config/settings.json')) {
-  const config = await s3.downloadFile('config/settings.json');
-  // Use config
-}
-```
-
-## Batch Operations
-
-### Process Multiple Files
-
-```typescript
-const files = await s3.listFiles({ prefix: 'incoming/', maxKeys: 1000 });
-
-for (const file of files) {
-  try {
-    const content = await s3.downloadFile(file.name);
-    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
-    const archiveKey = file.name.replace('incoming/', 'archive/');
-    await s3.moveFile(file.name, archiveKey);
-
-    console.log(`Processed ${file.name}`);
-
-  } catch (error) {
-    console.error(`Failed to process ${file.name}:`, error);
-    // Continue with next file
-  }
-}
-```
-
-### Parallel Processing
-
-```typescript
-const files = await s3.listFiles({ prefix: 'incoming/' });
-
-// Process files in parallel (be mindful of rate limits)
-const results = await Promise.allSettled(
-  files.map(async (file) => {
-    const content = await s3.downloadFile(file.name);
-    const result = await processData(content);
-    await s3.uploadFile(
-      file.name.replace('incoming/', 'output/'),
-      JSON.stringify(result)
-    );
-    return file.name;
-  })
-);
-
-// Check results
-results.forEach((result, index) => {
-  if (result.status === 'fulfilled') {
-    console.log(`Success: ${result.value}`);
-  } else {
-    console.error(`Failed: ${files[index].name}:`, result.reason);
-  }
-});
-```
-
-## Presigned URLs
-
-Use the `S3PresignService` for temporary access:
-
-```typescript
-import { S3PresignService } from '@fluentcommerce/fc-connect-sdk';
-
-const presignService = new S3PresignService(
-  s3Config,
-  bucketName,
-  logger
-);
-
-// Generate download URL (valid for 1 hour)
-const downloadUrl = await presignService.generatePresignedDownloadUrl(
-  'reports/monthly-report.pdf',
-  3600  // 1 hour in seconds
-);
-
-console.log('Download here:', downloadUrl);
-// https://my-bucket.s3.amazonaws.com/reports/monthly-report.pdf?X-Amz-...
-
-// Generate upload URL
-const uploadUrl = await presignService.generatePresignedUploadUrl(
-  'incoming/upload.csv',
-  3600
-);
-
-console.log('Upload here:', uploadUrl);
-```
-
-## S3-Specific Patterns
-
-### Date-Based Organization
-
-```typescript
-function getDateBasedKey(filename: string, prefix: string): string {
-  const now = new Date();
-  const year = now.getFullYear();
-  const month = String(now.getMonth() + 1).padStart(2, '0');
-  const day = String(now.getDate()).padStart(2, '0');
-
-  return `${prefix}/${year}/${month}/${day}/${filename}`;
-}
-
-// Archive with date structure
-await s3.moveFile(
-  'incoming/orders.csv',
-  getDateBasedKey('orders.csv', 'archive')
-);
-// Result: archive/2025/01/15/orders.csv
-```
-
-### Multi-Prefix Processing
-
-```typescript
-const prefixes = ['orders', 'inventory', 'products'];
-
-for (const prefix of prefixes) {
-  const files = await s3.listFiles({ prefix: `incoming/${prefix}/` });
-
-  for (const file of files) {
-    const content = await s3.downloadFile(file.name);
-    await processByType(prefix, content);
-
-    await s3.moveFile(
-      file.name,
-      file.name.replace('incoming/', 'processed/')
-    );
-  }
-}
-```
-
-## Error Handling
-
-### Common S3 Errors
-
-```typescript
-try {
-  await s3.downloadFile('missing-file.csv');
-} catch (error: any) {
-  switch (error.name) {
-    case 'NoSuchKey':
-      console.error('File does not exist');
-      break;
-    case 'NoSuchBucket':
-      console.error('Bucket does not exist');
-      break;
-    case 'AccessDenied':
-      console.error('Permission denied - check IAM policy');
-      break;
-    case 'InvalidBucketName':
-      console.error('Invalid bucket name');
-      break;
-    default:
-      console.error('S3 error:', error.message);
-  }
-}
-```
-
-### Retry Logic
-
-```typescript
-async function downloadWithRetry(
-  s3: S3DataSource,
-  key: string,
-  maxRetries = 3
-): Promise<string> {
-  for (let attempt = 1; attempt <= maxRetries; attempt++) {
-    try {
-      return await s3.downloadFile(key);
-    } catch (error: any) {
-      if (error.name === 'NoSuchKey') {
-        throw error; // Don't retry if file doesn't exist
-      }
-
-      if (attempt === maxRetries) throw error;
-
-      const delay = Math.pow(2, attempt) * 1000; // Exponential backoff
-      console.log(`Retry ${attempt}/${maxRetries} after ${delay}ms`);
-      await new Promise(resolve => setTimeout(resolve, delay));
-    }
-  }
-  throw new Error('Should not reach here');
-}
-```
-
-## Parquet Support
-
-S3 data source supports writing Parquet files for efficient data storage and transfer.
-
-### Write Parquet Content
-
-```typescript
-try {
-  // Prepare data records
-  const records = [
-    { sku: 'SKU-001', quantity: 10, price: 99.99, available: true },
-    { sku: 'SKU-002', quantity: 25, price: 149.99, available: true }
-  ];
-  
-  // Generate Parquet content as Buffer
-  const parquetBuffer = await s3.writeParquetContent(records, {
-    compression: 'GZIP',      // Options: 'UNCOMPRESSED', 'GZIP', 'SNAPPY', 'LZO', 'BROTLI'
-    rowGroupSize: 5000,       // Number of rows per row group
-    schema: {                 // Optional: explicit schema (auto-detected if not provided)
-      sku: { type: 'UTF8' },
-      quantity: { type: 'INT64' },
-      price: { type: 'DOUBLE' },
-      available: { type: 'BOOLEAN' }
-    }
-  });
-  
-  // Upload Parquet file to S3
-  await s3.uploadFile('data/inventory.parquet', parquetBuffer);
-  
-  console.log(`Generated Parquet file: ${parquetBuffer.length} bytes`);
-} finally {
-  await s3.dispose();
-}
-```
-
-### Parquet with Compression
-
-```typescript
-try {
-  const records = /* ... large dataset ... */;
-  
-  // Use SNAPPY compression for faster processing
-  const compressed = await s3.writeParquetContent(records, {
-    compression: 'SNAPPY',
-    rowGroupSize: 10000
-  });
-  
-  // Use GZIP for smaller file size
-  const gzipped = await s3.writeParquetContent(records, {
-    compression: 'GZIP',
-    rowGroupSize: 10000
-  });
-  
-  console.log(`SNAPPY: ${compressed.length} bytes`);
-  console.log(`GZIP: ${gzipped.length} bytes`);
-  
-  // Upload smaller file
-  await s3.uploadFile('data/compressed.parquet', gzipped);
-} finally {
-  await s3.dispose();
-}
-```
-
-### Parquet Export Pattern
-
-```typescript
-async function exportToParquet(s3: S3DataSource, records: any[], outputKey: string) {
-  // Generate Parquet file
-  const parquetBuffer = await s3.writeParquetContent(records, {
-    compression: 'GZIP',
-    rowGroupSize: 10000
-  });
-  
-  // Upload to S3
-  await s3.uploadFile(outputKey, parquetBuffer);
-  
-  console.log(`Exported ${records.length} records to ${outputKey}`);
-}
-
-try {
-  // Query data from Fluent or other source
-  const inventoryData = await fetchInventoryData();
-  
-  // Export to Parquet
-  const date = new Date().toISOString().split('T')[0];
-  await exportToParquet(s3, inventoryData, `exports/inventory_${date}.parquet`);
-} finally {
-  await s3.dispose();
-}
-```
-
-**Note:** For reading Parquet files from S3, use `ParquetParserService` from the SDK:
-
-```typescript
-import { ParquetParserService } from '@fluentcommerce/fc-connect-sdk';
-
-const parser = new ParquetParserService();
-const content = await s3.downloadFile('data/inventory.parquet', {
-  encoding: 'binary'  // S3 uses 'binary' encoding for binary files
-});
-const records = await parser.parse(content as Buffer);
-```
-
-## Key Takeaways
-
-- 🎯 S3 uses buckets and keys (no leading slashes in keys)
-- 🎯 Move is implemented as copy + delete (2 operations)
-- 🎯 Presigned URLs provide temporary access without credentials
-- 🎯 Date-based prefixes help organize large datasets
-- 🎯 `writeParquetContent()` generates compressed Parquet files efficiently
-- 🎯 Always handle NoSuchKey and AccessDenied errors
-- 🎯 Use retry logic with exponential backoff for transient errors
-
-## Next Steps
-
-Continue to [Module 4: SFTP Operations](./file-operations-04-sftp-operations.md) for SFTP-specific features.
-
----
-
-**Related Resources:**
-- [Quick Reference](../../../02-CORE-GUIDES/advanced-services/advanced-services-quick-reference.md) - S3 operations cheat sheet
-- [Common Patterns](../examples/common-patterns.ts) - Copy-paste ready snippets
-- [AWS S3 Documentation](https://docs.aws.amazon.com/s3/) - Official AWS docs
+# Module 3: S3 Operations
+
+**Level:** Intermediate
+**Estimated Time:** 25 minutes
+
+## Overview
+
+Complete guide to S3-specific file operations, including presigned URLs, batch operations, and S3-specific features.
+
+## Learning Objectives
+
+By the end of this module, you will:
+- ✅ Master all S3 file operations (list, read, write, move, copy, delete)
+- ✅ Understand S3-specific concepts (buckets, keys, regions)
+- ✅ Learn presigned URL generation for temporary access
+- ✅ Implement efficient batch operations
+- ✅ Handle S3-specific errors
+
+## S3 Concepts
+
+### Buckets and Keys
+
+```typescript
+// Bucket: Top-level container
+const bucketName = 'my-data-bucket';
+
+// Key: Object path within bucket (no leading slash!)
+const key = 'incoming/orders/2025-01-15.csv';
+//           └─ prefix ─┘ └──── file ────┘
+
+// Full S3 URL: s3://my-data-bucket/incoming/orders/2025-01-15.csv
+```
+
+### Regions
+
+```typescript
+const s3 = new S3DataSource({
+  type: 'S3_CSV',
+  connectionId: 's3-operations',
+  name: 'S3 Operations',
+  s3Config: {
+    region: 'us-east-1',  // Must match bucket region
+    bucket: 'my-bucket',
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!
+  }
+}, logger);
+```
+
+## All S3 Operations
+
+### List Files
+
+```typescript
+// List all files
+const allFiles = await s3.listFiles();
+
+// List with prefix
+const incomingFiles = await s3.listFiles({ prefix: 'incoming/' });
+
+// List with maxKeys for pagination
+const csvFiles = await s3.listFiles({ prefix: 'incoming/', maxKeys: 100 });
+
+// List with delimiter for folder structure
+const folders = await s3.listFiles({ prefix: 'incoming/', delimiter: '/' });
+
+// Examine metadata
+files.forEach(file => {
+  console.log(`Name: ${file.name}`);
+  console.log(`Path: ${file.path}`);
+  console.log(`Size: ${file.size} bytes`);
+  console.log(`Source: ${file.source}`); // 'S3'
+  if (file.lastModified) {
+    console.log(`Modified: ${file.lastModified}`); // ISO string
+  }
+});
+```
+
+### Download Files
+
+```typescript
+// Download as string
+const csvContent = await s3.downloadFile('data/orders.csv');
+
+// Handle large files
+try {
+  const content = await s3.downloadFile('large-file.csv');
+  console.log(`Downloaded ${content.length} bytes`);
+} catch (error: any) {
+  if (error.name === 'NoSuchKey') {
+    console.error('File does not exist');
+  } else {
+    console.error('Download failed:', error);
+  }
+}
+```
+
+### Upload Files
+
+```typescript
+import { Buffer } from 'node:buffer'; // Required for Deno/Versori runtime
+
+// Upload string content
+const data = JSON.stringify({ status: 'processed' });
+await s3.uploadFile('output/results.json', data);
+
+// Upload buffer
+const buffer = Buffer.from('Hello, S3!');
+await s3.uploadFile('messages/greeting.txt', buffer);
+
+// Upload with error handling
+try {
+  await s3.uploadFile('output/data.csv', csvContent);
+  console.log('Upload successful');
+} catch (error: any) {
+  if (error.name === 'AccessDenied') {
+    console.error('No write permission');
+  } else {
+    console.error('Upload failed:', error);
+  }
+}
+```
+
+### Move Files
+
+```typescript
+// Move (copy + delete source - DEFAULT BEHAVIOR)
+await s3.moveFile('incoming/file.csv', 'processed/file.csv');
+// Source file is DELETED by default
+
+// Move without deleting source
+await s3.moveFile('incoming/file.csv', 'processed/file.csv', false);
+// Source file is preserved
+
+// Move to date-based archive
+const today = new Date().toISOString().split('T')[0];
+await s3.moveFile(
+  'incoming/orders.csv',
+  `archive/${today}/orders.csv`
+);
+
+// Move with error handling
+try {
+  await s3.moveFile(sourceKey, destKey);
+  console.log('File moved successfully');
+} catch (error: any) {
+  if (error.name === 'NoSuchKey') {
+    console.error('Source file not found');
+  } else {
+    console.error('Move failed:', error);
+  }
+}
+```
+
+### Copy Files
+
+```typescript
+// Copy to backup
+await s3.copyFile('important/data.csv', 'backup/data.csv');
+
+// Copy with metadata
+await s3.copyFile('source/file.txt', 'dest/file.txt', {
+  metadata: { processedBy: 'sdk' }
+});
+
+// Copy from different bucket
+await s3.copyFile('source/file.txt', 'dest/file.txt', {
+  sourceBucket: 'other-bucket'
+});
+```
+
+### Delete Files
+
+```typescript
+// Delete single file
+await s3.deleteFile('temp/old-file.csv');
+
+// Delete with confirmation
+const fileToDelete = 'archive/old/data.csv';
+const exists = await s3.fileExists(fileToDelete);
+if (exists) {
+  await s3.deleteFile(fileToDelete);
+  console.log('File deleted');
+}
+```
+
+### Check File Existence
+
+```typescript
+// Check if file exists
+const exists = await s3.fileExists('incoming/orders.csv');
+console.log(`File exists: ${exists}`);
+
+// Conditional processing
+if (await s3.fileExists('config/settings.json')) {
+  const config = await s3.downloadFile('config/settings.json');
+  // Use config
+}
+```
+
+## Batch Operations
+
+### Process Multiple Files
+
+```typescript
+const files = await s3.listFiles({ prefix: 'incoming/', maxKeys: 1000 });
+
+for (const file of files) {
+  try {
+    const content = await s3.downloadFile(file.name);
+    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
+    const archiveKey = file.name.replace('incoming/', 'archive/');
+    await s3.moveFile(file.name, archiveKey);
+
+    console.log(`Processed ${file.name}`);
+
+  } catch (error) {
+    console.error(`Failed to process ${file.name}:`, error);
+    // Continue with next file
+  }
+}
+```
+
+### Parallel Processing
+
+```typescript
+const files = await s3.listFiles({ prefix: 'incoming/' });
+
+// Process files in parallel (be mindful of rate limits)
+const results = await Promise.allSettled(
+  files.map(async (file) => {
+    const content = await s3.downloadFile(file.name);
+    const result = await processData(content);
+    await s3.uploadFile(
+      file.name.replace('incoming/', 'output/'),
+      JSON.stringify(result)
+    );
+    return file.name;
+  })
+);
+
+// Check results
+results.forEach((result, index) => {
+  if (result.status === 'fulfilled') {
+    console.log(`Success: ${result.value}`);
+  } else {
+    console.error(`Failed: ${files[index].name}:`, result.reason);
+  }
+});
+```
+
+## Presigned URLs
+
+Use the `S3PresignService` for temporary access:
+
+```typescript
+import { S3PresignService } from '@fluentcommerce/fc-connect-sdk';
+
+const presignService = new S3PresignService(
+  s3Config,
+  bucketName,
+  logger
+);
+
+// Generate download URL (valid for 1 hour)
+const downloadUrl = await presignService.generatePresignedDownloadUrl(
+  'reports/monthly-report.pdf',
+  3600  // 1 hour in seconds
+);
+
+console.log('Download here:', downloadUrl);
+// https://my-bucket.s3.amazonaws.com/reports/monthly-report.pdf?X-Amz-...
+
+// Generate upload URL
+const uploadUrl = await presignService.generatePresignedUploadUrl(
+  'incoming/upload.csv',
+  3600
+);
+
+console.log('Upload here:', uploadUrl);
+```
+
+## S3-Specific Patterns
+
+### Date-Based Organization
+
+```typescript
+function getDateBasedKey(filename: string, prefix: string): string {
+  const now = new Date();
+  const year = now.getFullYear();
+  const month = String(now.getMonth() + 1).padStart(2, '0');
+  const day = String(now.getDate()).padStart(2, '0');
+
+  return `${prefix}/${year}/${month}/${day}/${filename}`;
+}
+
+// Archive with date structure
+await s3.moveFile(
+  'incoming/orders.csv',
+  getDateBasedKey('orders.csv', 'archive')
+);
+// Result: archive/2025/01/15/orders.csv
+```
+
+### Multi-Prefix Processing
+
+```typescript
+const prefixes = ['orders', 'inventory', 'products'];
+
+for (const prefix of prefixes) {
+  const files = await s3.listFiles({ prefix: `incoming/${prefix}/` });
+
+  for (const file of files) {
+    const content = await s3.downloadFile(file.name);
+    await processByType(prefix, content);
+
+    await s3.moveFile(
+      file.name,
+      file.name.replace('incoming/', 'processed/')
+    );
+  }
+}
+```
+
+## Error Handling
+
+### Common S3 Errors
+
+```typescript
+try {
+  await s3.downloadFile('missing-file.csv');
+} catch (error: any) {
+  switch (error.name) {
+    case 'NoSuchKey':
+      console.error('File does not exist');
+      break;
+    case 'NoSuchBucket':
+      console.error('Bucket does not exist');
+      break;
+    case 'AccessDenied':
+      console.error('Permission denied - check IAM policy');
+      break;
+    case 'InvalidBucketName':
+      console.error('Invalid bucket name');
+      break;
+    default:
+      console.error('S3 error:', error.message);
+  }
+}
+```
+
+### Retry Logic
+
+```typescript
+async function downloadWithRetry(
+  s3: S3DataSource,
+  key: string,
+  maxRetries = 3
+): Promise<string> {
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      return await s3.downloadFile(key);
+    } catch (error: any) {
+      if (error.name === 'NoSuchKey') {
+        throw error; // Don't retry if file doesn't exist
+      }
+
+      if (attempt === maxRetries) throw error;
+
+      const delay = Math.pow(2, attempt) * 1000; // Exponential backoff
+      console.log(`Retry ${attempt}/${maxRetries} after ${delay}ms`);
+      await new Promise(resolve => setTimeout(resolve, delay));
+    }
+  }
+  throw new Error('Should not reach here');
+}
+```
+
+## Parquet Support
+
+S3 data source supports writing Parquet files for efficient data storage and transfer.
+
+### Write Parquet Content
+
+```typescript
+try {
+  // Prepare data records
+  const records = [
+    { sku: 'SKU-001', quantity: 10, price: 99.99, available: true },
+    { sku: 'SKU-002', quantity: 25, price: 149.99, available: true }
+  ];
+  
+  // Generate Parquet content as Buffer
+  const parquetBuffer = await s3.writeParquetContent(records, {
+    compression: 'GZIP',      // Options: 'UNCOMPRESSED', 'GZIP', 'SNAPPY', 'LZO', 'BROTLI'
+    rowGroupSize: 5000,       // Number of rows per row group
+    schema: {                 // Optional: explicit schema (auto-detected if not provided)
+      sku: { type: 'UTF8' },
+      quantity: { type: 'INT64' },
+      price: { type: 'DOUBLE' },
+      available: { type: 'BOOLEAN' }
+    }
+  });
+  
+  // Upload Parquet file to S3
+  await s3.uploadFile('data/inventory.parquet', parquetBuffer);
+  
+  console.log(`Generated Parquet file: ${parquetBuffer.length} bytes`);
+} finally {
+  await s3.dispose();
+}
+```
+
+### Parquet with Compression
+
+```typescript
+try {
+  const records = /* ... large dataset ... */;
+  
+  // Use SNAPPY compression for faster processing
+  const compressed = await s3.writeParquetContent(records, {
+    compression: 'SNAPPY',
+    rowGroupSize: 10000
+  });
+  
+  // Use GZIP for smaller file size
+  const gzipped = await s3.writeParquetContent(records, {
+    compression: 'GZIP',
+    rowGroupSize: 10000
+  });
+  
+  console.log(`SNAPPY: ${compressed.length} bytes`);
+  console.log(`GZIP: ${gzipped.length} bytes`);
+  
+  // Upload smaller file
+  await s3.uploadFile('data/compressed.parquet', gzipped);
+} finally {
+  await s3.dispose();
+}
+```
+
+### Parquet Export Pattern
+
+```typescript
+async function exportToParquet(s3: S3DataSource, records: any[], outputKey: string) {
+  // Generate Parquet file
+  const parquetBuffer = await s3.writeParquetContent(records, {
+    compression: 'GZIP',
+    rowGroupSize: 10000
+  });
+  
+  // Upload to S3
+  await s3.uploadFile(outputKey, parquetBuffer);
+  
+  console.log(`Exported ${records.length} records to ${outputKey}`);
+}
+
+try {
+  // Query data from Fluent or other source
+  const inventoryData = await fetchInventoryData();
+  
+  // Export to Parquet
+  const date = new Date().toISOString().split('T')[0];
+  await exportToParquet(s3, inventoryData, `exports/inventory_${date}.parquet`);
+} finally {
+  await s3.dispose();
+}
+```
+
+**Note:** For reading Parquet files from S3, use `ParquetParserService` from the SDK:
+
+```typescript
+import { ParquetParserService } from '@fluentcommerce/fc-connect-sdk';
+
+const parser = new ParquetParserService();
+const content = await s3.downloadFile('data/inventory.parquet', {
+  encoding: 'binary'  // S3 uses 'binary' encoding for binary files
+});
+const records = await parser.parse(content as Buffer);
+```
+
+## Key Takeaways
+
+- 🎯 S3 uses buckets and keys (no leading slashes in keys)
+- 🎯 Move is implemented as copy + delete (2 operations)
+- 🎯 Presigned URLs provide temporary access without credentials
+- 🎯 Date-based prefixes help organize large datasets
+- 🎯 `writeParquetContent()` generates compressed Parquet files efficiently
+- 🎯 Always handle NoSuchKey and AccessDenied errors
+- 🎯 Use retry logic with exponential backoff for transient errors
+
+## Next Steps
+
+Continue to [Module 4: SFTP Operations](./file-operations-04-sftp-operations.md) for SFTP-specific features.
+
+---
+
+**Related Resources:**
+- [Quick Reference](../../../02-CORE-GUIDES/advanced-services/advanced-services-quick-reference.md) - S3 operations cheat sheet
+- [Common Patterns](../examples/common-patterns.ts) - Copy-paste ready snippets
+- [AWS S3 Documentation](https://docs.aws.amazon.com/s3/) - Official AWS docs