@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

package/docs/04-REFERENCE/platforms/versori/platforms-versori-readme.md

@@ -1,299 +1,299 @@
-# Versori Platform Integration Guide
-
-[← Back to Documentation](../../../00-START-HERE/readme.md)
-
-**Complete guide to deploying Fluent Commerce integrations on Versori Platform**
-
----
-
-## Overview
-
-The Versori Platform provides a managed serverless runtime for deploying Fluent Commerce integrations with built-in features for HTTP workflows, scheduled tasks, webhook handling, and distributed state management.
-
-**SDK Package**: `@fluentcommerce/fc-connect-sdk` (latest)
-**Versori Runtime**: `@versori/run` v0.4.4+
-
-### Key Platform Capabilities
-
-- **Managed Runtime**: Deploy workflows without infrastructure management
-- **OAuth2 Connections**: Built-in authentication with Fluent Commerce API
-- **KV Storage**: Distributed key-value store for state management
-- **Cron Scheduling**: Time-based recurring workflows
-- **HTTP Webhooks**: Event-driven integrations
-- **Auto-Scaling**: Automatic scaling based on workload
-- **Monitoring**: Built-in logs and execution tracking
-
-### When to Use Versori Platform
-
-| Use Case | Versori Platform | Standalone Node.js |
-|----------|------------------|-------------------|
-| **Production integrations** | ✅ Recommended | ⚠️ Requires infrastructure |
-| **Scheduled workflows** | ✅ Built-in cron | ❌ External scheduler needed |
-| **Webhook endpoints** | ✅ Auto-provisioned | ❌ Web server needed |
-| **State management** | ✅ Built-in KV store | ❌ External storage needed |
-| **Scaling** | ✅ Automatic | ❌ Manual scaling |
-| **Monitoring** | ✅ Built-in logs | ❌ Custom logging needed |
-| **Quick prototyping** | ✅ Fast deploy | ✅ Local development |
-
----
-
-## Learning Path
-
-This guide is organized into **8 progressive modules**. Follow them in order for the best learning experience:
-
-| Module | Topic | Level | Time | What You'll Learn |
-|--------|-------|-------|------|-------------------|
-| [Module 1](./modules/platforms-versori-01-introduction.md) | **Introduction** | Beginner | 15 min | Versori platform overview, capabilities, architecture |
-| [Module 2](./modules/platforms-versori-02-quick-start.md) | **Quick Start** | Beginner | 20 min | First connector, setup, basic HTTP workflow |
-| [Module 3](./modules/platforms-versori-03-authentication.md) | **Authentication** | Beginner | 25 min | OAuth2 connections, FluentVersoriClient usage |
-| [Module 4](./modules/platforms-versori-04-workflows.md) | **Workflows** | Intermediate | 30 min | HTTP webhooks, scheduled tasks, fn() composition, non-JSON responses |
-| [Module 5](./modules/platforms-versori-05-connections.md) | **Connections** | Intermediate | 20 min | Connection types, management, validation, security |
-| [Module 6](./modules/platforms-versori-06-kv-storage.md) | **KV Storage** | Intermediate | 25 min | VersoriKVAdapter, file tracking, distributed locking |
-| [Module 7](./modules/platforms-versori-07-deployment.md) | **Deployment** | Advanced | 30 min | Deploying connectors, monitoring, logs, CI/CD |
-| [Module 8](./modules/platforms-versori-08-best-practices.md) | **Best Practices** | Advanced | 30 min | Production patterns, error handling, troubleshooting |
-
-**Total Learning Time**: ~3 hours
-
----
-
-## Quick Navigation
-
-### By Use Case
-
-| I Want To... | Start Here | Then See |
-|--------------|------------|----------|
-| **Deploy my first connector** | [Module 2: Quick Start](./modules/platforms-versori-02-quick-start.md) | [Module 7: Deployment](./modules/platforms-versori-07-deployment.md) |
-| **Set up Fluent API authentication** | [Module 3: Authentication](./modules/platforms-versori-03-authentication.md) | [Module 5: Connections](./modules/platforms-versori-05-connections.md) |
-| **Create scheduled inventory sync** | [Module 4: Workflows](./modules/platforms-versori-04-workflows.md) | [Module 6: KV Storage](./modules/platforms-versori-06-kv-storage.md) |
-| **Process incoming webhooks** | [Module 4: Workflows](./modules/platforms-versori-04-workflows.md) | [Module 8: Best Practices](./modules/platforms-versori-08-best-practices.md) |
-| **Track processed files** | [Module 6: KV Storage](./modules/platforms-versori-06-kv-storage.md) | [Module 8: Best Practices](./modules/platforms-versori-08-best-practices.md) |
-| **Debug production issues** | [Module 8: Best Practices](./modules/platforms-versori-08-best-practices.md) | [Module 7: Deployment](./modules/platforms-versori-07-deployment.md) |
-| **Optimize costs** | [Module 8: Best Practices](./modules/platforms-versori-08-best-practices.md) | [Module 4: Workflows](./modules/platforms-versori-04-workflows.md) |
-
-### By Workflow Type
-
-| Workflow Type | Use Case | Module | Example |
-|---------------|----------|--------|---------|
-| **HTTP** | External API calls to Fluent | [Module 4](./modules/platforms-versori-04-workflows.md#http-functions-external-api-calls) | Query inventory, create orders |
-| **Webhook** | Receive external webhooks | [Module 4](./modules/platforms-versori-04-workflows.md#webhook-functions-receiving-external-requests) | SFCC orders, Rubix events |
-| **Scheduled** | Time-based recurring tasks | [Module 4](./modules/platforms-versori-04-workflows.md#scheduled-functions-time-based-recurring-tasks) | Daily inventory sync |
-| **Internal (fn)** | Data transformation, state | [Module 4](./modules/platforms-versori-04-workflows.md#internal-functions-fn-data-transformation-state) | File tracking, validation |
-
----
-
-## Real-World Use Cases
-
-### E-Commerce Order Integration
-
-**Scenario**: Receive SFCC order XML via webhook, transform to Fluent GraphQL, create orders
-
-**Modules**: [2](./modules/platforms-versori-02-quick-start.md), [3](./modules/platforms-versori-03-authentication.md), [4](./modules/platforms-versori-04-workflows.md), [6](./modules/platforms-versori-06-kv-storage.md)
-
-**Connector Example**: [SFCC Connector Example](../../../01-TEMPLATES/versori/webhooks/template-webhook-xml-order-ingestion.md)
-
-**Key Features**:
-- HTTP webhook endpoint for SFCC XML
-- OAuth2 connection to Fluent Commerce
-- GraphQLMutationMapper for XML → Fluent transformation
-- Custom XML response handlers
-
----
-
-### Daily Inventory Sync
-
-**Scenario**: Fetch CSV from S3 every 6 hours, parse, send to Fluent via Batch API
-
-**Modules**: [4](./modules/platforms-versori-04-workflows.md), [6](./modules/platforms-versori-06-kv-storage.md), [8](./modules/platforms-versori-08-best-practices.md)
-
-**Connector Example:** `connectors/Sample versori connectors/versori_connector_with_fluent_sdk/` (at repository root, outside docs folder)
-
-**Key Features**:
-- Scheduled workflow with cron (`0 */6 * * *`)
-- VersoriFileTracker to prevent duplicate processing
-- S3DataSource for CSV ingestion
-- UniversalMapper for field transformations
-- Batch API for efficient updates
-
----
-
-### Real-Time Inventory Updates
-
-**Scenario**: Receive Fluent Rubix webhook, validate signature, process event
-
-**Modules**: [3](./modules/platforms-versori-03-authentication.md), [4](./modules/platforms-versori-04-workflows.md), [8](./modules/platforms-versori-08-best-practices.md)
-
-**Key Features**:
-- WebhookValidationService for signature verification
-- Event parsing and validation
-- Connection-based authentication
-- Error handling and logging
-
----
-
-### Parquet Extraction to S3
-
-**Scenario**: Query Fluent GraphQL hourly, transform to Parquet, upload to S3
-
-**Modules**: [4](./modules/platforms-versori-04-workflows.md), [6](./modules/platforms-versori-06-kv-storage.md), [7](./modules/platforms-versori-07-deployment.md)
-
-**Connector Example:** `connectors/Sample versori connectors/inventory-extraction-connector/` (at repository root, outside docs folder)
-
-**Key Features**:
-- Scheduled hourly extraction
-- Auto-pagination for large datasets
-- ParquetParserService for columnar format
-- S3DataSource for uploads
-- KV state for incremental extraction
-
----
-
-## Documentation Structure
-
-```
-versori/
-├── readme.md (this file)
-└── modules/
-    ├── 01-introduction.md           # Platform overview, architecture, capabilities
-    ├── 02-quick-start.md            # First connector, basic HTTP workflow
-    ├── 03-authentication.md         # OAuth2, connections, FluentVersoriClient
-    ├── 04-workflows.md              # HTTP, webhook, scheduled, fn(), non-JSON responses
-    ├── 05-connections.md            # OAuth2, API keys, multi-connection, security
-    ├── 06-kv-storage.md             # VersoriKVAdapter, file tracking, locking
-    ├── 07-deployment.md             # Deploy, monitor, logs, CI/CD, versioning
-    └── 08-best-practices.md         # Error handling, performance, security, troubleshooting
-```
-
----
-
-## Prerequisites
-
-Before starting this guide, you should:
-
-1. ✅ Have a Versori account ([sign up](https://versori.com))
-2. ✅ Have Fluent Commerce API credentials (clientId, clientSecret, retailerId)
-3. ✅ Install Node.js ≥18.0.0
-4. ✅ Install the SDK: `npm install @fluentcommerce/fc-connect-sdk`
-5. ✅ Basic TypeScript knowledge
-6. ✅ Familiarity with Fluent Commerce concepts (optional but helpful)
-
-**New to the SDK?** Start with the [Getting Started Guide](../../../00-START-HERE/getting-started.md) first.
-
----
-
-## Key Concepts at a Glance
-
-### Universal Client Factory
-
-```typescript
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-// Auto-detects Versori context and creates appropriate client
-const client = await createClient(ctx);
-```
-
-### Workflow Types
-
-```typescript
-import { http, webhook, schedule, fn } from '@versori/run';
-
-// External API calls (requires connection)
-export const apiCall = http('name', { connection: 'fluent_commerce' }, handler);
-
-// Receive webhooks
-export const receiver = webhook('name')
-  .then(fn('handler', handler));
-
-// Time-based tasks - with API access
-export const dailySync = schedule('name', '0 0 * * *')
-  .then(http('task', { connection: 'fluent_commerce' }, handler));
-
-// Time-based tasks - KV only
-export const dailyCleanup = schedule('cleanup', '0 0 * * *')
-  .then(fn('task', handler));
-
-// Internal processing (NO external API access)
-export const process = fn('name', handler);
-```
-
-### KV Storage for State
-
-```typescript
-import { VersoriKVAdapter, VersoriFileTracker } from '@fluentcommerce/fc-connect-sdk';
-
-const kv = ctx.openKv(':project:');
-const tracker = new VersoriFileTracker(kv, 'inventory');
-
-// Track processed files
-if (await tracker.wasFileProcessed('file.csv')) {
-  return { skipped: true };
-}
-await tracker.markFileProcessed('file.csv', { records: 100 });
-```
-
----
-
-## Related Documentation
-
-### SDK Guides
-- [Getting Started Guide](../../../00-START-HERE/getting-started.md) - SDK setup and basics
-- [Auto-Pagination Guide](../../../02-CORE-GUIDES/auto-pagination/auto-pagination-readme.md) - Cursor-based pagination
-- [Resolver Development Guide](../../../02-CORE-GUIDES/mapping/resolvers/mapping-resolvers-readme.md) - Custom transformers
-- [Universal Mapping Guide](../../../02-CORE-GUIDES/mapping/mapping-readme.md) - Field mapping
-
-### Platform-Specific
-- [Webhook Response Patterns](./modules/platforms-versori-04-workflows.md#critical-non-json-response-handlers-xml-html-csv) - Non-JSON responses (XML, HTML, CSV)
-- [API Reference](../../../02-CORE-GUIDES/api-reference/api-reference-readme.md) - Complete SDK API
-
-### Connector Examples
-- [SFCC Connector Examples](../../../01-TEMPLATES/versori/webhooks/template-webhook-xml-order-ingestion.md) - Order integration
-- [Inventory Connectors](../../../01-TEMPLATES/versori/workflows/readme.md) - CSV/Parquet examples
-
----
-
-## Version Information
-
-**Current Versions:**
-- **@versori/run**: v0.4.4 (latest stable)
-- **@fluentcommerce/fc-connect-sdk**: Check [npm](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk) for latest
-
-**Compatibility**: This guide covers @versori/run v0.4.x and all recent SDK versions.
-
----
-
-## Learning Paths by Skill Level
-
-### Beginner Path (Start here if new to Versori)
-1. [Module 1: Introduction](./modules/platforms-versori-01-introduction.md)
-2. [Module 2: Quick Start](./modules/platforms-versori-02-quick-start.md)
-3. [Module 3: Authentication](./modules/platforms-versori-03-authentication.md)
-4. [Module 4: Workflows](./modules/platforms-versori-04-workflows.md) (sections 1-3)
-
-### Intermediate Path (Familiar with basics)
-1. [Module 4: Workflows](./modules/platforms-versori-04-workflows.md) (complete)
-2. [Module 5: Connections](./modules/platforms-versori-05-connections.md)
-3. [Module 6: KV Storage](./modules/platforms-versori-06-kv-storage.md)
-4. [Module 7: Deployment](./modules/platforms-versori-07-deployment.md)
-
-### Advanced Path (Production deployments)
-1. [Module 7: Deployment](./modules/platforms-versori-07-deployment.md)
-2. [Module 8: Best Practices](./modules/platforms-versori-08-best-practices.md)
-3. [Webhook Response Patterns](./modules/platforms-versori-04-workflows.md#critical-non-json-response-handlers-xml-html-csv)
-4. Review connector examples for production patterns
-
----
-
-## Get Started
-
-Ready to deploy your first Versori connector? Begin with [Module 1: Introduction](./modules/platforms-versori-01-introduction.md) to understand the platform architecture and capabilities.
-
----
-
-## Support
-
-- **Documentation Issues**: Check [Module 8: Best Practices](./modules/platforms-versori-08-best-practices.md#troubleshooting)
-- **Connector Examples**: Browse `connectors/` directory (at repository root, outside docs folder)
-- **SDK Reference**: See [API Reference](../../../02-CORE-GUIDES/api-reference/api-reference-readme.md)
-
----
-
-**Next**: [Module 1: Introduction →](./modules/platforms-versori-01-introduction.md)
+# Versori Platform Integration Guide
+
+[← Back to Documentation](../../../00-START-HERE/readme.md)
+
+**Complete guide to deploying Fluent Commerce integrations on Versori Platform**
+
+---
+
+## Overview
+
+The Versori Platform provides a managed serverless runtime for deploying Fluent Commerce integrations with built-in features for HTTP workflows, scheduled tasks, webhook handling, and distributed state management.
+
+**SDK Package**: `@fluentcommerce/fc-connect-sdk` (latest)
+**Versori Runtime**: `@versori/run` v0.4.4+
+
+### Key Platform Capabilities
+
+- **Managed Runtime**: Deploy workflows without infrastructure management
+- **OAuth2 Connections**: Built-in authentication with Fluent Commerce API
+- **KV Storage**: Distributed key-value store for state management
+- **Cron Scheduling**: Time-based recurring workflows
+- **HTTP Webhooks**: Event-driven integrations
+- **Auto-Scaling**: Automatic scaling based on workload
+- **Monitoring**: Built-in logs and execution tracking
+
+### When to Use Versori Platform
+
+| Use Case | Versori Platform | Standalone Node.js |
+|----------|------------------|-------------------|
+| **Production integrations** | ✅ Recommended | ⚠️ Requires infrastructure |
+| **Scheduled workflows** | ✅ Built-in cron | ❌ External scheduler needed |
+| **Webhook endpoints** | ✅ Auto-provisioned | ❌ Web server needed |
+| **State management** | ✅ Built-in KV store | ❌ External storage needed |
+| **Scaling** | ✅ Automatic | ❌ Manual scaling |
+| **Monitoring** | ✅ Built-in logs | ❌ Custom logging needed |
+| **Quick prototyping** | ✅ Fast deploy | ✅ Local development |
+
+---
+
+## Learning Path
+
+This guide is organized into **8 progressive modules**. Follow them in order for the best learning experience:
+
+| Module | Topic | Level | Time | What You'll Learn |
+|--------|-------|-------|------|-------------------|
+| [Module 1](./modules/platforms-versori-01-introduction.md) | **Introduction** | Beginner | 15 min | Versori platform overview, capabilities, architecture |
+| [Module 2](./modules/platforms-versori-02-quick-start.md) | **Quick Start** | Beginner | 20 min | First connector, setup, basic HTTP workflow |
+| [Module 3](./modules/platforms-versori-03-authentication.md) | **Authentication** | Beginner | 25 min | OAuth2 connections, FluentVersoriClient usage |
+| [Module 4](./modules/platforms-versori-04-workflows.md) | **Workflows** | Intermediate | 30 min | HTTP webhooks, scheduled tasks, fn() composition, non-JSON responses |
+| [Module 5](./modules/platforms-versori-05-connections.md) | **Connections** | Intermediate | 20 min | Connection types, management, validation, security |
+| [Module 6](./modules/platforms-versori-06-kv-storage.md) | **KV Storage** | Intermediate | 25 min | VersoriKVAdapter, file tracking, distributed locking |
+| [Module 7](./modules/platforms-versori-07-deployment.md) | **Deployment** | Advanced | 30 min | Deploying connectors, monitoring, logs, CI/CD |
+| [Module 8](./modules/platforms-versori-08-best-practices.md) | **Best Practices** | Advanced | 30 min | Production patterns, error handling, troubleshooting |
+
+**Total Learning Time**: ~3 hours
+
+---
+
+## Quick Navigation
+
+### By Use Case
+
+| I Want To... | Start Here | Then See |
+|--------------|------------|----------|
+| **Deploy my first connector** | [Module 2: Quick Start](./modules/platforms-versori-02-quick-start.md) | [Module 7: Deployment](./modules/platforms-versori-07-deployment.md) |
+| **Set up Fluent API authentication** | [Module 3: Authentication](./modules/platforms-versori-03-authentication.md) | [Module 5: Connections](./modules/platforms-versori-05-connections.md) |
+| **Create scheduled inventory sync** | [Module 4: Workflows](./modules/platforms-versori-04-workflows.md) | [Module 6: KV Storage](./modules/platforms-versori-06-kv-storage.md) |
+| **Process incoming webhooks** | [Module 4: Workflows](./modules/platforms-versori-04-workflows.md) | [Module 8: Best Practices](./modules/platforms-versori-08-best-practices.md) |
+| **Track processed files** | [Module 6: KV Storage](./modules/platforms-versori-06-kv-storage.md) | [Module 8: Best Practices](./modules/platforms-versori-08-best-practices.md) |
+| **Debug production issues** | [Module 8: Best Practices](./modules/platforms-versori-08-best-practices.md) | [Module 7: Deployment](./modules/platforms-versori-07-deployment.md) |
+| **Optimize costs** | [Module 8: Best Practices](./modules/platforms-versori-08-best-practices.md) | [Module 4: Workflows](./modules/platforms-versori-04-workflows.md) |
+
+### By Workflow Type
+
+| Workflow Type | Use Case | Module | Example |
+|---------------|----------|--------|---------|
+| **HTTP** | External API calls to Fluent | [Module 4](./modules/platforms-versori-04-workflows.md#http-functions-external-api-calls) | Query inventory, create orders |
+| **Webhook** | Receive external webhooks | [Module 4](./modules/platforms-versori-04-workflows.md#webhook-functions-receiving-external-requests) | SFCC orders, Rubix events |
+| **Scheduled** | Time-based recurring tasks | [Module 4](./modules/platforms-versori-04-workflows.md#scheduled-functions-time-based-recurring-tasks) | Daily inventory sync |
+| **Internal (fn)** | Data transformation, state | [Module 4](./modules/platforms-versori-04-workflows.md#internal-functions-fn-data-transformation-state) | File tracking, validation |
+
+---
+
+## Real-World Use Cases
+
+### E-Commerce Order Integration
+
+**Scenario**: Receive SFCC order XML via webhook, transform to Fluent GraphQL, create orders
+
+**Modules**: [2](./modules/platforms-versori-02-quick-start.md), [3](./modules/platforms-versori-03-authentication.md), [4](./modules/platforms-versori-04-workflows.md), [6](./modules/platforms-versori-06-kv-storage.md)
+
+**Connector Example**: [SFCC Connector Example](../../../01-TEMPLATES/versori/webhooks/template-webhook-xml-order-ingestion.md)
+
+**Key Features**:
+- HTTP webhook endpoint for SFCC XML
+- OAuth2 connection to Fluent Commerce
+- GraphQLMutationMapper for XML → Fluent transformation
+- Custom XML response handlers
+
+---
+
+### Daily Inventory Sync
+
+**Scenario**: Fetch CSV from S3 every 6 hours, parse, send to Fluent via Batch API
+
+**Modules**: [4](./modules/platforms-versori-04-workflows.md), [6](./modules/platforms-versori-06-kv-storage.md), [8](./modules/platforms-versori-08-best-practices.md)
+
+**Connector Example:** `connectors/Sample versori connectors/versori_connector_with_fluent_sdk/` (at repository root, outside docs folder)
+
+**Key Features**:
+- Scheduled workflow with cron (`0 */6 * * *`)
+- VersoriFileTracker to prevent duplicate processing
+- S3DataSource for CSV ingestion
+- UniversalMapper for field transformations
+- Batch API for efficient updates
+
+---
+
+### Real-Time Inventory Updates
+
+**Scenario**: Receive Fluent Rubix webhook, validate signature, process event
+
+**Modules**: [3](./modules/platforms-versori-03-authentication.md), [4](./modules/platforms-versori-04-workflows.md), [8](./modules/platforms-versori-08-best-practices.md)
+
+**Key Features**:
+- WebhookValidationService for signature verification
+- Event parsing and validation
+- Connection-based authentication
+- Error handling and logging
+
+---
+
+### Parquet Extraction to S3
+
+**Scenario**: Query Fluent GraphQL hourly, transform to Parquet, upload to S3
+
+**Modules**: [4](./modules/platforms-versori-04-workflows.md), [6](./modules/platforms-versori-06-kv-storage.md), [7](./modules/platforms-versori-07-deployment.md)
+
+**Connector Example:** `connectors/Sample versori connectors/inventory-extraction-connector/` (at repository root, outside docs folder)
+
+**Key Features**:
+- Scheduled hourly extraction
+- Auto-pagination for large datasets
+- ParquetParserService for columnar format
+- S3DataSource for uploads
+- KV state for incremental extraction
+
+---
+
+## Documentation Structure
+
+```
+versori/
+├── readme.md (this file)
+└── modules/
+    ├── 01-introduction.md           # Platform overview, architecture, capabilities
+    ├── 02-quick-start.md            # First connector, basic HTTP workflow
+    ├── 03-authentication.md         # OAuth2, connections, FluentVersoriClient
+    ├── 04-workflows.md              # HTTP, webhook, scheduled, fn(), non-JSON responses
+    ├── 05-connections.md            # OAuth2, API keys, multi-connection, security
+    ├── 06-kv-storage.md             # VersoriKVAdapter, file tracking, locking
+    ├── 07-deployment.md             # Deploy, monitor, logs, CI/CD, versioning
+    └── 08-best-practices.md         # Error handling, performance, security, troubleshooting
+```
+
+---
+
+## Prerequisites
+
+Before starting this guide, you should:
+
+1. ✅ Have a Versori account ([sign up](https://versori.com))
+2. ✅ Have Fluent Commerce API credentials (clientId, clientSecret, retailerId)
+3. ✅ Install Node.js ≥18.0.0
+4. ✅ Install the SDK: `npm install @fluentcommerce/fc-connect-sdk`
+5. ✅ Basic TypeScript knowledge
+6. ✅ Familiarity with Fluent Commerce concepts (optional but helpful)
+
+**New to the SDK?** Start with the [Getting Started Guide](../../../00-START-HERE/getting-started.md) first.
+
+---
+
+## Key Concepts at a Glance
+
+### Universal Client Factory
+
+```typescript
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+// Auto-detects Versori context and creates appropriate client
+const client = await createClient(ctx);
+```
+
+### Workflow Types
+
+```typescript
+import { http, webhook, schedule, fn } from '@versori/run';
+
+// External API calls (requires connection)
+export const apiCall = http('name', { connection: 'fluent_commerce' }, handler);
+
+// Receive webhooks
+export const receiver = webhook('name')
+  .then(fn('handler', handler));
+
+// Time-based tasks - with API access
+export const dailySync = schedule('name', '0 0 * * *')
+  .then(http('task', { connection: 'fluent_commerce' }, handler));
+
+// Time-based tasks - KV only
+export const dailyCleanup = schedule('cleanup', '0 0 * * *')
+  .then(fn('task', handler));
+
+// Internal processing (NO external API access)
+export const process = fn('name', handler);
+```
+
+### KV Storage for State
+
+```typescript
+import { VersoriKVAdapter, VersoriFileTracker } from '@fluentcommerce/fc-connect-sdk';
+
+const kv = ctx.openKv(':project:');
+const tracker = new VersoriFileTracker(kv, 'inventory');
+
+// Track processed files
+if (await tracker.wasFileProcessed('file.csv')) {
+  return { skipped: true };
+}
+await tracker.markFileProcessed('file.csv', { records: 100 });
+```
+
+---
+
+## Related Documentation
+
+### SDK Guides
+- [Getting Started Guide](../../../00-START-HERE/getting-started.md) - SDK setup and basics
+- [Auto-Pagination Guide](../../../02-CORE-GUIDES/auto-pagination/auto-pagination-readme.md) - Cursor-based pagination
+- [Resolver Development Guide](../../../02-CORE-GUIDES/mapping/resolvers/mapping-resolvers-readme.md) - Custom transformers
+- [Universal Mapping Guide](../../../02-CORE-GUIDES/mapping/mapping-readme.md) - Field mapping
+
+### Platform-Specific
+- [Webhook Response Patterns](./modules/platforms-versori-04-workflows.md#critical-non-json-response-handlers-xml-html-csv) - Non-JSON responses (XML, HTML, CSV)
+- [API Reference](../../../02-CORE-GUIDES/api-reference/api-reference-readme.md) - Complete SDK API
+
+### Connector Examples
+- [SFCC Connector Examples](../../../01-TEMPLATES/versori/webhooks/template-webhook-xml-order-ingestion.md) - Order integration
+- [Inventory Connectors](../../../01-TEMPLATES/versori/workflows/readme.md) - CSV/Parquet examples
+
+---
+
+## Version Information
+
+**Current Versions:**
+- **@versori/run**: v0.4.4 (latest stable)
+- **@fluentcommerce/fc-connect-sdk**: Check [npm](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk) for latest
+
+**Compatibility**: This guide covers @versori/run v0.4.x and all recent SDK versions.
+
+---
+
+## Learning Paths by Skill Level
+
+### Beginner Path (Start here if new to Versori)
+1. [Module 1: Introduction](./modules/platforms-versori-01-introduction.md)
+2. [Module 2: Quick Start](./modules/platforms-versori-02-quick-start.md)
+3. [Module 3: Authentication](./modules/platforms-versori-03-authentication.md)
+4. [Module 4: Workflows](./modules/platforms-versori-04-workflows.md) (sections 1-3)
+
+### Intermediate Path (Familiar with basics)
+1. [Module 4: Workflows](./modules/platforms-versori-04-workflows.md) (complete)
+2. [Module 5: Connections](./modules/platforms-versori-05-connections.md)
+3. [Module 6: KV Storage](./modules/platforms-versori-06-kv-storage.md)
+4. [Module 7: Deployment](./modules/platforms-versori-07-deployment.md)
+
+### Advanced Path (Production deployments)
+1. [Module 7: Deployment](./modules/platforms-versori-07-deployment.md)
+2. [Module 8: Best Practices](./modules/platforms-versori-08-best-practices.md)
+3. [Webhook Response Patterns](./modules/platforms-versori-04-workflows.md#critical-non-json-response-handlers-xml-html-csv)
+4. Review connector examples for production patterns
+
+---
+
+## Get Started
+
+Ready to deploy your first Versori connector? Begin with [Module 1: Introduction](./modules/platforms-versori-01-introduction.md) to understand the platform architecture and capabilities.
+
+---
+
+## Support
+
+- **Documentation Issues**: Check [Module 8: Best Practices](./modules/platforms-versori-08-best-practices.md#troubleshooting)
+- **Connector Examples**: Browse `connectors/` directory (at repository root, outside docs folder)
+- **SDK Reference**: See [API Reference](../../../02-CORE-GUIDES/api-reference/api-reference-readme.md)
+
+---
+
+**Next**: [Module 1: Introduction →](./modules/platforms-versori-01-introduction.md)