@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

package/docs/04-REFERENCE/platforms/versori/modules/platforms-versori-04-workflows.md

@@ -1,2476 +1,2476 @@
-# Module 4: Workflows - HTTP, Webhooks, Scheduled & Internal Functions
-
-[← Back to Versori Platform Guide](../platforms-versori-readme.md)
-
-**Module 4 of 8** | **Level**: Intermediate | **Time**: 30 minutes
-
----
-
-## Learning Objectives
-
-By the end of this module, you will:
-
-- ✅ Master all four workflow types: http(), webhook(), schedule(), fn()
-- ✅ Understand when to use each workflow type
-- ✅ Implement HTTP workflows with Fluent API calls
-- ✅ Build webhook receivers with signature validation
-- ✅ Create scheduled tasks with cron patterns
-- ✅ Compose multi-step workflows with fn()
-- ✅ **Handle non-JSON responses** (XML, HTML, CSV) correctly
-- ✅ Implement error handling and retry strategies
-
----
-
-## Workflow Types Overview
-
-Versori provides four fundamental workflow types, each with specific capabilities and use cases:
-
-| Type           | Purpose               | External API Access              | Context                      | Use When                              |
-| -------------- | --------------------- | -------------------------------- | ---------------------------- | ------------------------------------- |
-| **http()**     | External API calls    | ✅ Yes (requires connection)     | `fetch`, `log`, `activation` | Query/mutate Fluent API               |
-| **webhook()**  | Receive HTTP requests | ❌ No (unless chained with http) | `data`, `request()`, `log`   | Receive SFCC orders, Rubix events     |
-| **schedule()** | Time-based tasks      | ✅ Yes (if connection provided)  | `fetch`, `log`, `activation` | Daily sync, hourly extraction         |
-| **fn()**       | Internal processing   | ❌ No                            | `openKv`, `log`, `request()` | Data transformation, state management |
-
----
-
-## ⚠️ CRITICAL: Accessing Headers & Choosing Workflow Types
-
-### Accessing HTTP Headers
-
-**The `Context<D>` interface does NOT have a `headers` property.** Always use `ctx.request()`:
-
-```typescript
-// ✅ CORRECT - Access headers via request()
-const req = ctx.request();
-const apiKey = req?.headers['x-api-key'] as string;
-const contentType = req?.headers['content-type'];
-
-// ❌ WRONG - ctx.headers doesn't exist in @versori/run
-const apiKey = ctx.headers?.get?.('x-api-key'); // ERROR!
-```
-
-### When to Use http() vs fn()
-
-**Decision Rule:** Do you need to call external APIs (Fluent Commerce, S3 presigned URLs, etc.)?
-
-#### Use `http()` When:
-
-- ✅ Calling Fluent Commerce GraphQL API
-- ✅ Need connection credentials and authentication
-- ✅ Require `ctx.fetch` with OAuth2 auth
-- ✅ Need `connectionVariables` or `baseUrl`
-
-**What you get in http():**
-
-```typescript
-http('my-task', { connection: 'fluent_commerce' }, async ctx => {
-  ctx.fetch; // ✅ Authenticated fetch with connection
-  ctx.connectionVariables; // ✅ Connection configuration
-  ctx.baseUrl; // ✅ API base URL from connection
-  ctx.request(); // ✅ HTTP request object (for headers)
-  (ctx.log, ctx.data, ctx.activation, ctx.openKv()); // ✅ All standard context
-
-  // Can call external APIs:
-  const client = await createClient(ctx); // ✅ Works!
-});
-```
-
-#### Use `fn()` When:
-
-- ✅ Pure data transformation (no external API calls)
-- ✅ State management with KV storage only
-- ✅ Parsing, mapping, validation logic
-- ✅ File tracking and deduplication
-
-**What you get in fn():**
-
-```typescript
-fn('my-task', async ctx => {
-  ctx.data; // ✅ Input data
-  ctx.log; // ✅ Logger
-  ctx.activation; // ✅ Variables from activation
-  ctx.openKv(); // ✅ KV storage access
-  ctx.request(); // ✅ HTTP request object (for headers)
-
-  // ❌ NO ctx.fetch - cannot make authenticated API calls
-  // ❌ NO connectionVariables - no connection context
-  // ❌ CANNOT call createClient() - will fail
-});
-```
-
-### Example: Adhoc Extraction (Requires http())
-
-```typescript
-// ✅ CORRECT - Use http() for Fluent API access with connection-based security
-export const adhocExtraction = webhook('adhoc-extract', {
-  connection: 'webhook-auth',  // ← Platform validates API key automatically
-  response: { mode: 'sync' },
-}).then(
-  http('execute-extraction', { connection: 'fluent_commerce' }, async ctx => {
-    const { log, data } = ctx;
-
-    // ✅ If we're here, authentication already passed via connection
-    // No manual validation code needed!
-
-    // http() provides connection context for createClient()
-    const client = await createClient(ctx); // ✅ Works!
-    const result = await client.graphql({ query: '...' });
-
-    return { success: true, data: result.data };
-  })
-);
-
-// ❌ WRONG - fn() cannot access Fluent API
-export const brokenExtraction = webhook('adhoc-extract', {
-  connection: 'webhook-auth'
-}).then(
-  fn('execute-extraction', async ctx => {
-    const client = await createClient(ctx); // ❌ FAILS - no connection context in fn()
-  })
-);
-```
-
-### Quick Decision Table
-
-| Need To                         | Use      | Reason                               |
-| ------------------------------- | -------- | ------------------------------------ |
-| Call Fluent GraphQL API         | `http()` | Requires connection + authentication |
-| Parse CSV to JSON               | `fn()`   | No external API needed               |
-| Check if file already processed | `fn()`   | Uses KV storage only                 |
-| Send batch to Fluent            | `http()` | Requires Fluent API access           |
-| Transform/map data              | `fn()`   | Pure data transformation             |
-| Query external REST API         | `http()` | Requires fetch + connection          |
-| Access HTTP headers             | **Both** | Use `ctx.request()` in either        |
-
----
-
-## ⚠️ Deno Compatibility: Buffer Import
-
-**CRITICAL for Versori Platform (Deno runtime):** Always import Buffer explicitly when working with binary data, file uploads, or base64 encoding/decoding.
-
-### Why Buffer Import is Required
-
-Versori runs on Deno, not Node.js. In Node.js, `Buffer` is globally available, but in Deno it must be explicitly imported from `node:buffer`.
-
-```typescript
-// ✅ CORRECT - Always import Buffer in Versori/Deno
-import { Buffer } from 'node:buffer';
-
-await sftp.uploadFile('/path/file.xml', Buffer.from(xmlContent, 'utf-8'));
-const decoded = Buffer.from(base64String, 'base64').toString('utf-8');
-
-// ❌ WRONG - Buffer is not global in Deno
-await sftp.uploadFile('/path/file.xml', Buffer.from(xmlContent, 'utf-8'));  // ReferenceError!
-```
-
-### When to Import Buffer
-
-Import Buffer when your workflow involves:
-
-| Operation | Example | Requires Buffer? |
-|-----------|---------|------------------|
-| **File uploads** (SFTP, S3) | `sftp.uploadFile()` | ✅ Yes |
-| **Base64 encoding/decoding** | `Buffer.from(str, 'base64')` | ✅ Yes |
-| **Binary data handling** | Working with binary files | ✅ Yes |
-| **String encoding** | `Buffer.from(str, 'utf-8')` | ✅ Yes |
-| **XML response generation** | Returning XML as string | ❌ No (string only) |
-| **JSON operations** | `JSON.parse()`, `JSON.stringify()` | ❌ No |
-| **GraphQL queries** | `client.graphql()` | ❌ No |
-
-### Pattern: Add Buffer Import at Top of File
-
-```typescript
-// ✅ CORRECT Pattern - Add at top of file with other imports
-import { Buffer } from 'node:buffer';  // Required for Deno
-import { schedule, http, fn } from '@versori/run';
-import { createClient, SftpDataSource } from '@fluentcommerce/fc-connect-sdk';
-
-export const sftpUpload = schedule('upload', '0 * * * *')
-  .then(fn('prepare-file', async (ctx) => {
-    // Buffer available here
-    const fileContent = Buffer.from(ctx.data.content, 'utf-8');
-    return { fileContent };
-  }));
-```
-
-**See Also:** All examples in this module that use Buffer include the import statement.
-
----
-
-## HTTP Functions - External API Calls
-
-HTTP workflows enable authenticated calls to external APIs, including Fluent Commerce.
-
-### Basic HTTP Workflow
-
-```typescript
-import { http } from '@versori/run';
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-/**
- * Query inventory positions from Fluent Commerce
- *
- * Endpoint: https://{workspace}.versori.run/query-inventory
- * Method: GET
- */
-export const queryInventory = http(
-  'query-inventory',
-  {
-    connection: 'fluent_commerce', // CRITICAL: Provides OAuth2 auth
-    timeout: 30000, // 30 second timeout
-    retry: {
-      attempts: 3, // Retry up to 3 times
-      delay: 1000, // 1 second between retries
-    },
-  },
-  async ctx => {
-    ctx.log('info', 'Starting inventory query');
-
-    try {
-      // Create SDK client (auto-configured from connection)
-      const client = await createClient(ctx);
-
-      // GraphQL query - schema validated against Fluent Commerce API
-      const result = await client.graphql({
-        query: `
-        query GetInventoryPositions($first: Int!) {
-          inventoryPositions(first: $first) {
-            edges {
-              node {
-                id
-                ref
-                productRef
-                locationRef
-                onHand          # ✅ Correct field for InventoryPosition
-                status
-              }
-              cursor
-            }
-            pageInfo {
-              hasNextPage
-              endCursor
-            }
-          }
-        }
-      `,
-        variables: { first: 100 },
-      });
-
-      // Check for GraphQL errors
-      if (result.errors?.length) {
-        throw new Error(`GraphQL error: ${result.errors[0].message}`);
-      }
-
-      const positions = result.data.inventoryPositions.edges;
-      ctx.log('info', `Retrieved ${positions.length} inventory positions`);
-
-      return {
-        success: true,
-        count: positions.length,
-        data: positions.map(edge => edge.node),
-        pageInfo: result.data.inventoryPositions.pageInfo,
-      };
-    } catch (error) {
-      ctx.log('error', 'Inventory query failed', {
-        error: error instanceof Error ? error.message : String(error),
-      });
-
-      return {
-        success: false,
-        error: error instanceof Error ? error.message : 'Unknown error',
-      };
-    }
-  }
-);
-```
-
-### HTTP with Query Parameters
-
-```typescript
-export const searchOrders = http(
-  'search-orders',
-  {
-    connection: 'fluent_commerce',
-  },
-  async ctx => {
-    // Extract query parameters
-    const status = ctx.query?.status || 'OPEN';
-    const limit = parseInt(ctx.query?.limit || '50');
-    const customerRef = ctx.query?.customerRef;
-
-    ctx.log('info', 'Searching orders', { status, limit, customerRef });
-
-    const client = await createClient(ctx);
-
-    // Build GraphQL query with filters - schema validated
-    const result = await client.graphql({
-      query: `
-      query SearchOrders($status: String!, $first: Int!, $customerRef: String) {
-        orders(status: $status, first: $first, customerRef: $customerRef) {
-          edges {
-            node {
-              id
-              ref
-              status
-              totalPrice
-              customer {
-                ref
-                firstName
-                lastName
-              }
-              items {
-                edges {
-                  node {
-                    productRef
-                    quantity
-                    price
-                  }
-                }
-              }
-            }
-          }
-        }
-      }
-    `,
-      variables: { status, first: limit, customerRef },
-    });
-
-    return {
-      orders: result.data.orders.edges.map(e => e.node),
-      count: result.data.orders.edges.length,
-    };
-  }
-);
-```
-
-### HTTP with POST Body (Mutations)
-
-```typescript
-import { http } from '@versori/run';
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-/**
- * Create inventory position
- *
- * POST https://{workspace}.versori.run/create-inventory
- * Body: { productRef, locationRef, qty }
- */
-export const createInventory = http(
-  'create-inventory',
-  {
-    connection: 'fluent_commerce',
-  },
-  async ctx => {
-    // Extract POST body
-    const { productRef, locationRef, qty } = ctx.data || {};
-
-    // Validation
-    if (!productRef || !locationRef || qty === undefined) {
-      return {
-        success: false,
-        error: 'Missing required fields: productRef, locationRef, qty',
-      };
-    }
-
-    const client = await createClient(ctx);
-
-    // GraphQL mutation - schema validated
-    const result = await client.graphql({
-      query: `
-      mutation CreateInventoryPosition($input: CreateInventoryPositionInput!) {
-        createInventoryPosition(input: $input) {
-          id
-          ref
-          productRef
-          locationRef
-          onHand
-          status
-        }
-      }
-    `,
-      variables: {
-        input: {
-          productRef,
-          locationRef,
-          qty,
-          type: 'AVAILABLE',
-        },
-      },
-    });
-
-    if (result.errors?.length) {
-      return {
-        success: false,
-        error: result.errors[0].message,
-      };
-    }
-
-    ctx.log('info', 'Inventory position created', {
-      id: result.data.createInventoryPosition.id,
-    });
-
-    return {
-      success: true,
-      data: result.data.createInventoryPosition,
-    };
-  }
-);
-```
-
----
-
-## Webhook Functions - Receiving External Requests
-
-Webhook workflows receive external HTTP requests. They provide `ctx.data` (parsed body) and `ctx.request()` for accessing headers and raw request details.
-
-### Basic Webhook Receiver
-
-```typescript
-import { webhook } from '@versori/run';
-import { parseWebhookRequest } from '@fluentcommerce/fc-connect-sdk';
-
-/**
- * Receive SFCC order webhook
- *
- * POST https://{workspace}.versori.run/receive-order
- * Body: XML order payload
- */
-export const receiveOrder = webhook('receive-order', async ctx => {
-  const req = ctx.request();
-  ctx.log('info', 'Received order webhook', {
-    contentType: req?.headers['content-type'],
-    bodySize: JSON.stringify(ctx.data).length,
-  });
-
-  try {
-    // Parse incoming payload
-    const payload = parseWebhookRequest(ctx.data);
-
-    if (!payload) {
-      return {
-        success: false,
-        error: 'Invalid payload format',
-        status: 400,
-      };
-    }
-
-    // Process order (use fn() or http() in chain)
-    ctx.log('info', 'Order parsed successfully', {
-      orderId: payload.orderId,
-    });
-
-    return {
-      success: true,
-      orderId: payload.orderId,
-      status: 200,
-    };
-  } catch (error) {
-    ctx.log('error', 'Webhook processing failed', {
-      error: error instanceof Error ? error.message : String(error),
-    });
-
-    return {
-      success: false,
-      error: error instanceof Error ? error.message : 'Processing failed',
-      status: 500,
-    };
-  }
-});
-```
-
-### Webhook with Signature Validation (Fluent Rubix)
-
-**IMPORTANT**: The webhook validation is **ONLY** for webhooks sent from **Fluent Commerce Rubix workflows**.
-
-```typescript
-import { webhook } from '@versori/run';
-import {
-  WebhookValidationService,
-  SignatureAlgorithm,
-  parseWebhookRequest,
-  validateFluentEvent,
-} from '@fluentcommerce/fc-connect-sdk';
-
-/**
- * Receive Fluent Rubix webhook with signature validation
- *
- * POST https://{workspace}.versori.run/rubix-event
- * Headers: fluent-signature (or x-fluent-signature)
- */
-export const receiveRubixEvent = webhook('rubix-event', async ctx => {
-  const logger = ctx.log; // Use native Versori logger
-
-  // Get public key from connector variables
-  const publicKey = ctx.vars?.FLUENT_WEBHOOK_PUBLIC_KEY;
-  if (!publicKey) {
-    logger.error('Missing FLUENT_WEBHOOK_PUBLIC_KEY in connector variables');
-    return { error: 'Configuration error: missing public key', status: 500 };
-  }
-
-  // IMPORTANT: This validator is ONLY for Fluent Commerce Rubix workflows
-  const validator = new WebhookValidationService(
-    {
-      algorithm: SignatureAlgorithm.SHA512_WITH_RSA,
-      strictValidation: true,
-    },
-    logger
-  );
-
-  // Extract signature from headers using ctx.request()
-  const req = ctx.request();
-  const signature = req?.headers['fluent-signature'] || req?.headers['x-fluent-signature'];
-
-  if (!signature) {
-    logger.warn('Missing webhook signature in headers');
-    return { error: 'Missing signature', status: 401 };
-  }
-
-  // Validate Fluent Commerce Rubix webhook signature
-  const validationResult = await validator.validateWebhookSignature(
-    JSON.stringify(ctx.data),
-    signature,
-    publicKey,
-    SignatureAlgorithm.SHA512_WITH_RSA
-  );
-
-  if (!validationResult.isValid) {
-    logger.error('Fluent Commerce Rubix webhook validation failed', validationResult);
-    return {
-      error: 'Invalid Fluent Rubix webhook signature',
-      details: validationResult.error,
-      status: 401,
-    };
-  }
-
-  // Parse webhook payload
-  const payload = parseWebhookRequest(ctx.data, logger, 'receiveRubixEvent');
-
-  if (!payload) {
-    return { error: 'Invalid payload', status: 400 };
-  }
-
-  // Validate event structure
-  const validation = validateFluentEvent(payload, logger, 'receiveRubixEvent');
-  if (!validation.isValid) {
-    return {
-      error: 'Validation failed',
-      details: validation.warnings,
-      status: 400,
-    };
-  }
-
-  logger.info('Rubix webhook validated successfully', {
-    eventName: payload.name,
-    entityType: payload.entityType,
-  });
-
-  return {
-    success: true,
-    eventName: payload.name,
-    status: 200,
-  };
-});
-```
-
-### CRITICAL: Non-JSON Response Handlers (XML, HTML, CSV)
-
-**Problem**: By default, Versori JSON-encodes all webhook responses. This breaks XML, HTML, CSV, and other non-JSON content.
-
-**Solution**: Use custom `onSuccess` and `onError` handlers that return `Response` objects.
-
-#### XML Response Example
-
-```typescript
-import { webhook, fn } from '@versori/run';
-
-/**
- * Return XML response from webhook
- *
- * GET/POST https://{workspace}.versori.run/order-status-xml
- * Returns: Raw XML (NOT JSON-encoded)
- */
-export const orderStatusXML = webhook('order-status-xml', {
-  response: {
-    mode: 'sync',
-    onSuccess: ctx => {
-      // ctx.data contains the final value from .then() chain
-      return new Response(ctx.data, {
-        status: 200,
-        headers: {
-          'Content-Type': 'application/xml; charset=utf-8',
-          'X-Execution-Id': ctx.executionId,
-        },
-      });
-    },
-    onError: ctx => {
-      // ctx.data contains the error from .catch()
-      const errorXml = `<?xml version="1.0" encoding="UTF-8"?>
-<ErrorResponse>
-  <Error>
-    <Code>PROCESSING_ERROR</Code>
-    <Message>${ctx.data?.message || 'Unknown error'}</Message>
-    <Timestamp>${new Date().toISOString()}</Timestamp>
-    <ExecutionId>${ctx.executionId}</ExecutionId>
-  </Error>
-</ErrorResponse>`;
-
-      return new Response(errorXml, {
-        status: 500,
-        headers: {
-          'Content-Type': 'application/xml; charset=utf-8',
-          'X-Execution-Id': ctx.executionId,
-        },
-      });
-    },
-  },
-  cors: true,
-})
-  .then(
-    fn('generate-xml', ({ data }) => {
-      // Return raw XML string - this becomes ctx.data in onSuccess
-      const orderId = data?.orderId || 'unknown';
-      return `<?xml version="1.0" encoding="UTF-8"?>
-<OrderStatusResponse>
-  <OrderId>${orderId}</OrderId>
-  <Status>SHIPPED</Status>
-  <Timestamp>${new Date().toISOString()}</Timestamp>
-</OrderStatusResponse>`;
-    })
-  )
-  .catch(({ data }) => {
-    // Return error - this becomes ctx.data in onError
-    return { message: data instanceof Error ? data.message : String(data) };
-  });
-```
-
-**Why This Works**:
-
-- @versori/run's `sendResponse()` function streams `Response` objects directly **without JSON encoding**
-- The Content-Type header is preserved exactly as specified
-- Works with @versori/run v0.4.4 and all v0.4.x versions
-
-#### HTML Response Example
-
-```typescript
-export const statusPage = webhook('status-page', {
-  response: {
-    mode: 'sync',
-    onSuccess: ctx =>
-      new Response(ctx.data, {
-        status: 200,
-        headers: { 'Content-Type': 'text/html; charset=utf-8' },
-      }),
-  },
-}).then(
-  fn('generate-html', () => {
-    return `<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <title>Order Status</title>
-</head>
-<body>
-  <h1>System Operational</h1>
-  <p>All services running normally.</p>
-</body>
-</html>`;
-  })
-);
-```
-
-#### CSV Response Example
-
-```typescript
-export const exportCSV = webhook('export-csv', {
-  response: {
-    mode: 'sync',
-    onSuccess: ctx =>
-      new Response(ctx.data, {
-        status: 200,
-        headers: {
-          'Content-Type': 'text/csv; charset=utf-8',
-          'Content-Disposition': 'attachment; filename="orders.csv"',
-        },
-      }),
-  },
-}).then(
-  fn('generate-csv', () => {
-    return 'OrderId,Status,Total\n123,SHIPPED,99.99\n456,PENDING,149.99';
-  })
-);
-```
-
-#### Complex Multi-Step Workflow with XML Response
-
-```typescript
-import { webhook, fn, http } from '@versori/run';
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-import { XMLBuilder } from 'fast-xml-parser';
-
-/**
- * Fetch order from Fluent, return as XML
- *
- * POST https://{workspace}.versori.run/order-detail-xml
- * Body: { orderId }
- * Returns: Order details as XML
- */
-export const orderDetailXML = webhook('order-detail-xml', {
-  response: {
-    mode: 'sync',
-    onSuccess: ctx =>
-      new Response(ctx.data, {
-        status: 200,
-        headers: {
-          'Content-Type': 'application/xml; charset=utf-8',
-          'X-Execution-Id': ctx.executionId,
-          'X-Order-Id': ctx.metadata?.orderId || 'unknown',
-        },
-      }),
-    onError: ctx => {
-      const errorXml = `<?xml version="1.0" encoding="UTF-8"?>
-<ErrorResponse>
-  <Error>
-    <Code>PROCESSING_ERROR</Code>
-    <Message>${ctx.data?.message || 'Unknown error'}</Message>
-    <Timestamp>${new Date().toISOString()}</Timestamp>
-    <ExecutionId>${ctx.executionId}</ExecutionId>
-  </Error>
-</ErrorResponse>`;
-
-      return new Response(errorXml, {
-        status: 500,
-        headers: {
-          'Content-Type': 'application/xml; charset=utf-8',
-          'X-Execution-Id': ctx.executionId,
-        },
-      });
-    },
-  },
-  cors: true,
-})
-  // Step 1: Parse incoming request
-  .then(
-    fn('parse-request', ({ data }) => {
-      const orderId = data?.orderId;
-      if (!orderId) {
-        throw new Error('OrderId missing from request');
-      }
-      return { orderId };
-    })
-  )
-
-  // Step 2: Fetch from Fluent Commerce
-  .then(
-    http(
-      'fetch-order',
-      {
-        connection: 'fluent_commerce',
-      },
-      async ctx => {
-        const { orderId } = ctx.data;
-        const client = await createClient(ctx);
-
-        // GraphQL query - schema validated
-        const result = await client.graphql({
-          query: `
-        query GetOrder($ref: String!) {
-          order(ref: $ref) {
-            id
-            ref
-            status
-            totalPrice
-            customer {
-              ref
-              firstName
-              lastName
-            }
-          }
-        }
-      `,
-          variables: { ref: orderId },
-        });
-
-        if (!result.data?.order) {
-          throw new Error(`Order not found: ${orderId}`);
-        }
-
-        return {
-          orderId,
-          orderData: result.data.order,
-        };
-      }
-    )
-  )
-
-  // Step 3: Build XML response
-  .then(
-    fn('build-xml', ({ data }) => {
-      const builder = new XMLBuilder({
-        ignoreAttributes: false,
-        attributeNamePrefix: '@',
-        format: true,
-      });
-
-      const xmlObject = {
-        '?xml': { '@version': '1.0', '@encoding': 'UTF-8' },
-        OrderDetailResponse: {
-          '@orderId': data.orderId,
-          Order: {
-            Id: data.orderData.id,
-            Ref: data.orderData.ref,
-            Status: data.orderData.status,
-            TotalPrice: data.orderData.totalPrice,
-            Customer: {
-              Ref: data.orderData.customer.ref,
-              Name: `${data.orderData.customer.firstName} ${data.orderData.customer.lastName}`,
-            },
-          },
-        },
-      };
-
-      return builder.build(xmlObject);
-    })
-  )
-
-  .catch(({ data }) => {
-    // Return error message as object - onError handler will format as XML
-    return { message: data instanceof Error ? data.message : String(data) };
-  });
-```
-
-**Key Patterns**:
-
-- `onSuccess` and `onError` **return Response objects**
-- Workflow steps **return raw strings** (NOT Response objects)
-- Content-Type header matches actual content format
-- Error handler uses same Content-Type as success handler
-
----
-
-## Scheduled Functions - Time-Based Recurring Tasks
-
-Scheduled workflows run on a cron schedule. They **MUST** be chained with `.then()` to add processing logic. To access external APIs (like Fluent Commerce), chain with `http()` task.
-
-### ⚠️ CRITICAL: schedule() Signature
-
-**schedule() does NOT accept a handler or options as parameters**. It returns a `Workflow` that must be chained.
-
-**Signature**:
-```typescript
-function schedule(
-  id: string,
-  schedule: string,
-  activationPredicate?: ActivationPredicate
-): Workflow<ScheduleData>
-```
-
-**activationPredicate**: Optional - `'all'` or custom filter function `(activation?: Activation) => boolean`
-
-### Basic Scheduled Workflow
-
-```typescript
-import { schedule, http } from '@versori/run';
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-/**
- * Daily inventory sync - runs at 2 AM UTC daily
- *
- * Cron: 0 2 * * * (every day at 2:00 AM)
- */
-export const dailyInventorySync = schedule(
-  'daily-inventory-sync',
-  '0 2 * * *'
-)
-  .then(
-    http(
-      'sync-inventory',
-      { connection: 'fluent_commerce' },
-      async ctx => {
-        ctx.log.info('Starting daily inventory sync');
-
-        const client = await createClient(ctx);
-
-        // Fetch inventory from external source (e.g., S3)
-        const inventoryData = await fetchInventoryFromS3(ctx);
-
-        // Create batch job
-        const job = await client.createJob({
-          name: 'Daily Inventory Sync',
-          retailerId: ctx.activation.getVariable('FLUENT_RETAILER_ID'),
-        });
-
-        // Send batch data
-        const batch = await client.sendBatch(job.id, {
-          action: 'UPSERT',
-          entityType: 'INVENTORY',
-          entities: inventoryData,
-        });
-
-        ctx.log.info('Daily sync complete', {
-          jobId: job.id,
-          batchId: batch.id,
-          recordCount: inventoryData.length,
-        });
-
-        return {
-          success: true,
-          jobId: job.id,
-          recordCount: inventoryData.length,
-        };
-      }
-    )
-  );
-```
-
-### Common Cron Patterns
-
-```typescript
-// Every minute - with http() for API access
-export const everyMinute = schedule('every-minute', '* * * * *')
-  .then(http('task', { connection: 'fluent_commerce' }, async (ctx) => {
-    // Fluent API access available
-    const client = await createClient(ctx);
-    // ... process
-  }));
-
-// Every minute - with fn() for KV-only
-export const everyMinuteKV = schedule('every-minute-kv', '* * * * *')
-  .then(fn('task', async (ctx) => {
-    // KV storage only, no external API
-    const kv = ctx.openKv(':project:');
-    // ... process
-  }));
-
-// Every hour at minute 0
-export const hourly = schedule('hourly', '0 * * * *')
-  .then(http('sync', { connection: 'fluent_commerce' }, async (ctx) => {
-    // Hourly inventory sync
-  }));
-
-// Every 6 hours - Fluent inventory snapshot
-export const every6Hours = schedule('every-6-hours', '0 */6 * * *')
-  .then(http('snapshot', { connection: 'fluent_commerce' }, async (ctx) => {
-    // Extract inventory snapshot every 6 hours
-  }));
-
-// Daily at 2 AM - Full sync
-export const dailyAt2AM = schedule('daily-2am', '0 2 * * *')
-  .then(http('full-sync', { connection: 'fluent_commerce' }, async (ctx) => {
-    // Daily full inventory sync
-  }));
-
-// Weekdays at 9 AM - Business hours processing
-export const weekdaysAt9AM = schedule('weekdays-9am', '0 9 * * 1-5')
-  .then(http('business-hours', { connection: 'fluent_commerce' }, async (ctx) => {
-    // Weekday order processing
-  }));
-
-// First of every month at midnight - Monthly reports
-export const monthlyFirst = schedule('monthly-first', '0 0 1 * *')
-  .then(http('monthly-report', { connection: 'fluent_commerce' }, async (ctx) => {
-    // Generate monthly inventory reports
-  }));
-
-// Every Sunday at 3 AM - Weekly cleanup
-export const weeklySunday = schedule('weekly-sunday', '0 3 * * 0')
-  .then(http('weekly-cleanup', { connection: 'fluent_commerce' }, async (ctx) => {
-    // Weekly data cleanup
-  }));
-
-// With activation predicate (filter by activation)
-export const allActivations = schedule('all-act', '0 * * * *', 'all')
-  .then(fn('task', async (ctx) => {
-    // Runs for all activations
-  }));
-
-export const customPredicate = schedule('custom', '0 * * * *', (a) => a?.id?.startsWith('prod'))
-  .then(fn('task', async (ctx) => {
-    // Runs only for production activations
-  }));
-```
-
-### Scheduled Workflow with State Management
-
-```typescript
-import { schedule, fn, http } from '@versori/run';
-import { createClient, VersoriFileTracker } from '@fluentcommerce/fc-connect-sdk';
-
-/**
- * Hourly incremental sync with file tracking
- *
- * Cron: 0 * * * * (every hour)
- */
-export const hourlyIncrementalSync = schedule(
-  'hourly-sync',
-  '0 * * * *'
-)
-  .then(
-    fn('check-files', async ctx => {
-      const kv = ctx.openKv(':project:');
-      const tracker = new VersoriFileTracker(kv, 'hourly-sync');
-
-      const lastFile = await tracker.getLastProcessedFile();
-      const newFiles = await listFilesAfter(lastFile);
-
-      if (newFiles.length === 0) {
-        ctx.log.info('No new files to process');
-        throw new Error('SKIP'); // Signal to skip processing
-      }
-
-      return { newFiles, tracker };
-    })
-  )
-  .then(
-    http(
-      'process-files',
-      { connection: 'fluent_commerce' },
-      async ctx => {
-        const { newFiles, tracker } = ctx.data;
-        const client = await createClient(ctx);
-        let processedCount = 0;
-
-        for (const file of newFiles) {
-          if (await tracker.wasFileProcessed(file.name)) {
-            ctx.log.info('Skipping already processed file', { file: file.name });
-            continue;
-          }
-
-          const records = await processFile(file);
-
-          const job = await client.createJob({ name: `Hourly Sync - ${file.name}` });
-          await client.sendBatch(job.id, {
-            action: 'UPSERT',
-            entityType: 'INVENTORY',
-            entities: records,
-          });
-
-          await tracker.markFileProcessed(file.name, {
-            recordCount: records.length,
-            timestamp: Date.now(),
-          });
-
-          await tracker.setLastProcessedFile(file.name);
-          processedCount += records.length;
-        }
-
-        ctx.log.info('Hourly sync complete', {
-          filesProcessed: newFiles.length,
-          recordsProcessed: processedCount,
-        });
-
-        return {
-          success: true,
-          filesProcessed: newFiles.length,
-          recordsProcessed: processedCount,
-        };
-      }
-    )
-  )
-  .catch(({ data }) => {
-    if (data.message === 'SKIP') {
-      return { skipped: true, reason: 'No new files' };
-    }
-    return { success: false, error: data.message };
-  });
-```
-
----
-
-## Internal Functions (fn) - Data Transformation & State
-
-Internal functions (`fn()`) are for processing that **does NOT require external API access**. They have access to KV storage and logging, but **NOT** `ctx.fetch`.
-
-### File Tracking with fn()
-
-```typescript
-import { fn } from '@versori/run';
-import { VersoriFileTracker } from '@fluentcommerce/fc-connect-sdk';
-
-/**
- * Track file processing state
- *
- * Used internally by other workflows (NOT exposed as HTTP endpoint)
- */
-export const trackFileProcessing = fn('track-file', async ctx => {
-  const kv = ctx.openKv(':project:');
-  const tracker = new VersoriFileTracker(kv, 'inventory-ingestion');
-
-  const fileName = ctx.data?.fileName;
-  if (!fileName) {
-    return { error: 'Missing fileName' };
-  }
-
-  // Check if processed
-  if (await tracker.wasFileProcessed(fileName)) {
-    return { skipped: true, reason: 'Already processed' };
-  }
-
-  // Mark as processed
-  await tracker.markFileProcessed(fileName, {
-    records: ctx.data?.recordCount || 0,
-    timestamp: Date.now(),
-  });
-
-  return { tracked: true, fileName };
-});
-```
-
-### Data Transformation with fn()
-
-```typescript
-import { fn } from '@versori/run';
-import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-
-/**
- * Transform CSV data to Fluent format
- *
- * Used as part of workflow composition
- */
-export const transformInventoryData = fn('transform-inventory', async ctx => {
-  const rawData = ctx.data?.records;
-  if (!rawData || !Array.isArray(rawData)) {
-    return { error: 'Invalid input data' };
-  }
-
-  // Define field mapping
-  const mappingConfig = {
-    fields: {
-      productRef: { source: 'sku_id', required: true },
-      locationRef: { source: 'location_code', required: true },
-      qty: { source: 'quantity', resolver: 'sdk.parseInt' },
-      status: { source: 'status', resolver: 'sdk.uppercase' },
-    },
-  };
-
-  const mapper = new UniversalMapper(mappingConfig);
-
-  // Transform all records
-  const transformed = [];
-  const errors = [];
-
-  for (const record of rawData) {
-    const result = await mapper.map(record);
-    if (result.success) {
-      transformed.push(result.data);
-    } else {
-      errors.push({ record, errors: result.errors });
-    }
-  }
-
-  ctx.log('info', 'Transformation complete', {
-    totalRecords: rawData.length,
-    transformed: transformed.length,
-    errors: errors.length,
-  });
-
-  return {
-    transformed,
-    errors,
-    stats: {
-      total: rawData.length,
-      success: transformed.length,
-      failed: errors.length,
-    },
-  };
-});
-```
-
----
-
-## Workflow Composition - Multi-Step Patterns
-
-Combine multiple workflow types using `.then()` and `.catch()` chaining.
-
-### Pattern 1: Webhook → fn() → http()
-
-```typescript
-import { webhook, fn, http } from '@versori/run';
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-/**
- * Receive order → validate → send to Fluent
- *
- * POST https://{workspace}.versori.run/process-order
- */
-export const processOrder = webhook('process-order')
-  // Step 1: Parse and validate (fn - no external API)
-  .then(
-    fn('validate-order', ({ data }) => {
-      if (!data?.orderId || !data?.items) {
-        throw new Error('Invalid order data: missing orderId or items');
-      }
-
-      return {
-        orderId: data.orderId,
-        items: data.items.map(item => ({
-          productRef: item.sku,
-          quantity: parseInt(item.qty, 10),
-          price: parseFloat(item.price),
-        })),
-      };
-    })
-  )
-
-  // Step 2: Send to Fluent (http - requires connection)
-  .then(
-    http(
-      'send-to-fluent',
-      {
-        connection: 'fluent_commerce',
-      },
-      async ctx => {
-        const { orderId, items } = ctx.data;
-        const client = await createClient(ctx);
-
-        // GraphQL mutation - schema validated
-        const result = await client.graphql({
-          query: `
-        mutation CreateOrder($input: CreateOrderInput!) {
-          createOrder(input: $input) {
-            id
-            ref
-            status
-          }
-        }
-      `,
-          variables: {
-            input: {
-              ref: orderId,
-              items: items.map(item => ({
-                productRef: item.productRef,
-                quantity: item.quantity,
-                price: item.price,
-              })),
-            },
-          },
-        });
-
-        return {
-          success: true,
-          fluentOrderId: result.data.createOrder.id,
-          fluentOrderRef: result.data.createOrder.ref,
-        };
-      }
-    )
-  )
-
-  // Error handling
-  .catch(({ data }) => {
-    return {
-      success: false,
-      error: data instanceof Error ? data.message : 'Processing failed',
-      status: 500,
-    };
-  });
-```
-
-### Pattern 2: Scheduled → fn() (File Tracking) → http() (API Call)
-
-```typescript
-import { schedule, fn, http } from '@versori/run';
-import { createClient, VersoriFileTracker } from '@fluentcommerce/fc-connect-sdk';
-
-/**
- * Daily sync with file tracking
- *
- * Cron: 0 1 * * * (daily at 1 AM)
- */
-export const dailySyncWithTracking = schedule('daily-sync', '0 1 * * *', {
-  connection: 'fluent_commerce',
-})
-  // Step 1: Check if already processed today (fn - KV access)
-  .then(
-    fn('check-processed', async ctx => {
-      const kv = ctx.openKv(':project:');
-      const tracker = new VersoriFileTracker(kv, 'daily-sync');
-
-      const today = new Date().toISOString().split('T')[0];
-      const fileKey = `inventory-${today}.csv`;
-
-      if (await tracker.wasFileProcessed(fileKey)) {
-        throw new Error('Already processed today');
-      }
-
-      return { fileKey, today };
-    })
-  )
-
-  // Step 2: Fetch and process (http - external API)
-  .then(
-    http(
-      'process-sync',
-      {
-        connection: 'fluent_commerce',
-      },
-      async ctx => {
-        const { fileKey } = ctx.data;
-        const client = await createClient(ctx);
-
-        // Fetch data from external source
-        const records = await fetchDailyInventory();
-
-        // Send to Fluent
-        const job = await client.createJob({ name: `Daily Sync ${fileKey}` });
-        await client.sendBatch(job.id, {
-          action: 'UPSERT',
-          entityType: 'INVENTORY',
-          entities: records,
-        });
-
-        return {
-          fileKey,
-          jobId: job.id,
-          recordCount: records.length,
-        };
-      }
-    )
-  )
-
-  // Step 3: Mark as processed (fn - KV access)
-  .then(
-    fn('mark-processed', async ctx => {
-      const kv = ctx.openKv(':project:');
-      const tracker = new VersoriFileTracker(kv, 'daily-sync');
-      const { fileKey, recordCount } = ctx.data;
-
-      await tracker.markFileProcessed(fileKey, {
-        recordCount,
-        timestamp: Date.now(),
-      });
-
-      return {
-        success: true,
-        fileKey,
-        recordCount,
-      };
-    })
-  )
-
-  .catch(({ data }) => {
-    if (data.message === 'Already processed today') {
-      return { skipped: true, reason: 'Already processed today' };
-    }
-    return { success: false, error: data.message };
-  });
-```
-
----
-
-## Error Handling & Retry Strategies
-
-### Basic Error Handling
-
-```typescript
-export const robustWorkflow = http(
-  'robust',
-  {
-    connection: 'fluent_commerce',
-    retry: {
-      attempts: 3,
-      delay: 1000,
-      backoff: 2, // Exponential backoff multiplier
-    },
-  },
-  async ctx => {
-    try {
-      const client = await createClient(ctx);
-      const result = await client.graphql({ query: '...' });
-
-      if (result.errors?.length) {
-        throw new Error(`GraphQL failed: ${result.errors[0].message}`);
-      }
-
-      return { success: true, data: result.data };
-    } catch (error) {
-      ctx.log('error', 'Operation failed', {
-        error: error instanceof Error ? error.message : String(error),
-        stack: error instanceof Error ? error.stack : undefined,
-      });
-
-      throw error; // Re-throw for retry mechanism
-    }
-  }
-);
-```
-
-### Advanced Error Handling with Fallback
-
-```typescript
-export const withFallback = http(
-  'with-fallback',
-  {
-    connection: 'fluent_commerce',
-  },
-  async ctx => {
-    const client = await createClient(ctx);
-
-    try {
-      // Primary operation
-      const result = await client.graphql({ query: '...' });
-      return { source: 'primary', data: result.data };
-    } catch (primaryError) {
-      ctx.log('warn', 'Primary operation failed, trying fallback', {
-        error: primaryError instanceof Error ? primaryError.message : String(primaryError),
-      });
-
-      try {
-        // Fallback operation
-        const fallbackResult = await client.graphql({ query: '... (simpler query)' });
-        return { source: 'fallback', data: fallbackResult.data };
-      } catch (fallbackError) {
-        ctx.log('error', 'Both primary and fallback failed', {
-          primaryError: primaryError instanceof Error ? primaryError.message : String(primaryError),
-          fallbackError:
-            fallbackError instanceof Error ? fallbackError.message : String(fallbackError),
-        });
-
-        throw new Error('All operations failed');
-      }
-    }
-  }
-);
-```
-
----
-
-## Real-World Fluent Commerce Use Cases
-
-This section provides detailed, production-ready examples for common Fluent Commerce integration patterns.
-
-### Use Case 1: Inventory Position Ingestion from CSV
-
-**Scenario**: Daily CSV file from warehouse management system → Fluent inventory positions
-
-```typescript
-import { schedule, fn, http } from '@versori/run';
-import {
-  createClient,
-  S3DataSource,
-  CSVParserService,
-  UniversalMapper,
-  VersoriFileTracker
-} from '@fluentcommerce/fc-connect-sdk';
-
-/**
- * Daily inventory ingestion from S3 CSV
- *
- * Cron: 0 3 * * * (3 AM daily)
- * Flow: Check file → Parse CSV → Transform → Send to Fluent
- */
-export const dailyInventoryIngestion = schedule('daily-inventory-ingestion', '0 3 * * *')
-  // Step 1: Check for new files (fn - KV only)
-  .then(fn('check-new-files', async ctx => {
-    const kv = ctx.openKv(':project:');
-    const tracker = new VersoriFileTracker(kv, 'inventory-ingestion');
-
-    const s3Config = {
-      bucket: ctx.activation.getVariable<string>('S3_BUCKET'),
-      region: ctx.activation.getVariable<string>('AWS_REGION'),
-      accessKeyId: ctx.activation.getVariable<string>('AWS_ACCESS_KEY_ID'),
-      secretAccessKey: ctx.activation.getVariable<string>('AWS_SECRET_ACCESS_KEY'),
-    };
-
-    const s3 = new S3DataSource(s3Config, ctx.log);
-    const files = await s3.listFiles({ prefix: 'inventory/daily/' });
-
-    // Filter unprocessed files
-    const newFiles = [];
-    for (const file of files) {
-      if (!(await tracker.wasFileProcessed(file.key))) {
-        newFiles.push(file);
-      }
-    }
-
-    if (newFiles.length === 0) {
-      throw new Error('NO_NEW_FILES');
-    }
-
-    ctx.log.info('Found new inventory files', { count: newFiles.length });
-    return { s3Config, files: newFiles, tracker };
-  }))
-
-  // Step 2: Parse and transform (fn - no API needed)
-  .then(fn('parse-transform', async ctx => {
-    const { s3Config, files, tracker } = ctx.data;
-    const s3 = new S3DataSource(s3Config, ctx.log);
-    const parser = new CSVParserService(ctx.log);
-
-    // Mapping configuration
-    const mappingConfig = {
-      fields: {
-        // Fluent field: CSV column
-        ref: { source: 'sku', required: true },
-        productRef: { source: 'sku', required: true },
-        locationRef: { source: 'location_code', required: true },
-        qty: { source: 'quantity', resolver: 'sdk.parseInt', required: true },
-        type: { value: 'AVAILABLE' },  // Static value
-        storageArea: { source: 'warehouse_zone' },
-        expectedOn: { source: 'delivery_date', resolver: 'sdk.formatDate' },
-      },
-    };
-
-    const mapper = new UniversalMapper(mappingConfig);
-    const allRecords = [];
-
-    for (const file of files) {
-      const content = await s3.readFile(file.key);
-      const parsed = await parser.parse(content, {
-        headers: true,
-        skipEmptyLines: true
-      });
-
-      // Transform each row
-      for (const row of parsed) {
-        const result = await mapper.map(row);
-        if (result.success) {
-          allRecords.push(result.data);
-        } else {
-          ctx.log.warn('Mapping failed', { row, errors: result.errors });
-        }
-      }
-    }
-
-    ctx.log.info('Parsed and transformed records', {
-      fileCount: files.length,
-      recordCount: allRecords.length
-    });
-
-    return { records: allRecords, files, tracker };
-  }))
-
-  // Step 3: Send to Fluent (http - requires API connection)
-  .then(http('send-to-fluent', { connection: 'fluent_commerce' }, async ctx => {
-    const { records, files, tracker } = ctx.data;
-    const client = await createClient(ctx);
-
-    // Create batch job
-    const job = await client.createJob({
-      name: `Daily Inventory Ingestion - ${new Date().toISOString().split('T')[0]}`,
-      retailerId: ctx.activation.getVariable<number>('FLUENT_RETAILER_ID'),
-    });
-
-    // Send in batches of 500
-    const batchSize = 500;
-    const batches = [];
-
-    for (let i = 0; i < records.length; i += batchSize) {
-      const chunk = records.slice(i, i + batchSize);
-      const batch = await client.sendBatch(job.id, {
-        action: 'UPSERT',
-        entityType: 'INVENTORY_POSITION',
-        entities: chunk,
-        meta: {
-          preprocessing: 'skip',  // Delta file, skip BPP
-        },
-      });
-      batches.push(batch.id);
-    }
-
-    // Mark files as processed
-    for (const file of files) {
-      await tracker.markFileProcessed(file.key, {
-        jobId: job.id,
-        recordCount: records.length,
-        timestamp: Date.now(),
-      });
-    }
-
-    ctx.log.info('Inventory ingestion complete', {
-      jobId: job.id,
-      batches: batches.length,
-      totalRecords: records.length,
-    });
-
-    return {
-      success: true,
-      jobId: job.id,
-      recordCount: records.length,
-      filesProcessed: files.length,
-    };
-  }))
-
-  .catch(({ data }) => {
-    if (data.message === 'NO_NEW_FILES') {
-      return { skipped: true, reason: 'No new files to process' };
-    }
-    return { success: false, error: data.message || 'Unknown error' };
-  });
-```
-
-### Use Case 2: Order Creation from SFCC XML Webhook
-
-**Scenario**: SFCC sends order XML → Validate → Create order in Fluent
-
-```typescript
-import { webhook, fn, http } from '@versori/run';
-import {
-  createClient,
-  XMLParserService,
-  GraphQLMutationMapper
-} from '@fluentcommerce/fc-connect-sdk';
-
-/**
- * Receive SFCC order XML webhook and create order in Fluent
- *
- * POST https://{workspace}.versori.run/sfcc-order-create
- * Content-Type: application/xml
- */
-export const sfccOrderCreate = webhook('sfcc-order-create', {
-  connection: 'sfcc-webhook-auth',  // Platform validates API key
-  response: {
-    mode: 'sync',
-    onSuccess: ctx => new Response(ctx.data, {
-      status: 200,
-      headers: { 'Content-Type': 'application/xml; charset=utf-8' },
-    }),
-    onError: ctx => {
-      const errorXml = `<?xml version="1.0"?>
-<ErrorResponse>
-  <Error>
-    <Code>PROCESSING_ERROR</Code>
-    <Message>${ctx.data?.message || 'Order processing failed'}</Message>
-    <ExecutionId>${ctx.executionId}</ExecutionId>
-  </Error>
-</ErrorResponse>`;
-      return new Response(errorXml, {
-        status: 500,
-        headers: { 'Content-Type': 'application/xml; charset=utf-8' },
-      });
-    },
-  },
-})
-  // Step 1: Parse XML (fn - no API needed)
-  .then(fn('parse-xml', async ctx => {
-    const parser = new XMLParserService(ctx.log);
-    const xmlData = await parser.parse(ctx.data);
-
-    // Validate required fields
-    if (!xmlData.order?.['@id']) {
-      throw new Error('Invalid order XML: missing order ID');
-    }
-
-    ctx.log.info('Parsed SFCC order XML', {
-      orderId: xmlData.order['@id'],
-      customerEmail: xmlData.order.customer?.email
-    });
-
-    return { xmlData };
-  }))
-
-  // Step 2: Transform and create order (http - Fluent API access)
-  .then(http('create-fluent-order', { connection: 'fluent_commerce' }, async ctx => {
-    const { xmlData } = ctx.data;
-    const client = await createClient(ctx);
-
-    // GraphQL mutation mapping config
-    const mappingConfig = {
-      mutationName: 'createOrder',
-      sourceFormat: 'xml',
-      arguments: {
-        input: {
-          ref: { source: 'order.@id' },
-          type: { value: 'STANDARD' },
-          retailer: { source: 'order.@retailerId', resolver: 'sdk.parseInt' },
-          customer: {
-            firstName: { source: 'order.customer.firstname' },
-            lastName: { source: 'order.customer.lastname' },
-            email: { source: 'order.customer.email' },
-          },
-          items: {
-            source: 'order.items.item',
-            isArray: true,
-            mapping: {
-              productRef: { source: '@sku' },
-              quantity: { source: 'quantity', resolver: 'sdk.parseInt' },
-              price: {
-                value: { source: 'price', resolver: 'sdk.parseFloat' },
-                currency: { source: '@currency', default: 'USD' },
-              },
-            },
-          },
-          fulfilment: {
-            type: { value: 'STANDARD' },
-            deliveryType: { source: 'order.shipping.method' },
-            deliveryAddress: {
-              name: { source: 'order.shipping.address.name' },
-              street: { source: 'order.shipping.address.street' },
-              city: { source: 'order.shipping.address.city' },
-              state: { source: 'order.shipping.address.state' },
-              postcode: { source: 'order.shipping.address.postalcode' },
-              country: { source: 'order.shipping.address.country' },
-            },
-          },
-          payments: {
-            source: 'order.payments.payment',
-            isArray: true,
-            mapping: {
-              method: { source: '@method' },
-              amount: { source: 'amount', resolver: 'sdk.parseFloat' },
-              cardType: { source: 'creditcard.type' },
-            },
-          },
-        },
-      },
-    };
-
-    const mapper = new GraphQLMutationMapper(mappingConfig, ctx.log, { fluentClient: client });
-    const { mutation, variables } = await mapper.generateMutation(xmlData);
-
-    // Execute mutation
-    const result = await client.graphql({ query: mutation, variables });
-
-    if (result.errors?.length) {
-      throw new Error(`Order creation failed: ${result.errors[0].message}`);
-    }
-
-    const order = result.data.createOrder;
-    ctx.log.info('Order created in Fluent', {
-      fluentOrderId: order.id,
-      sfccOrderId: xmlData.order['@id']
-    });
-
-    return {
-      fluentOrderId: order.id,
-      fluentOrderRef: order.ref,
-      sfccOrderId: xmlData.order['@id'],
-    };
-  }))
-
-  // Step 3: Generate success XML response (fn)
-  .then(fn('generate-response', ctx => {
-    const { fluentOrderId, sfccOrderId } = ctx.data;
-    return `<?xml version="1.0"?>
-<OrderResponse>
-  <Success>true</Success>
-  <SFCCOrderId>${sfccOrderId}</SFCCOrderId>
-  <FluentOrderId>${fluentOrderId}</FluentOrderId>
-  <Timestamp>${new Date().toISOString()}</Timestamp>
-</OrderResponse>`;
-  }))
-
-  .catch(({ data }) => {
-    return { message: data instanceof Error ? data.message : String(data) };
-  });
-```
-
-### Use Case 3: Virtual Position Extraction to SFTP
-
-**Scenario**: Scheduled extraction of Fluent virtual positions → XML → Upload to SFTP
-
-```typescript
-import { Buffer } from 'node:buffer';  // ⚠️ Required for Deno compatibility
-import { schedule, http, fn } from '@versori/run';
-import {
-  createClient,
-  ExtractionOrchestrator,
-  SftpDataSource,
-  VersoriFileTracker
-} from '@fluentcommerce/fc-connect-sdk';
-import { XMLBuilder } from 'fast-xml-parser';
-
-/**
- * Extract virtual positions and upload to SFTP as XML
- *
- * Cron: 0 */4 * * * (every 4 hours)
- */
-export const virtualPositionExtraction = schedule('virtual-position-extraction', '0 */4 * * *')
-  // Step 1: Extract from Fluent (http - API access)
-  .then(http('extract-positions', { connection: 'fluent_commerce' }, async ctx => {
-    const client = await createClient(ctx);
-
-    // Define extraction config
-    const extractionConfig = {
-      query: `
-        query GetVirtualPositions($first: Int!, $after: String) {
-          virtualPositions(first: $first, after: $after) {
-            edges {
-              node {
-                id
-                ref
-                productRef
-                groupRef
-                onHand
-                quantity
-                type
-                status
-                createdOn
-                updatedOn
-              }
-              cursor
-            }
-            pageInfo {
-              hasNextPage
-              endCursor
-            }
-          }
-        }
-      `,
-      variables: { first: 200 },
-      pathToData: 'virtualPositions',
-      pathToCursor: 'pageInfo.endCursor',
-      pathToHasNext: 'pageInfo.hasNextPage',
-    };
-
-    // Use ExtractionOrchestrator for auto-pagination
-    const orchestrator = new ExtractionOrchestrator(client, ctx.log);
-    const result = await orchestrator.extractWithPagination(extractionConfig);
-
-    if (!result.success) {
-      throw new Error(`Extraction failed: ${result.errors?.join(', ')}`);
-    }
-
-    ctx.log.info('Extracted virtual positions', {
-      recordCount: result.data?.length || 0
-    });
-
-    return { positions: result.data || [] };
-  }))
-
-  // Step 2: Transform to XML (fn - no API)
-  .then(fn('transform-to-xml', ctx => {
-    const { positions } = ctx.data;
-
-    const xmlBuilder = new XMLBuilder({
-      ignoreAttributes: false,
-      attributeNamePrefix: '@',
-      format: true,
-      indentBy: '  ',
-    });
-
-    const xmlObject = {
-      '?xml': { '@version': '1.0', '@encoding': 'UTF-8' },
-      VirtualPositionFeed: {
-        '@timestamp': new Date().toISOString(),
-        '@recordCount': positions.length,
-        Positions: {
-          Position: positions.map(pos => ({
-            '@id': pos.id,
-            Ref: pos.ref,
-            ProductRef: pos.productRef,
-            GroupRef: pos.groupRef,
-            OnHand: pos.onHand,
-            Quantity: pos.quantity,
-            Type: pos.type,
-            Status: pos.status,
-            CreatedOn: pos.createdOn,
-            UpdatedOn: pos.updatedOn,
-          })),
-        },
-      },
-    };
-
-    const xmlContent = xmlBuilder.build(xmlObject);
-
-    const fileName = `virtual-positions-${new Date().toISOString().replace(/:/g, '-')}.xml`;
-
-    ctx.log.info('Generated XML feed', { fileName, recordCount: positions.length });
-
-    return { xmlContent, fileName, recordCount: positions.length };
-  }))
-
-  // Step 3: Upload to SFTP (fn - external SFTP, not Fluent API)
-  .then(fn('upload-to-sftp', async ctx => {
-    const { xmlContent, fileName, recordCount } = ctx.data;
-
-    const sftpConfig = {
-      host: ctx.activation.getVariable<string>('SFTP_HOST'),
-      port: ctx.activation.getVariable<number>('SFTP_PORT') || 22,
-      username: ctx.activation.getVariable<string>('SFTP_USERNAME'),
-      password: ctx.activation.getVariable<string>('SFTP_PASSWORD'),
-    };
-
-    const sftp = new SftpDataSource(sftpConfig, ctx.log);
-    await sftp.connect();
-
-    try {
-      const remotePath = `/outbound/${fileName}`;
-      await sftp.uploadFile(remotePath, Buffer.from(xmlContent, 'utf-8'));
-
-      ctx.log.info('Uploaded to SFTP', { remotePath, recordCount });
-
-      // Track in KV
-      const kv = ctx.openKv(':project:');
-      const tracker = new VersoriFileTracker(kv, 'virtual-position-extraction');
-      await tracker.markFileProcessed(fileName, {
-        recordCount,
-        timestamp: Date.now(),
-        remotePath,
-      });
-
-      return {
-        success: true,
-        fileName,
-        remotePath,
-        recordCount,
-      };
-    } finally {
-      await sftp.disconnect();
-    }
-  }))
-
-  .catch(({ data }) => ({
-    success: false,
-    error: data instanceof Error ? data.message : String(data),
-  }));
-```
-
-### Use Case 4: Multi-Tenant Order Status Webhook
-
-**Scenario**: Multiple customers share one connector, route to correct Fluent instance
-
-```typescript
-import { webhook, fn, http } from '@versori/run';
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-/**
- * Multi-tenant order status update
- *
- * POST https://{workspace}.versori.run/order-status-update
- * Body: { customerId, orderId, status }
- */
-export const orderStatusUpdate = webhook('order-status-update', {
-  response: { mode: 'sync' },
-})
-  // Step 1: Route to correct connection (fn)
-  .then(fn('route-connection', ctx => {
-    const { customerId, orderId, status } = ctx.data;
-
-    if (!customerId || !orderId || !status) {
-      throw new Error('Missing required fields: customerId, orderId, status');
-    }
-
-    // Access all connections via activation.connections
-    const connections = ctx.activation.connections;
-
-    // Find customer-specific Fluent connection
-    const connectionName = `fluent_${customerId.toLowerCase()}`;
-    const connection = connections?.find(c => c.name === connectionName);
-
-    if (!connection) {
-      throw new Error(`No Fluent connection found for customer: ${customerId}`);
-    }
-
-    ctx.log.info('Routed to customer connection', {
-      customerId,
-      connectionName,
-      connectionId: connection.id
-    });
-
-    return { connectionName, orderId, status, customerId };
-  }))
-
-  // Step 2: Update order status (http - with dynamic connection)
-  .then(http('update-order', (ctx) => {
-    // Return dynamic connection name
-    return { connection: ctx.data.connectionName };
-  }, async ctx => {
-    const { orderId, status, customerId } = ctx.data;
-    const client = await createClient(ctx);
-
-    // Update order status
-    const result = await client.graphql({
-      query: `
-        mutation UpdateOrder($ref: String!, $status: String!) {
-          updateOrder(input: { ref: $ref, status: $status }) {
-            id
-            ref
-            status
-          }
-        }
-      `,
-      variables: { ref: orderId, status },
-    });
-
-    if (result.errors?.length) {
-      throw new Error(`Failed to update order: ${result.errors[0].message}`);
-    }
-
-    ctx.log.info('Order status updated', {
-      customerId,
-      orderId,
-      newStatus: status
-    });
-
-    return {
-      success: true,
-      customerId,
-      orderId,
-      status: result.data.updateOrder.status,
-    };
-  }))
-
-  .catch(({ data }) => ({
-    success: false,
-    error: data instanceof Error ? data.message : String(data),
-    status: 500,
-  }));
-```
-
-### Use Case 5: Product Catalog Sync with Enrichment
-
-**Scenario**: Fetch products from PIM system → Enrich → Update Fluent catalog
-
-```typescript
-import { schedule, fn, http } from '@versori/run';
-import {
-  createClient,
-  UniversalMapper,
-  VersoriFileTracker
-} from '@fluentcommerce/fc-connect-sdk';
-
-/**
- * Daily product catalog sync
- *
- * Cron: 0 4 * * * (4 AM daily)
- */
-export const productCatalogSync = schedule('product-catalog-sync', '0 4 * * *')
-  // Step 1: Fetch from external PIM (http - external API)
-  .then(http('fetch-from-pim', { connection: 'pim_system' }, async ctx => {
-    // Fetch products from PIM API
-    const response = await ctx.fetch('/api/v1/products?updated_since=yesterday');
-    const products = await response.json();
-
-    ctx.log.info('Fetched products from PIM', { count: products.length });
-    return { pimProducts: products };
-  }))
-
-  // Step 2: Enrich and transform (fn - data processing)
-  .then(fn('enrich-transform', async ctx => {
-    const { pimProducts } = ctx.data;
-
-    const mappingConfig = {
-      fields: {
-        ref: { source: 'sku', required: true },
-        type: { value: 'STANDARD' },
-        name: { source: 'name', required: true },
-        summary: { source: 'short_description' },
-        gtin: { source: 'barcode' },
-        prices: {
-          source: 'pricing',
-          isArray: true,
-          mapping: {
-            type: { source: 'price_type' },
-            value: { source: 'amount', resolver: 'sdk.parseFloat' },
-            currency: { source: 'currency', default: 'USD' },
-          },
-        },
-        attributes: {
-          source: 'custom_attributes',
-          isArray: true,
-          mapping: {
-            name: { source: 'attr_name' },
-            value: { source: 'attr_value', resolver: 'sdk.toString' },
-            type: { value: 'STRING' },
-          },
-        },
-        taxType: {
-          type: { source: 'tax.type' },
-          group: { source: 'tax.group' },
-          tariff: { source: 'tax.tariff_code' },
-        },
-      },
-    };
-
-    const mapper = new UniversalMapper(mappingConfig);
-    const enrichedProducts = [];
-
-    for (const product of pimProducts) {
-      const result = await mapper.map(product);
-      if (result.success) {
-        enrichedProducts.push(result.data);
-      } else {
-        ctx.log.warn('Product mapping failed', {
-          sku: product.sku,
-          errors: result.errors
-        });
-      }
-    }
-
-    ctx.log.info('Products enriched', { count: enrichedProducts.length });
-    return { products: enrichedProducts };
-  }))
-
-  // Step 3: Send to Fluent (http - Fluent API)
-  .then(http('sync-to-fluent', { connection: 'fluent_commerce' }, async ctx => {
-    const { products } = ctx.data;
-    const client = await createClient(ctx);
-
-    const job = await client.createJob({
-      name: `Product Catalog Sync - ${new Date().toISOString().split('T')[0]}`,
-      retailerId: ctx.activation.getVariable<number>('FLUENT_RETAILER_ID'),
-    });
-
-    // Send in chunks
-    const batchSize = 100;
-    const batches = [];
-
-    for (let i = 0; i < products.length; i += batchSize) {
-      const chunk = products.slice(i, i + batchSize);
-      const batch = await client.sendBatch(job.id, {
-        action: 'UPSERT',
-        entityType: 'PRODUCT',
-        entities: chunk,
-        meta: {
-          preprocessing: 'apply',  // Full snapshot, use BPP
-        },
-      });
-      batches.push(batch.id);
-    }
-
-    ctx.log.info('Product sync complete', {
-      jobId: job.id,
-      productCount: products.length,
-      batchCount: batches.length,
-    });
-
-    return {
-      success: true,
-      jobId: job.id,
-      productCount: products.length,
-    };
-  }))
-
-  .catch(({ data }) => ({
-    success: false,
-    error: data instanceof Error ? data.message : String(data),
-  }));
-```
-
----
-
-## ⚠️ CRITICAL: `.parallel()` Error Behavior
-
-**BEFORE USING `.parallel()` - READ THIS:**
-
-The `.parallel()` method has **all-or-nothing error behavior** that makes it **UNSUITABLE for most batch processing use cases**.
-
-### What Happens When One Task Fails
-
-```typescript
-// ❌ PROBLEM: If ANY file fails, you lose ALL results
-schedule('process-files', '0 2 * * *')
-  .then(fn('fetch', () => ['file1.xml', 'file2.xml', 'file3.xml']))
-  .unpack()
-  .parallel(fn('process', async (ctx) => {
-    return await processFile(ctx.data);
-  }));
-```
-
-**If `file2.xml` fails:**
-- ❌ `file1.xml` might have processed successfully but **result is lost**
-- ❌ `file3.xml` never runs (or is cancelled mid-execution)
-- ❌ **Entire workflow fails**
-- ❌ **NO partial results returned**
-- ❌ You can't retry only failed items
-
-### Implementation Detail
-
-The `.parallel()` method uses RxJS `mergeMap` + `toArray()`:
-- Any error in `mergeMap` propagates to the stream
-- `toArray()` never completes if the stream errors
-- **Result: one failure stops everything**
-
-### Comparison: `.parallel()` vs `Promise.allSettled`
-
-| Feature | `.parallel()` | `Promise.allSettled` |
-|---------|--------------|---------------------|
-| Fault tolerance | ❌ Fails on first error | ✅ Continues on errors |
-| Partial results | ❌ None if any fail | ✅ All results |
-| Error isolation | ❌ No isolation | ✅ Complete isolation |
-| Retry failures | ❌ Must retry all | ✅ Retry only failures |
-
-### When to Use `.parallel()`
-
-**ONLY use `.parallel()` when:**
-1. ✅ **All tasks MUST succeed** (transactional requirement)
-2. ✅ **Small number of items** (3-10 max)
-3. ✅ **Fast, reliable operations** (< 10 seconds each)
-4. ✅ **Partial success is worse than complete failure**
-
-**Examples where `.parallel()` is appropriate:**
-- Fetching 3-5 required entity types (all needed for next step)
-- Validating multiple webhook signatures (all must be valid)
-- Small, predictable, low-failure-rate operations
-
-### When to Use `Promise.allSettled` (SDK Pattern)
-
-**PREFER `Promise.allSettled` for:**
-1. ✅ **Batch processing** (files, records, entities)
-2. ✅ **Large datasets** (10+ items)
-3. ✅ **Failures are expected** (network issues, bad data)
-4. ✅ **Partial success is valuable** (process 990/1000 items)
-5. ✅ **Need retry logic** (retry only failures)
-
-**Example using SDK pattern:**
-```typescript
-export const batchProcess = schedule('batch', '0 */6 * * *')
-  .then(
-    http('process', { connection: 'fluent_commerce' }, async (ctx) => {
-      const items = await fetchItems();
-
-      // ✅ Use Promise.allSettled for fault tolerance
-      const results = await Promise.allSettled(
-        items.map(item =>
-          processItem(item)
-            .then(result => ({ success: true, item, result }))
-            .catch(error => ({ success: false, item, error: error.message }))
-        )
-      );
-
-      const successes = results
-        .filter(r => r.status === 'fulfilled')
-        .map(r => r.value);
-
-      const failures = results
-        .filter(r => r.status === 'rejected' || !r.value.success);
-
-      ctx.log.info(`Processed ${successes.length} items, ${failures.length} failed`);
-
-      // ✅ Handle failures gracefully
-      if (failures.length > 0) {
-        // Store failures for retry
-        const kv = ctx.openKv(':project:');
-        await kv.set('failed-items', failures);
-      }
-
-      return { successes, failures };
-    })
-  );
-```
-
----
-
-## Parallel Processing with `.unpack()` and `.parallel()`
-
-Versori supports parallel processing via `.unpack()` and `.parallel()` methods, but **they have critical limitations** that affect fault tolerance and error handling (see warning above).
-
-### Available Methods
-
-```typescript
-import { schedule, fn } from '@versori/run';
-
-schedule('process-files', '0 2 * * *')
-  .then(fn('fetch-files', (ctx) => {
-    return ['file1.xml', 'file2.xml', 'file3.xml']; // Returns array
-  }))
-  .unpack()    // ✅ Converts array to ArrayTask
-  .parallel(   // ✅ Processes each item in parallel
-    fn('process-file', async (ctx) => {
-      // ctx.data is now a single item from the array
-      return await processFile(ctx.data);
-    })
-  );
-```
-
-### ⚠️ CRITICAL LIMITATIONS
-
-#### 1. **NOT Fault-Tolerant: One Failure Stops Everything**
-
-**Problem**: If any parallel task fails, the **entire workflow fails** and **no results are returned**.
-
-```typescript
-// ❌ RISKY: If file2.xml fails, entire workflow fails
-schedule('process-files', '0 2 * * *')
-  .then(fn('fetch-files', (ctx) => ['file1.xml', 'file2.xml', 'file3.xml']))
-  .unpack()
-  .parallel(fn('process-file', async (ctx) => {
-    // If ANY file fails here, ALL results lost
-    return await processFile(ctx.data);
-  }));
-
-// Result:
-// ✅ file1.xml might complete
-// ❌ file2.xml fails → ENTIRE WORKFLOW FAILS
-// ❌ file3.xml NEVER RUNS (or gets cancelled)
-// ❌ No partial results returned
-```
-
-**Why**: Uses RxJS `mergeMap` + `toArray()` which stops on first error.
-
-#### 2. **Shared Timeout Across All Tasks**
-
-**Problem**: All parallel tasks share the **same workflow timeout**.
-
-| Trigger Type | Timeout | Impact |
-|-------------|---------|--------|
-| **HTTP/Webhook** | 30 seconds | All parallel tasks must complete in 30s total |
-| **Schedule** | 5 minutes | All parallel tasks must complete in 5min total |
-
-```typescript
-// ⚠️ If processing 10 files in parallel:
-schedule('process-files', '0 2 * * *')
-  .then(fn('fetch-files', (ctx) => Array(10).fill('file.xml')))
-  .unpack()
-  .parallel(fn('process-file', async (ctx) => {
-    // If ANY file takes > 5 minutes, ENTIRE workflow fails
-    return await processFile(ctx.data);
-  }));
-```
-
-#### 3. **NOT ACID Compliant**
-
-**Problem**: No atomicity guarantees. If one task fails:
-- ✅ Successful tasks may have completed their work
-- ❌ But you won't know which ones succeeded
-- ❌ No rollback mechanism
-- ❌ No transaction support
-
-### ✅ Recommended: Use `Promise.allSettled()` Instead
-
-For **fault-tolerant** parallel processing, use `Promise.allSettled()` which continues even when some tasks fail:
-
-```typescript
-import { schedule, fn } from '@versori/run';
-
-schedule('process-files', '0 2 * * *')
-  .then(fn('process-all-files', async (ctx) => {
-    const files = ['file1.xml', 'file2.xml', 'file3.xml'];
-    
-    // ✅ Fault-tolerant: Continues even if some fail
-    const results = await Promise.allSettled(
-      files.map(file => processFile(file))
-    );
-    
-    // Process results
-    const successes = results
-      .filter(r => r.status === 'fulfilled')
-      .map(r => r.value);
-    
-    const failures = results
-      .filter(r => r.status === 'rejected')
-      .map(r => ({ file: r.reason.file, error: r.reason.message }));
-    
-    ctx.log.info(`Processed ${successes.length} files, ${failures.length} failed`);
-    
-    return { successes, failures };
-  }));
-```
-
-**Comparison**:
-
-| Feature | `.unpack().parallel()` | `Promise.allSettled()` |
-|---------|------------------------|------------------------|
-| Fault tolerance | ❌ Fails on first error | ✅ Continues on errors |
-| Partial results | ❌ No results if any fail | ✅ Returns all results |
-| Error isolation | ❌ No isolation | ✅ Complete isolation |
-| Time limits | ⚠️ Shared timeout | ⚠️ Shared timeout |
-| Best for | All-or-nothing workflows | Real-world with failures |
-
-### When to Use `.unpack().parallel()`
-
-**Only use if**:
-- ✅ All tasks **must** succeed (transactional)
-- ✅ You can wrap each task with error handling that returns error objects instead of throwing
-- ✅ You're okay with losing all results on any failure
-
-**Example with error handling**:
-
-```typescript
-schedule('process-files', '0 2 * * *')
-  .then(fn('fetch-files', (ctx) => ['file1.xml', 'file2.xml', 'file3.xml']))
-  .unpack()
-  .parallel(fn('process-file', async (ctx) => {
-    try {
-      const result = await processFile(ctx.data);
-      return { success: true, file: ctx.data, result };
-    } catch (error) {
-      // ✅ Return error object instead of throwing
-      return { 
-        success: false, 
-        file: ctx.data, 
-        error: error.message 
-      };
-    }
-  }))
-  .then(fn('process-results', (ctx) => {
-    // ✅ Now you have all results (success + failures)
-    const results = ctx.data;
-    const successes = results.filter(r => r.success);
-    const failures = results.filter(r => !r.success);
-    
-    ctx.log.info(`Processed ${successes.length} files, ${failures.length} failed`);
-    return { successes, failures };
-  }));
-```
-
-### When to Use `Promise.allSettled()` (Recommended)
-
-**Use `Promise.allSettled()` for**:
-- ✅ Batch API submissions
-- ✅ File processing
-- ✅ Any scenario where failures are expected
-- ✅ When you need partial results
-
-**Already implemented in your code**:
-
-```typescript
-// ✅ Your current BatchProcessorService uses this pattern
-const batchResults = await Promise.allSettled(
-  batchChunk.map((chunk, index) =>
-    this.client.sendBatch(jobId, {
-      action: 'UPSERT',
-      entityType: 'INVENTORY',
-      entities: chunk,
-    }).then(batch => ({ success: true, batch }))
-      .catch(error => ({ success: false, error }))
-  )
-);
-```
-
----
-
-## Key Takeaways
-
-- 🎯 **http()** for external API calls - requires connection, provides `ctx.fetch`
-- 🎯 **webhook()** for receiving requests - provides `ctx.data`, `ctx.request()` for headers
-- 🎯 **schedule()** for time-based tasks - supports cron patterns, can have connection
-- 🎯 **fn()** for internal processing - NO external API access, has `ctx.openKv()`
-- 🎯 **Non-JSON responses** require custom `onSuccess`/`onError` handlers returning Response objects
-- 🎯 **Workflow composition** with `.then()` and `.catch()` enables multi-step patterns
-- 🎯 **Error handling** with try/catch and retry configuration ensures robustness
-- ⚠️ **`.unpack().parallel()`** exists but is NOT fault-tolerant - use `Promise.allSettled()` for resilience
-
----
-
-## Practice Exercise
-
-Create a scheduled workflow that:
-
-1. Runs hourly (cron: `0 * * * *`)
-2. Fetches inventory from an S3 CSV file
-3. Checks KV storage to avoid duplicate processing
-4. Transforms data using UniversalMapper
-5. Sends to Fluent via Batch API
-6. Marks file as processed in KV storage
-7. Returns XML response on error
-
-**Hints**:
-
-- Use `schedule()` with connection
-- Chain with `fn()` for KV checks
-- Use `http()` context for Fluent API calls
-- Implement custom error handler for XML response
-
-**Solution** available in [Module 8: Best Practices](./platforms-versori-08-best-practices.md#practice-solutions)
-
----
-
-## Next Steps
-
-Now that you've mastered all workflow types, let's explore connection management in detail.
-
-Continue to [Module 5: Connections →](./platforms-versori-05-connections.md) to learn about OAuth2 connection types, management, and validation.
-
----
-
-## Related Documentation
-
-- [Module 3: Authentication](./platforms-versori-03-authentication.md) - OAuth2 basics
-- [Module 5: Connections](./platforms-versori-05-connections.md) - Connection management
-- [Module 6: KV Storage](./platforms-versori-06-kv-storage.md) - State management
-- [Webhook Response Patterns](.././modules/platforms-versori-04-workflows.md#critical-non-json-response-handlers-xml-html-csv) - Complete non-JSON response guide
-
----
-
-[← Previous: Module 3](./platforms-versori-03-authentication.md) | [Back to Guide](../platforms-versori-readme.md) | [Next: Module 5: Connections →](./platforms-versori-05-connections.md)
+# Module 4: Workflows - HTTP, Webhooks, Scheduled & Internal Functions
+
+[← Back to Versori Platform Guide](../platforms-versori-readme.md)
+
+**Module 4 of 8** | **Level**: Intermediate | **Time**: 30 minutes
+
+---
+
+## Learning Objectives
+
+By the end of this module, you will:
+
+- ✅ Master all four workflow types: http(), webhook(), schedule(), fn()
+- ✅ Understand when to use each workflow type
+- ✅ Implement HTTP workflows with Fluent API calls
+- ✅ Build webhook receivers with signature validation
+- ✅ Create scheduled tasks with cron patterns
+- ✅ Compose multi-step workflows with fn()
+- ✅ **Handle non-JSON responses** (XML, HTML, CSV) correctly
+- ✅ Implement error handling and retry strategies
+
+---
+
+## Workflow Types Overview
+
+Versori provides four fundamental workflow types, each with specific capabilities and use cases:
+
+| Type           | Purpose               | External API Access              | Context                      | Use When                              |
+| -------------- | --------------------- | -------------------------------- | ---------------------------- | ------------------------------------- |
+| **http()**     | External API calls    | ✅ Yes (requires connection)     | `fetch`, `log`, `activation` | Query/mutate Fluent API               |
+| **webhook()**  | Receive HTTP requests | ❌ No (unless chained with http) | `data`, `request()`, `log`   | Receive SFCC orders, Rubix events     |
+| **schedule()** | Time-based tasks      | ✅ Yes (if connection provided)  | `fetch`, `log`, `activation` | Daily sync, hourly extraction         |
+| **fn()**       | Internal processing   | ❌ No                            | `openKv`, `log`, `request()` | Data transformation, state management |
+
+---
+
+## ⚠️ CRITICAL: Accessing Headers & Choosing Workflow Types
+
+### Accessing HTTP Headers
+
+**The `Context<D>` interface does NOT have a `headers` property.** Always use `ctx.request()`:
+
+```typescript
+// ✅ CORRECT - Access headers via request()
+const req = ctx.request();
+const apiKey = req?.headers['x-api-key'] as string;
+const contentType = req?.headers['content-type'];
+
+// ❌ WRONG - ctx.headers doesn't exist in @versori/run
+const apiKey = ctx.headers?.get?.('x-api-key'); // ERROR!
+```
+
+### When to Use http() vs fn()
+
+**Decision Rule:** Do you need to call external APIs (Fluent Commerce, S3 presigned URLs, etc.)?
+
+#### Use `http()` When:
+
+- ✅ Calling Fluent Commerce GraphQL API
+- ✅ Need connection credentials and authentication
+- ✅ Require `ctx.fetch` with OAuth2 auth
+- ✅ Need `connectionVariables` or `baseUrl`
+
+**What you get in http():**
+
+```typescript
+http('my-task', { connection: 'fluent_commerce' }, async ctx => {
+  ctx.fetch; // ✅ Authenticated fetch with connection
+  ctx.connectionVariables; // ✅ Connection configuration
+  ctx.baseUrl; // ✅ API base URL from connection
+  ctx.request(); // ✅ HTTP request object (for headers)
+  (ctx.log, ctx.data, ctx.activation, ctx.openKv()); // ✅ All standard context
+
+  // Can call external APIs:
+  const client = await createClient(ctx); // ✅ Works!
+});
+```
+
+#### Use `fn()` When:
+
+- ✅ Pure data transformation (no external API calls)
+- ✅ State management with KV storage only
+- ✅ Parsing, mapping, validation logic
+- ✅ File tracking and deduplication
+
+**What you get in fn():**
+
+```typescript
+fn('my-task', async ctx => {
+  ctx.data; // ✅ Input data
+  ctx.log; // ✅ Logger
+  ctx.activation; // ✅ Variables from activation
+  ctx.openKv(); // ✅ KV storage access
+  ctx.request(); // ✅ HTTP request object (for headers)
+
+  // ❌ NO ctx.fetch - cannot make authenticated API calls
+  // ❌ NO connectionVariables - no connection context
+  // ❌ CANNOT call createClient() - will fail
+});
+```
+
+### Example: Adhoc Extraction (Requires http())
+
+```typescript
+// ✅ CORRECT - Use http() for Fluent API access with connection-based security
+export const adhocExtraction = webhook('adhoc-extract', {
+  connection: 'webhook-auth',  // ← Platform validates API key automatically
+  response: { mode: 'sync' },
+}).then(
+  http('execute-extraction', { connection: 'fluent_commerce' }, async ctx => {
+    const { log, data } = ctx;
+
+    // ✅ If we're here, authentication already passed via connection
+    // No manual validation code needed!
+
+    // http() provides connection context for createClient()
+    const client = await createClient(ctx); // ✅ Works!
+    const result = await client.graphql({ query: '...' });
+
+    return { success: true, data: result.data };
+  })
+);
+
+// ❌ WRONG - fn() cannot access Fluent API
+export const brokenExtraction = webhook('adhoc-extract', {
+  connection: 'webhook-auth'
+}).then(
+  fn('execute-extraction', async ctx => {
+    const client = await createClient(ctx); // ❌ FAILS - no connection context in fn()
+  })
+);
+```
+
+### Quick Decision Table
+
+| Need To                         | Use      | Reason                               |
+| ------------------------------- | -------- | ------------------------------------ |
+| Call Fluent GraphQL API         | `http()` | Requires connection + authentication |
+| Parse CSV to JSON               | `fn()`   | No external API needed               |
+| Check if file already processed | `fn()`   | Uses KV storage only                 |
+| Send batch to Fluent            | `http()` | Requires Fluent API access           |
+| Transform/map data              | `fn()`   | Pure data transformation             |
+| Query external REST API         | `http()` | Requires fetch + connection          |
+| Access HTTP headers             | **Both** | Use `ctx.request()` in either        |
+
+---
+
+## ⚠️ Deno Compatibility: Buffer Import
+
+**CRITICAL for Versori Platform (Deno runtime):** Always import Buffer explicitly when working with binary data, file uploads, or base64 encoding/decoding.
+
+### Why Buffer Import is Required
+
+Versori runs on Deno, not Node.js. In Node.js, `Buffer` is globally available, but in Deno it must be explicitly imported from `node:buffer`.
+
+```typescript
+// ✅ CORRECT - Always import Buffer in Versori/Deno
+import { Buffer } from 'node:buffer';
+
+await sftp.uploadFile('/path/file.xml', Buffer.from(xmlContent, 'utf-8'));
+const decoded = Buffer.from(base64String, 'base64').toString('utf-8');
+
+// ❌ WRONG - Buffer is not global in Deno
+await sftp.uploadFile('/path/file.xml', Buffer.from(xmlContent, 'utf-8'));  // ReferenceError!
+```
+
+### When to Import Buffer
+
+Import Buffer when your workflow involves:
+
+| Operation | Example | Requires Buffer? |
+|-----------|---------|------------------|
+| **File uploads** (SFTP, S3) | `sftp.uploadFile()` | ✅ Yes |
+| **Base64 encoding/decoding** | `Buffer.from(str, 'base64')` | ✅ Yes |
+| **Binary data handling** | Working with binary files | ✅ Yes |
+| **String encoding** | `Buffer.from(str, 'utf-8')` | ✅ Yes |
+| **XML response generation** | Returning XML as string | ❌ No (string only) |
+| **JSON operations** | `JSON.parse()`, `JSON.stringify()` | ❌ No |
+| **GraphQL queries** | `client.graphql()` | ❌ No |
+
+### Pattern: Add Buffer Import at Top of File
+
+```typescript
+// ✅ CORRECT Pattern - Add at top of file with other imports
+import { Buffer } from 'node:buffer';  // Required for Deno
+import { schedule, http, fn } from '@versori/run';
+import { createClient, SftpDataSource } from '@fluentcommerce/fc-connect-sdk';
+
+export const sftpUpload = schedule('upload', '0 * * * *')
+  .then(fn('prepare-file', async (ctx) => {
+    // Buffer available here
+    const fileContent = Buffer.from(ctx.data.content, 'utf-8');
+    return { fileContent };
+  }));
+```
+
+**See Also:** All examples in this module that use Buffer include the import statement.
+
+---
+
+## HTTP Functions - External API Calls
+
+HTTP workflows enable authenticated calls to external APIs, including Fluent Commerce.
+
+### Basic HTTP Workflow
+
+```typescript
+import { http } from '@versori/run';
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+/**
+ * Query inventory positions from Fluent Commerce
+ *
+ * Endpoint: https://{workspace}.versori.run/query-inventory
+ * Method: GET
+ */
+export const queryInventory = http(
+  'query-inventory',
+  {
+    connection: 'fluent_commerce', // CRITICAL: Provides OAuth2 auth
+    timeout: 30000, // 30 second timeout
+    retry: {
+      attempts: 3, // Retry up to 3 times
+      delay: 1000, // 1 second between retries
+    },
+  },
+  async ctx => {
+    ctx.log('info', 'Starting inventory query');
+
+    try {
+      // Create SDK client (auto-configured from connection)
+      const client = await createClient(ctx);
+
+      // GraphQL query - schema validated against Fluent Commerce API
+      const result = await client.graphql({
+        query: `
+        query GetInventoryPositions($first: Int!) {
+          inventoryPositions(first: $first) {
+            edges {
+              node {
+                id
+                ref
+                productRef
+                locationRef
+                onHand          # ✅ Correct field for InventoryPosition
+                status
+              }
+              cursor
+            }
+            pageInfo {
+              hasNextPage
+              endCursor
+            }
+          }
+        }
+      `,
+        variables: { first: 100 },
+      });
+
+      // Check for GraphQL errors
+      if (result.errors?.length) {
+        throw new Error(`GraphQL error: ${result.errors[0].message}`);
+      }
+
+      const positions = result.data.inventoryPositions.edges;
+      ctx.log('info', `Retrieved ${positions.length} inventory positions`);
+
+      return {
+        success: true,
+        count: positions.length,
+        data: positions.map(edge => edge.node),
+        pageInfo: result.data.inventoryPositions.pageInfo,
+      };
+    } catch (error) {
+      ctx.log('error', 'Inventory query failed', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Unknown error',
+      };
+    }
+  }
+);
+```
+
+### HTTP with Query Parameters
+
+```typescript
+export const searchOrders = http(
+  'search-orders',
+  {
+    connection: 'fluent_commerce',
+  },
+  async ctx => {
+    // Extract query parameters
+    const status = ctx.query?.status || 'OPEN';
+    const limit = parseInt(ctx.query?.limit || '50');
+    const customerRef = ctx.query?.customerRef;
+
+    ctx.log('info', 'Searching orders', { status, limit, customerRef });
+
+    const client = await createClient(ctx);
+
+    // Build GraphQL query with filters - schema validated
+    const result = await client.graphql({
+      query: `
+      query SearchOrders($status: String!, $first: Int!, $customerRef: String) {
+        orders(status: $status, first: $first, customerRef: $customerRef) {
+          edges {
+            node {
+              id
+              ref
+              status
+              totalPrice
+              customer {
+                ref
+                firstName
+                lastName
+              }
+              items {
+                edges {
+                  node {
+                    productRef
+                    quantity
+                    price
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    `,
+      variables: { status, first: limit, customerRef },
+    });
+
+    return {
+      orders: result.data.orders.edges.map(e => e.node),
+      count: result.data.orders.edges.length,
+    };
+  }
+);
+```
+
+### HTTP with POST Body (Mutations)
+
+```typescript
+import { http } from '@versori/run';
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+/**
+ * Create inventory position
+ *
+ * POST https://{workspace}.versori.run/create-inventory
+ * Body: { productRef, locationRef, qty }
+ */
+export const createInventory = http(
+  'create-inventory',
+  {
+    connection: 'fluent_commerce',
+  },
+  async ctx => {
+    // Extract POST body
+    const { productRef, locationRef, qty } = ctx.data || {};
+
+    // Validation
+    if (!productRef || !locationRef || qty === undefined) {
+      return {
+        success: false,
+        error: 'Missing required fields: productRef, locationRef, qty',
+      };
+    }
+
+    const client = await createClient(ctx);
+
+    // GraphQL mutation - schema validated
+    const result = await client.graphql({
+      query: `
+      mutation CreateInventoryPosition($input: CreateInventoryPositionInput!) {
+        createInventoryPosition(input: $input) {
+          id
+          ref
+          productRef
+          locationRef
+          onHand
+          status
+        }
+      }
+    `,
+      variables: {
+        input: {
+          productRef,
+          locationRef,
+          qty,
+          type: 'AVAILABLE',
+        },
+      },
+    });
+
+    if (result.errors?.length) {
+      return {
+        success: false,
+        error: result.errors[0].message,
+      };
+    }
+
+    ctx.log('info', 'Inventory position created', {
+      id: result.data.createInventoryPosition.id,
+    });
+
+    return {
+      success: true,
+      data: result.data.createInventoryPosition,
+    };
+  }
+);
+```
+
+---
+
+## Webhook Functions - Receiving External Requests
+
+Webhook workflows receive external HTTP requests. They provide `ctx.data` (parsed body) and `ctx.request()` for accessing headers and raw request details.
+
+### Basic Webhook Receiver
+
+```typescript
+import { webhook } from '@versori/run';
+import { parseWebhookRequest } from '@fluentcommerce/fc-connect-sdk';
+
+/**
+ * Receive SFCC order webhook
+ *
+ * POST https://{workspace}.versori.run/receive-order
+ * Body: XML order payload
+ */
+export const receiveOrder = webhook('receive-order', async ctx => {
+  const req = ctx.request();
+  ctx.log('info', 'Received order webhook', {
+    contentType: req?.headers['content-type'],
+    bodySize: JSON.stringify(ctx.data).length,
+  });
+
+  try {
+    // Parse incoming payload
+    const payload = parseWebhookRequest(ctx.data);
+
+    if (!payload) {
+      return {
+        success: false,
+        error: 'Invalid payload format',
+        status: 400,
+      };
+    }
+
+    // Process order (use fn() or http() in chain)
+    ctx.log('info', 'Order parsed successfully', {
+      orderId: payload.orderId,
+    });
+
+    return {
+      success: true,
+      orderId: payload.orderId,
+      status: 200,
+    };
+  } catch (error) {
+    ctx.log('error', 'Webhook processing failed', {
+      error: error instanceof Error ? error.message : String(error),
+    });
+
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Processing failed',
+      status: 500,
+    };
+  }
+});
+```
+
+### Webhook with Signature Validation (Fluent Rubix)
+
+**IMPORTANT**: The webhook validation is **ONLY** for webhooks sent from **Fluent Commerce Rubix workflows**.
+
+```typescript
+import { webhook } from '@versori/run';
+import {
+  WebhookValidationService,
+  SignatureAlgorithm,
+  parseWebhookRequest,
+  validateFluentEvent,
+} from '@fluentcommerce/fc-connect-sdk';
+
+/**
+ * Receive Fluent Rubix webhook with signature validation
+ *
+ * POST https://{workspace}.versori.run/rubix-event
+ * Headers: fluent-signature (or x-fluent-signature)
+ */
+export const receiveRubixEvent = webhook('rubix-event', async ctx => {
+  const logger = ctx.log; // Use native Versori logger
+
+  // Get public key from connector variables
+  const publicKey = ctx.vars?.FLUENT_WEBHOOK_PUBLIC_KEY;
+  if (!publicKey) {
+    logger.error('Missing FLUENT_WEBHOOK_PUBLIC_KEY in connector variables');
+    return { error: 'Configuration error: missing public key', status: 500 };
+  }
+
+  // IMPORTANT: This validator is ONLY for Fluent Commerce Rubix workflows
+  const validator = new WebhookValidationService(
+    {
+      algorithm: SignatureAlgorithm.SHA512_WITH_RSA,
+      strictValidation: true,
+    },
+    logger
+  );
+
+  // Extract signature from headers using ctx.request()
+  const req = ctx.request();
+  const signature = req?.headers['fluent-signature'] || req?.headers['x-fluent-signature'];
+
+  if (!signature) {
+    logger.warn('Missing webhook signature in headers');
+    return { error: 'Missing signature', status: 401 };
+  }
+
+  // Validate Fluent Commerce Rubix webhook signature
+  const validationResult = await validator.validateWebhookSignature(
+    JSON.stringify(ctx.data),
+    signature,
+    publicKey,
+    SignatureAlgorithm.SHA512_WITH_RSA
+  );
+
+  if (!validationResult.isValid) {
+    logger.error('Fluent Commerce Rubix webhook validation failed', validationResult);
+    return {
+      error: 'Invalid Fluent Rubix webhook signature',
+      details: validationResult.error,
+      status: 401,
+    };
+  }
+
+  // Parse webhook payload
+  const payload = parseWebhookRequest(ctx.data, logger, 'receiveRubixEvent');
+
+  if (!payload) {
+    return { error: 'Invalid payload', status: 400 };
+  }
+
+  // Validate event structure
+  const validation = validateFluentEvent(payload, logger, 'receiveRubixEvent');
+  if (!validation.isValid) {
+    return {
+      error: 'Validation failed',
+      details: validation.warnings,
+      status: 400,
+    };
+  }
+
+  logger.info('Rubix webhook validated successfully', {
+    eventName: payload.name,
+    entityType: payload.entityType,
+  });
+
+  return {
+    success: true,
+    eventName: payload.name,
+    status: 200,
+  };
+});
+```
+
+### CRITICAL: Non-JSON Response Handlers (XML, HTML, CSV)
+
+**Problem**: By default, Versori JSON-encodes all webhook responses. This breaks XML, HTML, CSV, and other non-JSON content.
+
+**Solution**: Use custom `onSuccess` and `onError` handlers that return `Response` objects.
+
+#### XML Response Example
+
+```typescript
+import { webhook, fn } from '@versori/run';
+
+/**
+ * Return XML response from webhook
+ *
+ * GET/POST https://{workspace}.versori.run/order-status-xml
+ * Returns: Raw XML (NOT JSON-encoded)
+ */
+export const orderStatusXML = webhook('order-status-xml', {
+  response: {
+    mode: 'sync',
+    onSuccess: ctx => {
+      // ctx.data contains the final value from .then() chain
+      return new Response(ctx.data, {
+        status: 200,
+        headers: {
+          'Content-Type': 'application/xml; charset=utf-8',
+          'X-Execution-Id': ctx.executionId,
+        },
+      });
+    },
+    onError: ctx => {
+      // ctx.data contains the error from .catch()
+      const errorXml = `<?xml version="1.0" encoding="UTF-8"?>
+<ErrorResponse>
+  <Error>
+    <Code>PROCESSING_ERROR</Code>
+    <Message>${ctx.data?.message || 'Unknown error'}</Message>
+    <Timestamp>${new Date().toISOString()}</Timestamp>
+    <ExecutionId>${ctx.executionId}</ExecutionId>
+  </Error>
+</ErrorResponse>`;
+
+      return new Response(errorXml, {
+        status: 500,
+        headers: {
+          'Content-Type': 'application/xml; charset=utf-8',
+          'X-Execution-Id': ctx.executionId,
+        },
+      });
+    },
+  },
+  cors: true,
+})
+  .then(
+    fn('generate-xml', ({ data }) => {
+      // Return raw XML string - this becomes ctx.data in onSuccess
+      const orderId = data?.orderId || 'unknown';
+      return `<?xml version="1.0" encoding="UTF-8"?>
+<OrderStatusResponse>
+  <OrderId>${orderId}</OrderId>
+  <Status>SHIPPED</Status>
+  <Timestamp>${new Date().toISOString()}</Timestamp>
+</OrderStatusResponse>`;
+    })
+  )
+  .catch(({ data }) => {
+    // Return error - this becomes ctx.data in onError
+    return { message: data instanceof Error ? data.message : String(data) };
+  });
+```
+
+**Why This Works**:
+
+- @versori/run's `sendResponse()` function streams `Response` objects directly **without JSON encoding**
+- The Content-Type header is preserved exactly as specified
+- Works with @versori/run v0.4.4 and all v0.4.x versions
+
+#### HTML Response Example
+
+```typescript
+export const statusPage = webhook('status-page', {
+  response: {
+    mode: 'sync',
+    onSuccess: ctx =>
+      new Response(ctx.data, {
+        status: 200,
+        headers: { 'Content-Type': 'text/html; charset=utf-8' },
+      }),
+  },
+}).then(
+  fn('generate-html', () => {
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Order Status</title>
+</head>
+<body>
+  <h1>System Operational</h1>
+  <p>All services running normally.</p>
+</body>
+</html>`;
+  })
+);
+```
+
+#### CSV Response Example
+
+```typescript
+export const exportCSV = webhook('export-csv', {
+  response: {
+    mode: 'sync',
+    onSuccess: ctx =>
+      new Response(ctx.data, {
+        status: 200,
+        headers: {
+          'Content-Type': 'text/csv; charset=utf-8',
+          'Content-Disposition': 'attachment; filename="orders.csv"',
+        },
+      }),
+  },
+}).then(
+  fn('generate-csv', () => {
+    return 'OrderId,Status,Total\n123,SHIPPED,99.99\n456,PENDING,149.99';
+  })
+);
+```
+
+#### Complex Multi-Step Workflow with XML Response
+
+```typescript
+import { webhook, fn, http } from '@versori/run';
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+import { XMLBuilder } from 'fast-xml-parser';
+
+/**
+ * Fetch order from Fluent, return as XML
+ *
+ * POST https://{workspace}.versori.run/order-detail-xml
+ * Body: { orderId }
+ * Returns: Order details as XML
+ */
+export const orderDetailXML = webhook('order-detail-xml', {
+  response: {
+    mode: 'sync',
+    onSuccess: ctx =>
+      new Response(ctx.data, {
+        status: 200,
+        headers: {
+          'Content-Type': 'application/xml; charset=utf-8',
+          'X-Execution-Id': ctx.executionId,
+          'X-Order-Id': ctx.metadata?.orderId || 'unknown',
+        },
+      }),
+    onError: ctx => {
+      const errorXml = `<?xml version="1.0" encoding="UTF-8"?>
+<ErrorResponse>
+  <Error>
+    <Code>PROCESSING_ERROR</Code>
+    <Message>${ctx.data?.message || 'Unknown error'}</Message>
+    <Timestamp>${new Date().toISOString()}</Timestamp>
+    <ExecutionId>${ctx.executionId}</ExecutionId>
+  </Error>
+</ErrorResponse>`;
+
+      return new Response(errorXml, {
+        status: 500,
+        headers: {
+          'Content-Type': 'application/xml; charset=utf-8',
+          'X-Execution-Id': ctx.executionId,
+        },
+      });
+    },
+  },
+  cors: true,
+})
+  // Step 1: Parse incoming request
+  .then(
+    fn('parse-request', ({ data }) => {
+      const orderId = data?.orderId;
+      if (!orderId) {
+        throw new Error('OrderId missing from request');
+      }
+      return { orderId };
+    })
+  )
+
+  // Step 2: Fetch from Fluent Commerce
+  .then(
+    http(
+      'fetch-order',
+      {
+        connection: 'fluent_commerce',
+      },
+      async ctx => {
+        const { orderId } = ctx.data;
+        const client = await createClient(ctx);
+
+        // GraphQL query - schema validated
+        const result = await client.graphql({
+          query: `
+        query GetOrder($ref: String!) {
+          order(ref: $ref) {
+            id
+            ref
+            status
+            totalPrice
+            customer {
+              ref
+              firstName
+              lastName
+            }
+          }
+        }
+      `,
+          variables: { ref: orderId },
+        });
+
+        if (!result.data?.order) {
+          throw new Error(`Order not found: ${orderId}`);
+        }
+
+        return {
+          orderId,
+          orderData: result.data.order,
+        };
+      }
+    )
+  )
+
+  // Step 3: Build XML response
+  .then(
+    fn('build-xml', ({ data }) => {
+      const builder = new XMLBuilder({
+        ignoreAttributes: false,
+        attributeNamePrefix: '@',
+        format: true,
+      });
+
+      const xmlObject = {
+        '?xml': { '@version': '1.0', '@encoding': 'UTF-8' },
+        OrderDetailResponse: {
+          '@orderId': data.orderId,
+          Order: {
+            Id: data.orderData.id,
+            Ref: data.orderData.ref,
+            Status: data.orderData.status,
+            TotalPrice: data.orderData.totalPrice,
+            Customer: {
+              Ref: data.orderData.customer.ref,
+              Name: `${data.orderData.customer.firstName} ${data.orderData.customer.lastName}`,
+            },
+          },
+        },
+      };
+
+      return builder.build(xmlObject);
+    })
+  )
+
+  .catch(({ data }) => {
+    // Return error message as object - onError handler will format as XML
+    return { message: data instanceof Error ? data.message : String(data) };
+  });
+```
+
+**Key Patterns**:
+
+- `onSuccess` and `onError` **return Response objects**
+- Workflow steps **return raw strings** (NOT Response objects)
+- Content-Type header matches actual content format
+- Error handler uses same Content-Type as success handler
+
+---
+
+## Scheduled Functions - Time-Based Recurring Tasks
+
+Scheduled workflows run on a cron schedule. They **MUST** be chained with `.then()` to add processing logic. To access external APIs (like Fluent Commerce), chain with `http()` task.
+
+### ⚠️ CRITICAL: schedule() Signature
+
+**schedule() does NOT accept a handler or options as parameters**. It returns a `Workflow` that must be chained.
+
+**Signature**:
+```typescript
+function schedule(
+  id: string,
+  schedule: string,
+  activationPredicate?: ActivationPredicate
+): Workflow<ScheduleData>
+```
+
+**activationPredicate**: Optional - `'all'` or custom filter function `(activation?: Activation) => boolean`
+
+### Basic Scheduled Workflow
+
+```typescript
+import { schedule, http } from '@versori/run';
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+/**
+ * Daily inventory sync - runs at 2 AM UTC daily
+ *
+ * Cron: 0 2 * * * (every day at 2:00 AM)
+ */
+export const dailyInventorySync = schedule(
+  'daily-inventory-sync',
+  '0 2 * * *'
+)
+  .then(
+    http(
+      'sync-inventory',
+      { connection: 'fluent_commerce' },
+      async ctx => {
+        ctx.log.info('Starting daily inventory sync');
+
+        const client = await createClient(ctx);
+
+        // Fetch inventory from external source (e.g., S3)
+        const inventoryData = await fetchInventoryFromS3(ctx);
+
+        // Create batch job
+        const job = await client.createJob({
+          name: 'Daily Inventory Sync',
+          retailerId: ctx.activation.getVariable('FLUENT_RETAILER_ID'),
+        });
+
+        // Send batch data
+        const batch = await client.sendBatch(job.id, {
+          action: 'UPSERT',
+          entityType: 'INVENTORY',
+          entities: inventoryData,
+        });
+
+        ctx.log.info('Daily sync complete', {
+          jobId: job.id,
+          batchId: batch.id,
+          recordCount: inventoryData.length,
+        });
+
+        return {
+          success: true,
+          jobId: job.id,
+          recordCount: inventoryData.length,
+        };
+      }
+    )
+  );
+```
+
+### Common Cron Patterns
+
+```typescript
+// Every minute - with http() for API access
+export const everyMinute = schedule('every-minute', '* * * * *')
+  .then(http('task', { connection: 'fluent_commerce' }, async (ctx) => {
+    // Fluent API access available
+    const client = await createClient(ctx);
+    // ... process
+  }));
+
+// Every minute - with fn() for KV-only
+export const everyMinuteKV = schedule('every-minute-kv', '* * * * *')
+  .then(fn('task', async (ctx) => {
+    // KV storage only, no external API
+    const kv = ctx.openKv(':project:');
+    // ... process
+  }));
+
+// Every hour at minute 0
+export const hourly = schedule('hourly', '0 * * * *')
+  .then(http('sync', { connection: 'fluent_commerce' }, async (ctx) => {
+    // Hourly inventory sync
+  }));
+
+// Every 6 hours - Fluent inventory snapshot
+export const every6Hours = schedule('every-6-hours', '0 */6 * * *')
+  .then(http('snapshot', { connection: 'fluent_commerce' }, async (ctx) => {
+    // Extract inventory snapshot every 6 hours
+  }));
+
+// Daily at 2 AM - Full sync
+export const dailyAt2AM = schedule('daily-2am', '0 2 * * *')
+  .then(http('full-sync', { connection: 'fluent_commerce' }, async (ctx) => {
+    // Daily full inventory sync
+  }));
+
+// Weekdays at 9 AM - Business hours processing
+export const weekdaysAt9AM = schedule('weekdays-9am', '0 9 * * 1-5')
+  .then(http('business-hours', { connection: 'fluent_commerce' }, async (ctx) => {
+    // Weekday order processing
+  }));
+
+// First of every month at midnight - Monthly reports
+export const monthlyFirst = schedule('monthly-first', '0 0 1 * *')
+  .then(http('monthly-report', { connection: 'fluent_commerce' }, async (ctx) => {
+    // Generate monthly inventory reports
+  }));
+
+// Every Sunday at 3 AM - Weekly cleanup
+export const weeklySunday = schedule('weekly-sunday', '0 3 * * 0')
+  .then(http('weekly-cleanup', { connection: 'fluent_commerce' }, async (ctx) => {
+    // Weekly data cleanup
+  }));
+
+// With activation predicate (filter by activation)
+export const allActivations = schedule('all-act', '0 * * * *', 'all')
+  .then(fn('task', async (ctx) => {
+    // Runs for all activations
+  }));
+
+export const customPredicate = schedule('custom', '0 * * * *', (a) => a?.id?.startsWith('prod'))
+  .then(fn('task', async (ctx) => {
+    // Runs only for production activations
+  }));
+```
+
+### Scheduled Workflow with State Management
+
+```typescript
+import { schedule, fn, http } from '@versori/run';
+import { createClient, VersoriFileTracker } from '@fluentcommerce/fc-connect-sdk';
+
+/**
+ * Hourly incremental sync with file tracking
+ *
+ * Cron: 0 * * * * (every hour)
+ */
+export const hourlyIncrementalSync = schedule(
+  'hourly-sync',
+  '0 * * * *'
+)
+  .then(
+    fn('check-files', async ctx => {
+      const kv = ctx.openKv(':project:');
+      const tracker = new VersoriFileTracker(kv, 'hourly-sync');
+
+      const lastFile = await tracker.getLastProcessedFile();
+      const newFiles = await listFilesAfter(lastFile);
+
+      if (newFiles.length === 0) {
+        ctx.log.info('No new files to process');
+        throw new Error('SKIP'); // Signal to skip processing
+      }
+
+      return { newFiles, tracker };
+    })
+  )
+  .then(
+    http(
+      'process-files',
+      { connection: 'fluent_commerce' },
+      async ctx => {
+        const { newFiles, tracker } = ctx.data;
+        const client = await createClient(ctx);
+        let processedCount = 0;
+
+        for (const file of newFiles) {
+          if (await tracker.wasFileProcessed(file.name)) {
+            ctx.log.info('Skipping already processed file', { file: file.name });
+            continue;
+          }
+
+          const records = await processFile(file);
+
+          const job = await client.createJob({ name: `Hourly Sync - ${file.name}` });
+          await client.sendBatch(job.id, {
+            action: 'UPSERT',
+            entityType: 'INVENTORY',
+            entities: records,
+          });
+
+          await tracker.markFileProcessed(file.name, {
+            recordCount: records.length,
+            timestamp: Date.now(),
+          });
+
+          await tracker.setLastProcessedFile(file.name);
+          processedCount += records.length;
+        }
+
+        ctx.log.info('Hourly sync complete', {
+          filesProcessed: newFiles.length,
+          recordsProcessed: processedCount,
+        });
+
+        return {
+          success: true,
+          filesProcessed: newFiles.length,
+          recordsProcessed: processedCount,
+        };
+      }
+    )
+  )
+  .catch(({ data }) => {
+    if (data.message === 'SKIP') {
+      return { skipped: true, reason: 'No new files' };
+    }
+    return { success: false, error: data.message };
+  });
+```
+
+---
+
+## Internal Functions (fn) - Data Transformation & State
+
+Internal functions (`fn()`) are for processing that **does NOT require external API access**. They have access to KV storage and logging, but **NOT** `ctx.fetch`.
+
+### File Tracking with fn()
+
+```typescript
+import { fn } from '@versori/run';
+import { VersoriFileTracker } from '@fluentcommerce/fc-connect-sdk';
+
+/**
+ * Track file processing state
+ *
+ * Used internally by other workflows (NOT exposed as HTTP endpoint)
+ */
+export const trackFileProcessing = fn('track-file', async ctx => {
+  const kv = ctx.openKv(':project:');
+  const tracker = new VersoriFileTracker(kv, 'inventory-ingestion');
+
+  const fileName = ctx.data?.fileName;
+  if (!fileName) {
+    return { error: 'Missing fileName' };
+  }
+
+  // Check if processed
+  if (await tracker.wasFileProcessed(fileName)) {
+    return { skipped: true, reason: 'Already processed' };
+  }
+
+  // Mark as processed
+  await tracker.markFileProcessed(fileName, {
+    records: ctx.data?.recordCount || 0,
+    timestamp: Date.now(),
+  });
+
+  return { tracked: true, fileName };
+});
+```
+
+### Data Transformation with fn()
+
+```typescript
+import { fn } from '@versori/run';
+import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+
+/**
+ * Transform CSV data to Fluent format
+ *
+ * Used as part of workflow composition
+ */
+export const transformInventoryData = fn('transform-inventory', async ctx => {
+  const rawData = ctx.data?.records;
+  if (!rawData || !Array.isArray(rawData)) {
+    return { error: 'Invalid input data' };
+  }
+
+  // Define field mapping
+  const mappingConfig = {
+    fields: {
+      productRef: { source: 'sku_id', required: true },
+      locationRef: { source: 'location_code', required: true },
+      qty: { source: 'quantity', resolver: 'sdk.parseInt' },
+      status: { source: 'status', resolver: 'sdk.uppercase' },
+    },
+  };
+
+  const mapper = new UniversalMapper(mappingConfig);
+
+  // Transform all records
+  const transformed = [];
+  const errors = [];
+
+  for (const record of rawData) {
+    const result = await mapper.map(record);
+    if (result.success) {
+      transformed.push(result.data);
+    } else {
+      errors.push({ record, errors: result.errors });
+    }
+  }
+
+  ctx.log('info', 'Transformation complete', {
+    totalRecords: rawData.length,
+    transformed: transformed.length,
+    errors: errors.length,
+  });
+
+  return {
+    transformed,
+    errors,
+    stats: {
+      total: rawData.length,
+      success: transformed.length,
+      failed: errors.length,
+    },
+  };
+});
+```
+
+---
+
+## Workflow Composition - Multi-Step Patterns
+
+Combine multiple workflow types using `.then()` and `.catch()` chaining.
+
+### Pattern 1: Webhook → fn() → http()
+
+```typescript
+import { webhook, fn, http } from '@versori/run';
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+/**
+ * Receive order → validate → send to Fluent
+ *
+ * POST https://{workspace}.versori.run/process-order
+ */
+export const processOrder = webhook('process-order')
+  // Step 1: Parse and validate (fn - no external API)
+  .then(
+    fn('validate-order', ({ data }) => {
+      if (!data?.orderId || !data?.items) {
+        throw new Error('Invalid order data: missing orderId or items');
+      }
+
+      return {
+        orderId: data.orderId,
+        items: data.items.map(item => ({
+          productRef: item.sku,
+          quantity: parseInt(item.qty, 10),
+          price: parseFloat(item.price),
+        })),
+      };
+    })
+  )
+
+  // Step 2: Send to Fluent (http - requires connection)
+  .then(
+    http(
+      'send-to-fluent',
+      {
+        connection: 'fluent_commerce',
+      },
+      async ctx => {
+        const { orderId, items } = ctx.data;
+        const client = await createClient(ctx);
+
+        // GraphQL mutation - schema validated
+        const result = await client.graphql({
+          query: `
+        mutation CreateOrder($input: CreateOrderInput!) {
+          createOrder(input: $input) {
+            id
+            ref
+            status
+          }
+        }
+      `,
+          variables: {
+            input: {
+              ref: orderId,
+              items: items.map(item => ({
+                productRef: item.productRef,
+                quantity: item.quantity,
+                price: item.price,
+              })),
+            },
+          },
+        });
+
+        return {
+          success: true,
+          fluentOrderId: result.data.createOrder.id,
+          fluentOrderRef: result.data.createOrder.ref,
+        };
+      }
+    )
+  )
+
+  // Error handling
+  .catch(({ data }) => {
+    return {
+      success: false,
+      error: data instanceof Error ? data.message : 'Processing failed',
+      status: 500,
+    };
+  });
+```
+
+### Pattern 2: Scheduled → fn() (File Tracking) → http() (API Call)
+
+```typescript
+import { schedule, fn, http } from '@versori/run';
+import { createClient, VersoriFileTracker } from '@fluentcommerce/fc-connect-sdk';
+
+/**
+ * Daily sync with file tracking
+ *
+ * Cron: 0 1 * * * (daily at 1 AM)
+ */
+export const dailySyncWithTracking = schedule('daily-sync', '0 1 * * *', {
+  connection: 'fluent_commerce',
+})
+  // Step 1: Check if already processed today (fn - KV access)
+  .then(
+    fn('check-processed', async ctx => {
+      const kv = ctx.openKv(':project:');
+      const tracker = new VersoriFileTracker(kv, 'daily-sync');
+
+      const today = new Date().toISOString().split('T')[0];
+      const fileKey = `inventory-${today}.csv`;
+
+      if (await tracker.wasFileProcessed(fileKey)) {
+        throw new Error('Already processed today');
+      }
+
+      return { fileKey, today };
+    })
+  )
+
+  // Step 2: Fetch and process (http - external API)
+  .then(
+    http(
+      'process-sync',
+      {
+        connection: 'fluent_commerce',
+      },
+      async ctx => {
+        const { fileKey } = ctx.data;
+        const client = await createClient(ctx);
+
+        // Fetch data from external source
+        const records = await fetchDailyInventory();
+
+        // Send to Fluent
+        const job = await client.createJob({ name: `Daily Sync ${fileKey}` });
+        await client.sendBatch(job.id, {
+          action: 'UPSERT',
+          entityType: 'INVENTORY',
+          entities: records,
+        });
+
+        return {
+          fileKey,
+          jobId: job.id,
+          recordCount: records.length,
+        };
+      }
+    )
+  )
+
+  // Step 3: Mark as processed (fn - KV access)
+  .then(
+    fn('mark-processed', async ctx => {
+      const kv = ctx.openKv(':project:');
+      const tracker = new VersoriFileTracker(kv, 'daily-sync');
+      const { fileKey, recordCount } = ctx.data;
+
+      await tracker.markFileProcessed(fileKey, {
+        recordCount,
+        timestamp: Date.now(),
+      });
+
+      return {
+        success: true,
+        fileKey,
+        recordCount,
+      };
+    })
+  )
+
+  .catch(({ data }) => {
+    if (data.message === 'Already processed today') {
+      return { skipped: true, reason: 'Already processed today' };
+    }
+    return { success: false, error: data.message };
+  });
+```
+
+---
+
+## Error Handling & Retry Strategies
+
+### Basic Error Handling
+
+```typescript
+export const robustWorkflow = http(
+  'robust',
+  {
+    connection: 'fluent_commerce',
+    retry: {
+      attempts: 3,
+      delay: 1000,
+      backoff: 2, // Exponential backoff multiplier
+    },
+  },
+  async ctx => {
+    try {
+      const client = await createClient(ctx);
+      const result = await client.graphql({ query: '...' });
+
+      if (result.errors?.length) {
+        throw new Error(`GraphQL failed: ${result.errors[0].message}`);
+      }
+
+      return { success: true, data: result.data };
+    } catch (error) {
+      ctx.log('error', 'Operation failed', {
+        error: error instanceof Error ? error.message : String(error),
+        stack: error instanceof Error ? error.stack : undefined,
+      });
+
+      throw error; // Re-throw for retry mechanism
+    }
+  }
+);
+```
+
+### Advanced Error Handling with Fallback
+
+```typescript
+export const withFallback = http(
+  'with-fallback',
+  {
+    connection: 'fluent_commerce',
+  },
+  async ctx => {
+    const client = await createClient(ctx);
+
+    try {
+      // Primary operation
+      const result = await client.graphql({ query: '...' });
+      return { source: 'primary', data: result.data };
+    } catch (primaryError) {
+      ctx.log('warn', 'Primary operation failed, trying fallback', {
+        error: primaryError instanceof Error ? primaryError.message : String(primaryError),
+      });
+
+      try {
+        // Fallback operation
+        const fallbackResult = await client.graphql({ query: '... (simpler query)' });
+        return { source: 'fallback', data: fallbackResult.data };
+      } catch (fallbackError) {
+        ctx.log('error', 'Both primary and fallback failed', {
+          primaryError: primaryError instanceof Error ? primaryError.message : String(primaryError),
+          fallbackError:
+            fallbackError instanceof Error ? fallbackError.message : String(fallbackError),
+        });
+
+        throw new Error('All operations failed');
+      }
+    }
+  }
+);
+```
+
+---
+
+## Real-World Fluent Commerce Use Cases
+
+This section provides detailed, production-ready examples for common Fluent Commerce integration patterns.
+
+### Use Case 1: Inventory Position Ingestion from CSV
+
+**Scenario**: Daily CSV file from warehouse management system → Fluent inventory positions
+
+```typescript
+import { schedule, fn, http } from '@versori/run';
+import {
+  createClient,
+  S3DataSource,
+  CSVParserService,
+  UniversalMapper,
+  VersoriFileTracker
+} from '@fluentcommerce/fc-connect-sdk';
+
+/**
+ * Daily inventory ingestion from S3 CSV
+ *
+ * Cron: 0 3 * * * (3 AM daily)
+ * Flow: Check file → Parse CSV → Transform → Send to Fluent
+ */
+export const dailyInventoryIngestion = schedule('daily-inventory-ingestion', '0 3 * * *')
+  // Step 1: Check for new files (fn - KV only)
+  .then(fn('check-new-files', async ctx => {
+    const kv = ctx.openKv(':project:');
+    const tracker = new VersoriFileTracker(kv, 'inventory-ingestion');
+
+    const s3Config = {
+      bucket: ctx.activation.getVariable<string>('S3_BUCKET'),
+      region: ctx.activation.getVariable<string>('AWS_REGION'),
+      accessKeyId: ctx.activation.getVariable<string>('AWS_ACCESS_KEY_ID'),
+      secretAccessKey: ctx.activation.getVariable<string>('AWS_SECRET_ACCESS_KEY'),
+    };
+
+    const s3 = new S3DataSource(s3Config, ctx.log);
+    const files = await s3.listFiles({ prefix: 'inventory/daily/' });
+
+    // Filter unprocessed files
+    const newFiles = [];
+    for (const file of files) {
+      if (!(await tracker.wasFileProcessed(file.key))) {
+        newFiles.push(file);
+      }
+    }
+
+    if (newFiles.length === 0) {
+      throw new Error('NO_NEW_FILES');
+    }
+
+    ctx.log.info('Found new inventory files', { count: newFiles.length });
+    return { s3Config, files: newFiles, tracker };
+  }))
+
+  // Step 2: Parse and transform (fn - no API needed)
+  .then(fn('parse-transform', async ctx => {
+    const { s3Config, files, tracker } = ctx.data;
+    const s3 = new S3DataSource(s3Config, ctx.log);
+    const parser = new CSVParserService(ctx.log);
+
+    // Mapping configuration
+    const mappingConfig = {
+      fields: {
+        // Fluent field: CSV column
+        ref: { source: 'sku', required: true },
+        productRef: { source: 'sku', required: true },
+        locationRef: { source: 'location_code', required: true },
+        qty: { source: 'quantity', resolver: 'sdk.parseInt', required: true },
+        type: { value: 'AVAILABLE' },  // Static value
+        storageArea: { source: 'warehouse_zone' },
+        expectedOn: { source: 'delivery_date', resolver: 'sdk.formatDate' },
+      },
+    };
+
+    const mapper = new UniversalMapper(mappingConfig);
+    const allRecords = [];
+
+    for (const file of files) {
+      const content = await s3.readFile(file.key);
+      const parsed = await parser.parse(content, {
+        headers: true,
+        skipEmptyLines: true
+      });
+
+      // Transform each row
+      for (const row of parsed) {
+        const result = await mapper.map(row);
+        if (result.success) {
+          allRecords.push(result.data);
+        } else {
+          ctx.log.warn('Mapping failed', { row, errors: result.errors });
+        }
+      }
+    }
+
+    ctx.log.info('Parsed and transformed records', {
+      fileCount: files.length,
+      recordCount: allRecords.length
+    });
+
+    return { records: allRecords, files, tracker };
+  }))
+
+  // Step 3: Send to Fluent (http - requires API connection)
+  .then(http('send-to-fluent', { connection: 'fluent_commerce' }, async ctx => {
+    const { records, files, tracker } = ctx.data;
+    const client = await createClient(ctx);
+
+    // Create batch job
+    const job = await client.createJob({
+      name: `Daily Inventory Ingestion - ${new Date().toISOString().split('T')[0]}`,
+      retailerId: ctx.activation.getVariable<number>('FLUENT_RETAILER_ID'),
+    });
+
+    // Send in batches of 500
+    const batchSize = 500;
+    const batches = [];
+
+    for (let i = 0; i < records.length; i += batchSize) {
+      const chunk = records.slice(i, i + batchSize);
+      const batch = await client.sendBatch(job.id, {
+        action: 'UPSERT',
+        entityType: 'INVENTORY_POSITION',
+        entities: chunk,
+        meta: {
+          preprocessing: 'skip',  // Delta file, skip BPP
+        },
+      });
+      batches.push(batch.id);
+    }
+
+    // Mark files as processed
+    for (const file of files) {
+      await tracker.markFileProcessed(file.key, {
+        jobId: job.id,
+        recordCount: records.length,
+        timestamp: Date.now(),
+      });
+    }
+
+    ctx.log.info('Inventory ingestion complete', {
+      jobId: job.id,
+      batches: batches.length,
+      totalRecords: records.length,
+    });
+
+    return {
+      success: true,
+      jobId: job.id,
+      recordCount: records.length,
+      filesProcessed: files.length,
+    };
+  }))
+
+  .catch(({ data }) => {
+    if (data.message === 'NO_NEW_FILES') {
+      return { skipped: true, reason: 'No new files to process' };
+    }
+    return { success: false, error: data.message || 'Unknown error' };
+  });
+```
+
+### Use Case 2: Order Creation from SFCC XML Webhook
+
+**Scenario**: SFCC sends order XML → Validate → Create order in Fluent
+
+```typescript
+import { webhook, fn, http } from '@versori/run';
+import {
+  createClient,
+  XMLParserService,
+  GraphQLMutationMapper
+} from '@fluentcommerce/fc-connect-sdk';
+
+/**
+ * Receive SFCC order XML webhook and create order in Fluent
+ *
+ * POST https://{workspace}.versori.run/sfcc-order-create
+ * Content-Type: application/xml
+ */
+export const sfccOrderCreate = webhook('sfcc-order-create', {
+  connection: 'sfcc-webhook-auth',  // Platform validates API key
+  response: {
+    mode: 'sync',
+    onSuccess: ctx => new Response(ctx.data, {
+      status: 200,
+      headers: { 'Content-Type': 'application/xml; charset=utf-8' },
+    }),
+    onError: ctx => {
+      const errorXml = `<?xml version="1.0"?>
+<ErrorResponse>
+  <Error>
+    <Code>PROCESSING_ERROR</Code>
+    <Message>${ctx.data?.message || 'Order processing failed'}</Message>
+    <ExecutionId>${ctx.executionId}</ExecutionId>
+  </Error>
+</ErrorResponse>`;
+      return new Response(errorXml, {
+        status: 500,
+        headers: { 'Content-Type': 'application/xml; charset=utf-8' },
+      });
+    },
+  },
+})
+  // Step 1: Parse XML (fn - no API needed)
+  .then(fn('parse-xml', async ctx => {
+    const parser = new XMLParserService(ctx.log);
+    const xmlData = await parser.parse(ctx.data);
+
+    // Validate required fields
+    if (!xmlData.order?.['@id']) {
+      throw new Error('Invalid order XML: missing order ID');
+    }
+
+    ctx.log.info('Parsed SFCC order XML', {
+      orderId: xmlData.order['@id'],
+      customerEmail: xmlData.order.customer?.email
+    });
+
+    return { xmlData };
+  }))
+
+  // Step 2: Transform and create order (http - Fluent API access)
+  .then(http('create-fluent-order', { connection: 'fluent_commerce' }, async ctx => {
+    const { xmlData } = ctx.data;
+    const client = await createClient(ctx);
+
+    // GraphQL mutation mapping config
+    const mappingConfig = {
+      mutationName: 'createOrder',
+      sourceFormat: 'xml',
+      arguments: {
+        input: {
+          ref: { source: 'order.@id' },
+          type: { value: 'STANDARD' },
+          retailer: { source: 'order.@retailerId', resolver: 'sdk.parseInt' },
+          customer: {
+            firstName: { source: 'order.customer.firstname' },
+            lastName: { source: 'order.customer.lastname' },
+            email: { source: 'order.customer.email' },
+          },
+          items: {
+            source: 'order.items.item',
+            isArray: true,
+            mapping: {
+              productRef: { source: '@sku' },
+              quantity: { source: 'quantity', resolver: 'sdk.parseInt' },
+              price: {
+                value: { source: 'price', resolver: 'sdk.parseFloat' },
+                currency: { source: '@currency', default: 'USD' },
+              },
+            },
+          },
+          fulfilment: {
+            type: { value: 'STANDARD' },
+            deliveryType: { source: 'order.shipping.method' },
+            deliveryAddress: {
+              name: { source: 'order.shipping.address.name' },
+              street: { source: 'order.shipping.address.street' },
+              city: { source: 'order.shipping.address.city' },
+              state: { source: 'order.shipping.address.state' },
+              postcode: { source: 'order.shipping.address.postalcode' },
+              country: { source: 'order.shipping.address.country' },
+            },
+          },
+          payments: {
+            source: 'order.payments.payment',
+            isArray: true,
+            mapping: {
+              method: { source: '@method' },
+              amount: { source: 'amount', resolver: 'sdk.parseFloat' },
+              cardType: { source: 'creditcard.type' },
+            },
+          },
+        },
+      },
+    };
+
+    const mapper = new GraphQLMutationMapper(mappingConfig, ctx.log, { fluentClient: client });
+    const { mutation, variables } = await mapper.generateMutation(xmlData);
+
+    // Execute mutation
+    const result = await client.graphql({ query: mutation, variables });
+
+    if (result.errors?.length) {
+      throw new Error(`Order creation failed: ${result.errors[0].message}`);
+    }
+
+    const order = result.data.createOrder;
+    ctx.log.info('Order created in Fluent', {
+      fluentOrderId: order.id,
+      sfccOrderId: xmlData.order['@id']
+    });
+
+    return {
+      fluentOrderId: order.id,
+      fluentOrderRef: order.ref,
+      sfccOrderId: xmlData.order['@id'],
+    };
+  }))
+
+  // Step 3: Generate success XML response (fn)
+  .then(fn('generate-response', ctx => {
+    const { fluentOrderId, sfccOrderId } = ctx.data;
+    return `<?xml version="1.0"?>
+<OrderResponse>
+  <Success>true</Success>
+  <SFCCOrderId>${sfccOrderId}</SFCCOrderId>
+  <FluentOrderId>${fluentOrderId}</FluentOrderId>
+  <Timestamp>${new Date().toISOString()}</Timestamp>
+</OrderResponse>`;
+  }))
+
+  .catch(({ data }) => {
+    return { message: data instanceof Error ? data.message : String(data) };
+  });
+```
+
+### Use Case 3: Virtual Position Extraction to SFTP
+
+**Scenario**: Scheduled extraction of Fluent virtual positions → XML → Upload to SFTP
+
+```typescript
+import { Buffer } from 'node:buffer';  // ⚠️ Required for Deno compatibility
+import { schedule, http, fn } from '@versori/run';
+import {
+  createClient,
+  ExtractionOrchestrator,
+  SftpDataSource,
+  VersoriFileTracker
+} from '@fluentcommerce/fc-connect-sdk';
+import { XMLBuilder } from 'fast-xml-parser';
+
+/**
+ * Extract virtual positions and upload to SFTP as XML
+ *
+ * Cron: 0 */4 * * * (every 4 hours)
+ */
+export const virtualPositionExtraction = schedule('virtual-position-extraction', '0 */4 * * *')
+  // Step 1: Extract from Fluent (http - API access)
+  .then(http('extract-positions', { connection: 'fluent_commerce' }, async ctx => {
+    const client = await createClient(ctx);
+
+    // Define extraction config
+    const extractionConfig = {
+      query: `
+        query GetVirtualPositions($first: Int!, $after: String) {
+          virtualPositions(first: $first, after: $after) {
+            edges {
+              node {
+                id
+                ref
+                productRef
+                groupRef
+                onHand
+                quantity
+                type
+                status
+                createdOn
+                updatedOn
+              }
+              cursor
+            }
+            pageInfo {
+              hasNextPage
+              endCursor
+            }
+          }
+        }
+      `,
+      variables: { first: 200 },
+      pathToData: 'virtualPositions',
+      pathToCursor: 'pageInfo.endCursor',
+      pathToHasNext: 'pageInfo.hasNextPage',
+    };
+
+    // Use ExtractionOrchestrator for auto-pagination
+    const orchestrator = new ExtractionOrchestrator(client, ctx.log);
+    const result = await orchestrator.extractWithPagination(extractionConfig);
+
+    if (!result.success) {
+      throw new Error(`Extraction failed: ${result.errors?.join(', ')}`);
+    }
+
+    ctx.log.info('Extracted virtual positions', {
+      recordCount: result.data?.length || 0
+    });
+
+    return { positions: result.data || [] };
+  }))
+
+  // Step 2: Transform to XML (fn - no API)
+  .then(fn('transform-to-xml', ctx => {
+    const { positions } = ctx.data;
+
+    const xmlBuilder = new XMLBuilder({
+      ignoreAttributes: false,
+      attributeNamePrefix: '@',
+      format: true,
+      indentBy: '  ',
+    });
+
+    const xmlObject = {
+      '?xml': { '@version': '1.0', '@encoding': 'UTF-8' },
+      VirtualPositionFeed: {
+        '@timestamp': new Date().toISOString(),
+        '@recordCount': positions.length,
+        Positions: {
+          Position: positions.map(pos => ({
+            '@id': pos.id,
+            Ref: pos.ref,
+            ProductRef: pos.productRef,
+            GroupRef: pos.groupRef,
+            OnHand: pos.onHand,
+            Quantity: pos.quantity,
+            Type: pos.type,
+            Status: pos.status,
+            CreatedOn: pos.createdOn,
+            UpdatedOn: pos.updatedOn,
+          })),
+        },
+      },
+    };
+
+    const xmlContent = xmlBuilder.build(xmlObject);
+
+    const fileName = `virtual-positions-${new Date().toISOString().replace(/:/g, '-')}.xml`;
+
+    ctx.log.info('Generated XML feed', { fileName, recordCount: positions.length });
+
+    return { xmlContent, fileName, recordCount: positions.length };
+  }))
+
+  // Step 3: Upload to SFTP (fn - external SFTP, not Fluent API)
+  .then(fn('upload-to-sftp', async ctx => {
+    const { xmlContent, fileName, recordCount } = ctx.data;
+
+    const sftpConfig = {
+      host: ctx.activation.getVariable<string>('SFTP_HOST'),
+      port: ctx.activation.getVariable<number>('SFTP_PORT') || 22,
+      username: ctx.activation.getVariable<string>('SFTP_USERNAME'),
+      password: ctx.activation.getVariable<string>('SFTP_PASSWORD'),
+    };
+
+    const sftp = new SftpDataSource(sftpConfig, ctx.log);
+    await sftp.connect();
+
+    try {
+      const remotePath = `/outbound/${fileName}`;
+      await sftp.uploadFile(remotePath, Buffer.from(xmlContent, 'utf-8'));
+
+      ctx.log.info('Uploaded to SFTP', { remotePath, recordCount });
+
+      // Track in KV
+      const kv = ctx.openKv(':project:');
+      const tracker = new VersoriFileTracker(kv, 'virtual-position-extraction');
+      await tracker.markFileProcessed(fileName, {
+        recordCount,
+        timestamp: Date.now(),
+        remotePath,
+      });
+
+      return {
+        success: true,
+        fileName,
+        remotePath,
+        recordCount,
+      };
+    } finally {
+      await sftp.disconnect();
+    }
+  }))
+
+  .catch(({ data }) => ({
+    success: false,
+    error: data instanceof Error ? data.message : String(data),
+  }));
+```
+
+### Use Case 4: Multi-Tenant Order Status Webhook
+
+**Scenario**: Multiple customers share one connector, route to correct Fluent instance
+
+```typescript
+import { webhook, fn, http } from '@versori/run';
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+/**
+ * Multi-tenant order status update
+ *
+ * POST https://{workspace}.versori.run/order-status-update
+ * Body: { customerId, orderId, status }
+ */
+export const orderStatusUpdate = webhook('order-status-update', {
+  response: { mode: 'sync' },
+})
+  // Step 1: Route to correct connection (fn)
+  .then(fn('route-connection', ctx => {
+    const { customerId, orderId, status } = ctx.data;
+
+    if (!customerId || !orderId || !status) {
+      throw new Error('Missing required fields: customerId, orderId, status');
+    }
+
+    // Access all connections via activation.connections
+    const connections = ctx.activation.connections;
+
+    // Find customer-specific Fluent connection
+    const connectionName = `fluent_${customerId.toLowerCase()}`;
+    const connection = connections?.find(c => c.name === connectionName);
+
+    if (!connection) {
+      throw new Error(`No Fluent connection found for customer: ${customerId}`);
+    }
+
+    ctx.log.info('Routed to customer connection', {
+      customerId,
+      connectionName,
+      connectionId: connection.id
+    });
+
+    return { connectionName, orderId, status, customerId };
+  }))
+
+  // Step 2: Update order status (http - with dynamic connection)
+  .then(http('update-order', (ctx) => {
+    // Return dynamic connection name
+    return { connection: ctx.data.connectionName };
+  }, async ctx => {
+    const { orderId, status, customerId } = ctx.data;
+    const client = await createClient(ctx);
+
+    // Update order status
+    const result = await client.graphql({
+      query: `
+        mutation UpdateOrder($ref: String!, $status: String!) {
+          updateOrder(input: { ref: $ref, status: $status }) {
+            id
+            ref
+            status
+          }
+        }
+      `,
+      variables: { ref: orderId, status },
+    });
+
+    if (result.errors?.length) {
+      throw new Error(`Failed to update order: ${result.errors[0].message}`);
+    }
+
+    ctx.log.info('Order status updated', {
+      customerId,
+      orderId,
+      newStatus: status
+    });
+
+    return {
+      success: true,
+      customerId,
+      orderId,
+      status: result.data.updateOrder.status,
+    };
+  }))
+
+  .catch(({ data }) => ({
+    success: false,
+    error: data instanceof Error ? data.message : String(data),
+    status: 500,
+  }));
+```
+
+### Use Case 5: Product Catalog Sync with Enrichment
+
+**Scenario**: Fetch products from PIM system → Enrich → Update Fluent catalog
+
+```typescript
+import { schedule, fn, http } from '@versori/run';
+import {
+  createClient,
+  UniversalMapper,
+  VersoriFileTracker
+} from '@fluentcommerce/fc-connect-sdk';
+
+/**
+ * Daily product catalog sync
+ *
+ * Cron: 0 4 * * * (4 AM daily)
+ */
+export const productCatalogSync = schedule('product-catalog-sync', '0 4 * * *')
+  // Step 1: Fetch from external PIM (http - external API)
+  .then(http('fetch-from-pim', { connection: 'pim_system' }, async ctx => {
+    // Fetch products from PIM API
+    const response = await ctx.fetch('/api/v1/products?updated_since=yesterday');
+    const products = await response.json();
+
+    ctx.log.info('Fetched products from PIM', { count: products.length });
+    return { pimProducts: products };
+  }))
+
+  // Step 2: Enrich and transform (fn - data processing)
+  .then(fn('enrich-transform', async ctx => {
+    const { pimProducts } = ctx.data;
+
+    const mappingConfig = {
+      fields: {
+        ref: { source: 'sku', required: true },
+        type: { value: 'STANDARD' },
+        name: { source: 'name', required: true },
+        summary: { source: 'short_description' },
+        gtin: { source: 'barcode' },
+        prices: {
+          source: 'pricing',
+          isArray: true,
+          mapping: {
+            type: { source: 'price_type' },
+            value: { source: 'amount', resolver: 'sdk.parseFloat' },
+            currency: { source: 'currency', default: 'USD' },
+          },
+        },
+        attributes: {
+          source: 'custom_attributes',
+          isArray: true,
+          mapping: {
+            name: { source: 'attr_name' },
+            value: { source: 'attr_value', resolver: 'sdk.toString' },
+            type: { value: 'STRING' },
+          },
+        },
+        taxType: {
+          type: { source: 'tax.type' },
+          group: { source: 'tax.group' },
+          tariff: { source: 'tax.tariff_code' },
+        },
+      },
+    };
+
+    const mapper = new UniversalMapper(mappingConfig);
+    const enrichedProducts = [];
+
+    for (const product of pimProducts) {
+      const result = await mapper.map(product);
+      if (result.success) {
+        enrichedProducts.push(result.data);
+      } else {
+        ctx.log.warn('Product mapping failed', {
+          sku: product.sku,
+          errors: result.errors
+        });
+      }
+    }
+
+    ctx.log.info('Products enriched', { count: enrichedProducts.length });
+    return { products: enrichedProducts };
+  }))
+
+  // Step 3: Send to Fluent (http - Fluent API)
+  .then(http('sync-to-fluent', { connection: 'fluent_commerce' }, async ctx => {
+    const { products } = ctx.data;
+    const client = await createClient(ctx);
+
+    const job = await client.createJob({
+      name: `Product Catalog Sync - ${new Date().toISOString().split('T')[0]}`,
+      retailerId: ctx.activation.getVariable<number>('FLUENT_RETAILER_ID'),
+    });
+
+    // Send in chunks
+    const batchSize = 100;
+    const batches = [];
+
+    for (let i = 0; i < products.length; i += batchSize) {
+      const chunk = products.slice(i, i + batchSize);
+      const batch = await client.sendBatch(job.id, {
+        action: 'UPSERT',
+        entityType: 'PRODUCT',
+        entities: chunk,
+        meta: {
+          preprocessing: 'apply',  // Full snapshot, use BPP
+        },
+      });
+      batches.push(batch.id);
+    }
+
+    ctx.log.info('Product sync complete', {
+      jobId: job.id,
+      productCount: products.length,
+      batchCount: batches.length,
+    });
+
+    return {
+      success: true,
+      jobId: job.id,
+      productCount: products.length,
+    };
+  }))
+
+  .catch(({ data }) => ({
+    success: false,
+    error: data instanceof Error ? data.message : String(data),
+  }));
+```
+
+---
+
+## ⚠️ CRITICAL: `.parallel()` Error Behavior
+
+**BEFORE USING `.parallel()` - READ THIS:**
+
+The `.parallel()` method has **all-or-nothing error behavior** that makes it **UNSUITABLE for most batch processing use cases**.
+
+### What Happens When One Task Fails
+
+```typescript
+// ❌ PROBLEM: If ANY file fails, you lose ALL results
+schedule('process-files', '0 2 * * *')
+  .then(fn('fetch', () => ['file1.xml', 'file2.xml', 'file3.xml']))
+  .unpack()
+  .parallel(fn('process', async (ctx) => {
+    return await processFile(ctx.data);
+  }));
+```
+
+**If `file2.xml` fails:**
+- ❌ `file1.xml` might have processed successfully but **result is lost**
+- ❌ `file3.xml` never runs (or is cancelled mid-execution)
+- ❌ **Entire workflow fails**
+- ❌ **NO partial results returned**
+- ❌ You can't retry only failed items
+
+### Implementation Detail
+
+The `.parallel()` method uses RxJS `mergeMap` + `toArray()`:
+- Any error in `mergeMap` propagates to the stream
+- `toArray()` never completes if the stream errors
+- **Result: one failure stops everything**
+
+### Comparison: `.parallel()` vs `Promise.allSettled`
+
+| Feature | `.parallel()` | `Promise.allSettled` |
+|---------|--------------|---------------------|
+| Fault tolerance | ❌ Fails on first error | ✅ Continues on errors |
+| Partial results | ❌ None if any fail | ✅ All results |
+| Error isolation | ❌ No isolation | ✅ Complete isolation |
+| Retry failures | ❌ Must retry all | ✅ Retry only failures |
+
+### When to Use `.parallel()`
+
+**ONLY use `.parallel()` when:**
+1. ✅ **All tasks MUST succeed** (transactional requirement)
+2. ✅ **Small number of items** (3-10 max)
+3. ✅ **Fast, reliable operations** (< 10 seconds each)
+4. ✅ **Partial success is worse than complete failure**
+
+**Examples where `.parallel()` is appropriate:**
+- Fetching 3-5 required entity types (all needed for next step)
+- Validating multiple webhook signatures (all must be valid)
+- Small, predictable, low-failure-rate operations
+
+### When to Use `Promise.allSettled` (SDK Pattern)
+
+**PREFER `Promise.allSettled` for:**
+1. ✅ **Batch processing** (files, records, entities)
+2. ✅ **Large datasets** (10+ items)
+3. ✅ **Failures are expected** (network issues, bad data)
+4. ✅ **Partial success is valuable** (process 990/1000 items)
+5. ✅ **Need retry logic** (retry only failures)
+
+**Example using SDK pattern:**
+```typescript
+export const batchProcess = schedule('batch', '0 */6 * * *')
+  .then(
+    http('process', { connection: 'fluent_commerce' }, async (ctx) => {
+      const items = await fetchItems();
+
+      // ✅ Use Promise.allSettled for fault tolerance
+      const results = await Promise.allSettled(
+        items.map(item =>
+          processItem(item)
+            .then(result => ({ success: true, item, result }))
+            .catch(error => ({ success: false, item, error: error.message }))
+        )
+      );
+
+      const successes = results
+        .filter(r => r.status === 'fulfilled')
+        .map(r => r.value);
+
+      const failures = results
+        .filter(r => r.status === 'rejected' || !r.value.success);
+
+      ctx.log.info(`Processed ${successes.length} items, ${failures.length} failed`);
+
+      // ✅ Handle failures gracefully
+      if (failures.length > 0) {
+        // Store failures for retry
+        const kv = ctx.openKv(':project:');
+        await kv.set('failed-items', failures);
+      }
+
+      return { successes, failures };
+    })
+  );
+```
+
+---
+
+## Parallel Processing with `.unpack()` and `.parallel()`
+
+Versori supports parallel processing via `.unpack()` and `.parallel()` methods, but **they have critical limitations** that affect fault tolerance and error handling (see warning above).
+
+### Available Methods
+
+```typescript
+import { schedule, fn } from '@versori/run';
+
+schedule('process-files', '0 2 * * *')
+  .then(fn('fetch-files', (ctx) => {
+    return ['file1.xml', 'file2.xml', 'file3.xml']; // Returns array
+  }))
+  .unpack()    // ✅ Converts array to ArrayTask
+  .parallel(   // ✅ Processes each item in parallel
+    fn('process-file', async (ctx) => {
+      // ctx.data is now a single item from the array
+      return await processFile(ctx.data);
+    })
+  );
+```
+
+### ⚠️ CRITICAL LIMITATIONS
+
+#### 1. **NOT Fault-Tolerant: One Failure Stops Everything**
+
+**Problem**: If any parallel task fails, the **entire workflow fails** and **no results are returned**.
+
+```typescript
+// ❌ RISKY: If file2.xml fails, entire workflow fails
+schedule('process-files', '0 2 * * *')
+  .then(fn('fetch-files', (ctx) => ['file1.xml', 'file2.xml', 'file3.xml']))
+  .unpack()
+  .parallel(fn('process-file', async (ctx) => {
+    // If ANY file fails here, ALL results lost
+    return await processFile(ctx.data);
+  }));
+
+// Result:
+// ✅ file1.xml might complete
+// ❌ file2.xml fails → ENTIRE WORKFLOW FAILS
+// ❌ file3.xml NEVER RUNS (or gets cancelled)
+// ❌ No partial results returned
+```
+
+**Why**: Uses RxJS `mergeMap` + `toArray()` which stops on first error.
+
+#### 2. **Shared Timeout Across All Tasks**
+
+**Problem**: All parallel tasks share the **same workflow timeout**.
+
+| Trigger Type | Timeout | Impact |
+|-------------|---------|--------|
+| **HTTP/Webhook** | 30 seconds | All parallel tasks must complete in 30s total |
+| **Schedule** | 5 minutes | All parallel tasks must complete in 5min total |
+
+```typescript
+// ⚠️ If processing 10 files in parallel:
+schedule('process-files', '0 2 * * *')
+  .then(fn('fetch-files', (ctx) => Array(10).fill('file.xml')))
+  .unpack()
+  .parallel(fn('process-file', async (ctx) => {
+    // If ANY file takes > 5 minutes, ENTIRE workflow fails
+    return await processFile(ctx.data);
+  }));
+```
+
+#### 3. **NOT ACID Compliant**
+
+**Problem**: No atomicity guarantees. If one task fails:
+- ✅ Successful tasks may have completed their work
+- ❌ But you won't know which ones succeeded
+- ❌ No rollback mechanism
+- ❌ No transaction support
+
+### ✅ Recommended: Use `Promise.allSettled()` Instead
+
+For **fault-tolerant** parallel processing, use `Promise.allSettled()` which continues even when some tasks fail:
+
+```typescript
+import { schedule, fn } from '@versori/run';
+
+schedule('process-files', '0 2 * * *')
+  .then(fn('process-all-files', async (ctx) => {
+    const files = ['file1.xml', 'file2.xml', 'file3.xml'];
+    
+    // ✅ Fault-tolerant: Continues even if some fail
+    const results = await Promise.allSettled(
+      files.map(file => processFile(file))
+    );
+    
+    // Process results
+    const successes = results
+      .filter(r => r.status === 'fulfilled')
+      .map(r => r.value);
+    
+    const failures = results
+      .filter(r => r.status === 'rejected')
+      .map(r => ({ file: r.reason.file, error: r.reason.message }));
+    
+    ctx.log.info(`Processed ${successes.length} files, ${failures.length} failed`);
+    
+    return { successes, failures };
+  }));
+```
+
+**Comparison**:
+
+| Feature | `.unpack().parallel()` | `Promise.allSettled()` |
+|---------|------------------------|------------------------|
+| Fault tolerance | ❌ Fails on first error | ✅ Continues on errors |
+| Partial results | ❌ No results if any fail | ✅ Returns all results |
+| Error isolation | ❌ No isolation | ✅ Complete isolation |
+| Time limits | ⚠️ Shared timeout | ⚠️ Shared timeout |
+| Best for | All-or-nothing workflows | Real-world with failures |
+
+### When to Use `.unpack().parallel()`
+
+**Only use if**:
+- ✅ All tasks **must** succeed (transactional)
+- ✅ You can wrap each task with error handling that returns error objects instead of throwing
+- ✅ You're okay with losing all results on any failure
+
+**Example with error handling**:
+
+```typescript
+schedule('process-files', '0 2 * * *')
+  .then(fn('fetch-files', (ctx) => ['file1.xml', 'file2.xml', 'file3.xml']))
+  .unpack()
+  .parallel(fn('process-file', async (ctx) => {
+    try {
+      const result = await processFile(ctx.data);
+      return { success: true, file: ctx.data, result };
+    } catch (error) {
+      // ✅ Return error object instead of throwing
+      return { 
+        success: false, 
+        file: ctx.data, 
+        error: error.message 
+      };
+    }
+  }))
+  .then(fn('process-results', (ctx) => {
+    // ✅ Now you have all results (success + failures)
+    const results = ctx.data;
+    const successes = results.filter(r => r.success);
+    const failures = results.filter(r => !r.success);
+    
+    ctx.log.info(`Processed ${successes.length} files, ${failures.length} failed`);
+    return { successes, failures };
+  }));
+```
+
+### When to Use `Promise.allSettled()` (Recommended)
+
+**Use `Promise.allSettled()` for**:
+- ✅ Batch API submissions
+- ✅ File processing
+- ✅ Any scenario where failures are expected
+- ✅ When you need partial results
+
+**Already implemented in your code**:
+
+```typescript
+// ✅ Your current BatchProcessorService uses this pattern
+const batchResults = await Promise.allSettled(
+  batchChunk.map((chunk, index) =>
+    this.client.sendBatch(jobId, {
+      action: 'UPSERT',
+      entityType: 'INVENTORY',
+      entities: chunk,
+    }).then(batch => ({ success: true, batch }))
+      .catch(error => ({ success: false, error }))
+  )
+);
+```
+
+---
+
+## Key Takeaways
+
+- 🎯 **http()** for external API calls - requires connection, provides `ctx.fetch`
+- 🎯 **webhook()** for receiving requests - provides `ctx.data`, `ctx.request()` for headers
+- 🎯 **schedule()** for time-based tasks - supports cron patterns, can have connection
+- 🎯 **fn()** for internal processing - NO external API access, has `ctx.openKv()`
+- 🎯 **Non-JSON responses** require custom `onSuccess`/`onError` handlers returning Response objects
+- 🎯 **Workflow composition** with `.then()` and `.catch()` enables multi-step patterns
+- 🎯 **Error handling** with try/catch and retry configuration ensures robustness
+- ⚠️ **`.unpack().parallel()`** exists but is NOT fault-tolerant - use `Promise.allSettled()` for resilience
+
+---
+
+## Practice Exercise
+
+Create a scheduled workflow that:
+
+1. Runs hourly (cron: `0 * * * *`)
+2. Fetches inventory from an S3 CSV file
+3. Checks KV storage to avoid duplicate processing
+4. Transforms data using UniversalMapper
+5. Sends to Fluent via Batch API
+6. Marks file as processed in KV storage
+7. Returns XML response on error
+
+**Hints**:
+
+- Use `schedule()` with connection
+- Chain with `fn()` for KV checks
+- Use `http()` context for Fluent API calls
+- Implement custom error handler for XML response
+
+**Solution** available in [Module 8: Best Practices](./platforms-versori-08-best-practices.md#practice-solutions)
+
+---
+
+## Next Steps
+
+Now that you've mastered all workflow types, let's explore connection management in detail.
+
+Continue to [Module 5: Connections →](./platforms-versori-05-connections.md) to learn about OAuth2 connection types, management, and validation.
+
+---
+
+## Related Documentation
+
+- [Module 3: Authentication](./platforms-versori-03-authentication.md) - OAuth2 basics
+- [Module 5: Connections](./platforms-versori-05-connections.md) - Connection management
+- [Module 6: KV Storage](./platforms-versori-06-kv-storage.md) - State management
+- [Webhook Response Patterns](.././modules/platforms-versori-04-workflows.md#critical-non-json-response-handlers-xml-html-csv) - Complete non-JSON response guide
+
+---
+
+[← Previous: Module 3](./platforms-versori-03-authentication.md) | [Back to Guide](../platforms-versori-readme.md) | [Next: Module 5: Connections →](./platforms-versori-05-connections.md)