@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/03-PATTERN-GUIDES/integration-patterns/integration-patterns-readme.md

@@ -1,134 +1,134 @@
-# Integration Patterns Learning Path
-
-> **Complete guide to integration patterns for Fluent Commerce SDK**
-> Progressive learning modules with real schema examples and verified code patterns
-
-## 📚 What You'll Learn
-
-This guide teaches you proven architectural patterns for building robust Fluent Commerce integrations. By the end, you'll understand:
-
-- ✅ When to use real-time vs batch processing
-- ✅ How to implement scheduled workflows with SDK services
-- ✅ Delta sync strategies for incremental updates
-- ✅ Webhook processing with GraphQL mutations and signature validation
-- ✅ Error handling, retry, and resilience patterns
-- ✅ Advanced integration services:
-  - Webhook validation with cryptographic signatures
-  - Partial batch recovery for resumable workflows
-  - Job lifecycle tracking and monitoring
-  - Preflight validation for large batches
-
-## 🎯 Learning Path Overview
-
-This guide is organized into **6 progressive modules**. Follow them in order for the best learning experience:
-
-| Module | Topic | Level | Estimated Time |
-|--------|-------|-------|----------------|
-| [Module 1](./modules/integration-patterns-01-real-time-processing.md) | **Real-Time Processing** - Immediate event processing | Beginner | 30 minutes |
-| [Module 2](./modules/integration-patterns-02-batch-processing.md) | **Batch Processing** - Scheduled high-volume workflows + Job tracking, partial recovery | Intermediate | 60 minutes |
-| [Module 3](./modules/integration-patterns-03-delta-sync.md) | **Delta Sync** - Change detection & incremental updates | Advanced | 60 minutes |
-| [Module 4](./modules/integration-patterns-04-webhook-patterns.md) | **Webhook Patterns** - Event-driven integration + **NEW**: Signature validation | Intermediate | 45 minutes |
-| [Module 5](./modules/integration-patterns-05-error-handling.md) | **Error Handling** - Resilience & retry strategies | Intermediate | 45 minutes |
-| [Module 6](./modules/integration-patterns-06-advanced-integration-services.md) | **Advanced Integration Services** - Webhook validation, batch recovery, job tracking, preflight validation | Advanced | 60 minutes |
-
-## 🚀 Quick Navigation
-
-### By Use Case
-
-- **First time building integrations?** → Start with [Module 1: Real-Time Processing](./modules/integration-patterns-01-real-time-processing.md)
-- **Need to process large files daily?** → Jump to [Module 2: Batch Processing](./modules/integration-patterns-02-batch-processing.md)
-- **Want to sync only changes?** → See [Module 3: Delta Sync](./modules/integration-patterns-03-delta-sync.md)
-- **Building webhook endpoints?** → Check [Module 4: Webhook Patterns](./modules/integration-patterns-04-webhook-patterns.md)
-- **Need error handling?** → Review [Module 5: Error Handling](./modules/integration-patterns-05-error-handling.md)
-- **Need webhook validation or job tracking?** → See [Module 6: Advanced Integration Services](./modules/integration-patterns-06-advanced-integration-services.md)
-
-### By Pattern Type
-
-| Pattern | Complexity | Best For | Latency | Module |
-|---------|------------|----------|---------|--------|
-| **Real-Time Events** | Low | Order webhooks | Seconds | Module 1 |
-| **Scheduled Batch** | Medium | Daily inventory sync | Hours | Module 2 |
-| **Delta Sync** | High | Incremental updates | Minutes | Module 3 |
-| **Webhook-Triggered** | Low-Medium | SFCC/external events | Seconds | Module 4 |
-| **Error Resilience** | Medium | All patterns | N/A | Module 5 |
-| **Webhook Validation** | Low | Secure webhooks | Seconds | Module 6 |
-| **Batch Recovery** | Medium | Partial failures | Variable | Module 6 |
-| **Job Tracking** | Low | Async workflows | N/A | Module 6 |
-| **Preflight Validation** | Low | Large batches | Seconds | Module 6 |
-
-## 📖 Quick Reference
-
-For quick lookups, see:
-- **[Quick Reference](../../02-CORE-GUIDES/advanced-services/advanced-services-quick-reference.md)** - Pattern decision matrix
-- **[Complete Examples](../../01-TEMPLATES/readme.md)** - Production-ready implementations
-- **[Pattern Selection](./integration-patterns-quick-reference.md)** - Choose the right pattern
-
-## 🎓 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. ✅ Be familiar with SDK basics (`createClient`, `FluentClient`)
-4. ✅ Understand GraphQL queries and mutations
-
-**New to the SDK?** Start with the [Getting Started Guide](../../00-START-HERE/getting-started.md) first.
-
-## 🔍 Pattern Overview at a Glance
-
-### Volume Guidelines
-
-| Events/Hour | Recommended Pattern | Infrastructure | Example |
-|-------------|---------------------|----------------|---------|
-| < 100 | Real-Time (Module 1) | Simple | Order webhooks |
-| 100-1,000 | Real-Time/Webhook (1/4) | Simple | SFCC events |
-| 1,000-10,000 | Batch (Module 2) | Scheduled | Daily inventory |
-| > 10,000 | Batch + Delta (2+3) | Advanced | Multi-channel sync |
-
-### Pattern Combinations
-
-Common pattern combinations for production systems:
-
-1. **Webhook + Batch** - Real-time orders + daily inventory
-2. **Batch + Delta** - Full sync daily + hourly changes
-3. **Real-Time + Error Handling** - Critical flow with resilience
-
-## 📚 Complete Working Examples
-
-All patterns link to complete, production-ready implementations:
-
-### Versori Platform
-- [XML Order Ingestion](../../01-TEMPLATES/versori/webhooks/template-webhook-xml-order-ingestion.md)
-- [CSV Inventory Batch API](../../01-TEMPLATES/versori/workflows/ingestion/batch-api/template-ingestion-s3-csv-inventory-batch.md)
-- [SFTP CSV Inventory Batch API](../../01-TEMPLATES/versori/workflows/ingestion/batch-api/template-ingestion-sftp-csv-inventory-batch.md)
-
-### Standalone Scripts
-- [S3 CSV → Batch API](../../01-TEMPLATES/standalone/s3-csv-batch-api.md)
-- [Webhook Payload Processing](../../01-TEMPLATES/standalone/webhook-payload-processing.md)
-
-### Reusable Patterns
-- [Error Handling & Retry](../../01-TEMPLATES/patterns/error-handling-retry.md)
-- [State & Duplicate Prevention](../../01-TEMPLATES/patterns/state-duplicate-prevention.md)
-- [CSV Schema Validation](../../01-TEMPLATES/patterns/csv-schema-validation-and-rejection-report.md)
-
-## 🎯 Learning Outcomes
-
-After completing this guide, you will be able to:
-
-- ✅ Choose the right integration pattern for your use case
-- ✅ Implement real-time event processing with SDK services
-- ✅ Build scheduled batch workflows with Batch API
-- ✅ Add delta sync for efficient incremental updates
-- ✅ Process webhooks with proper validation
-- ✅ Implement robust error handling and retry logic
-- ✅ Use advanced services (webhook validation, batch recovery, job tracking, preflight validation)
-- ✅ Combine patterns for production-ready integrations
-
-## 🚦 Next Steps
-
-1. **Start Learning**: Begin with [Module 1: Real-Time Processing](./modules/integration-patterns-01-real-time-processing.md)
-2. **Explore Examples**: Browse [Use Case Examples](../../01-TEMPLATES/readme.md) for complete implementations
-
----
-
-**Ready to build?** Start with [Module 1: Real-Time Processing](./modules/integration-patterns-01-real-time-processing.md) →
+# Integration Patterns Learning Path
+
+> **Complete guide to integration patterns for Fluent Commerce SDK**
+> Progressive learning modules with real schema examples and verified code patterns
+
+## 📚 What You'll Learn
+
+This guide teaches you proven architectural patterns for building robust Fluent Commerce integrations. By the end, you'll understand:
+
+- ✅ When to use real-time vs batch processing
+- ✅ How to implement scheduled workflows with SDK services
+- ✅ Delta sync strategies for incremental updates
+- ✅ Webhook processing with GraphQL mutations and signature validation
+- ✅ Error handling, retry, and resilience patterns
+- ✅ Advanced integration services:
+  - Webhook validation with cryptographic signatures
+  - Partial batch recovery for resumable workflows
+  - Job lifecycle tracking and monitoring
+  - Preflight validation for large batches
+
+## 🎯 Learning Path Overview
+
+This guide is organized into **6 progressive modules**. Follow them in order for the best learning experience:
+
+| Module | Topic | Level | Estimated Time |
+|--------|-------|-------|----------------|
+| [Module 1](./modules/integration-patterns-01-real-time-processing.md) | **Real-Time Processing** - Immediate event processing | Beginner | 30 minutes |
+| [Module 2](./modules/integration-patterns-02-batch-processing.md) | **Batch Processing** - Scheduled high-volume workflows + Job tracking, partial recovery | Intermediate | 60 minutes |
+| [Module 3](./modules/integration-patterns-03-delta-sync.md) | **Delta Sync** - Change detection & incremental updates | Advanced | 60 minutes |
+| [Module 4](./modules/integration-patterns-04-webhook-patterns.md) | **Webhook Patterns** - Event-driven integration + **NEW**: Signature validation | Intermediate | 45 minutes |
+| [Module 5](./modules/integration-patterns-05-error-handling.md) | **Error Handling** - Resilience & retry strategies | Intermediate | 45 minutes |
+| [Module 6](./modules/integration-patterns-06-advanced-integration-services.md) | **Advanced Integration Services** - Webhook validation, batch recovery, job tracking, preflight validation | Advanced | 60 minutes |
+
+## 🚀 Quick Navigation
+
+### By Use Case
+
+- **First time building integrations?** → Start with [Module 1: Real-Time Processing](./modules/integration-patterns-01-real-time-processing.md)
+- **Need to process large files daily?** → Jump to [Module 2: Batch Processing](./modules/integration-patterns-02-batch-processing.md)
+- **Want to sync only changes?** → See [Module 3: Delta Sync](./modules/integration-patterns-03-delta-sync.md)
+- **Building webhook endpoints?** → Check [Module 4: Webhook Patterns](./modules/integration-patterns-04-webhook-patterns.md)
+- **Need error handling?** → Review [Module 5: Error Handling](./modules/integration-patterns-05-error-handling.md)
+- **Need webhook validation or job tracking?** → See [Module 6: Advanced Integration Services](./modules/integration-patterns-06-advanced-integration-services.md)
+
+### By Pattern Type
+
+| Pattern | Complexity | Best For | Latency | Module |
+|---------|------------|----------|---------|--------|
+| **Real-Time Events** | Low | Order webhooks | Seconds | Module 1 |
+| **Scheduled Batch** | Medium | Daily inventory sync | Hours | Module 2 |
+| **Delta Sync** | High | Incremental updates | Minutes | Module 3 |
+| **Webhook-Triggered** | Low-Medium | SFCC/external events | Seconds | Module 4 |
+| **Error Resilience** | Medium | All patterns | N/A | Module 5 |
+| **Webhook Validation** | Low | Secure webhooks | Seconds | Module 6 |
+| **Batch Recovery** | Medium | Partial failures | Variable | Module 6 |
+| **Job Tracking** | Low | Async workflows | N/A | Module 6 |
+| **Preflight Validation** | Low | Large batches | Seconds | Module 6 |
+
+## 📖 Quick Reference
+
+For quick lookups, see:
+- **[Quick Reference](../../02-CORE-GUIDES/advanced-services/advanced-services-quick-reference.md)** - Pattern decision matrix
+- **[Complete Examples](../../01-TEMPLATES/readme.md)** - Production-ready implementations
+- **[Pattern Selection](./integration-patterns-quick-reference.md)** - Choose the right pattern
+
+## 🎓 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. ✅ Be familiar with SDK basics (`createClient`, `FluentClient`)
+4. ✅ Understand GraphQL queries and mutations
+
+**New to the SDK?** Start with the [Getting Started Guide](../../00-START-HERE/getting-started.md) first.
+
+## 🔍 Pattern Overview at a Glance
+
+### Volume Guidelines
+
+| Events/Hour | Recommended Pattern | Infrastructure | Example |
+|-------------|---------------------|----------------|---------|
+| < 100 | Real-Time (Module 1) | Simple | Order webhooks |
+| 100-1,000 | Real-Time/Webhook (1/4) | Simple | SFCC events |
+| 1,000-10,000 | Batch (Module 2) | Scheduled | Daily inventory |
+| > 10,000 | Batch + Delta (2+3) | Advanced | Multi-channel sync |
+
+### Pattern Combinations
+
+Common pattern combinations for production systems:
+
+1. **Webhook + Batch** - Real-time orders + daily inventory
+2. **Batch + Delta** - Full sync daily + hourly changes
+3. **Real-Time + Error Handling** - Critical flow with resilience
+
+## 📚 Complete Working Examples
+
+All patterns link to complete, production-ready implementations:
+
+### Versori Platform
+- [XML Order Ingestion](../../01-TEMPLATES/versori/webhooks/template-webhook-xml-order-ingestion.md)
+- [CSV Inventory Batch API](../../01-TEMPLATES/versori/workflows/ingestion/batch-api/template-ingestion-s3-csv-inventory-batch.md)
+- [SFTP CSV Inventory Batch API](../../01-TEMPLATES/versori/workflows/ingestion/batch-api/template-ingestion-sftp-csv-inventory-batch.md)
+
+### Standalone Scripts
+- [S3 CSV → Batch API](../../01-TEMPLATES/standalone/s3-csv-batch-api.md)
+- [Webhook Payload Processing](../../01-TEMPLATES/standalone/webhook-payload-processing.md)
+
+### Reusable Patterns
+- [Error Handling & Retry](../../01-TEMPLATES/patterns/error-handling-retry.md)
+- [State & Duplicate Prevention](../../01-TEMPLATES/patterns/state-duplicate-prevention.md)
+- [CSV Schema Validation](../../01-TEMPLATES/patterns/csv-schema-validation-and-rejection-report.md)
+
+## 🎯 Learning Outcomes
+
+After completing this guide, you will be able to:
+
+- ✅ Choose the right integration pattern for your use case
+- ✅ Implement real-time event processing with SDK services
+- ✅ Build scheduled batch workflows with Batch API
+- ✅ Add delta sync for efficient incremental updates
+- ✅ Process webhooks with proper validation
+- ✅ Implement robust error handling and retry logic
+- ✅ Use advanced services (webhook validation, batch recovery, job tracking, preflight validation)
+- ✅ Combine patterns for production-ready integrations
+
+## 🚦 Next Steps
+
+1. **Start Learning**: Begin with [Module 1: Real-Time Processing](./modules/integration-patterns-01-real-time-processing.md)
+2. **Explore Examples**: Browse [Use Case Examples](../../01-TEMPLATES/readme.md) for complete implementations
+
+---
+
+**Ready to build?** Start with [Module 1: Real-Time Processing](./modules/integration-patterns-01-real-time-processing.md) →