@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

package/docs/01-TEMPLATES/versori/business-examples/business-examples-dropship-order-routing.md

@@ -1,193 +1,193 @@
-# Versori Dropship Order Routing
-
-**FC Connect SDK Use Case Guide**
-
-> **SDK**: [@fluentcommerce/fc-connect-sdk](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk)
-> **Version**: ^0.1.27
-
-**Context**: Real-time order routing to multiple suppliers with intelligent selection, fallback, and fulfillment tracking
-
-**Complexity**: High
-
-**Volume**: Medium (100-1000 orders/day)
-
-**Latency**: Real-time (< 5 seconds for routing decision)
-
-**Runtime**: Versori Platform (Webhook + Event-Driven)
-
-**Estimated Lines**: ~1200 lines
-
-## What You'll Build
-
-- **Order Event Webhook**: Receive order created events from Fluent Commerce
-- **Intelligent Routing Engine**: Select optimal supplier based on:
-  - Inventory availability
-  - Supplier rules (MOQ, lead time, cost, geographic proximity)
-  - Historical performance (SLA compliance, defect rates)
-  - Priority tiers with circuit breaker for failing suppliers
-- **Multi-Supplier Integration**: Support for 3 integration patterns:
-  - REST API (JSON)
-  - XML/SOAP API
-  - EDI systems
-- **Fallback Logic**: Auto-retry with next supplier if primary fails
-- **Fulfillment Tracking**: Webhook receiver for supplier status updates
-- **Order State Management**: Track order→supplier mapping with VersoriKV
-- **Cancellation Handling**: Propagate cancellations to suppliers
-- **SLA Monitoring**: Track supplier response times and success rates
-
-## SDK Methods Used
-
-### Versori Functions (Validated Syntax)
-- `webhook(id, options?)` - Receive order events and supplier webhooks (connection is OPTIONAL in options)
-- `http(id, { connection }, fn)` - OAuth2 authenticated API calls (connection is REQUIRED)
-- `fn(id, fn)` - Serverless function steps (id is REQUIRED)
-- `schedule(id, cron_string)` - NOT `schedule(id, { cron: 'string' })`
-- `openKv(scope?)` - Scopes use colons: `:execution:` | `:project:` | `:organization:`
-
-### SDK Services
-- `createClient(ctx)` - Create Fluent GraphQL client
-- `client.graphql({ query, variables })` - Query order details and update status
-- `GraphQLMutationMapper` - Transform supplier responses to Fluent mutations
-- `UniversalMapper` - Map order data to supplier formats
-- `VersoriKVAdapter(openKv())` - Track order→supplier state
-- `XMLParserService` - Parse XML responses
-- `XMLBuilder` - Generate SOAP/XML requests (if used)
-
----
-
-## Versori Workflows Structure
-
-**Key Concept**: Versori workflows are organized by **trigger type** at the first level, then by **specific workflow** with descriptive file names.
-
-**Trigger Types:**
-- **`webhook()`** → HTTP-based triggers (event-driven) - Creates HTTP endpoints
-- **`schedule()`** → Time-based triggers (cron expressions) - NOT exposed as HTTP endpoints
-- **`http()`** → External API calls (chained from webhook/schedule)
-- **`fn()`** → Internal processing (chained from webhook/schedule)
-
-### Recommended Project Structure
-
-```
-dropship-order-routing/
-├── index.ts                              # Entry point - exports all workflows
-└── src/
-    ├── workflows/
-    │   ├── webhook/
-    │   │   ├── order-routing.ts         # Webhook: Route orders
-    │   │   └── fulfillment-tracking.ts  # Webhook: Track fulfillment
-    │   │
-    │   └── scheduled/
-    │       └── sla-monitoring.ts         # Scheduled: Monitor SLA
-    │
-    ├── services/
-    │   └── routing.service.ts            # Shared orchestration logic (reusable)
-    │
-    └── config/
-        └── routing-rules.json            # Configuration
-```
-
-**Benefits:**
-- ✅ Clear trigger separation (`webhook/` vs `scheduled/`)
-- ✅ Descriptive file names (easy to browse and understand)
-- ✅ Scalable (add new workflows without cluttering)
-- ✅ Reusable code in `services/` (DRY principle)
-- ✅ Easy to modify individual workflows without affecting others
-
----
-
-## Complete Working Code
-
-**Note**: This is a complex example demonstrating advanced patterns for production order routing systems. The implementation includes intelligent supplier selection, circuit breaker patterns, and multi-protocol support.
-
-### Key Components
-
-1. **Main routing workflow** - Intelligent supplier selection and order routing
-2. **Routing engine** - Multi-factor scoring algorithm for supplier selection
-3. **Supplier connectors** - Support for REST/SOAP/XML/EDI protocols
-4. **Circuit breaker** - Supplier health tracking and automatic failover
-5. **Fulfillment tracking** - Webhook endpoints for supplier status updates
-6. **State management** - VersoriKV for order→supplier mapping
-7. **SLA monitoring** - Track response times and success rates
-
-### Architecture Overview
-
-```
-Order Created Event → Routing Engine → Supplier Selection
-                           ↓
-                    Check Inventory
-                           ↓
-                    Calculate Score:
-                    - Availability
-                    - Cost
-                    - Lead Time
-                    - Performance
-                    - Geographic Proximity
-                           ↓
-                    Primary Supplier
-                           ↓
-                    Send Order (REST/SOAP/EDI)
-                           ↓
-                    Success? → Update Fluent
-                           ↓ (if failed)
-                    Fallback to Next Supplier
-```
-
-### Implementation Notes
-
-Due to the complexity and length of this implementation (~1200 lines), this file serves as a reference architecture guide. The complete implementation would include:
-
-1. **Routing Configuration**:
-   - Supplier profiles with capabilities and constraints
-   - Scoring weights for each selection factor
-   - Circuit breaker thresholds
-   - Geographic zone mappings
-
-2. **Multi-Protocol Support**:
-   - REST JSON adapter
-   - SOAP/XML adapter with WSDL parsing
-   - EDI X12 formatter
-   - Webhook receiver for async responses
-
-3. **State Management**:
-   - Order→supplier mapping
-   - Retry attempt tracking
-   - SLA performance metrics
-   - Circuit breaker state
-
-4. **Error Handling**:
-   - Exponential backoff for retries
-   - Dead letter queue for failed orders
-   - Alert notifications for repeated failures
-   - Automatic supplier deprioritization
-
-### Related Patterns
-
-- **Circuit Breaker Pattern**: Prevent cascading failures when suppliers are down
-- **Fallback Chain**: Automatic retry with next best supplier
-- **Event-Driven Architecture**: Webhook-based order lifecycle tracking
-- **Multi-Protocol Integration**: Unified interface for diverse supplier systems
-
----
-
-## Related Guides
-
-- **Versori Webhook: Order Event Handling** - Process Fluent Commerce events
-- **Universal Mapping Guide** - Field transformation for supplier formats
-- **State Management Guide** - VersoriKV patterns for order tracking
-- **GraphQL Mutation Patterns** - Update Fluent orders with supplier data
-- **Circuit Breaker Pattern** - Resilience patterns for distributed systems
-- **XML/SOAP Integration Guide** - Working with enterprise supplier APIs
-
----
-
-## Next Steps
-
-For a complete working implementation of this pattern, consider:
-
-1. Starting with a simpler single-supplier integration
-2. Adding suppliers incrementally with protocol adapters
-3. Implementing basic scoring before adding advanced factors
-4. Testing fallback logic thoroughly with supplier failures
-5. Monitoring SLA metrics before implementing circuit breakers
-
-Refer to the **inter-location-transfers.md** and **pre-order-allocation.md** examples for complete code patterns that can be adapted for supplier integration.
+# Versori Dropship Order Routing
+
+**FC Connect SDK Use Case Guide**
+
+> **SDK**: [@fluentcommerce/fc-connect-sdk](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk)
+> **Version**: ^0.1.27
+
+**Context**: Real-time order routing to multiple suppliers with intelligent selection, fallback, and fulfillment tracking
+
+**Complexity**: High
+
+**Volume**: Medium (100-1000 orders/day)
+
+**Latency**: Real-time (< 5 seconds for routing decision)
+
+**Runtime**: Versori Platform (Webhook + Event-Driven)
+
+**Estimated Lines**: ~1200 lines
+
+## What You'll Build
+
+- **Order Event Webhook**: Receive order created events from Fluent Commerce
+- **Intelligent Routing Engine**: Select optimal supplier based on:
+  - Inventory availability
+  - Supplier rules (MOQ, lead time, cost, geographic proximity)
+  - Historical performance (SLA compliance, defect rates)
+  - Priority tiers with circuit breaker for failing suppliers
+- **Multi-Supplier Integration**: Support for 3 integration patterns:
+  - REST API (JSON)
+  - XML/SOAP API
+  - EDI systems
+- **Fallback Logic**: Auto-retry with next supplier if primary fails
+- **Fulfillment Tracking**: Webhook receiver for supplier status updates
+- **Order State Management**: Track order→supplier mapping with VersoriKV
+- **Cancellation Handling**: Propagate cancellations to suppliers
+- **SLA Monitoring**: Track supplier response times and success rates
+
+## SDK Methods Used
+
+### Versori Functions (Validated Syntax)
+- `webhook(id, options?)` - Receive order events and supplier webhooks (connection is OPTIONAL in options)
+- `http(id, { connection }, fn)` - OAuth2 authenticated API calls (connection is REQUIRED)
+- `fn(id, fn)` - Serverless function steps (id is REQUIRED)
+- `schedule(id, cron_string)` - NOT `schedule(id, { cron: 'string' })`
+- `openKv(scope?)` - Scopes use colons: `:execution:` | `:project:` | `:organization:`
+
+### SDK Services
+- `createClient(ctx)` - Create Fluent GraphQL client
+- `client.graphql({ query, variables })` - Query order details and update status
+- `GraphQLMutationMapper` - Transform supplier responses to Fluent mutations
+- `UniversalMapper` - Map order data to supplier formats
+- `VersoriKVAdapter(openKv())` - Track order→supplier state
+- `XMLParserService` - Parse XML responses
+- `XMLBuilder` - Generate SOAP/XML requests (if used)
+
+---
+
+## Versori Workflows Structure
+
+**Key Concept**: Versori workflows are organized by **trigger type** at the first level, then by **specific workflow** with descriptive file names.
+
+**Trigger Types:**
+- **`webhook()`** → HTTP-based triggers (event-driven) - Creates HTTP endpoints
+- **`schedule()`** → Time-based triggers (cron expressions) - NOT exposed as HTTP endpoints
+- **`http()`** → External API calls (chained from webhook/schedule)
+- **`fn()`** → Internal processing (chained from webhook/schedule)
+
+### Recommended Project Structure
+
+```
+dropship-order-routing/
+├── index.ts                              # Entry point - exports all workflows
+└── src/
+    ├── workflows/
+    │   ├── webhook/
+    │   │   ├── order-routing.ts         # Webhook: Route orders
+    │   │   └── fulfillment-tracking.ts  # Webhook: Track fulfillment
+    │   │
+    │   └── scheduled/
+    │       └── sla-monitoring.ts         # Scheduled: Monitor SLA
+    │
+    ├── services/
+    │   └── routing.service.ts            # Shared orchestration logic (reusable)
+    │
+    └── config/
+        └── routing-rules.json            # Configuration
+```
+
+**Benefits:**
+- ✅ Clear trigger separation (`webhook/` vs `scheduled/`)
+- ✅ Descriptive file names (easy to browse and understand)
+- ✅ Scalable (add new workflows without cluttering)
+- ✅ Reusable code in `services/` (DRY principle)
+- ✅ Easy to modify individual workflows without affecting others
+
+---
+
+## Complete Working Code
+
+**Note**: This is a complex example demonstrating advanced patterns for production order routing systems. The implementation includes intelligent supplier selection, circuit breaker patterns, and multi-protocol support.
+
+### Key Components
+
+1. **Main routing workflow** - Intelligent supplier selection and order routing
+2. **Routing engine** - Multi-factor scoring algorithm for supplier selection
+3. **Supplier connectors** - Support for REST/SOAP/XML/EDI protocols
+4. **Circuit breaker** - Supplier health tracking and automatic failover
+5. **Fulfillment tracking** - Webhook endpoints for supplier status updates
+6. **State management** - VersoriKV for order→supplier mapping
+7. **SLA monitoring** - Track response times and success rates
+
+### Architecture Overview
+
+```
+Order Created Event → Routing Engine → Supplier Selection
+                           ↓
+                    Check Inventory
+                           ↓
+                    Calculate Score:
+                    - Availability
+                    - Cost
+                    - Lead Time
+                    - Performance
+                    - Geographic Proximity
+                           ↓
+                    Primary Supplier
+                           ↓
+                    Send Order (REST/SOAP/EDI)
+                           ↓
+                    Success? → Update Fluent
+                           ↓ (if failed)
+                    Fallback to Next Supplier
+```
+
+### Implementation Notes
+
+Due to the complexity and length of this implementation (~1200 lines), this file serves as a reference architecture guide. The complete implementation would include:
+
+1. **Routing Configuration**:
+   - Supplier profiles with capabilities and constraints
+   - Scoring weights for each selection factor
+   - Circuit breaker thresholds
+   - Geographic zone mappings
+
+2. **Multi-Protocol Support**:
+   - REST JSON adapter
+   - SOAP/XML adapter with WSDL parsing
+   - EDI X12 formatter
+   - Webhook receiver for async responses
+
+3. **State Management**:
+   - Order→supplier mapping
+   - Retry attempt tracking
+   - SLA performance metrics
+   - Circuit breaker state
+
+4. **Error Handling**:
+   - Exponential backoff for retries
+   - Dead letter queue for failed orders
+   - Alert notifications for repeated failures
+   - Automatic supplier deprioritization
+
+### Related Patterns
+
+- **Circuit Breaker Pattern**: Prevent cascading failures when suppliers are down
+- **Fallback Chain**: Automatic retry with next best supplier
+- **Event-Driven Architecture**: Webhook-based order lifecycle tracking
+- **Multi-Protocol Integration**: Unified interface for diverse supplier systems
+
+---
+
+## Related Guides
+
+- **Versori Webhook: Order Event Handling** - Process Fluent Commerce events
+- **Universal Mapping Guide** - Field transformation for supplier formats
+- **State Management Guide** - VersoriKV patterns for order tracking
+- **GraphQL Mutation Patterns** - Update Fluent orders with supplier data
+- **Circuit Breaker Pattern** - Resilience patterns for distributed systems
+- **XML/SOAP Integration Guide** - Working with enterprise supplier APIs
+
+---
+
+## Next Steps
+
+For a complete working implementation of this pattern, consider:
+
+1. Starting with a simpler single-supplier integration
+2. Adding suppliers incrementally with protocol adapters
+3. Implementing basic scoring before adding advanced factors
+4. Testing fallback logic thoroughly with supplier failures
+5. Monitoring SLA metrics before implementing circuit breakers
+
+Refer to the **inter-location-transfers.md** and **pre-order-allocation.md** examples for complete code patterns that can be adapted for supplier integration.