@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

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

@@ -1,313 +1,313 @@
-# Connector Scenarios Learning Path
-
-> **Complete guide to building production connectors with the Fluent Connect SDK**
-> Progressive learning modules with real-world implementation patterns and verified code examples
-
-## 📚 What You'll Learn
-
-This guide teaches you how to build end-to-end connectors for Fluent Commerce integrations using the SDK. By the end, you'll understand:
-
-- ✅ How to architect complete data flows from source to Fluent Commerce
-- ✅ How to combine data sources (SFTP, S3), parsers (CSV, JSON, Parquet), and transformations
-- ✅ How to implement validation, state management, and error handling
-- ✅ How to handle batch processing and monitoring
-- ✅ How to build bidirectional sync patterns (ingestion and extraction)
-- ✅ How to aggregate data from multiple sources
-- ✅ Real production patterns for inventory, orders, and product catalog sync
-
-## 🎯 Learning Path Overview
-
-This guide is organized into **7 progressive modules**. Follow them in order for the best learning experience:
-
-| Module                                             | Topic                                                                    | Level        |
-| -------------------------------------------------- | ------------------------------------------------------------------------ | ------------ |
-| [Module 1](./modules/connector-scenarios-01-foundations.md)            | **Foundations** - Connector architecture, data flow patterns             | Beginner     |
-| [Module 2](./modules/connector-scenarios-02-simple-scenarios.md)       | **Simple Scenarios** - SFTP CSV ingestion, basic transformations         | Beginner     |
-| [Module 3](./modules/connector-scenarios-03-intermediate-scenarios.md) | **Intermediate Scenarios** - S3 Parquet, JSON orders, validation         | Intermediate |
-| [Module 4](./modules/connector-scenarios-04-advanced-scenarios.md)     | **Advanced Scenarios** - State management, multi-source aggregation      | Advanced     |
-| [Module 5](./modules/connector-scenarios-05-bidirectional-sync.md)     | **Bidirectional Sync** - Extraction patterns, Fluent to external systems | Advanced     |
-| [Module 6](./modules/connector-scenarios-06-production-patterns.md)    | **Production Patterns** - Error handling, monitoring, deployment         | Intermediate |
-| [Module 7](./modules/connector-scenarios-07-reference.md)              | **Reference** - Complete pattern catalog, best practices                 | Reference    |
-
-## 🚀 Quick Navigation
-
-### By Use Case
-
-- **First time building a connector?** → Start with [Module 1: Foundations](./modules/connector-scenarios-01-foundations.md)
-- **Need SFTP CSV ingestion?** → Jump to [Module 2: Simple Scenarios](./modules/connector-scenarios-02-simple-scenarios.md)
-- **Need S3 Parquet processing?** → See [Module 3: Intermediate Scenarios](./modules/connector-scenarios-03-intermediate-scenarios.md)
-- **Need multi-source aggregation?** → Check [Module 4: Advanced Scenarios](./modules/connector-scenarios-04-advanced-scenarios.md)
-- **Need to export from Fluent?** → See [Module 5: Bidirectional Sync](./modules/connector-scenarios-05-bidirectional-sync.md)
-- **Want code examples?** → Browse [Examples Directory](./examples/)
-
-### By Scenario Type
-
-Different connector types require different patterns and complexity levels:
-
-| Scenario                 | Complexity | Data Source | Format   | Example                                                 |
-| ------------------------ | ---------- | ----------- | -------- | ------------------------------------------------------- |
-| SFTP CSV to Inventory    | Simple     | SFTP        | CSV      | [Examples](./examples/common-patterns.ts)  |
-| S3 Parquet to Products   | Medium     | S3          | Parquet  | [Examples](./examples/common-patterns.ts) |
-| SFTP JSON to Orders      | Medium     | SFTP        | JSON     | [Examples](./examples/common-patterns.ts)    |
-| S3 CSV with State        | Medium     | S3          | CSV      | [Examples](./examples/common-patterns.ts)        |
-| Multi-Source Aggregation | High       | SFTP+S3     | Multiple | [Examples](./examples/common-patterns.ts)        |
-| Fluent to SFTP Export    | Medium     | Fluent API  | JSON/CSV | [Examples](./examples/common-patterns.ts)       |
-
-### By Component
-
-Find examples by SDK component usage:
-
-| Component            | Use Case              | Example                                                              |
-| -------------------- | --------------------- | -------------------------------------------------------------------- |
-| `SftpDataSource`     | SFTP file operations  | [SFTP CSV Scenario](./examples/common-patterns.ts)    |
-| `S3DataSource`       | S3 file operations    | [S3 Parquet Scenario](./examples/common-patterns.ts) |
-| `UniversalMapper`    | Field transformations | All scenarios                                                        |
-| `StateService`       | Duplicate prevention  | [State Management Scenario](./examples/common-patterns.ts)  |
-| `FluentClient`       | Batch API operations  | [Multi-Source Scenario](./examples/common-patterns.ts)      |
-| `ExtractionOrchestrator`  | Fluent data export    | [Bidirectional Scenario](./examples/common-patterns.ts)    |
-
-## 📖 Quick Reference
-
-For quick lookups, see:
-
-- [Quick Reference Cheat Sheet](./connector-scenarios-quick-reference.md) - All patterns on one page
-- [Common Patterns](./examples/common-patterns.ts) - Copy-paste ready snippets
-- [Best Practices](./modules/connector-scenarios-06-production-patterns.md#best-practices) - Production guidelines
-
-## 🎓 Prerequisites
-
-Before starting this guide, you should:
-
-1. ✅ Have the SDK installed: `npm install @fluentcommerce/fc-connect-sdk`
-2. ✅ Have Fluent API credentials (clientId, clientSecret, retailerId)
-3. ✅ Understand basic SDK concepts (client creation, services)
-4. ✅ Have access to data sources (SFTP, S3) if testing integrations
-
-**New to the SDK?** Start with the [Getting Started Guide](../../00-START-HERE/getting-started.md) first.
-
-## 🔍 Key Concepts at a Glance
-
-### Complete Connector Architecture
-
-```typescript
-// A complete connector combines multiple SDK components:
-
-// 1. Data Source (where data comes from)
-const sftpSource = new SftpDataSource({...});
-
-// 2. Parser (how to read the data format)
-const parser = new CSVParserService({...});
-
-// 3. Field Mapper (how to transform fields)
-const mapper = new UniversalMapper({...});
-
-// 4. Fluent Client (where data goes)
-const client = await createClient({...});
-
-// 5. State Management (prevent duplicates)
-// ⚠️ IMPORTANT: StateService constructor takes only logger (optional)
-const stateService = new StateService(logger);
-// KV adapter must be passed to EVERY method call
-const kv = openKv(); // Or VersoriKVAdapter for Versori platform
-const workflowId = 'my-workflow';
-
-// 6. Orchestration (tie it all together)
-async function processFiles() {
-  const files = await sftpSource.listFiles();
-  for (const file of files) {
-    // KV adapter MUST be passed to every method
-    if (await stateService.isFileProcessed(kv, file.name, workflowId)) continue;
-
-    const content = await sftpSource.downloadFile(file.name);
-    const records = await parser.parse(content);
-    const transformed = await mapper.mapBatch(records);
-
-    await client.sendBatch(jobId, { entities: transformed });
-    // KV adapter MUST be passed to every method
-    await stateService.markFileProcessed(kv, file.name, {}, workflowId);
-  }
-}
-```
-
-### Data Flow Pattern
-
-```
-┌─────────────┐     ┌─────────┐     ┌─────────────┐     ┌──────────┐     ┌─────────────┐
-│ Data Source │ --> │  Parser │ --> │ Field Mapper│ --> │  Batch   │ --> │   Fluent    │
-│ SFTP/S3/etc │     │ CSV/JSON│     │  Transform  │     │   API    │     │  Commerce   │
-└─────────────┘     └─────────┘     └─────────────┘     └──────────┘     └─────────────┘
-       │                                    │                                     │
-       │                                    │                                     │
-       v                                    v                                     v
-┌─────────────┐                    ┌─────────────┐                      ┌─────────────┐
-│    State    │                    │ Validation  │                      │  Monitoring │
-│ Management  │                    │   Service   │                      │   Metrics   │
-└─────────────┘                    └─────────────┘                      └─────────────┘
-```
-
-### Scenario Complexity Comparison
-
-| Feature              | Simple              | Intermediate           | Advanced                   |
-| -------------------- | ------------------- | ---------------------- | -------------------------- |
-| **Data Sources**     | Single (SFTP or S3) | Single with options    | Multiple sources           |
-| **Formats**          | CSV only            | CSV, JSON, Parquet     | Multiple formats           |
-| **Validation**       | Basic field checks  | Schema validation      | Cross-source validation    |
-| **State Management** | None or simple      | File-level tracking    | Record-level + checkpoints |
-| **Error Handling**   | Basic try-catch     | Retry + move to errors | Recovery + notifications   |
-| **Batch Processing** | Single batch        | Multiple batches       | Streaming + chunking       |
-| **Monitoring**       | Basic logging       | Metrics tracking       | Full observability         |
-
-## 🛠️ Complete Example
-
-Here's a minimal but complete connector (SFTP CSV to Fluent Inventory):
-
-```typescript
-import {
-  createClient,
-  SftpDataSource,
-  UniversalMapper,
-  createConsoleLogger,
-} from '@fluentcommerce/fc-connect-sdk';
-
-// Initialize services
-const logger = createConsoleLogger();
-
-const sftpSource = new SftpDataSource(
-  {
-    type: 'SFTP_CSV',
-    connectionId: 'inventory-sftp',
-    name: 'Inventory SFTP',
-    settings: {
-      host: process.env.SFTP_HOST,
-      username: process.env.SFTP_USERNAME,
-      password: process.env.SFTP_PASSWORD,
-      remotePath: '/inventory/updates',
-      csvHeaders: ['sku', 'location', 'quantity', 'status'],
-    },
-  },
-  logger
-);
-
-const mapper = new UniversalMapper({
-  fields: {
-    ref: { source: 'sku', resolver: 'sdk.uppercase' },
-    locationRef: { source: 'location' },
-    qty: { source: 'quantity', resolver: 'sdk.parseInt' },
-    status: { source: 'status' },
-  },
-});
-
-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,
-  },
-});
-
-// Main process
-async function syncInventory() {
-  const files = await sftpSource.listFiles({ filePattern: '*.csv' });
-
-  for (const file of files) {
-    logger.info(`Processing: ${file.name}`);
-
-    const content = await sftpSource.downloadFile(file.name);
-    const parser = new CSVParserService();
-    const records = await parser.parse(content as string);
-
-    const transformed = [];
-    for (const record of records) {
-      const result = await mapper.map(record);
-      if (result.success) transformed.push(result.data);
-    }
-
-    const job = await client.createJob({
-      name: `Inventory Update - ${file.name}`,
-      retailerId: process.env.FLUENT_RETAILER_ID,
-    });
-
-    await client.sendBatch(job.id, {
-      action: 'UPSERT',
-      entityType: 'INVENTORY',
-      entities: transformed.map(r => ({
-        ref: r.ref,
-        productRef: r.ref,
-        locationRef: r.locationRef,
-        qty: r.qty,
-        status: r.status,
-      })),
-    });
-
-    logger.info(`✅ Processed ${transformed.length} records`);
-  }
-}
-
-syncInventory();
-```
-
-**What this does:**
-
-1. Connects to SFTP and lists CSV files
-2. Downloads and parses each file
-3. Transforms fields using UniversalMapper
-4. Sends data to Fluent via Batch API
-5. Logs progress and results
-
-## 📂 Repository Structure
-
-```
-docs/guides/connector-scenarios/
-├── readme.md                              # This file - main index
-├── quick-reference.md                     # Cheat sheet for patterns
-│
-├── modules/                               # Learning modules
-│   ├── 01-foundations.md                  # Architecture and concepts
-│   ├── 02-simple-scenarios.md             # SFTP CSV basics
-│   ├── 03-intermediate-scenarios.md       # S3 Parquet, JSON, validation
-│   ├── 04-advanced-scenarios.md           # State, multi-source, streaming
-│   ├── 05-bidirectional-sync.md           # Extraction and export
-│   ├── 06-production-patterns.md          # Error handling, monitoring
-│   └── 07-reference.md                    # Complete pattern catalog
-│
-└── examples/                              # Complete working examples
-    ├── readme.md                          # Examples index
-    ├── common-patterns.ts                 # Reusable code patterns
-    ├── scenario-1-sftp-csv-inventory.ts   # Scenario 1: SFTP CSV
-    ├── scenario-2-s3-parquet-products.ts  # Scenario 2: S3 Parquet
-    ├── scenario-3-sftp-json-orders.ts     # Scenario 3: SFTP JSON
-    ├── scenario-4-s3-csv-state.ts         # Scenario 4: State management
-    ├── scenario-5-multi-source.ts         # Scenario 5: Multi-source
-    └── scenario-6-bidirectional.ts        # Scenario 6: Bidirectional sync
-```
-
-## 🔗 Related Documentation
-
-- [Universal Mapping Guide](../../02-CORE-GUIDES/mapping/mapping-readme.md) - Field transformation details
-- [Auto-Pagination Guide](../../02-CORE-GUIDES/auto-pagination/auto-pagination-readme.md) - Efficient data fetching
-- [Resolver Development Guide](../../02-CORE-GUIDES/mapping/resolvers/mapping-resolvers-readme.md) - Custom transformation functions
-- [Getting Started](../../00-START-HERE/getting-started.md) - SDK basics
-- [API Reference](../../02-CORE-GUIDES/api-reference/api-reference-readme.md) - Complete SDK API
-
-## 💡 Tips for Best Results
-
-1. **Start simple** - Begin with Scenario 1 (SFTP CSV) before complex patterns
-2. **Validate early** - Test transformations with sample data first
-3. **Use state management** - Always track processed files to prevent duplicates
-4. **Handle errors gracefully** - Move failed files to error folders for review
-5. **Monitor performance** - Log metrics for processing time and record counts
-6. **Test incrementally** - Validate each component (source, parser, mapper) separately
-
-## 🚦 Getting Started
-
-Ready to begin? Start with [Module 1: Foundations →](./modules/connector-scenarios-01-foundations.md)
-
----
-
-**Need Help?**
-
-- 📖 Browse [Examples](./examples/)
-- 🔍 Check [Production Patterns](./modules/connector-scenarios-06-production-patterns.md)
-- 📚 See [Best Practices](./modules/connector-scenarios-06-production-patterns.md#best-practices)
-- 📧 Contact support@fluentcommerce.com
+# Connector Scenarios Learning Path
+
+> **Complete guide to building production connectors with the Fluent Connect SDK**
+> Progressive learning modules with real-world implementation patterns and verified code examples
+
+## 📚 What You'll Learn
+
+This guide teaches you how to build end-to-end connectors for Fluent Commerce integrations using the SDK. By the end, you'll understand:
+
+- ✅ How to architect complete data flows from source to Fluent Commerce
+- ✅ How to combine data sources (SFTP, S3), parsers (CSV, JSON, Parquet), and transformations
+- ✅ How to implement validation, state management, and error handling
+- ✅ How to handle batch processing and monitoring
+- ✅ How to build bidirectional sync patterns (ingestion and extraction)
+- ✅ How to aggregate data from multiple sources
+- ✅ Real production patterns for inventory, orders, and product catalog sync
+
+## 🎯 Learning Path Overview
+
+This guide is organized into **7 progressive modules**. Follow them in order for the best learning experience:
+
+| Module                                             | Topic                                                                    | Level        |
+| -------------------------------------------------- | ------------------------------------------------------------------------ | ------------ |
+| [Module 1](./modules/connector-scenarios-01-foundations.md)            | **Foundations** - Connector architecture, data flow patterns             | Beginner     |
+| [Module 2](./modules/connector-scenarios-02-simple-scenarios.md)       | **Simple Scenarios** - SFTP CSV ingestion, basic transformations         | Beginner     |
+| [Module 3](./modules/connector-scenarios-03-intermediate-scenarios.md) | **Intermediate Scenarios** - S3 Parquet, JSON orders, validation         | Intermediate |
+| [Module 4](./modules/connector-scenarios-04-advanced-scenarios.md)     | **Advanced Scenarios** - State management, multi-source aggregation      | Advanced     |
+| [Module 5](./modules/connector-scenarios-05-bidirectional-sync.md)     | **Bidirectional Sync** - Extraction patterns, Fluent to external systems | Advanced     |
+| [Module 6](./modules/connector-scenarios-06-production-patterns.md)    | **Production Patterns** - Error handling, monitoring, deployment         | Intermediate |
+| [Module 7](./modules/connector-scenarios-07-reference.md)              | **Reference** - Complete pattern catalog, best practices                 | Reference    |
+
+## 🚀 Quick Navigation
+
+### By Use Case
+
+- **First time building a connector?** → Start with [Module 1: Foundations](./modules/connector-scenarios-01-foundations.md)
+- **Need SFTP CSV ingestion?** → Jump to [Module 2: Simple Scenarios](./modules/connector-scenarios-02-simple-scenarios.md)
+- **Need S3 Parquet processing?** → See [Module 3: Intermediate Scenarios](./modules/connector-scenarios-03-intermediate-scenarios.md)
+- **Need multi-source aggregation?** → Check [Module 4: Advanced Scenarios](./modules/connector-scenarios-04-advanced-scenarios.md)
+- **Need to export from Fluent?** → See [Module 5: Bidirectional Sync](./modules/connector-scenarios-05-bidirectional-sync.md)
+- **Want code examples?** → Browse [Examples Directory](./examples/)
+
+### By Scenario Type
+
+Different connector types require different patterns and complexity levels:
+
+| Scenario                 | Complexity | Data Source | Format   | Example                                                 |
+| ------------------------ | ---------- | ----------- | -------- | ------------------------------------------------------- |
+| SFTP CSV to Inventory    | Simple     | SFTP        | CSV      | [Examples](./examples/common-patterns.ts)  |
+| S3 Parquet to Products   | Medium     | S3          | Parquet  | [Examples](./examples/common-patterns.ts) |
+| SFTP JSON to Orders      | Medium     | SFTP        | JSON     | [Examples](./examples/common-patterns.ts)    |
+| S3 CSV with State        | Medium     | S3          | CSV      | [Examples](./examples/common-patterns.ts)        |
+| Multi-Source Aggregation | High       | SFTP+S3     | Multiple | [Examples](./examples/common-patterns.ts)        |
+| Fluent to SFTP Export    | Medium     | Fluent API  | JSON/CSV | [Examples](./examples/common-patterns.ts)       |
+
+### By Component
+
+Find examples by SDK component usage:
+
+| Component            | Use Case              | Example                                                              |
+| -------------------- | --------------------- | -------------------------------------------------------------------- |
+| `SftpDataSource`     | SFTP file operations  | [SFTP CSV Scenario](./examples/common-patterns.ts)    |
+| `S3DataSource`       | S3 file operations    | [S3 Parquet Scenario](./examples/common-patterns.ts) |
+| `UniversalMapper`    | Field transformations | All scenarios                                                        |
+| `StateService`       | Duplicate prevention  | [State Management Scenario](./examples/common-patterns.ts)  |
+| `FluentClient`       | Batch API operations  | [Multi-Source Scenario](./examples/common-patterns.ts)      |
+| `ExtractionOrchestrator`  | Fluent data export    | [Bidirectional Scenario](./examples/common-patterns.ts)    |
+
+## 📖 Quick Reference
+
+For quick lookups, see:
+
+- [Quick Reference Cheat Sheet](./connector-scenarios-quick-reference.md) - All patterns on one page
+- [Common Patterns](./examples/common-patterns.ts) - Copy-paste ready snippets
+- [Best Practices](./modules/connector-scenarios-06-production-patterns.md#best-practices) - Production guidelines
+
+## 🎓 Prerequisites
+
+Before starting this guide, you should:
+
+1. ✅ Have the SDK installed: `npm install @fluentcommerce/fc-connect-sdk`
+2. ✅ Have Fluent API credentials (clientId, clientSecret, retailerId)
+3. ✅ Understand basic SDK concepts (client creation, services)
+4. ✅ Have access to data sources (SFTP, S3) if testing integrations
+
+**New to the SDK?** Start with the [Getting Started Guide](../../00-START-HERE/getting-started.md) first.
+
+## 🔍 Key Concepts at a Glance
+
+### Complete Connector Architecture
+
+```typescript
+// A complete connector combines multiple SDK components:
+
+// 1. Data Source (where data comes from)
+const sftpSource = new SftpDataSource({...});
+
+// 2. Parser (how to read the data format)
+const parser = new CSVParserService({...});
+
+// 3. Field Mapper (how to transform fields)
+const mapper = new UniversalMapper({...});
+
+// 4. Fluent Client (where data goes)
+const client = await createClient({...});
+
+// 5. State Management (prevent duplicates)
+// ⚠️ IMPORTANT: StateService constructor takes only logger (optional)
+const stateService = new StateService(logger);
+// KV adapter must be passed to EVERY method call
+const kv = openKv(); // Or VersoriKVAdapter for Versori platform
+const workflowId = 'my-workflow';
+
+// 6. Orchestration (tie it all together)
+async function processFiles() {
+  const files = await sftpSource.listFiles();
+  for (const file of files) {
+    // KV adapter MUST be passed to every method
+    if (await stateService.isFileProcessed(kv, file.name, workflowId)) continue;
+
+    const content = await sftpSource.downloadFile(file.name);
+    const records = await parser.parse(content);
+    const transformed = await mapper.mapBatch(records);
+
+    await client.sendBatch(jobId, { entities: transformed });
+    // KV adapter MUST be passed to every method
+    await stateService.markFileProcessed(kv, file.name, {}, workflowId);
+  }
+}
+```
+
+### Data Flow Pattern
+
+```
+┌─────────────┐     ┌─────────┐     ┌─────────────┐     ┌──────────┐     ┌─────────────┐
+│ Data Source │ --> │  Parser │ --> │ Field Mapper│ --> │  Batch   │ --> │   Fluent    │
+│ SFTP/S3/etc │     │ CSV/JSON│     │  Transform  │     │   API    │     │  Commerce   │
+└─────────────┘     └─────────┘     └─────────────┘     └──────────┘     └─────────────┘
+       │                                    │                                     │
+       │                                    │                                     │
+       v                                    v                                     v
+┌─────────────┐                    ┌─────────────┐                      ┌─────────────┐
+│    State    │                    │ Validation  │                      │  Monitoring │
+│ Management  │                    │   Service   │                      │   Metrics   │
+└─────────────┘                    └─────────────┘                      └─────────────┘
+```
+
+### Scenario Complexity Comparison
+
+| Feature              | Simple              | Intermediate           | Advanced                   |
+| -------------------- | ------------------- | ---------------------- | -------------------------- |
+| **Data Sources**     | Single (SFTP or S3) | Single with options    | Multiple sources           |
+| **Formats**          | CSV only            | CSV, JSON, Parquet     | Multiple formats           |
+| **Validation**       | Basic field checks  | Schema validation      | Cross-source validation    |
+| **State Management** | None or simple      | File-level tracking    | Record-level + checkpoints |
+| **Error Handling**   | Basic try-catch     | Retry + move to errors | Recovery + notifications   |
+| **Batch Processing** | Single batch        | Multiple batches       | Streaming + chunking       |
+| **Monitoring**       | Basic logging       | Metrics tracking       | Full observability         |
+
+## 🛠️ Complete Example
+
+Here's a minimal but complete connector (SFTP CSV to Fluent Inventory):
+
+```typescript
+import {
+  createClient,
+  SftpDataSource,
+  UniversalMapper,
+  createConsoleLogger,
+} from '@fluentcommerce/fc-connect-sdk';
+
+// Initialize services
+const logger = createConsoleLogger();
+
+const sftpSource = new SftpDataSource(
+  {
+    type: 'SFTP_CSV',
+    connectionId: 'inventory-sftp',
+    name: 'Inventory SFTP',
+    settings: {
+      host: process.env.SFTP_HOST,
+      username: process.env.SFTP_USERNAME,
+      password: process.env.SFTP_PASSWORD,
+      remotePath: '/inventory/updates',
+      csvHeaders: ['sku', 'location', 'quantity', 'status'],
+    },
+  },
+  logger
+);
+
+const mapper = new UniversalMapper({
+  fields: {
+    ref: { source: 'sku', resolver: 'sdk.uppercase' },
+    locationRef: { source: 'location' },
+    qty: { source: 'quantity', resolver: 'sdk.parseInt' },
+    status: { source: 'status' },
+  },
+});
+
+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,
+  },
+});
+
+// Main process
+async function syncInventory() {
+  const files = await sftpSource.listFiles({ filePattern: '*.csv' });
+
+  for (const file of files) {
+    logger.info(`Processing: ${file.name}`);
+
+    const content = await sftpSource.downloadFile(file.name);
+    const parser = new CSVParserService();
+    const records = await parser.parse(content as string);
+
+    const transformed = [];
+    for (const record of records) {
+      const result = await mapper.map(record);
+      if (result.success) transformed.push(result.data);
+    }
+
+    const job = await client.createJob({
+      name: `Inventory Update - ${file.name}`,
+      retailerId: process.env.FLUENT_RETAILER_ID,
+    });
+
+    await client.sendBatch(job.id, {
+      action: 'UPSERT',
+      entityType: 'INVENTORY',
+      entities: transformed.map(r => ({
+        ref: r.ref,
+        productRef: r.ref,
+        locationRef: r.locationRef,
+        qty: r.qty,
+        status: r.status,
+      })),
+    });
+
+    logger.info(`✅ Processed ${transformed.length} records`);
+  }
+}
+
+syncInventory();
+```
+
+**What this does:**
+
+1. Connects to SFTP and lists CSV files
+2. Downloads and parses each file
+3. Transforms fields using UniversalMapper
+4. Sends data to Fluent via Batch API
+5. Logs progress and results
+
+## 📂 Repository Structure
+
+```
+docs/guides/connector-scenarios/
+├── readme.md                              # This file - main index
+├── quick-reference.md                     # Cheat sheet for patterns
+│
+├── modules/                               # Learning modules
+│   ├── 01-foundations.md                  # Architecture and concepts
+│   ├── 02-simple-scenarios.md             # SFTP CSV basics
+│   ├── 03-intermediate-scenarios.md       # S3 Parquet, JSON, validation
+│   ├── 04-advanced-scenarios.md           # State, multi-source, streaming
+│   ├── 05-bidirectional-sync.md           # Extraction and export
+│   ├── 06-production-patterns.md          # Error handling, monitoring
+│   └── 07-reference.md                    # Complete pattern catalog
+│
+└── examples/                              # Complete working examples
+    ├── readme.md                          # Examples index
+    ├── common-patterns.ts                 # Reusable code patterns
+    ├── scenario-1-sftp-csv-inventory.ts   # Scenario 1: SFTP CSV
+    ├── scenario-2-s3-parquet-products.ts  # Scenario 2: S3 Parquet
+    ├── scenario-3-sftp-json-orders.ts     # Scenario 3: SFTP JSON
+    ├── scenario-4-s3-csv-state.ts         # Scenario 4: State management
+    ├── scenario-5-multi-source.ts         # Scenario 5: Multi-source
+    └── scenario-6-bidirectional.ts        # Scenario 6: Bidirectional sync
+```
+
+## 🔗 Related Documentation
+
+- [Universal Mapping Guide](../../02-CORE-GUIDES/mapping/mapping-readme.md) - Field transformation details
+- [Auto-Pagination Guide](../../02-CORE-GUIDES/auto-pagination/auto-pagination-readme.md) - Efficient data fetching
+- [Resolver Development Guide](../../02-CORE-GUIDES/mapping/resolvers/mapping-resolvers-readme.md) - Custom transformation functions
+- [Getting Started](../../00-START-HERE/getting-started.md) - SDK basics
+- [API Reference](../../02-CORE-GUIDES/api-reference/api-reference-readme.md) - Complete SDK API
+
+## 💡 Tips for Best Results
+
+1. **Start simple** - Begin with Scenario 1 (SFTP CSV) before complex patterns
+2. **Validate early** - Test transformations with sample data first
+3. **Use state management** - Always track processed files to prevent duplicates
+4. **Handle errors gracefully** - Move failed files to error folders for review
+5. **Monitor performance** - Log metrics for processing time and record counts
+6. **Test incrementally** - Validate each component (source, parser, mapper) separately
+
+## 🚦 Getting Started
+
+Ready to begin? Start with [Module 1: Foundations →](./modules/connector-scenarios-01-foundations.md)
+
+---
+
+**Need Help?**
+
+- 📖 Browse [Examples](./examples/)
+- 🔍 Check [Production Patterns](./modules/connector-scenarios-06-production-patterns.md)
+- 📚 See [Best Practices](./modules/connector-scenarios-06-production-patterns.md#best-practices)
+- 📧 Contact support@fluentcommerce.com