@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/01-TEMPLATES/versori/versori-platform-guide.md

@@ -1,201 +1,201 @@
-# Versori Platform Templates
-
-> **Production-ready templates for Versori platform**
-> Complete integration examples for webhooks, scheduled workflows, and patterns
-
-## Overview
-
-This directory contains production-ready templates designed specifically for the Versori integration platform. Each template follows Versori best practices and leverages platform-specific features like KV storage, connections, and runtime context.
-
-## Directory Structure
-
-```
-versori/
-├── business-examples/      # Real-world business scenarios
-├── patterns/               # Versori-specific patterns
-├── webhooks/               # Webhook-triggered integrations
-└── workflows/             # Scheduled and manual workflows
-    ├── extraction/         # Data extraction workflows
-    └── ingestion/          # Data ingestion workflows
-```
-
-## Quick Navigation
-
-| I Want To... | Directory | Complexity |
-|--|--|--|
-| **Handle webhook triggers** | [webhooks/](./webhooks/) | Medium |
-| **Schedule data extraction** | [workflows/extraction/](./workflows/extraction/) | Medium |
-| **Schedule data ingestion** | [workflows/ingestion/](./workflows/ingestion/) | Medium |
-| **Learn Versori patterns** | [patterns/](./patterns/) | Advanced |
-| **See business examples** | [business-examples/](./business-examples/) | Advanced |
-
-## Available Directories
-
-### [Business Examples](./business-examples/)
-Real-world business scenarios:
-- Dropship Order Routing
-- GraphQL Parquet Extraction
-- Inter-Location Transfers
-- Pre-Order Allocation
-
-### [Patterns](./patterns/)
-Versori-specific patterns:
-- Dual Workflow Connector
-- KV State Management
-- XML Response Patterns
-- Connection Validation
-
-### [Webhooks](./webhooks/)
-Webhook-triggered integrations:
-- ASN Purchase Order
-- Dropship Routing
-- Flash Sale Reserve
-- RMA Returns Comprehensive
-- Payment Gateway Integration
-- Generic XML Order
-- XML Order Ingestion
-
-### [Workflows](./workflows/)
-Scheduled and manual workflows:
-- **[Extraction](./workflows/extraction/)** - Export data from Fluent
-- **[Ingestion](./workflows/ingestion/)** - Import data to Fluent
-
-## Key Features
-
-All Versori templates include:
-- **KV Storage** - State management with Versori KV
-- **Connections** - Pre-configured connection objects
-- **Context API** - Access to `ctx.log`, `ctx.connections`, `ctx.kv`
-- **Runtime Detection** - Automatic Versori runtime configuration
-- **Error Handling** - Platform-specific error patterns
-
-## Using These Templates
-
-1. **Choose a template** that matches your use case
-2. **Copy to Versori** platform
-3. **Configure connections** in Versori UI
-4. **Set environment variables**
-5. **Test** with sample data
-6. **Deploy** and monitor
-
-## SDK Automatic Behaviors (v0.1.40+)
-
-Recent SDK enhancements provide automatic validation and retry for improved reliability:
-
-### retailerId Validation
-
-**Event/Job/Batch APIs automatically validate `retailerId` before API calls:**
-- Fail-fast with clear error messages if missing
-- Three configuration methods: connection variables, client.setRetailerId(), or event payload
-- See [Event API Guide](./workflows/ingestion/event-api/event-api-guide.md) and [Batch API Guide](./workflows/ingestion/batch-api/batch-api-guide.md) for details
-
-**Example:**
-```typescript
-// Option 1: Via connection (recommended)
-// Configure in Versori Connection UI: { "retailerId": "1" }
-const client = await createClient(ctx);
-await client.sendEvent(event); // ✅ Works automatically
-
-// Option 2: Set on client
-const client = await createClient(ctx);
-client.setRetailerId('1');
-await client.sendEvent(event); // ✅ Works
-
-// Option 3: In event payload
-await client.sendEvent({ ...event, retailerId: '1' }); // ✅ Works
-```
-
-### 401 Auth Retry
-
-**Automatic retry for platform authentication failures:**
-- **Max retries:** 3 attempts for 401 errors
-- **Delay:** Exponential backoff (1s → 2s → 4s)
-- **Applies to:** ALL API methods (Event, Job, Batch, GraphQL)
-- **Log message:** `"[fc-connect-sdk:auth] Platform auth failure (401), retrying..."`
-
-**Why this matters:**
-- Platform-managed OAuth2 tokens can expire between validation and use
-- Clock skew between Versori and Fluent API can cause timing issues
-- SDK automatically waits for platform token refresh
-
-### Connection Validation
-
-**`createClient()` automatically validates Versori context:**
-- **Validates:** `ctx.fetch` presence (throws error if missing)
-- **Warns:** If `retailerId` not found in connection (logs helpful hints)
-- **Checks:** `ctx.log` availability (logs warning if missing)
-
-See [Connection Validation Pattern](./patterns/versori-patterns-connection-validation-pattern.md) for complete details.
-
-### sendBatch() Retry Protection
-
-**NEW:** `sendBatch()` now includes automatic retry:**
-- Protects against transient network failures
-- Automatic retry for 401, 5xx, and network errors
-- Prevents loss of significant data processing work
-
-**Example benefit:**
-```typescript
-// Process 10,000 inventory records (30 seconds)
-const entities = await processInventoryFile();
-
-// Network hiccup during batch submission
-await client.sendBatch(jobId, { entities, action: 'UPSERT' });
-// ✅ SDK auto-retries transient network failure
-// ✅ 30 seconds of processing NOT wasted
-```
-
-### Template Compatibility
-
-**All templates remain compatible:**
-- Existing code continues to work unchanged
-- New validations provide fail-fast behavior
-- Retry logic is automatic and transparent
-
-**Upgrade benefits:**
-- Better error messages for misconfiguration
-- Improved reliability for transient failures
-- Reduced workflow failures from auth timing issues
-
----
-
-## Versori-Specific Features
-
-### Context API
-```typescript
-import { schedule } from '@versori/run';
-
-export const task = schedule('task', '0 2 * * *', async (ctx) => {
-  const { log, connections, openKv } = ctx;
-
-  // Use Versori logger
-  log.info('Starting task');
-
-  // Access connections
-  const fluentConnection = connections['fluent'];
-
-  // Use KV storage
-  const kv = openKv(':project:');
-  await kv.set(['key'], 'value');
-});
-```
-
-### Buffer Import (Required)
-```typescript
-// Always import Buffer in Versori runtime
-import { Buffer } from 'node:buffer';
-```
-
-## Related Documentation
-
-- [Versori Platform Guide](../../04-REFERENCE/platforms/versori/) - Complete Versori documentation
-- [Core Guides](../../02-CORE-GUIDES/) - SDK fundamentals
-- [Pattern Guides](../../03-PATTERN-GUIDES/) - Integration patterns
-
-## Support
-
-Need help with Versori templates?
-- Review [Versori Platform Guide](../../04-REFERENCE/platforms/versori/)
-- Check [Connection Security](../../04-REFERENCE/platforms/versori/platforms-versori-webhook-connection-security.md)
-- See [Workflow Task Types](../../04-REFERENCE/platforms/versori/platforms-versori-workflow-task-types.md)
-- Contact support@fluentcommerce.com
+# Versori Platform Templates
+
+> **Production-ready templates for Versori platform**
+> Complete integration examples for webhooks, scheduled workflows, and patterns
+
+## Overview
+
+This directory contains production-ready templates designed specifically for the Versori integration platform. Each template follows Versori best practices and leverages platform-specific features like KV storage, connections, and runtime context.
+
+## Directory Structure
+
+```
+versori/
+├── business-examples/      # Real-world business scenarios
+├── patterns/               # Versori-specific patterns
+├── webhooks/               # Webhook-triggered integrations
+└── workflows/             # Scheduled and manual workflows
+    ├── extraction/         # Data extraction workflows
+    └── ingestion/          # Data ingestion workflows
+```
+
+## Quick Navigation
+
+| I Want To... | Directory | Complexity |
+|--|--|--|
+| **Handle webhook triggers** | [webhooks/](./webhooks/) | Medium |
+| **Schedule data extraction** | [workflows/extraction/](./workflows/extraction/) | Medium |
+| **Schedule data ingestion** | [workflows/ingestion/](./workflows/ingestion/) | Medium |
+| **Learn Versori patterns** | [patterns/](./patterns/) | Advanced |
+| **See business examples** | [business-examples/](./business-examples/) | Advanced |
+
+## Available Directories
+
+### [Business Examples](./business-examples/)
+Real-world business scenarios:
+- Dropship Order Routing
+- GraphQL Parquet Extraction
+- Inter-Location Transfers
+- Pre-Order Allocation
+
+### [Patterns](./patterns/)
+Versori-specific patterns:
+- Dual Workflow Connector
+- KV State Management
+- XML Response Patterns
+- Connection Validation
+
+### [Webhooks](./webhooks/)
+Webhook-triggered integrations:
+- ASN Purchase Order
+- Dropship Routing
+- Flash Sale Reserve
+- RMA Returns Comprehensive
+- Payment Gateway Integration
+- Generic XML Order
+- XML Order Ingestion
+
+### [Workflows](./workflows/)
+Scheduled and manual workflows:
+- **[Extraction](./workflows/extraction/)** - Export data from Fluent
+- **[Ingestion](./workflows/ingestion/)** - Import data to Fluent
+
+## Key Features
+
+All Versori templates include:
+- **KV Storage** - State management with Versori KV
+- **Connections** - Pre-configured connection objects
+- **Context API** - Access to `ctx.log`, `ctx.connections`, `ctx.kv`
+- **Runtime Detection** - Automatic Versori runtime configuration
+- **Error Handling** - Platform-specific error patterns
+
+## Using These Templates
+
+1. **Choose a template** that matches your use case
+2. **Copy to Versori** platform
+3. **Configure connections** in Versori UI
+4. **Set environment variables**
+5. **Test** with sample data
+6. **Deploy** and monitor
+
+## SDK Automatic Behaviors (v0.1.40+)
+
+Recent SDK enhancements provide automatic validation and retry for improved reliability:
+
+### retailerId Validation
+
+**Event/Job/Batch APIs automatically validate `retailerId` before API calls:**
+- Fail-fast with clear error messages if missing
+- Three configuration methods: connection variables, client.setRetailerId(), or event payload
+- See [Event API Guide](./workflows/ingestion/event-api/event-api-guide.md) and [Batch API Guide](./workflows/ingestion/batch-api/batch-api-guide.md) for details
+
+**Example:**
+```typescript
+// Option 1: Via connection (recommended)
+// Configure in Versori Connection UI: { "retailerId": "1" }
+const client = await createClient(ctx);
+await client.sendEvent(event); // ✅ Works automatically
+
+// Option 2: Set on client
+const client = await createClient(ctx);
+client.setRetailerId('1');
+await client.sendEvent(event); // ✅ Works
+
+// Option 3: In event payload
+await client.sendEvent({ ...event, retailerId: '1' }); // ✅ Works
+```
+
+### 401 Auth Retry
+
+**Automatic retry for platform authentication failures:**
+- **Max retries:** 3 attempts for 401 errors
+- **Delay:** Exponential backoff (1s → 2s → 4s)
+- **Applies to:** ALL API methods (Event, Job, Batch, GraphQL)
+- **Log message:** `"[fc-connect-sdk:auth] Platform auth failure (401), retrying..."`
+
+**Why this matters:**
+- Platform-managed OAuth2 tokens can expire between validation and use
+- Clock skew between Versori and Fluent API can cause timing issues
+- SDK automatically waits for platform token refresh
+
+### Connection Validation
+
+**`createClient()` automatically validates Versori context:**
+- **Validates:** `ctx.fetch` presence (throws error if missing)
+- **Warns:** If `retailerId` not found in connection (logs helpful hints)
+- **Checks:** `ctx.log` availability (logs warning if missing)
+
+See [Connection Validation Pattern](./patterns/versori-patterns-connection-validation-pattern.md) for complete details.
+
+### sendBatch() Retry Protection
+
+**NEW:** `sendBatch()` now includes automatic retry:**
+- Protects against transient network failures
+- Automatic retry for 401, 5xx, and network errors
+- Prevents loss of significant data processing work
+
+**Example benefit:**
+```typescript
+// Process 10,000 inventory records (30 seconds)
+const entities = await processInventoryFile();
+
+// Network hiccup during batch submission
+await client.sendBatch(jobId, { entities, action: 'UPSERT' });
+// ✅ SDK auto-retries transient network failure
+// ✅ 30 seconds of processing NOT wasted
+```
+
+### Template Compatibility
+
+**All templates remain compatible:**
+- Existing code continues to work unchanged
+- New validations provide fail-fast behavior
+- Retry logic is automatic and transparent
+
+**Upgrade benefits:**
+- Better error messages for misconfiguration
+- Improved reliability for transient failures
+- Reduced workflow failures from auth timing issues
+
+---
+
+## Versori-Specific Features
+
+### Context API
+```typescript
+import { schedule } from '@versori/run';
+
+export const task = schedule('task', '0 2 * * *', async (ctx) => {
+  const { log, connections, openKv } = ctx;
+
+  // Use Versori logger
+  log.info('Starting task');
+
+  // Access connections
+  const fluentConnection = connections['fluent'];
+
+  // Use KV storage
+  const kv = openKv(':project:');
+  await kv.set(['key'], 'value');
+});
+```
+
+### Buffer Import (Required)
+```typescript
+// Always import Buffer in Versori runtime
+import { Buffer } from 'node:buffer';
+```
+
+## Related Documentation
+
+- [Versori Platform Guide](../../04-REFERENCE/platforms/versori/) - Complete Versori documentation
+- [Core Guides](../../02-CORE-GUIDES/) - SDK fundamentals
+- [Pattern Guides](../../03-PATTERN-GUIDES/) - Integration patterns
+
+## Support
+
+Need help with Versori templates?
+- Review [Versori Platform Guide](../../04-REFERENCE/platforms/versori/)
+- Check [Connection Security](../../04-REFERENCE/platforms/versori/platforms-versori-webhook-connection-security.md)
+- See [Workflow Task Types](../../04-REFERENCE/platforms/versori/platforms-versori-workflow-task-types.md)
+- Contact support@fluentcommerce.com