@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/03-PATTERN-GUIDES/connector-scenarios/examples/connector-scenarios-readme.md

@@ -1,253 +1,253 @@
-# Connector Scenarios - Examples
-
-This directory contains complete, runnable examples for each connector scenario covered in the guide.
-
-## Available Examples
-
-### Scenario 1: SFTP CSV to Fluent Inventory
-
-**File:** Use `common-patterns.ts` and module 02 snippets (standalone file coming soon)
-**Complexity:** Low
-**Description:** Complete SFTP CSV inventory ingestion connector with validation, transformation, and error handling.
-
-**What it demonstrates:**
-
-- SFTP connection and file listing
-- CSV parsing with headers
-- Field mapping and transformation
-- Batch API usage for inventory updates
-- File archival and error handling
-- State management for duplicate prevention
-
-**Run:**
-
-```bash
-ts-node examples/scenario-1-sftp-csv-inventory.ts
-```
-
-### Scenario 2: S3 Parquet to Fluent Products
-
-**File:** Use module 03 snippets (standalone file coming soon)
-**Complexity:** Medium
-**Description:** S3 Parquet product catalog sync with enrichment.
-
-**What it demonstrates:**
-
-- S3 file operations
-- Parquet columnar format parsing
-- Nested field transformations
-- Data enrichment patterns
-- GraphQL mutations for products
-
-**Run:**
-
-```bash
-ts-node examples/scenario-2-s3-parquet-products.ts
-```
-
-### Scenario 3: SFTP JSON to Fluent Orders
-
-**File:** Use module 03 snippets (standalone file coming soon)
-**Complexity:** Medium
-**Description:** JSON order file processing with schema validation.
-
-**What it demonstrates:**
-
-- JSON parsing and validation
-- Schema-based validation
-- Complex nested data transformation
-- Order creation via GraphQL
-- Detailed error reporting
-
-**Run:**
-
-```bash
-ts-node examples/scenario-3-sftp-json-orders.ts
-```
-
-### Scenario 4: S3 CSV with State Management
-
-**File:** Use module 04 snippets (standalone file coming soon)
-**Complexity:** High
-**Description:** Large CSV file processing with streaming and checkpoints.
-
-**What it demonstrates:**
-
-- Streaming large files (memory efficient)
-- Record-level checkpointing
-- Recovery from failures
-- Batch processing with progress tracking
-- Advanced state management
-
-**Run:**
-
-```bash
-ts-node examples/scenario-4-s3-csv-state.ts
-```
-
-### Scenario 5: Multi-Source Aggregation
-
-**File:** Use module 04 snippets (standalone file coming soon)
-**Complexity:** High
-**Description:** Aggregate inventory from SFTP and S3, reconcile with Fluent.
-
-**What it demonstrates:**
-
-- Multiple data source orchestration
-- Data aggregation by key
-- Reconciliation with existing data
-- Delta calculation and updates
-- Report generation
-
-**Run:**
-
-```bash
-ts-node examples/scenario-5-multi-source.ts
-```
-
-### Scenario 6: Bidirectional Sync
-
-**File:** Use module 05 snippets (standalone file coming soon)
-**Complexity:** Medium
-**Description:** Extract data from Fluent and export to SFTP.
-
-**What it demonstrates:**
-
-- GraphQL queries with auto-pagination
-- Data extraction patterns
-- Multiple export formats (JSON, CSV, JSONL)
-- SFTP uploads
-- Export manifest generation
-
-**Run:**
-
-```bash
-ts-node examples/scenario-6-bidirectional.ts
-```
-
-### Common Patterns
-
-**File:** `common-patterns.ts`
-**Description:** Reusable code patterns and utility functions.
-
-**Includes:**
-
-- Field mapping patterns
-- Validation utilities
-- Error handling helpers
-- State management utilities
-- File operation helpers
-- Retry logic implementations
-
-## Example Structure
-
-Each example follows this structure:
-
-```typescript
-// 1. Imports and type definitions
-import { ... } from '@fluentcommerce/fc-connect-sdk';
-
-// 2. Configuration
-const config = { ... };
-
-// 3. Service initialization
-const logger = createConsoleLogger();
-const dataSource = new SftpDataSource({ ... }, logger);
-const mapper = new UniversalMapper({ ... });
-const client = await createClient({ ... });
-
-// 4. Main processing function
-async function processData() {
-  // List files
-  // Download and parse
-  // Validate and transform
-  // Send to Fluent
-  // Archive and track state
-}
-
-// 5. Error handling and execution
-processData()
-  .then(() => console.log('✅ Complete'))
-  .catch(err => console.error('❌ Failed:', err));
-```
-
-## Running Examples
-
-### Prerequisites
-
-1. Install dependencies:
-
-```bash
-npm install @fluentcommerce/fc-connect-sdk
-```
-
-2. Set environment variables (copy `.env.example` to `.env`):
-
-```bash
-# Fluent Commerce
-FLUENT_BASE_URL=https://api.fluentcommerce.com
-FLUENT_CLIENT_ID=your-client-id
-FLUENT_CLIENT_SECRET=your-client-secret
-FLUENT_RETAILER_ID=1
-
-# SFTP (if needed)
-SFTP_HOST=sftp.example.com
-SFTP_USERNAME=user
-SFTP_PASSWORD=password
-
-# S3 (if needed)
-AWS_ACCESS_KEY_ID=your-key
-AWS_SECRET_ACCESS_KEY=your-secret
-S3_BUCKET=your-bucket
-AWS_REGION=us-east-1
-```
-
-3. Run an example:
-
-```bash
-# Using ts-node
-ts-node examples/scenario-1-sftp-csv-inventory.ts
-
-# Or compile first
-tsc examples/scenario-1-sftp-csv-inventory.ts
-node examples/scenario-1-sftp-csv-inventory.js
-```
-
-### Testing Examples
-
-Each example can be tested with sample data:
-
-```bash
-# Create test data directory
-mkdir -p test-data
-
-# Add sample CSV
-echo "sku,location,quantity,status
-SKU-001,WH-A,100,available
-SKU-002,WH-A,50,available" > test-data/inventory.csv
-
-# Run example against test data
-ts-node examples/scenario-1-sftp-csv-inventory.ts
-```
-
-## Customizing Examples
-
-Each example is designed to be customized for your specific use case:
-
-1. **Update configuration** - Change SFTP/S3 settings, file patterns
-2. **Modify field mappings** - Adjust transformations to match your data
-3. **Add validation rules** - Include business-specific validation
-4. **Customize error handling** - Add notifications, custom error logging
-5. **Adjust batch sizes** - Tune for your data volume
-
-## Next Steps
-
-- Review [Module 1: Foundations](../modules/connector-scenarios-01-foundations.md) for architecture overview
-- See [Quick Reference](../connector-scenarios-quick-reference.md) for code snippets
-- Check [Module 6: Production Patterns](../modules/connector-scenarios-06-production-patterns.md) for deployment guidance
-
-## Support
-
-- Full documentation: [connector-scenarios/readme.md](../connector-scenarios-readme.md)
-- SDK API reference: [docs/api-reference/readme.md](../../../02-CORE-GUIDES/api-reference/api-reference-readme.md)
-- Report issues: [GitHub Issues](https://github.com/fluentcommerce/fc-connect-sdk/issues)
+# Connector Scenarios - Examples
+
+This directory contains complete, runnable examples for each connector scenario covered in the guide.
+
+## Available Examples
+
+### Scenario 1: SFTP CSV to Fluent Inventory
+
+**File:** Use `common-patterns.ts` and module 02 snippets (standalone file coming soon)
+**Complexity:** Low
+**Description:** Complete SFTP CSV inventory ingestion connector with validation, transformation, and error handling.
+
+**What it demonstrates:**
+
+- SFTP connection and file listing
+- CSV parsing with headers
+- Field mapping and transformation
+- Batch API usage for inventory updates
+- File archival and error handling
+- State management for duplicate prevention
+
+**Run:**
+
+```bash
+ts-node examples/scenario-1-sftp-csv-inventory.ts
+```
+
+### Scenario 2: S3 Parquet to Fluent Products
+
+**File:** Use module 03 snippets (standalone file coming soon)
+**Complexity:** Medium
+**Description:** S3 Parquet product catalog sync with enrichment.
+
+**What it demonstrates:**
+
+- S3 file operations
+- Parquet columnar format parsing
+- Nested field transformations
+- Data enrichment patterns
+- GraphQL mutations for products
+
+**Run:**
+
+```bash
+ts-node examples/scenario-2-s3-parquet-products.ts
+```
+
+### Scenario 3: SFTP JSON to Fluent Orders
+
+**File:** Use module 03 snippets (standalone file coming soon)
+**Complexity:** Medium
+**Description:** JSON order file processing with schema validation.
+
+**What it demonstrates:**
+
+- JSON parsing and validation
+- Schema-based validation
+- Complex nested data transformation
+- Order creation via GraphQL
+- Detailed error reporting
+
+**Run:**
+
+```bash
+ts-node examples/scenario-3-sftp-json-orders.ts
+```
+
+### Scenario 4: S3 CSV with State Management
+
+**File:** Use module 04 snippets (standalone file coming soon)
+**Complexity:** High
+**Description:** Large CSV file processing with streaming and checkpoints.
+
+**What it demonstrates:**
+
+- Streaming large files (memory efficient)
+- Record-level checkpointing
+- Recovery from failures
+- Batch processing with progress tracking
+- Advanced state management
+
+**Run:**
+
+```bash
+ts-node examples/scenario-4-s3-csv-state.ts
+```
+
+### Scenario 5: Multi-Source Aggregation
+
+**File:** Use module 04 snippets (standalone file coming soon)
+**Complexity:** High
+**Description:** Aggregate inventory from SFTP and S3, reconcile with Fluent.
+
+**What it demonstrates:**
+
+- Multiple data source orchestration
+- Data aggregation by key
+- Reconciliation with existing data
+- Delta calculation and updates
+- Report generation
+
+**Run:**
+
+```bash
+ts-node examples/scenario-5-multi-source.ts
+```
+
+### Scenario 6: Bidirectional Sync
+
+**File:** Use module 05 snippets (standalone file coming soon)
+**Complexity:** Medium
+**Description:** Extract data from Fluent and export to SFTP.
+
+**What it demonstrates:**
+
+- GraphQL queries with auto-pagination
+- Data extraction patterns
+- Multiple export formats (JSON, CSV, JSONL)
+- SFTP uploads
+- Export manifest generation
+
+**Run:**
+
+```bash
+ts-node examples/scenario-6-bidirectional.ts
+```
+
+### Common Patterns
+
+**File:** `common-patterns.ts`
+**Description:** Reusable code patterns and utility functions.
+
+**Includes:**
+
+- Field mapping patterns
+- Validation utilities
+- Error handling helpers
+- State management utilities
+- File operation helpers
+- Retry logic implementations
+
+## Example Structure
+
+Each example follows this structure:
+
+```typescript
+// 1. Imports and type definitions
+import { ... } from '@fluentcommerce/fc-connect-sdk';
+
+// 2. Configuration
+const config = { ... };
+
+// 3. Service initialization
+const logger = createConsoleLogger();
+const dataSource = new SftpDataSource({ ... }, logger);
+const mapper = new UniversalMapper({ ... });
+const client = await createClient({ ... });
+
+// 4. Main processing function
+async function processData() {
+  // List files
+  // Download and parse
+  // Validate and transform
+  // Send to Fluent
+  // Archive and track state
+}
+
+// 5. Error handling and execution
+processData()
+  .then(() => console.log('✅ Complete'))
+  .catch(err => console.error('❌ Failed:', err));
+```
+
+## Running Examples
+
+### Prerequisites
+
+1. Install dependencies:
+
+```bash
+npm install @fluentcommerce/fc-connect-sdk
+```
+
+2. Set environment variables (copy `.env.example` to `.env`):
+
+```bash
+# Fluent Commerce
+FLUENT_BASE_URL=https://api.fluentcommerce.com
+FLUENT_CLIENT_ID=your-client-id
+FLUENT_CLIENT_SECRET=your-client-secret
+FLUENT_RETAILER_ID=1
+
+# SFTP (if needed)
+SFTP_HOST=sftp.example.com
+SFTP_USERNAME=user
+SFTP_PASSWORD=password
+
+# S3 (if needed)
+AWS_ACCESS_KEY_ID=your-key
+AWS_SECRET_ACCESS_KEY=your-secret
+S3_BUCKET=your-bucket
+AWS_REGION=us-east-1
+```
+
+3. Run an example:
+
+```bash
+# Using ts-node
+ts-node examples/scenario-1-sftp-csv-inventory.ts
+
+# Or compile first
+tsc examples/scenario-1-sftp-csv-inventory.ts
+node examples/scenario-1-sftp-csv-inventory.js
+```
+
+### Testing Examples
+
+Each example can be tested with sample data:
+
+```bash
+# Create test data directory
+mkdir -p test-data
+
+# Add sample CSV
+echo "sku,location,quantity,status
+SKU-001,WH-A,100,available
+SKU-002,WH-A,50,available" > test-data/inventory.csv
+
+# Run example against test data
+ts-node examples/scenario-1-sftp-csv-inventory.ts
+```
+
+## Customizing Examples
+
+Each example is designed to be customized for your specific use case:
+
+1. **Update configuration** - Change SFTP/S3 settings, file patterns
+2. **Modify field mappings** - Adjust transformations to match your data
+3. **Add validation rules** - Include business-specific validation
+4. **Customize error handling** - Add notifications, custom error logging
+5. **Adjust batch sizes** - Tune for your data volume
+
+## Next Steps
+
+- Review [Module 1: Foundations](../modules/connector-scenarios-01-foundations.md) for architecture overview
+- See [Quick Reference](../connector-scenarios-quick-reference.md) for code snippets
+- Check [Module 6: Production Patterns](../modules/connector-scenarios-06-production-patterns.md) for deployment guidance
+
+## Support
+
+- Full documentation: [connector-scenarios/readme.md](../connector-scenarios-readme.md)
+- SDK API reference: [docs/api-reference/readme.md](../../../02-CORE-GUIDES/api-reference/api-reference-readme.md)
+- Report issues: [GitHub Issues](https://github.com/fluentcommerce/fc-connect-sdk/issues)