@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/01-TEMPLATES/versori/webhooks/webhook-templates-guide.md

@@ -1,140 +1,140 @@
-# Versori Webhook Templates
-
-> **Webhook-triggered integration templates for Versori platform**
-> Real-time event processing with complete error handling
-
-## Overview
-
-This directory contains production-ready webhook templates for the Versori platform. Each template demonstrates real-time event processing with proper validation, error handling, and XML/JSON response patterns.
-
-## Available Templates
-
-| Template | Description | Complexity | Response Format |
-|----------|-------------|------------|-----------------|
-| **[ASN Purchase Order](./template-webhook-asn-purchase-order.md)** | Process Advanced Shipping Notice webhooks | Medium | XML |
-| **[Dropship Routing](./template-webhook-dropship-routing.md)** | Route orders to dropship vendors | Advanced | JSON |
-| **[Flash Sale Reserve](./template-webhook-flash-sale-reserve.md)** | Reserve inventory for flash sales | Advanced | JSON |
-| **[RMA Returns Comprehensive](./template-webhook-rma-returns-comprehensive.md)** | Process return merchandise authorization | Advanced | XML |
-| **[Payment Gateway Integration](./template-webhook-payment-gateway-integration.md)** | Handle payment webhooks | Medium | JSON |
-| **[Generic XML Order](./template-webhook-generic-xml-order.md)** | Generic XML order processing (vendor-agnostic) | Beginner | XML |
-| **[SFCC XML Order Ingestion](./template-webhook-xml-order-ingestion.md)** | SFCC-specific XML order ingestion (orders.order.* structure) | Medium | XML |
-
-### Choosing Between Generic and SFCC XML Order Templates
-
-**Use [Generic XML Order](./template-webhook-generic-xml-order.md) when:**
-- ✅ Processing XML orders from any vendor (Shopify, custom systems, etc.)
-- ✅ Need a simpler, vendor-agnostic template
-- ✅ Want to adapt the template for your specific XML structure
-- ✅ Starting with a basic template and customizing
-
-**Use [SFCC XML Order Ingestion](./template-webhook-xml-order-ingestion.md) when:**
-- ✅ Specifically processing SFCC (Salesforce Commerce Cloud) orders
-- ✅ Using SFCC native XML structure (`orders.order.*` fields)
-- ✅ Need SFCC-specific resolvers (name parsing, address normalization)
-- ✅ Want a production-ready template optimized for SFCC
-
-## Quick Navigation
-
-### By Use Case
-
-| I Want To... | Template | Complexity |
-|--|--|--|
-| **Process order webhooks (any vendor)** | [Generic XML Order](./template-webhook-generic-xml-order.md) | Beginner |
-| **Process SFCC order webhooks** | [SFCC XML Order Ingestion](./template-webhook-xml-order-ingestion.md) | Medium |
-| **Handle ASN documents** | [ASN Purchase Order](./template-webhook-asn-purchase-order.md) | Medium |
-| **Route dropship orders** | [Dropship Routing](./template-webhook-dropship-routing.md) | Advanced |
-| **Manage flash sales** | [Flash Sale Reserve](./template-webhook-flash-sale-reserve.md) | Advanced |
-| **Process returns** | [RMA Returns Comprehensive](./template-webhook-rma-returns-comprehensive.md) | Advanced |
-| **Handle payments** | [Payment Gateway Integration](./template-webhook-payment-gateway-integration.md) | Medium |
-
-### By Response Format
-
-| Format | Templates |
-|--------|-----------|
-| **XML** | [ASN Purchase Order](./template-webhook-asn-purchase-order.md), [Generic XML Order](./template-webhook-generic-xml-order.md), [SFCC XML Order Ingestion](./template-webhook-xml-order-ingestion.md), [RMA Returns](./template-webhook-rma-returns-comprehensive.md) |
-| **JSON** | [Dropship Routing](./template-webhook-dropship-routing.md), [Flash Sale Reserve](./template-webhook-flash-sale-reserve.md), [Payment Gateway](./template-webhook-payment-gateway-integration.md) |
-
-## Webhook Template Structure
-
-Each template includes:
-- **Webhook Signature** - Function signature and imports
-- **Request Validation** - Schema validation and authentication
-- **Business Logic** - Complete processing logic
-- **Response Pattern** - XML or JSON response
-- **Error Handling** - Graceful error recovery
-- **Testing Guide** - Test with sample payloads
-
-## Versori Webhook Features
-
-### Buffer Import (Required)
-```typescript
-import { Buffer } from 'node:buffer';
-import { webhook } from '@versori/run';
-```
-
-### Context API
-```typescript
-export const handler = webhook('handler', async (ctx, request) => {
-  const { log, connections, openKv } = ctx;
-
-  // Use Versori logger
-  log.info('Processing webhook', { path: request.path });
-
-  // Access connections
-  const fluentClient = await createClient({ ...ctx, log });
-
-  // Use KV storage
-  const kv = openKv(':project:');
-  await kv.set(['webhook', request.id], { processed: true });
-});
-```
-
-### XML Response Pattern
-```typescript
-return {
-  statusCode: 200,
-  headers: { 'Content-Type': 'application/xml' },
-  body: `<?xml version="1.0" encoding="UTF-8"?>
-<response>
-  <status>success</status>
-  <orderId>${orderId}</orderId>
-</response>`
-};
-```
-
-## Using These Templates
-
-1. **Choose a template** that matches your webhook scenario
-2. **Copy to Versori** webhook function
-3. **Configure webhook URL** in external system
-4. **Set environment variables**
-5. **Test** with sample payloads (use Versori test tool)
-6. **Monitor** logs and errors
-
-## Testing Webhooks
-
-### In Versori Platform
-1. Use Versori's webhook testing tool
-2. Send sample payloads
-3. Review logs and responses
-4. Verify KV storage updates
-
-### With External Tools
-1. Use curl or Postman
-2. Send to Versori webhook URL
-3. Check response codes
-4. Monitor Versori logs
-
-## Related Documentation
-
-- [Versori Patterns](../patterns/) - XML Response Patterns
-- [Webhook Validation Guide](../../../02-CORE-GUIDES/webhook-validation/) - Secure webhooks
-- [Versori Platform Guide](../../../04-REFERENCE/platforms/versori/) - Complete platform docs
-
-## Support
-
-Need help with webhook templates?
-- Review [Webhook Auth Guide](../../../04-REFERENCE/platforms/versori/platforms-versori-webhook-auth-quick-reference.md)
-- Check [Connection Security](../../../04-REFERENCE/platforms/versori/platforms-versori-webhook-connection-security.md)
-- See testing guides in each template
-- Contact support@fluentcommerce.com
+# Versori Webhook Templates
+
+> **Webhook-triggered integration templates for Versori platform**
+> Real-time event processing with complete error handling
+
+## Overview
+
+This directory contains production-ready webhook templates for the Versori platform. Each template demonstrates real-time event processing with proper validation, error handling, and XML/JSON response patterns.
+
+## Available Templates
+
+| Template | Description | Complexity | Response Format |
+|----------|-------------|------------|-----------------|
+| **[ASN Purchase Order](./template-webhook-asn-purchase-order.md)** | Process Advanced Shipping Notice webhooks | Medium | XML |
+| **[Dropship Routing](./template-webhook-dropship-routing.md)** | Route orders to dropship vendors | Advanced | JSON |
+| **[Flash Sale Reserve](./template-webhook-flash-sale-reserve.md)** | Reserve inventory for flash sales | Advanced | JSON |
+| **[RMA Returns Comprehensive](./template-webhook-rma-returns-comprehensive.md)** | Process return merchandise authorization | Advanced | XML |
+| **[Payment Gateway Integration](./template-webhook-payment-gateway-integration.md)** | Handle payment webhooks | Medium | JSON |
+| **[Generic XML Order](./template-webhook-generic-xml-order.md)** | Generic XML order processing (vendor-agnostic) | Beginner | XML |
+| **[SFCC XML Order Ingestion](./template-webhook-xml-order-ingestion.md)** | SFCC-specific XML order ingestion (orders.order.* structure) | Medium | XML |
+
+### Choosing Between Generic and SFCC XML Order Templates
+
+**Use [Generic XML Order](./template-webhook-generic-xml-order.md) when:**
+- ✅ Processing XML orders from any vendor (Shopify, custom systems, etc.)
+- ✅ Need a simpler, vendor-agnostic template
+- ✅ Want to adapt the template for your specific XML structure
+- ✅ Starting with a basic template and customizing
+
+**Use [SFCC XML Order Ingestion](./template-webhook-xml-order-ingestion.md) when:**
+- ✅ Specifically processing SFCC (Salesforce Commerce Cloud) orders
+- ✅ Using SFCC native XML structure (`orders.order.*` fields)
+- ✅ Need SFCC-specific resolvers (name parsing, address normalization)
+- ✅ Want a production-ready template optimized for SFCC
+
+## Quick Navigation
+
+### By Use Case
+
+| I Want To... | Template | Complexity |
+|--|--|--|
+| **Process order webhooks (any vendor)** | [Generic XML Order](./template-webhook-generic-xml-order.md) | Beginner |
+| **Process SFCC order webhooks** | [SFCC XML Order Ingestion](./template-webhook-xml-order-ingestion.md) | Medium |
+| **Handle ASN documents** | [ASN Purchase Order](./template-webhook-asn-purchase-order.md) | Medium |
+| **Route dropship orders** | [Dropship Routing](./template-webhook-dropship-routing.md) | Advanced |
+| **Manage flash sales** | [Flash Sale Reserve](./template-webhook-flash-sale-reserve.md) | Advanced |
+| **Process returns** | [RMA Returns Comprehensive](./template-webhook-rma-returns-comprehensive.md) | Advanced |
+| **Handle payments** | [Payment Gateway Integration](./template-webhook-payment-gateway-integration.md) | Medium |
+
+### By Response Format
+
+| Format | Templates |
+|--------|-----------|
+| **XML** | [ASN Purchase Order](./template-webhook-asn-purchase-order.md), [Generic XML Order](./template-webhook-generic-xml-order.md), [SFCC XML Order Ingestion](./template-webhook-xml-order-ingestion.md), [RMA Returns](./template-webhook-rma-returns-comprehensive.md) |
+| **JSON** | [Dropship Routing](./template-webhook-dropship-routing.md), [Flash Sale Reserve](./template-webhook-flash-sale-reserve.md), [Payment Gateway](./template-webhook-payment-gateway-integration.md) |
+
+## Webhook Template Structure
+
+Each template includes:
+- **Webhook Signature** - Function signature and imports
+- **Request Validation** - Schema validation and authentication
+- **Business Logic** - Complete processing logic
+- **Response Pattern** - XML or JSON response
+- **Error Handling** - Graceful error recovery
+- **Testing Guide** - Test with sample payloads
+
+## Versori Webhook Features
+
+### Buffer Import (Required)
+```typescript
+import { Buffer } from 'node:buffer';
+import { webhook } from '@versori/run';
+```
+
+### Context API
+```typescript
+export const handler = webhook('handler', async (ctx, request) => {
+  const { log, connections, openKv } = ctx;
+
+  // Use Versori logger
+  log.info('Processing webhook', { path: request.path });
+
+  // Access connections
+  const fluentClient = await createClient({ ...ctx, log });
+
+  // Use KV storage
+  const kv = openKv(':project:');
+  await kv.set(['webhook', request.id], { processed: true });
+});
+```
+
+### XML Response Pattern
+```typescript
+return {
+  statusCode: 200,
+  headers: { 'Content-Type': 'application/xml' },
+  body: `<?xml version="1.0" encoding="UTF-8"?>
+<response>
+  <status>success</status>
+  <orderId>${orderId}</orderId>
+</response>`
+};
+```
+
+## Using These Templates
+
+1. **Choose a template** that matches your webhook scenario
+2. **Copy to Versori** webhook function
+3. **Configure webhook URL** in external system
+4. **Set environment variables**
+5. **Test** with sample payloads (use Versori test tool)
+6. **Monitor** logs and errors
+
+## Testing Webhooks
+
+### In Versori Platform
+1. Use Versori's webhook testing tool
+2. Send sample payloads
+3. Review logs and responses
+4. Verify KV storage updates
+
+### With External Tools
+1. Use curl or Postman
+2. Send to Versori webhook URL
+3. Check response codes
+4. Monitor Versori logs
+
+## Related Documentation
+
+- [Versori Patterns](../patterns/) - XML Response Patterns
+- [Webhook Validation Guide](../../../02-CORE-GUIDES/webhook-validation/) - Secure webhooks
+- [Versori Platform Guide](../../../04-REFERENCE/platforms/versori/) - Complete platform docs
+
+## Support
+
+Need help with webhook templates?
+- Review [Webhook Auth Guide](../../../04-REFERENCE/platforms/versori/platforms-versori-webhook-auth-quick-reference.md)
+- Check [Connection Security](../../../04-REFERENCE/platforms/versori/platforms-versori-webhook-connection-security.md)
+- See testing guides in each template
+- Contact support@fluentcommerce.com

package/docs/01-TEMPLATES/versori/workflows/_examples/sample-data/inventory-mapping.json

@@ -1,20 +1,20 @@
-{
-  "version": "1.0.0",
-  "description": "CSV inventory to Fluent Commerce Batch API mapping (external JSON)",
-  "fields": {
-    "locationRef": { "source": "locationRef", "required": true, "resolver": "sdk.trim" },
-    "skuRef": { "source": "skuRef", "required": true, "resolver": "sdk.trim" },
-    "qty": { "source": "qty", "required": true, "resolver": "sdk.parseInt" },
-    "type": { "source": "type", "required": true, "resolver": "sdk.uppercase" },
-    "status": { "source": "status", "required": true, "resolver": "sdk.uppercase" },
-    "expectedOn": { "source": "expectedOn", "required": false, "resolver": "sdk.formatDate" },
-    "attributes.expiryDate": {
-      "source": "expiryDate",
-      "required": false,
-      "resolver": "sdk.formatDate"
-    },
-    "attributes.batchNumber": { "source": "batchNumber", "required": false },
-    "attributes.condition": { "source": "condition", "required": false, "defaultValue": "NEW" },
-    "attributes.storageZone": { "source": "storageZone", "required": false }
-  }
-}
+{
+  "version": "1.0.0",
+  "description": "CSV inventory to Fluent Commerce Batch API mapping (external JSON)",
+  "fields": {
+    "locationRef": { "source": "locationRef", "required": true, "resolver": "sdk.trim" },
+    "skuRef": { "source": "skuRef", "required": true, "resolver": "sdk.trim" },
+    "qty": { "source": "qty", "required": true, "resolver": "sdk.parseInt" },
+    "type": { "source": "type", "required": true, "resolver": "sdk.uppercase" },
+    "status": { "source": "status", "required": true, "resolver": "sdk.uppercase" },
+    "expectedOn": { "source": "expectedOn", "required": false, "resolver": "sdk.formatDate" },
+    "attributes.expiryDate": {
+      "source": "expiryDate",
+      "required": false,
+      "resolver": "sdk.formatDate"
+    },
+    "attributes.batchNumber": { "source": "batchNumber", "required": false },
+    "attributes.condition": { "source": "condition", "required": false, "defaultValue": "NEW" },
+    "attributes.storageZone": { "source": "storageZone", "required": false }
+  }
+}

package/docs/01-TEMPLATES/versori/workflows/_examples/sample-data/products_2025-01-22.csv

@@ -1,11 +1,11 @@
-ref,type,status,gtin,name,summary,category_refs,price_default_currency,price_default_value,price_special_currency,price_special_value,tax_country,tax_group,tax_tariff,catalogue_ref,catalogue_type
-G_PROD_WITH_NO_STANDARD,VARIANT,ACTIVE,MH01-XS-Orange,Chaz Kangeroo Hoodie-XS-Orange main,<p>test short description</p>,STANDARD_CATEGORY,USD,52.000000,USD,9.000000,AU,Tax Group,Tax Tariff,PC:MASTER:2,MASTER
-G_PROD_002,VARIANT,ACTIVE,MH02-M-Blue,Kangeroo Hoodie-M-Blue,<p>Blue variant medium size</p>,STANDARD_CATEGORY|SEASONAL,USD,45.000000,USD,35.000000,AU,Tax Group,Tax Tariff,PC:MASTER:2,MASTER
-G_PROD_003,STANDARD,ACTIVE,MH03-BASE,Base Hoodie Product,<p>Base product without variants</p>,STANDARD_CATEGORY,USD,50.000000,,,AU,Tax Group,Tax Tariff,PC:MASTER:2,MASTER
-G_PROD_004,VARIANT,ACTIVE,MH04-L-Red,Kangeroo Hoodie-L-Red,<p>Red variant large size</p>,STANDARD_CATEGORY|CLEARANCE,USD,60.000000,USD,40.000000,AU,Tax Group,Tax Tariff,PC:MASTER:2,MASTER
-G_PROD_005,VARIANT,DISCONTINUED,MH05-S-Green,Old Hoodie-S-Green,<p>Discontinued variant</p>,STANDARD_CATEGORY,USD,30.000000,,,AU,Tax Group,Tax Tariff,PC:MASTER:2,MASTER
-G_PROD_006,VARIANT,ACTIVE,MH06-XL-Black,Premium Hoodie-XL-Black,<p>Premium black variant extra large</p>,STANDARD_CATEGORY|PREMIUM,USD,75.000000,USD,55.000000,AU,Tax Group,Tax Tariff,PC:MASTER:2,MASTER
-G_PROD_007,STANDARD,ACTIVE,MH07-BASIC,Basic Hoodie,<p>Entry level hoodie</p>,STANDARD_CATEGORY,USD,35.000000,,,AU,Tax Group,Tax Tariff,PC:MASTER:2,MASTER
-G_PROD_008,VARIANT,ACTIVE,MH08-M-White,Summer Hoodie-M-White,<p>Lightweight summer variant</p>,STANDARD_CATEGORY|SEASONAL|SUMMER,USD,42.000000,,,AU,Tax Group,Tax Tariff,PC:MASTER:2,MASTER
-G_PROD_009,VARIANT,ACTIVE,MH09-L-Navy,Classic Hoodie-L-Navy,<p>Classic navy large variant</p>,STANDARD_CATEGORY,USD,55.000000,USD,45.000000,AU,Tax Group,Tax Tariff,PC:MASTER:2,MASTER
-G_PROD_010,VARIANT,DISCONTINUED,MH10-S-Yellow,Retro Hoodie-S-Yellow,<p>Retro design discontinued</p>,STANDARD_CATEGORY|VINTAGE,USD,25.000000,,,AU,Tax Group,Tax Tariff,PC:MASTER:2,MASTER
+ref,type,status,gtin,name,summary,category_refs,price_default_currency,price_default_value,price_special_currency,price_special_value,tax_country,tax_group,tax_tariff,catalogue_ref,catalogue_type
+G_PROD_WITH_NO_STANDARD,VARIANT,ACTIVE,MH01-XS-Orange,Chaz Kangeroo Hoodie-XS-Orange main,<p>test short description</p>,STANDARD_CATEGORY,USD,52.000000,USD,9.000000,AU,Tax Group,Tax Tariff,PC:MASTER:2,MASTER
+G_PROD_002,VARIANT,ACTIVE,MH02-M-Blue,Kangeroo Hoodie-M-Blue,<p>Blue variant medium size</p>,STANDARD_CATEGORY|SEASONAL,USD,45.000000,USD,35.000000,AU,Tax Group,Tax Tariff,PC:MASTER:2,MASTER
+G_PROD_003,STANDARD,ACTIVE,MH03-BASE,Base Hoodie Product,<p>Base product without variants</p>,STANDARD_CATEGORY,USD,50.000000,,,AU,Tax Group,Tax Tariff,PC:MASTER:2,MASTER
+G_PROD_004,VARIANT,ACTIVE,MH04-L-Red,Kangeroo Hoodie-L-Red,<p>Red variant large size</p>,STANDARD_CATEGORY|CLEARANCE,USD,60.000000,USD,40.000000,AU,Tax Group,Tax Tariff,PC:MASTER:2,MASTER
+G_PROD_005,VARIANT,DISCONTINUED,MH05-S-Green,Old Hoodie-S-Green,<p>Discontinued variant</p>,STANDARD_CATEGORY,USD,30.000000,,,AU,Tax Group,Tax Tariff,PC:MASTER:2,MASTER
+G_PROD_006,VARIANT,ACTIVE,MH06-XL-Black,Premium Hoodie-XL-Black,<p>Premium black variant extra large</p>,STANDARD_CATEGORY|PREMIUM,USD,75.000000,USD,55.000000,AU,Tax Group,Tax Tariff,PC:MASTER:2,MASTER
+G_PROD_007,STANDARD,ACTIVE,MH07-BASIC,Basic Hoodie,<p>Entry level hoodie</p>,STANDARD_CATEGORY,USD,35.000000,,,AU,Tax Group,Tax Tariff,PC:MASTER:2,MASTER
+G_PROD_008,VARIANT,ACTIVE,MH08-M-White,Summer Hoodie-M-White,<p>Lightweight summer variant</p>,STANDARD_CATEGORY|SEASONAL|SUMMER,USD,42.000000,,,AU,Tax Group,Tax Tariff,PC:MASTER:2,MASTER
+G_PROD_009,VARIANT,ACTIVE,MH09-L-Navy,Classic Hoodie-L-Navy,<p>Classic navy large variant</p>,STANDARD_CATEGORY,USD,55.000000,USD,45.000000,AU,Tax Group,Tax Tariff,PC:MASTER:2,MASTER
+G_PROD_010,VARIANT,DISCONTINUED,MH10-S-Yellow,Retro Hoodie-S-Yellow,<p>Retro design discontinued</p>,STANDARD_CATEGORY|VINTAGE,USD,25.000000,,,AU,Tax Group,Tax Tariff,PC:MASTER:2,MASTER

package/docs/01-TEMPLATES/versori/workflows/_examples/sample-data/sample-data-guide.md

@@ -1,34 +1,34 @@
-# Sample Data
-
-> **Sample data files for testing workflows**
-
-## Overview
-
-This directory contains sample data files for testing ingestion and extraction workflows. Each file represents a common data format used in Fluent Commerce integrations.
-
-## Available Sample Files
-
-Use these files to test workflow templates before deploying to production.
-
-## Using Sample Data
-
-1. **Choose a template** from workflow directories
-2. **Locate matching sample file** in this directory
-3. **Upload to test environment** (S3, SFTP, or Versori file storage)
-4. **Configure workflow** to use sample file
-5. **Run workflow** with manual trigger
-6. **Verify results** in Fluent Commerce or destination
-
-## File Formats
-
-Sample files are provided in these formats:
-- **CSV** - Comma-separated values
-- **JSON** - JSON objects and arrays
-- **XML** - XML documents with various structures
-- **Parquet** - Columnar data format
-
-## Related Documentation
-
-- [Ingestion Workflows](../../ingestion/) - Data ingestion templates
-- [Extraction Workflows](../../extraction/) - Data extraction templates
-- [Testing Guide](../../../../../04-REFERENCE/testing/) - Complete testing guide
+# Sample Data
+
+> **Sample data files for testing workflows**
+
+## Overview
+
+This directory contains sample data files for testing ingestion and extraction workflows. Each file represents a common data format used in Fluent Commerce integrations.
+
+## Available Sample Files
+
+Use these files to test workflow templates before deploying to production.
+
+## Using Sample Data
+
+1. **Choose a template** from workflow directories
+2. **Locate matching sample file** in this directory
+3. **Upload to test environment** (S3, SFTP, or Versori file storage)
+4. **Configure workflow** to use sample file
+5. **Run workflow** with manual trigger
+6. **Verify results** in Fluent Commerce or destination
+
+## File Formats
+
+Sample files are provided in these formats:
+- **CSV** - Comma-separated values
+- **JSON** - JSON objects and arrays
+- **XML** - XML documents with various structures
+- **Parquet** - Columnar data format
+
+## Related Documentation
+
+- [Ingestion Workflows](../../ingestion/) - Data ingestion templates
+- [Extraction Workflows](../../extraction/) - Data extraction templates
+- [Testing Guide](../../../../../04-REFERENCE/testing/) - Complete testing guide

package/docs/01-TEMPLATES/versori/workflows/_examples/workflow-examples-guide.md

@@ -1,36 +1,36 @@
-# Workflow Examples
-
-> **Example files and sample data for testing workflows**
-
-## Overview
-
-This directory contains example files and sample data for testing Versori workflows. Use these files to test ingestion and extraction templates before deploying to production.
-
-## Directory Structure
-
-```
-_examples/
-└── sample-data/      # Sample data files for testing
-    ├── CSV files
-    ├── JSON files
-    ├── XML files
-    └── Parquet files
-```
-
-## Using Sample Data
-
-1. **Choose a workflow template** from parent directories
-2. **Download sample data** from this directory
-3. **Upload to test environment** (S3, SFTP)
-4. **Run workflow** with manual trigger
-5. **Verify results** in Fluent Commerce
-
-## Sample Data Files
-
-Check the [sample-data](./sample-data/) directory for example files matching each template.
-
-## Related Documentation
-
-- [Ingestion Workflows](../ingestion/) - Data ingestion templates
-- [Extraction Workflows](../extraction/) - Data extraction templates
-- [Testing Guide](../../../../04-REFERENCE/testing/) - Complete testing guide
+# Workflow Examples
+
+> **Example files and sample data for testing workflows**
+
+## Overview
+
+This directory contains example files and sample data for testing Versori workflows. Use these files to test ingestion and extraction templates before deploying to production.
+
+## Directory Structure
+
+```
+_examples/
+└── sample-data/      # Sample data files for testing
+    ├── CSV files
+    ├── JSON files
+    ├── XML files
+    └── Parquet files
+```
+
+## Using Sample Data
+
+1. **Choose a workflow template** from parent directories
+2. **Download sample data** from this directory
+3. **Upload to test environment** (S3, SFTP)
+4. **Run workflow** with manual trigger
+5. **Verify results** in Fluent Commerce
+
+## Sample Data Files
+
+Check the [sample-data](./sample-data/) directory for example files matching each template.
+
+## Related Documentation
+
+- [Ingestion Workflows](../ingestion/) - Data ingestion templates
+- [Extraction Workflows](../extraction/) - Data extraction templates
+- [Testing Guide](../../../../04-REFERENCE/testing/) - Complete testing guide