@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

package/docs/01-TEMPLATES/versori/patterns/versori-patterns-xml-response-patterns.md

@@ -1,1160 +1,1160 @@
-# Versori Webhook: XML/HTML Response Patterns
-
-**FC Connect SDK Use Case Guide**
-
-> **SDK**: [@fluentcommerce/fc-connect-sdk](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk)
-> **Version**: Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
-
-**Context**: Return non-JSON content (XML, HTML, CSV) from Versori HTTP webhooks
-
-**Complexity**: Low-Medium
-
-**Runtime**: Versori Platform
-
-**Estimated Lines**: ~300 lines
-
-## What You'll Build
-
-- Versori webhook with XML response
-- Custom onSuccess/onError handlers
-- Response object with proper Content-Type
-- XMLBuilder for generating XML
-- Error responses in XML format
-
-## SDK Methods Used
-
-- `webhook('name', { response: { mode, onSuccess, onError } })` - Versori webhook config
-- `XMLBuilder(options)` - Build XML responses
-- `builder.build(data)` - Generate XML string
-- `new Response(body, { status, headers })` - Custom response objects
-
----
-
-## Versori Workflows Structure
-
-**Key Concept**: Versori workflows are organized by **trigger type** at the first level, then by **specific workflow** with descriptive file names.
-
-**Trigger Types:**
-- **`webhook()`** → HTTP-based triggers (event-driven) - Creates HTTP endpoints
-- **`schedule()`** → Time-based triggers (cron expressions) - NOT exposed as HTTP endpoints
-- **`http()`** → External API calls (chained from webhook/schedule)
-- **`fn()`** → Internal processing (chained from webhook/schedule)
-
-### Recommended Project Structure
-
-```
-xml-response-patterns/
-├── index.ts                              # Entry point - exports all workflows
-└── src/
-    ├── workflows/
-    │   └── webhook/
-    │       └── xml-response.ts           # Webhook: Return XML responses
-    │
-    ├── services/
-    │   └── xml-builder.service.ts        # Shared XML building logic (reusable)
-    │
-    └── config/
-        └── xml-templates.json            # XML templates
-```
-
-**Benefits:**
-- ✅ Clear trigger separation (`webhook/` vs `scheduled/`)
-- ✅ Descriptive file names (easy to browse and understand)
-- ✅ Scalable (add new workflows without cluttering)
-- ✅ Reusable code in `services/` (DRY principle)
-- ✅ Easy to modify individual workflows without affecting others
-
----
-
-## The Critical Problem
-
-By default, Versori webhooks **JSON-encode all responses**. This breaks non-JSON content types like XML, HTML, and CSV.
-
-### The Wrong Way (Default Behavior)
-
-```typescript
-import { webhook, fn } from '@versori/run';
-
-// ❌ PROBLEM: Returns JSON-encoded XML string
-export const badExample = webhook('xml-endpoint', async (ctx) => {
-  return '<?xml version="1.0"?><order><id>123</id></order>';
-});
-
-// Response Body: "<?xml version=\"1.0\"?><order><id>123</id></order>"
-// Content-Type: application/json
-// Problem: XML is wrapped in JSON string with escaped quotes!
-```
-
-**What happens:**
-
-1. Your workflow returns an XML string
-2. Versori's default handler runs `JSON.stringify()` on it
-3. Client receives a JSON-encoded string instead of raw XML
-4. Content-Type is set to `application/json` instead of `application/xml`
-
-### The Right Way (Custom Response Objects)
-
-```typescript
-import { webhook, fn } from '@versori/run';
-
-// ✅ SOLUTION: Returns raw XML
-export const goodExample = webhook('xml-endpoint', {
-  response: {
-    mode: 'sync',
-    onSuccess: (ctx) => new Response(ctx.data, {
-      status: 200,
-      headers: { 'Content-Type': 'application/xml; charset=utf-8' }
-    }),
-    onError: (ctx) => new Response(ctx.data, {
-      status: 500,
-      headers: { 'Content-Type': 'application/xml; charset=utf-8' }
-    })
-  }
-})
-  .then(fn('generate-xml', () => {
-    return '<?xml version="1.0"?><order><id>123</id></order>';
-  }));
-
-// Response Body: <?xml version="1.0"?><order><id>123</id></order>
-// Content-Type: application/xml; charset=utf-8
-// Success: Raw XML streamed directly to client!
-```
-
-**Why this works:**
-
-- Custom handlers return `Response` objects
-- Versori's `sendResponse()` function streams Response bodies directly via Node.js `pipeline()`
-- No JSON encoding is applied to Response objects
-- Content-Type header is preserved exactly as specified
-
-## Complete Working Examples
-
-### Example 1: Basic JSON Response (Default Behavior)
-
-For JSON responses, no custom handlers are needed:
-
-```typescript
-import { webhook, fn } from '@versori/run';
-
-/**
- * Default JSON response - no custom handlers needed
- * Versori automatically JSON-encodes and sets Content-Type: application/json
- */
-export const jsonEndpoint = webhook('json-data', async (ctx) => {
-  return {
-    orderId: '12345',
-    status: 'COMPLETED',
-    items: [
-      { sku: 'ABC123', quantity: 2 },
-      { sku: 'DEF456', quantity: 1 }
-    ]
-  };
-});
-
-// Response Body: {"orderId":"12345","status":"COMPLETED","items":[...]}
-// Content-Type: application/json
-// ✅ Perfect for JSON data!
-```
-
-### Example 2: XML Response with XMLBuilder
-
-Full XML response workflow with proper error handling:
-
-```typescript
-import { webhook, fn, http } from '@versori/run';
-// FC Connect SDK
-// Install: npm install @fluentcommerce/fc-connect-sdk@latest
-// Docs: https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk
-// GitHub: https://github.com/fluentcommerce/fc-connect-sdk
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-import { XMLBuilder } from 'fast-xml-parser';
-
-/**
- * XML Response Webhook
- *
- * CRITICAL PATTERNS:
- * 1. Configure custom onSuccess/onError handlers
- * 2. Both handlers return Response objects
- * 3. Set Content-Type: application/xml
- * 4. Workflow steps return raw strings (not Response objects)
- * 5. Error handler also returns XML
- */
-export const orderXmlEndpoint = webhook('order-xml', {
-  response: {
-    mode: 'sync',
-    // Success handler - wraps XML string in Response object
-    onSuccess: (ctx) => new Response(ctx.data, {
-      status: 200,
-      headers: {
-        'Content-Type': 'application/xml; charset=utf-8',
-        'X-Execution-Id': ctx.executionId,
-        'Cache-Control': 'no-cache'
-      }
-    }),
-    // Error handler - also returns XML format
-    onError: (ctx) => new Response(ctx.data, {
-      status: 500,
-      headers: {
-        'Content-Type': 'application/xml; charset=utf-8',
-        'X-Execution-Id': ctx.executionId
-      }
-    })
-  },
-  cors: true
-})
-  // Step 1: Extract order ID from request
-  .then(fn('parse-request', ({ data }) => {
-    // Versori auto-parses XML when Content-Type is application/xml
-    const orderId = data?.OrderRequest?.OrderId;
-    if (!orderId) {
-      throw new Error('OrderId missing from request');
-    }
-    return { orderId };
-  }))
-  // Step 2: Fetch order from Fluent Commerce
-  .then(http('fetch-order', {
-    connection: 'fluent_commerce'
-  }, async (ctx) => {
-    const client = await createClient(ctx);
-    const result = await client.graphql({
-      query: `query GetOrder($ref: String) {
-        order(ref: $ref) {
-          id
-          ref
-          status
-          totalPrice
-          customer {
-            firstName
-            lastName
-            username
-          }
-          items(first: 50) {
-            edges {
-              node {
-                ref
-                quantity
-                price
-                product {
-                  ref
-                  name
-                }
-              }
-            }
-          }
-        }
-      }`,
-      variables: { ref: ctx.data.orderId }
-    });
-
-    if (!result.data?.order) {
-      throw new Error(`Order not found: ${ctx.data.orderId}`);
-    }
-
-    return { order: result.data.order };
-  }))
-  // Step 3: Transform to XML format
-  .then(fn('build-xml', ({ data }) => {
-    const { order } = data;
-
-    // Initialize XML Builder
-    const builder = new XMLBuilder({
-      ignoreAttributes: false,
-      attributeNamePrefix: '@',
-      format: true,
-      indentBy: '  ',
-      suppressEmptyNode: true
-    });
-
-    // Build XML structure
-    const xmlObject = {
-      '?xml': {
-        '@version': '1.0',
-        '@encoding': 'UTF-8'
-      },
-      OrderResponse: {
-        '@xmlns': 'http://api.example.com/schema/order/1.0',
-        Order: {
-          OrderId: order.ref,
-          Status: order.status,
-          TotalPrice: {
-            '@currency': 'USD',
-            '#text': order.totalPrice
-          },
-          Customer: {
-            FirstName: order.customer.firstName,
-            LastName: order.customer.lastName,
-            Email: order.customer.username
-          },
-          Items: {
-            Item: order.items.edges.map(edge => ({
-              SKU: edge.node.product.ref,
-              ProductName: edge.node.product.name,
-              Quantity: edge.node.quantity,
-              Price: edge.node.price
-            }))
-          }
-        }
-      }
-    };
-
-    // Generate XML string
-    const xmlString = builder.build(xmlObject);
-
-    // Return XML string - onSuccess handler will wrap it
-    return xmlString;
-  }))
-  // Error handling - return XML error format
-  .catch(({ data }) => {
-    const errorMessage = data instanceof Error ? data.message : String(data);
-
-    // Return error XML string - onError handler will wrap it
-    return `<?xml version="1.0" encoding="UTF-8"?>
-<OrderResponse xmlns="http://api.example.com/schema/order/1.0">
-  <Error>
-    <Code>PROCESSING_ERROR</Code>
-    <Message>${errorMessage}</Message>
-    <Timestamp>${new Date().toISOString()}</Timestamp>
-  </Error>
-</OrderResponse>`;
-  });
-```
-
-**Testing this endpoint:**
-
-```bash
-# Send XML request
-curl -X POST https://your-workspace.versori.run/order-xml \
-  -H "Content-Type: application/xml" \
-  -d '<?xml version="1.0"?>
-<OrderRequest>
-  <OrderId>ORD-12345</OrderId>
-</OrderRequest>'
-
-# Success Response (200 OK):
-<?xml version="1.0" encoding="UTF-8"?>
-<OrderResponse xmlns="http://api.example.com/schema/order/1.0">
-  <Order>
-    <OrderId>ORD-12345</OrderId>
-    <Status>COMPLETED</Status>
-    <TotalPrice currency="USD">199.99</TotalPrice>
-    ...
-  </Order>
-</OrderResponse>
-
-# Error Response (500 Internal Server Error):
-<?xml version="1.0" encoding="UTF-8"?>
-<OrderResponse xmlns="http://api.example.com/schema/order/1.0">
-  <Error>
-    <Code>PROCESSING_ERROR</Code>
-    <Message>Order not found: ORD-12345</Message>
-    <Timestamp>2025-01-15T10:30:00Z</Timestamp>
-  </Error>
-</OrderResponse>
-```
-
-### Example 3: HTML Response
-
-Return HTML pages from webhooks (useful for status pages, documentation):
-
-```typescript
-import { webhook, fn } from '@versori/run';
-
-export const statusPage = webhook('status', {
-  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">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>Service Status</title>
-  <style>
-    body {
-      font-family: Arial, sans-serif;
-      max-width: 800px;
-      margin: 50px auto;
-      padding: 20px;
-    }
-    .status {
-      padding: 20px;
-      background-color: #4CAF50;
-      color: white;
-      border-radius: 5px;
-    }
-    .service {
-      margin: 10px 0;
-      padding: 10px;
-      border: 1px solid #ddd;
-      border-radius: 3px;
-    }
-  </style>
-</head>
-<body>
-  <h1>Service Status Dashboard</h1>
-  <div class="status">
-    <h2>✓ All Systems Operational</h2>
-  </div>
-  <div class="service">
-    <h3>Inventory Ingestion</h3>
-    <p>Status: <strong>Operational</strong></p>
-    <p>Last Run: ${new Date().toISOString()}</p>
-  </div>
-  <div class="service">
-    <h3>Order Processing</h3>
-    <p>Status: <strong>Operational</strong></p>
-  </div>
-</body>
-</html>`;
-  }));
-```
-
-### Example 4: CSV Response
-
-Download data as CSV files:
-
-```typescript
-import { webhook, fn, http } from '@versori/run';
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-export const exportInventory = webhook('export-inventory-csv', {
-  response: {
-    mode: 'sync',
-    onSuccess: (ctx) => new Response(ctx.data, {
-      status: 200,
-      headers: {
-        'Content-Type': 'text/csv; charset=utf-8',
-        'Content-Disposition': 'attachment; filename="inventory-export.csv"'
-      }
-    })
-  }
-})
-  .then(http('fetch-inventory', {
-    connection: 'fluent_commerce'
-  }, async (ctx) => {
-    const client = await createClient(ctx);
-    const result = await client.graphql({
-      query: `query {
-        inventoryQuantities(first: 100) {
-          edges {
-            node {
-              ref
-              quantity
-              location { ref }
-              product { ref name }
-            }
-          }
-        }
-      }`
-    });
-
-    return { items: result.data.inventoryQuantities.edges };
-  }))
-  .then(fn('build-csv', ({ data }) => {
-    // CSV Header
-    let csv = 'SKU,Product Name,Location,Quantity\n';
-
-    // CSV Rows
-    data.items.forEach(edge => {
-      const item = edge.node;
-      const sku = item.product?.ref || '';
-      const name = (item.product?.name || '').replace(/"/g, '""'); // Escape quotes
-      const location = item.location?.ref || '';
-      const qty = item.quantity || 0;
-
-      csv += `"${sku}","${name}","${location}",${qty}\n`;
-    });
-
-    return csv;
-  }));
-```
-
-### Example 5: Plain Text Response
-
-Health check or simple text endpoints:
-
-```typescript
-import { webhook, fn } from '@versori/run';
-
-export const healthCheck = webhook('health', {
-  response: {
-    mode: 'sync',
-    onSuccess: (ctx) => new Response(ctx.data, {
-      status: 200,
-      headers: { 'Content-Type': 'text/plain; charset=utf-8' }
-    })
-  }
-})
-  .then(fn('check-health', () => {
-    const uptime = process.uptime();
-    const timestamp = new Date().toISOString();
-
-    return `Service Status: Operational
-Uptime: ${uptime.toFixed(0)} seconds
-Timestamp: ${timestamp}
-  }));
-```
-
-## Key Patterns Explained
-
-### Pattern 1: Why Custom Response Objects Are Needed
-
-**The Technical Details:**
-
-Versori's `sendResponse()` function (from @versori/run v0.4.4):
-
-```typescript
-function sendResponse(res, response) {
-  res.status(response.status);
-  response.headers.forEach((value, key) => {
-    res.setHeader(key, value);
-  });
-  if (response.body) {
-    pipeline(response.body, res);  // Streams directly without encoding
-  }
-}
-```
-
-**Key insight:** When you return a `Response` object, Versori uses Node.js `pipeline()` to stream the body directly to the HTTP response **without any JSON encoding**.
-
-**Default handlers** (when you don't provide custom ones):
-
-```typescript
-// Simplified version of default behavior
-const defaultOnSuccess = (ctx) => {
-  return JSON.stringify(ctx.data);  // ❌ Encodes everything as JSON
-};
-```
-
-### Pattern 2: onSuccess Handler Pattern
-
-The `onSuccess` handler receives context and must return a `Response` object:
-
-```typescript
-onSuccess: (ctx) => {
-  // ctx.data = output from final .then() step
-  // ctx.executionId = unique execution ID
-  // ctx.metadata = any metadata from workflow
-
-  return new Response(ctx.data, {
-    status: 200,  // HTTP status code
-    headers: {
-      'Content-Type': 'application/xml; charset=utf-8',
-      'X-Execution-Id': ctx.executionId,
-      'Cache-Control': 'no-cache',
-      // Any custom headers...
-    }
-  });
-}
-```
-
-**Important:** Your workflow steps should return **raw strings**, not Response objects. The handler wraps them.
-
-### Pattern 3: onError Handler Pattern
-
-The `onError` handler handles exceptions and should match the content type:
-
-```typescript
-onError: (ctx) => {
-  // ctx.data = error from .catch() or thrown exception
-  // ctx.executionId = unique execution ID
-
-  return new Response(ctx.data, {
-    status: 500,  // or 400, 404, etc.
-    headers: {
-      'Content-Type': 'application/xml; charset=utf-8',  // Match success type!
-      'X-Execution-Id': ctx.executionId
-    }
-  });
-}
-```
-
-**Best practice:** Use the same Content-Type for errors as for success responses. If your API returns XML on success, return XML errors too.
-
-### Pattern 4: Content-Type Headers
-
-Always include charset for text-based formats:
-
-```typescript
-// ✅ CORRECT - Includes charset
-'Content-Type': 'application/xml; charset=utf-8'
-'Content-Type': 'text/html; charset=utf-8'
-'Content-Type': 'text/csv; charset=utf-8'
-'Content-Type': 'text/plain; charset=utf-8'
-
-// ❌ INCOMPLETE - Missing charset (may work but not recommended)
-'Content-Type': 'application/xml'
-
-// ✅ CORRECT - Binary formats don't need charset
-'Content-Type': 'application/pdf'
-'Content-Type': 'image/png'
-```
-
-### Pattern 5: XMLBuilder Integration
-
-Using `fast-xml-parser` to generate clean XML:
-
-```typescript
-import { XMLBuilder } from 'fast-xml-parser';
-
-// Initialize builder with options
-const builder = new XMLBuilder({
-  ignoreAttributes: false,      // Include XML attributes
-  attributeNamePrefix: '@',      // Prefix for attributes
-  textNodeName: '#text',         // Key for text content
-  format: true,                  // Pretty-print
-  indentBy: '  ',                // Indentation
-  suppressEmptyNode: true        // Don't output <tag></tag> for nulls
-});
-
-// Define XML structure
-const xmlObject = {
-  '?xml': {                      // XML declaration
-    '@version': '1.0',
-    '@encoding': 'UTF-8'
-  },
-  Root: {
-    '@xmlns': 'http://...',      // Root attributes start with @
-    Child: 'value',
-    Another: {
-      '@id': '123',              // Element with attribute and text
-      '#text': 'content'
-    },
-    List: {
-      Item: ['item1', 'item2']   // Arrays become multiple elements
-    }
-  }
-};
-
-// Generate XML string
-const xmlString = builder.build(xmlObject);
-```
-
-**Generated Output:**
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<Root xmlns="http://...">
-  <Child>value</Child>
-  <Another id="123">content</Another>
-  <List>
-    <Item>item1</Item>
-    <Item>item2</Item>
-  </List>
-</Root>
-```
-
-## The JSON Encoding Problem
-
-### Side-by-Side Comparison
-
-#### ❌ WRONG: Default Behavior (JSON-Encoded)
-
-```typescript
-export const badXmlEndpoint = webhook('bad-xml', async (ctx) => {
-  return '<?xml version="1.0"?><order><id>123</id></order>';
-});
-```
-
-**What the client receives:**
-
-```bash
-$ curl https://workspace.versori.run/bad-xml
-
-# Response:
-"<?xml version=\"1.0\"?><order><id>123</id></order>"
-
-# Response Headers:
-Content-Type: application/json
-Content-Length: 52
-```
-
-**Problems:**
-
-1. XML is wrapped in quotes
-2. Special characters are escaped (`\n`, `\"`)
-3. Content-Type is JSON, not XML
-4. Cannot be parsed as XML by clients
-5. Requires client-side JSON parsing then XML parsing
-
-#### ✅ RIGHT: Custom Response Objects
-
-```typescript
-export const goodXmlEndpoint = webhook('good-xml', {
-  response: {
-    mode: 'sync',
-    onSuccess: (ctx) => new Response(ctx.data, {
-      status: 200,
-      headers: { 'Content-Type': 'application/xml; charset=utf-8' }
-    })
-  }
-})
-  .then(fn('gen', () => '<?xml version="1.0"?><order><id>123</id></order>'));
-```
-
-**What the client receives:**
-
-```bash
-$ curl https://workspace.versori.run/good-xml
-
-# Response:
-<?xml version="1.0"?><order><id>123</id></order>
-
-# Response Headers:
-Content-Type: application/xml; charset=utf-8
-Content-Length: 47
-```
-
-**Benefits:**
-
-1. Raw XML delivered to client
-2. No escaping or encoding
-3. Correct Content-Type header
-4. Client can parse directly as XML
-5. Standard HTTP semantics
-
-### Visual Example: What Gets Sent
-
-**Bad (JSON-encoded):**
-
-```
-HTTP/1.1 200 OK
-Content-Type: application/json
-
-"<?xml version=\"1.0\"?><order><id>123</id></order>"
-```
-
-**Good (Raw XML):**
-
-```
-HTTP/1.1 200 OK
-Content-Type: application/xml; charset=utf-8
-
-<?xml version="1.0"?><order><id>123</id></order>
-```
-
-## Common Issues and Solutions
-
-### Issue 1: XML Still Being JSON-Encoded
-
-**Symptom:** Response is wrapped in quotes with escaped characters.
-
-**Cause:** Missing custom response handlers.
-
-**Solution:**
-
-```typescript
-// ❌ Missing handlers
-export const endpoint = webhook('test')
-  .then(fn('gen', () => '<xml>data</xml>'));
-
-// ✅ Add custom handlers
-export const endpoint = webhook('test', {
-  response: {
-    mode: 'sync',
-    onSuccess: (ctx) => new Response(ctx.data, {
-      status: 200,
-      headers: { 'Content-Type': 'application/xml; charset=utf-8' }
-    })
-  }
-})
-  .then(fn('gen', () => '<xml>data</xml>'));
-```
-
-### Issue 2: Wrong Content-Type in Response
-
-**Symptom:** Browser tries to download file or displays incorrectly.
-
-**Cause:** Content-Type doesn't match actual content.
-
-**Solution:**
-
-```typescript
-// ❌ WRONG - XML with JSON content type
-headers: { 'Content-Type': 'application/json' }
-
-// ✅ RIGHT - Match content type to content
-headers: { 'Content-Type': 'application/xml; charset=utf-8' }
-```
-
-**Content-Type Reference:**
-
-- XML: `application/xml; charset=utf-8`
-- HTML: `text/html; charset=utf-8`
-- CSV: `text/csv; charset=utf-8`
-- Plain text: `text/plain; charset=utf-8`
-- JSON: `application/json` (default, no custom handler needed)
-
-### Issue 3: Error Responses Return JSON Instead of XML
-
-**Symptom:** Success returns XML, but errors return JSON.
-
-**Cause:** Missing `onError` handler.
-
-**Solution:**
-
-```typescript
-export const endpoint = webhook('test', {
-  response: {
-    mode: 'sync',
-    onSuccess: (ctx) => new Response(ctx.data, {
-      status: 200,
-      headers: { 'Content-Type': 'application/xml; charset=utf-8' }
-    }),
-    // ✅ Add error handler with same content type
-    onError: (ctx) => new Response(ctx.data, {
-      status: 500,
-      headers: { 'Content-Type': 'application/xml; charset=utf-8' }
-    })
-  }
-})
-  .then(fn('gen', () => '<success/>'))
-  .catch(() => '<error/>');  // Make sure .catch() returns XML string
-```
-
-### Issue 4: Accidental Double-Encoding
-
-**Symptom:** Response has extra quotes or escaped characters.
-
-**Cause:** Calling `JSON.stringify()` on data before returning.
-
-**Solution:**
-
-```typescript
-// ❌ WRONG - Don't stringify in handler
-onSuccess: (ctx) => new Response(JSON.stringify(ctx.data), {
-  status: 200,
-  headers: { 'Content-Type': 'application/xml; charset=utf-8' }
-})
-
-// ✅ RIGHT - Pass raw data
-onSuccess: (ctx) => new Response(ctx.data, {
-  status: 200,
-  headers: { 'Content-Type': 'application/xml; charset=utf-8' }
-})
-```
-
-## Testing Your Implementation
-
-### Test 1: Verify Content-Type Header
-
-```bash
-# Check response headers
-curl -v https://your-workspace.versori.run/your-endpoint
-
-# Look for:
-# ✅ Content-Type: application/xml; charset=utf-8
-# ❌ Content-Type: application/json
-```
-
-### Test 2: Verify Raw Content
-
-```bash
-# Get response body
-curl https://your-workspace.versori.run/your-endpoint
-
-# Expected (raw XML):
-# <?xml version="1.0" encoding="UTF-8"?>
-# <order><id>123</id></order>
-
-# NOT expected (JSON-encoded):
-# "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<order><id>123</id></order>"
-```
-
-### Test 3: Verify Error Handling
-
-```bash
-# Trigger an error (send invalid request)
-curl -X POST https://your-workspace.versori.run/your-endpoint \
-  -H "Content-Type: application/xml" \
-  -d '<?xml version="1.0"?><Invalid/>'
-
-# Should return:
-# - Status: 500 (or appropriate error code)
-# - Content-Type: application/xml (same as success)
-# - Body: XML error message
-```
-
-### Test 4: XML Parser Validation
-
-```bash
-# Pipe response through xmllint to validate XML
-curl https://your-workspace.versori.run/your-endpoint | xmllint --format -
-
-# Should format successfully without errors
-```
-
-## Implementation Checklist
-
-When implementing non-JSON webhooks, verify:
-
-- [ ] Webhook configured with `response.mode: 'sync'`
-- [ ] `onSuccess` handler defined and returns `Response` object
-- [ ] `onError` handler defined and returns `Response` object
-- [ ] Both handlers set correct `Content-Type` header
-- [ ] Content-Type includes `charset=utf-8` for text formats
-- [ ] Workflow `.then()` steps return raw strings (not Response objects)
-- [ ] Workflow `.catch()` returns error string in correct format
-- [ ] Status codes are appropriate (200, 400, 500, etc.)
-- [ ] Error handler uses same Content-Type as success handler
-- [ ] Tested with curl to verify raw output (no JSON encoding)
-- [ ] Tested error scenarios return proper format
-- [ ] No `JSON.stringify()` calls in custom handlers
-- [ ] XML validated with parser (if XML response)
-
-
-## Versori Syntax Validation
-
-### Critical: Buffer Import Required
-
-**For Deno/Versori runtime, ALWAYS import Buffer explicitly:**
-
-```typescript
-// ✅ CORRECT - Explicit import required
-import { Buffer } from 'node:buffer';
-
-// Use Buffer for encoding operations
-await sftp.uploadFile('utf8', Buffer.from(xmlContent), '/path/file.xml');
-const decoded = Buffer.from(base64String, 'base64').toString('utf-8');
-```
-
-**Why:** Deno runtime doesn't have `Buffer` as a global (unlike Node.js). Missing this import will cause runtime errors.
-
-### Validated Syntax Patterns for SDK ^0.1.27
-
-#### 1. Webhook Response Configuration
-
-```typescript
-// ✅ CORRECT - Webhook with custom response handlers
-export const endpoint = webhook('name', {
-  response: {
-    mode: 'sync',  // Required for custom handlers
-    onSuccess: (ctx) => new Response(ctx.data, {
-      status: 200,
-      headers: { 'Content-Type': 'application/xml; charset=utf-8' }
-    }),
-    onError: (ctx) => new Response(ctx.data, {
-      status: 500,
-      headers: { 'Content-Type': 'application/xml; charset=utf-8' }
-    })
-  },
-  cors: true  // Optional CORS configuration
-})
-  .then(fn('step', () => '<xml/>'));
-
-// ❌ WRONG - Missing response configuration
-export const endpoint = webhook('name', async (ctx) => {
-  return '<xml/>';  // Will be JSON-encoded!
-});
-```
-
-#### 2. Client Factory Usage
-
-```typescript
-// ✅ CORRECT - Use createClient() factory
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-export const endpoint = webhook('name', {
-  connection: 'fluent_commerce'
-}, async (ctx) => {
-  const client = await createClient(ctx);
-  // Client automatically configured from connection
-});
-
-// ❌ WRONG - Direct instantiation bypasses context detection
-import { FluentClient } from '@fluentcommerce/fc-connect-sdk';
-const client = new FluentClient(config);  // Don't do this in Versori
-```
-
-#### 3. Logging Best Practices
-
-```typescript
-// ✅ CORRECT - Use native log from context
-export const endpoint = webhook('name', {
-  connection: 'fluent_commerce'
-}, async (ctx) => {
-  const { log } = ctx;
-  log('Processing started', { orderId: '123' });
-
-  // SDK client receives log automatically
-  const client = await createClient(ctx);
-});
-
-// ❌ WRONG - Don't use LoggingService in Versori
-import { LoggingService } from '@fluentcommerce/fc-connect-sdk';
-const logger = new LoggingService();  // Not needed in Versori
-```
-
-#### 4. Auto-Pagination Syntax
-
-```typescript
-// ✅ CORRECT - pagination object (NOT config)
-const result = await client.graphql({
-  query,
-  variables: { first: 100 },
-  pagination: {  // Use 'pagination', not 'config'
-    maxPages: 50,
-    pageSize: 100
-  }
-});
-
-// ❌ WRONG - Old syntax with 'config'
-const result = await client.graphql({
-  query,
-  variables: { first: 100 },
-  config: {  // Use 'pagination' parameter instead
-    maxPages: 50
-  }
-});
-```
-
-#### 5. SDK Version Specification
-
-```json
-{
-  "dependencies": {
-    "@fluentcommerce/fc-connect-sdk": "^0.1.39",
-    "@versori/run": "latest",
-    "fast-xml-parser": "^4.3.0"
-  }
-}
-```
-
-#### 6. Workflow Step Return Values
-
-```typescript
-// ✅ CORRECT - Return raw data, let handlers wrap it
-export const endpoint = webhook('name', {
-  response: {
-    mode: 'sync',
-    onSuccess: (ctx) => new Response(ctx.data, {
-      status: 200,
-      headers: { 'Content-Type': 'application/xml; charset=utf-8' }
-    })
-  }
-})
-  .then(fn('generate', () => {
-    return '<xml>data</xml>';  // Return raw string
-  }));
-
-// ❌ WRONG - Don't return Response objects from workflow steps
-export const endpoint = webhook('name', {
-  response: { mode: 'sync', onSuccess: (ctx) => ctx.data }
-})
-  .then(fn('generate', () => {
-    return new Response('<xml>data</xml>');  // Wrong! Handler should do this
-  }));
-```
-
-#### 7. Error Handling Pattern
-
-```typescript
-// ✅ CORRECT - .catch() returns error data, onError wraps it
-export const endpoint = webhook('name', {
-  response: {
-    mode: 'sync',
-    onSuccess: (ctx) => new Response(ctx.data, {
-      status: 200,
-      headers: { 'Content-Type': 'application/xml; charset=utf-8' }
-    }),
-    onError: (ctx) => new Response(ctx.data, {
-      status: 500,
-      headers: { 'Content-Type': 'application/xml; charset=utf-8' }
-    })
-  }
-})
-  .then(fn('process', () => '<success/>'))
-  .catch((error) => {
-    // Return error XML string - onError handler will wrap it
-    return `<error>${error.message}</error>`;
-  });
-
-// ❌ WRONG - Throwing without catch or returning Response
-export const endpoint = webhook('name')
-  .then(fn('process', () => {
-    throw new Error('Failed');  // Will cause 500 with JSON error
-  }));
-```
-
-### Validation Checklist
-
-Before deploying to Versori, verify:
-
-**Syntax:**
-- [ ] Buffer explicitly imported: `import { Buffer } from 'node:buffer';`
-- [ ] webhook() has response.mode: 'sync' for custom handlers
-- [ ] onSuccess and onError both defined
-- [ ] Both handlers return Response objects
-- [ ] Workflow steps return raw data (not Response objects)
-
-**SDK Integration:**
-- [ ] createClient() used (not direct instantiation)
-- [ ] Native ctx.log used (not LoggingService)
-- [ ] Auto-pagination uses 'pagination' object (not 'config')
-- [ ] SDK version is ^0.1.27 or later
-
-**Response Handling:**
-- [ ] Content-Type headers match actual content
-- [ ] charset=utf-8 included for text formats
-- [ ] onError uses same Content-Type as onSuccess
-- [ ] Error .catch() returns proper format string
-
-**Testing:**
-- [ ] Tested with curl to verify raw output
-- [ ] Verified Content-Type header is correct
-- [ ] Tested error scenarios return proper format
-- [ ] Validated XML with parser (if XML)
-
-## Version Compatibility
-
-This pattern works with:
-
-**Versori Runtime:**
-- @versori/run v0.4.4 (latest stable)
-- @versori/run v0.4.3
-- @versori/run v0.4.2
-- @versori/run v0.4.1
-- @versori/run v0.4.0
-- @versori/run v0.4.0-alpha.2
-
-All v0.4.x versions use the same `sendResponse()` implementation that streams Response objects directly.
-
-**FC Connect SDK:**
-- @fluentcommerce/fc-connect-sdk v0.1.27+
-- @fluentcommerce/fc-connect-sdk v0.1.26
-- @fluentcommerce/fc-connect-sdk v0.1.25
-- All v0.1.x versions support Versori platform integration
-
-## Related Guides
-
-- **[Versori Platform Integration](../../../04-REFERENCE/platforms/versori/)** - Complete Versori platform guide
-- **[GraphQL Mutation Mapping Guide](../../../02-CORE-GUIDES/mapping/graphql-mutation-mapping/)** - XML/JSON to GraphQL mutations
-- **[Universal Mapping Guide](../../../02-CORE-GUIDES/mapping/)** - Field transformation patterns
-- **[Webhook Validation Guide](../../../02-CORE-GUIDES/webhook-validation/)** - Webhook signature validation
-
-## Real-World Example Reference
-
-See complete production implementation:
-
-- **File**: `Sandbox Hibbet SFCC to Fluent Order integration (1)/src/workflows/process-order-detail-request.ts`
-- **Pattern**: XML request → GraphQL query → XML response
-- **Features**: Full error handling, extraction mapping, XMLBuilder integration
-
-## Summary
-
-**Golden Rule:** For non-JSON content types in Versori webhooks, **ALWAYS** use custom `onSuccess` and `onError` handlers that return `Response` objects with the correct Content-Type header.
-
-**Why It Matters:**
-
-- Default handlers JSON-encode all responses (breaks XML/HTML/CSV)
-- Custom handlers bypass encoding and stream content directly
-- Proper Content-Type headers ensure correct client behavior
-- Consistent error handling provides better API experience
-
-**Impact:** This pattern saves hours of debugging and ensures proper content delivery for XML APIs, HTML pages, CSV exports, and other non-JSON formats. It's critical for SOAP integrations, enterprise systems, and file downloads.
+# Versori Webhook: XML/HTML Response Patterns
+
+**FC Connect SDK Use Case Guide**
+
+> **SDK**: [@fluentcommerce/fc-connect-sdk](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk)
+> **Version**: Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
+
+**Context**: Return non-JSON content (XML, HTML, CSV) from Versori HTTP webhooks
+
+**Complexity**: Low-Medium
+
+**Runtime**: Versori Platform
+
+**Estimated Lines**: ~300 lines
+
+## What You'll Build
+
+- Versori webhook with XML response
+- Custom onSuccess/onError handlers
+- Response object with proper Content-Type
+- XMLBuilder for generating XML
+- Error responses in XML format
+
+## SDK Methods Used
+
+- `webhook('name', { response: { mode, onSuccess, onError } })` - Versori webhook config
+- `XMLBuilder(options)` - Build XML responses
+- `builder.build(data)` - Generate XML string
+- `new Response(body, { status, headers })` - Custom response objects
+
+---
+
+## Versori Workflows Structure
+
+**Key Concept**: Versori workflows are organized by **trigger type** at the first level, then by **specific workflow** with descriptive file names.
+
+**Trigger Types:**
+- **`webhook()`** → HTTP-based triggers (event-driven) - Creates HTTP endpoints
+- **`schedule()`** → Time-based triggers (cron expressions) - NOT exposed as HTTP endpoints
+- **`http()`** → External API calls (chained from webhook/schedule)
+- **`fn()`** → Internal processing (chained from webhook/schedule)
+
+### Recommended Project Structure
+
+```
+xml-response-patterns/
+├── index.ts                              # Entry point - exports all workflows
+└── src/
+    ├── workflows/
+    │   └── webhook/
+    │       └── xml-response.ts           # Webhook: Return XML responses
+    │
+    ├── services/
+    │   └── xml-builder.service.ts        # Shared XML building logic (reusable)
+    │
+    └── config/
+        └── xml-templates.json            # XML templates
+```
+
+**Benefits:**
+- ✅ Clear trigger separation (`webhook/` vs `scheduled/`)
+- ✅ Descriptive file names (easy to browse and understand)
+- ✅ Scalable (add new workflows without cluttering)
+- ✅ Reusable code in `services/` (DRY principle)
+- ✅ Easy to modify individual workflows without affecting others
+
+---
+
+## The Critical Problem
+
+By default, Versori webhooks **JSON-encode all responses**. This breaks non-JSON content types like XML, HTML, and CSV.
+
+### The Wrong Way (Default Behavior)
+
+```typescript
+import { webhook, fn } from '@versori/run';
+
+// ❌ PROBLEM: Returns JSON-encoded XML string
+export const badExample = webhook('xml-endpoint', async (ctx) => {
+  return '<?xml version="1.0"?><order><id>123</id></order>';
+});
+
+// Response Body: "<?xml version=\"1.0\"?><order><id>123</id></order>"
+// Content-Type: application/json
+// Problem: XML is wrapped in JSON string with escaped quotes!
+```
+
+**What happens:**
+
+1. Your workflow returns an XML string
+2. Versori's default handler runs `JSON.stringify()` on it
+3. Client receives a JSON-encoded string instead of raw XML
+4. Content-Type is set to `application/json` instead of `application/xml`
+
+### The Right Way (Custom Response Objects)
+
+```typescript
+import { webhook, fn } from '@versori/run';
+
+// ✅ SOLUTION: Returns raw XML
+export const goodExample = webhook('xml-endpoint', {
+  response: {
+    mode: 'sync',
+    onSuccess: (ctx) => new Response(ctx.data, {
+      status: 200,
+      headers: { 'Content-Type': 'application/xml; charset=utf-8' }
+    }),
+    onError: (ctx) => new Response(ctx.data, {
+      status: 500,
+      headers: { 'Content-Type': 'application/xml; charset=utf-8' }
+    })
+  }
+})
+  .then(fn('generate-xml', () => {
+    return '<?xml version="1.0"?><order><id>123</id></order>';
+  }));
+
+// Response Body: <?xml version="1.0"?><order><id>123</id></order>
+// Content-Type: application/xml; charset=utf-8
+// Success: Raw XML streamed directly to client!
+```
+
+**Why this works:**
+
+- Custom handlers return `Response` objects
+- Versori's `sendResponse()` function streams Response bodies directly via Node.js `pipeline()`
+- No JSON encoding is applied to Response objects
+- Content-Type header is preserved exactly as specified
+
+## Complete Working Examples
+
+### Example 1: Basic JSON Response (Default Behavior)
+
+For JSON responses, no custom handlers are needed:
+
+```typescript
+import { webhook, fn } from '@versori/run';
+
+/**
+ * Default JSON response - no custom handlers needed
+ * Versori automatically JSON-encodes and sets Content-Type: application/json
+ */
+export const jsonEndpoint = webhook('json-data', async (ctx) => {
+  return {
+    orderId: '12345',
+    status: 'COMPLETED',
+    items: [
+      { sku: 'ABC123', quantity: 2 },
+      { sku: 'DEF456', quantity: 1 }
+    ]
+  };
+});
+
+// Response Body: {"orderId":"12345","status":"COMPLETED","items":[...]}
+// Content-Type: application/json
+// ✅ Perfect for JSON data!
+```
+
+### Example 2: XML Response with XMLBuilder
+
+Full XML response workflow with proper error handling:
+
+```typescript
+import { webhook, fn, http } from '@versori/run';
+// FC Connect SDK
+// Install: npm install @fluentcommerce/fc-connect-sdk@latest
+// Docs: https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk
+// GitHub: https://github.com/fluentcommerce/fc-connect-sdk
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+import { XMLBuilder } from 'fast-xml-parser';
+
+/**
+ * XML Response Webhook
+ *
+ * CRITICAL PATTERNS:
+ * 1. Configure custom onSuccess/onError handlers
+ * 2. Both handlers return Response objects
+ * 3. Set Content-Type: application/xml
+ * 4. Workflow steps return raw strings (not Response objects)
+ * 5. Error handler also returns XML
+ */
+export const orderXmlEndpoint = webhook('order-xml', {
+  response: {
+    mode: 'sync',
+    // Success handler - wraps XML string in Response object
+    onSuccess: (ctx) => new Response(ctx.data, {
+      status: 200,
+      headers: {
+        'Content-Type': 'application/xml; charset=utf-8',
+        'X-Execution-Id': ctx.executionId,
+        'Cache-Control': 'no-cache'
+      }
+    }),
+    // Error handler - also returns XML format
+    onError: (ctx) => new Response(ctx.data, {
+      status: 500,
+      headers: {
+        'Content-Type': 'application/xml; charset=utf-8',
+        'X-Execution-Id': ctx.executionId
+      }
+    })
+  },
+  cors: true
+})
+  // Step 1: Extract order ID from request
+  .then(fn('parse-request', ({ data }) => {
+    // Versori auto-parses XML when Content-Type is application/xml
+    const orderId = data?.OrderRequest?.OrderId;
+    if (!orderId) {
+      throw new Error('OrderId missing from request');
+    }
+    return { orderId };
+  }))
+  // Step 2: Fetch order from Fluent Commerce
+  .then(http('fetch-order', {
+    connection: 'fluent_commerce'
+  }, async (ctx) => {
+    const client = await createClient(ctx);
+    const result = await client.graphql({
+      query: `query GetOrder($ref: String) {
+        order(ref: $ref) {
+          id
+          ref
+          status
+          totalPrice
+          customer {
+            firstName
+            lastName
+            username
+          }
+          items(first: 50) {
+            edges {
+              node {
+                ref
+                quantity
+                price
+                product {
+                  ref
+                  name
+                }
+              }
+            }
+          }
+        }
+      }`,
+      variables: { ref: ctx.data.orderId }
+    });
+
+    if (!result.data?.order) {
+      throw new Error(`Order not found: ${ctx.data.orderId}`);
+    }
+
+    return { order: result.data.order };
+  }))
+  // Step 3: Transform to XML format
+  .then(fn('build-xml', ({ data }) => {
+    const { order } = data;
+
+    // Initialize XML Builder
+    const builder = new XMLBuilder({
+      ignoreAttributes: false,
+      attributeNamePrefix: '@',
+      format: true,
+      indentBy: '  ',
+      suppressEmptyNode: true
+    });
+
+    // Build XML structure
+    const xmlObject = {
+      '?xml': {
+        '@version': '1.0',
+        '@encoding': 'UTF-8'
+      },
+      OrderResponse: {
+        '@xmlns': 'http://api.example.com/schema/order/1.0',
+        Order: {
+          OrderId: order.ref,
+          Status: order.status,
+          TotalPrice: {
+            '@currency': 'USD',
+            '#text': order.totalPrice
+          },
+          Customer: {
+            FirstName: order.customer.firstName,
+            LastName: order.customer.lastName,
+            Email: order.customer.username
+          },
+          Items: {
+            Item: order.items.edges.map(edge => ({
+              SKU: edge.node.product.ref,
+              ProductName: edge.node.product.name,
+              Quantity: edge.node.quantity,
+              Price: edge.node.price
+            }))
+          }
+        }
+      }
+    };
+
+    // Generate XML string
+    const xmlString = builder.build(xmlObject);
+
+    // Return XML string - onSuccess handler will wrap it
+    return xmlString;
+  }))
+  // Error handling - return XML error format
+  .catch(({ data }) => {
+    const errorMessage = data instanceof Error ? data.message : String(data);
+
+    // Return error XML string - onError handler will wrap it
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<OrderResponse xmlns="http://api.example.com/schema/order/1.0">
+  <Error>
+    <Code>PROCESSING_ERROR</Code>
+    <Message>${errorMessage}</Message>
+    <Timestamp>${new Date().toISOString()}</Timestamp>
+  </Error>
+</OrderResponse>`;
+  });
+```
+
+**Testing this endpoint:**
+
+```bash
+# Send XML request
+curl -X POST https://your-workspace.versori.run/order-xml \
+  -H "Content-Type: application/xml" \
+  -d '<?xml version="1.0"?>
+<OrderRequest>
+  <OrderId>ORD-12345</OrderId>
+</OrderRequest>'
+
+# Success Response (200 OK):
+<?xml version="1.0" encoding="UTF-8"?>
+<OrderResponse xmlns="http://api.example.com/schema/order/1.0">
+  <Order>
+    <OrderId>ORD-12345</OrderId>
+    <Status>COMPLETED</Status>
+    <TotalPrice currency="USD">199.99</TotalPrice>
+    ...
+  </Order>
+</OrderResponse>
+
+# Error Response (500 Internal Server Error):
+<?xml version="1.0" encoding="UTF-8"?>
+<OrderResponse xmlns="http://api.example.com/schema/order/1.0">
+  <Error>
+    <Code>PROCESSING_ERROR</Code>
+    <Message>Order not found: ORD-12345</Message>
+    <Timestamp>2025-01-15T10:30:00Z</Timestamp>
+  </Error>
+</OrderResponse>
+```
+
+### Example 3: HTML Response
+
+Return HTML pages from webhooks (useful for status pages, documentation):
+
+```typescript
+import { webhook, fn } from '@versori/run';
+
+export const statusPage = webhook('status', {
+  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">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Service Status</title>
+  <style>
+    body {
+      font-family: Arial, sans-serif;
+      max-width: 800px;
+      margin: 50px auto;
+      padding: 20px;
+    }
+    .status {
+      padding: 20px;
+      background-color: #4CAF50;
+      color: white;
+      border-radius: 5px;
+    }
+    .service {
+      margin: 10px 0;
+      padding: 10px;
+      border: 1px solid #ddd;
+      border-radius: 3px;
+    }
+  </style>
+</head>
+<body>
+  <h1>Service Status Dashboard</h1>
+  <div class="status">
+    <h2>✓ All Systems Operational</h2>
+  </div>
+  <div class="service">
+    <h3>Inventory Ingestion</h3>
+    <p>Status: <strong>Operational</strong></p>
+    <p>Last Run: ${new Date().toISOString()}</p>
+  </div>
+  <div class="service">
+    <h3>Order Processing</h3>
+    <p>Status: <strong>Operational</strong></p>
+  </div>
+</body>
+</html>`;
+  }));
+```
+
+### Example 4: CSV Response
+
+Download data as CSV files:
+
+```typescript
+import { webhook, fn, http } from '@versori/run';
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+export const exportInventory = webhook('export-inventory-csv', {
+  response: {
+    mode: 'sync',
+    onSuccess: (ctx) => new Response(ctx.data, {
+      status: 200,
+      headers: {
+        'Content-Type': 'text/csv; charset=utf-8',
+        'Content-Disposition': 'attachment; filename="inventory-export.csv"'
+      }
+    })
+  }
+})
+  .then(http('fetch-inventory', {
+    connection: 'fluent_commerce'
+  }, async (ctx) => {
+    const client = await createClient(ctx);
+    const result = await client.graphql({
+      query: `query {
+        inventoryQuantities(first: 100) {
+          edges {
+            node {
+              ref
+              quantity
+              location { ref }
+              product { ref name }
+            }
+          }
+        }
+      }`
+    });
+
+    return { items: result.data.inventoryQuantities.edges };
+  }))
+  .then(fn('build-csv', ({ data }) => {
+    // CSV Header
+    let csv = 'SKU,Product Name,Location,Quantity\n';
+
+    // CSV Rows
+    data.items.forEach(edge => {
+      const item = edge.node;
+      const sku = item.product?.ref || '';
+      const name = (item.product?.name || '').replace(/"/g, '""'); // Escape quotes
+      const location = item.location?.ref || '';
+      const qty = item.quantity || 0;
+
+      csv += `"${sku}","${name}","${location}",${qty}\n`;
+    });
+
+    return csv;
+  }));
+```
+
+### Example 5: Plain Text Response
+
+Health check or simple text endpoints:
+
+```typescript
+import { webhook, fn } from '@versori/run';
+
+export const healthCheck = webhook('health', {
+  response: {
+    mode: 'sync',
+    onSuccess: (ctx) => new Response(ctx.data, {
+      status: 200,
+      headers: { 'Content-Type': 'text/plain; charset=utf-8' }
+    })
+  }
+})
+  .then(fn('check-health', () => {
+    const uptime = process.uptime();
+    const timestamp = new Date().toISOString();
+
+    return `Service Status: Operational
+Uptime: ${uptime.toFixed(0)} seconds
+Timestamp: ${timestamp}
+  }));
+```
+
+## Key Patterns Explained
+
+### Pattern 1: Why Custom Response Objects Are Needed
+
+**The Technical Details:**
+
+Versori's `sendResponse()` function (from @versori/run v0.4.4):
+
+```typescript
+function sendResponse(res, response) {
+  res.status(response.status);
+  response.headers.forEach((value, key) => {
+    res.setHeader(key, value);
+  });
+  if (response.body) {
+    pipeline(response.body, res);  // Streams directly without encoding
+  }
+}
+```
+
+**Key insight:** When you return a `Response` object, Versori uses Node.js `pipeline()` to stream the body directly to the HTTP response **without any JSON encoding**.
+
+**Default handlers** (when you don't provide custom ones):
+
+```typescript
+// Simplified version of default behavior
+const defaultOnSuccess = (ctx) => {
+  return JSON.stringify(ctx.data);  // ❌ Encodes everything as JSON
+};
+```
+
+### Pattern 2: onSuccess Handler Pattern
+
+The `onSuccess` handler receives context and must return a `Response` object:
+
+```typescript
+onSuccess: (ctx) => {
+  // ctx.data = output from final .then() step
+  // ctx.executionId = unique execution ID
+  // ctx.metadata = any metadata from workflow
+
+  return new Response(ctx.data, {
+    status: 200,  // HTTP status code
+    headers: {
+      'Content-Type': 'application/xml; charset=utf-8',
+      'X-Execution-Id': ctx.executionId,
+      'Cache-Control': 'no-cache',
+      // Any custom headers...
+    }
+  });
+}
+```
+
+**Important:** Your workflow steps should return **raw strings**, not Response objects. The handler wraps them.
+
+### Pattern 3: onError Handler Pattern
+
+The `onError` handler handles exceptions and should match the content type:
+
+```typescript
+onError: (ctx) => {
+  // ctx.data = error from .catch() or thrown exception
+  // ctx.executionId = unique execution ID
+
+  return new Response(ctx.data, {
+    status: 500,  // or 400, 404, etc.
+    headers: {
+      'Content-Type': 'application/xml; charset=utf-8',  // Match success type!
+      'X-Execution-Id': ctx.executionId
+    }
+  });
+}
+```
+
+**Best practice:** Use the same Content-Type for errors as for success responses. If your API returns XML on success, return XML errors too.
+
+### Pattern 4: Content-Type Headers
+
+Always include charset for text-based formats:
+
+```typescript
+// ✅ CORRECT - Includes charset
+'Content-Type': 'application/xml; charset=utf-8'
+'Content-Type': 'text/html; charset=utf-8'
+'Content-Type': 'text/csv; charset=utf-8'
+'Content-Type': 'text/plain; charset=utf-8'
+
+// ❌ INCOMPLETE - Missing charset (may work but not recommended)
+'Content-Type': 'application/xml'
+
+// ✅ CORRECT - Binary formats don't need charset
+'Content-Type': 'application/pdf'
+'Content-Type': 'image/png'
+```
+
+### Pattern 5: XMLBuilder Integration
+
+Using `fast-xml-parser` to generate clean XML:
+
+```typescript
+import { XMLBuilder } from 'fast-xml-parser';
+
+// Initialize builder with options
+const builder = new XMLBuilder({
+  ignoreAttributes: false,      // Include XML attributes
+  attributeNamePrefix: '@',      // Prefix for attributes
+  textNodeName: '#text',         // Key for text content
+  format: true,                  // Pretty-print
+  indentBy: '  ',                // Indentation
+  suppressEmptyNode: true        // Don't output <tag></tag> for nulls
+});
+
+// Define XML structure
+const xmlObject = {
+  '?xml': {                      // XML declaration
+    '@version': '1.0',
+    '@encoding': 'UTF-8'
+  },
+  Root: {
+    '@xmlns': 'http://...',      // Root attributes start with @
+    Child: 'value',
+    Another: {
+      '@id': '123',              // Element with attribute and text
+      '#text': 'content'
+    },
+    List: {
+      Item: ['item1', 'item2']   // Arrays become multiple elements
+    }
+  }
+};
+
+// Generate XML string
+const xmlString = builder.build(xmlObject);
+```
+
+**Generated Output:**
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<Root xmlns="http://...">
+  <Child>value</Child>
+  <Another id="123">content</Another>
+  <List>
+    <Item>item1</Item>
+    <Item>item2</Item>
+  </List>
+</Root>
+```
+
+## The JSON Encoding Problem
+
+### Side-by-Side Comparison
+
+#### ❌ WRONG: Default Behavior (JSON-Encoded)
+
+```typescript
+export const badXmlEndpoint = webhook('bad-xml', async (ctx) => {
+  return '<?xml version="1.0"?><order><id>123</id></order>';
+});
+```
+
+**What the client receives:**
+
+```bash
+$ curl https://workspace.versori.run/bad-xml
+
+# Response:
+"<?xml version=\"1.0\"?><order><id>123</id></order>"
+
+# Response Headers:
+Content-Type: application/json
+Content-Length: 52
+```
+
+**Problems:**
+
+1. XML is wrapped in quotes
+2. Special characters are escaped (`\n`, `\"`)
+3. Content-Type is JSON, not XML
+4. Cannot be parsed as XML by clients
+5. Requires client-side JSON parsing then XML parsing
+
+#### ✅ RIGHT: Custom Response Objects
+
+```typescript
+export const goodXmlEndpoint = webhook('good-xml', {
+  response: {
+    mode: 'sync',
+    onSuccess: (ctx) => new Response(ctx.data, {
+      status: 200,
+      headers: { 'Content-Type': 'application/xml; charset=utf-8' }
+    })
+  }
+})
+  .then(fn('gen', () => '<?xml version="1.0"?><order><id>123</id></order>'));
+```
+
+**What the client receives:**
+
+```bash
+$ curl https://workspace.versori.run/good-xml
+
+# Response:
+<?xml version="1.0"?><order><id>123</id></order>
+
+# Response Headers:
+Content-Type: application/xml; charset=utf-8
+Content-Length: 47
+```
+
+**Benefits:**
+
+1. Raw XML delivered to client
+2. No escaping or encoding
+3. Correct Content-Type header
+4. Client can parse directly as XML
+5. Standard HTTP semantics
+
+### Visual Example: What Gets Sent
+
+**Bad (JSON-encoded):**
+
+```
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+"<?xml version=\"1.0\"?><order><id>123</id></order>"
+```
+
+**Good (Raw XML):**
+
+```
+HTTP/1.1 200 OK
+Content-Type: application/xml; charset=utf-8
+
+<?xml version="1.0"?><order><id>123</id></order>
+```
+
+## Common Issues and Solutions
+
+### Issue 1: XML Still Being JSON-Encoded
+
+**Symptom:** Response is wrapped in quotes with escaped characters.
+
+**Cause:** Missing custom response handlers.
+
+**Solution:**
+
+```typescript
+// ❌ Missing handlers
+export const endpoint = webhook('test')
+  .then(fn('gen', () => '<xml>data</xml>'));
+
+// ✅ Add custom handlers
+export const endpoint = webhook('test', {
+  response: {
+    mode: 'sync',
+    onSuccess: (ctx) => new Response(ctx.data, {
+      status: 200,
+      headers: { 'Content-Type': 'application/xml; charset=utf-8' }
+    })
+  }
+})
+  .then(fn('gen', () => '<xml>data</xml>'));
+```
+
+### Issue 2: Wrong Content-Type in Response
+
+**Symptom:** Browser tries to download file or displays incorrectly.
+
+**Cause:** Content-Type doesn't match actual content.
+
+**Solution:**
+
+```typescript
+// ❌ WRONG - XML with JSON content type
+headers: { 'Content-Type': 'application/json' }
+
+// ✅ RIGHT - Match content type to content
+headers: { 'Content-Type': 'application/xml; charset=utf-8' }
+```
+
+**Content-Type Reference:**
+
+- XML: `application/xml; charset=utf-8`
+- HTML: `text/html; charset=utf-8`
+- CSV: `text/csv; charset=utf-8`
+- Plain text: `text/plain; charset=utf-8`
+- JSON: `application/json` (default, no custom handler needed)
+
+### Issue 3: Error Responses Return JSON Instead of XML
+
+**Symptom:** Success returns XML, but errors return JSON.
+
+**Cause:** Missing `onError` handler.
+
+**Solution:**
+
+```typescript
+export const endpoint = webhook('test', {
+  response: {
+    mode: 'sync',
+    onSuccess: (ctx) => new Response(ctx.data, {
+      status: 200,
+      headers: { 'Content-Type': 'application/xml; charset=utf-8' }
+    }),
+    // ✅ Add error handler with same content type
+    onError: (ctx) => new Response(ctx.data, {
+      status: 500,
+      headers: { 'Content-Type': 'application/xml; charset=utf-8' }
+    })
+  }
+})
+  .then(fn('gen', () => '<success/>'))
+  .catch(() => '<error/>');  // Make sure .catch() returns XML string
+```
+
+### Issue 4: Accidental Double-Encoding
+
+**Symptom:** Response has extra quotes or escaped characters.
+
+**Cause:** Calling `JSON.stringify()` on data before returning.
+
+**Solution:**
+
+```typescript
+// ❌ WRONG - Don't stringify in handler
+onSuccess: (ctx) => new Response(JSON.stringify(ctx.data), {
+  status: 200,
+  headers: { 'Content-Type': 'application/xml; charset=utf-8' }
+})
+
+// ✅ RIGHT - Pass raw data
+onSuccess: (ctx) => new Response(ctx.data, {
+  status: 200,
+  headers: { 'Content-Type': 'application/xml; charset=utf-8' }
+})
+```
+
+## Testing Your Implementation
+
+### Test 1: Verify Content-Type Header
+
+```bash
+# Check response headers
+curl -v https://your-workspace.versori.run/your-endpoint
+
+# Look for:
+# ✅ Content-Type: application/xml; charset=utf-8
+# ❌ Content-Type: application/json
+```
+
+### Test 2: Verify Raw Content
+
+```bash
+# Get response body
+curl https://your-workspace.versori.run/your-endpoint
+
+# Expected (raw XML):
+# <?xml version="1.0" encoding="UTF-8"?>
+# <order><id>123</id></order>
+
+# NOT expected (JSON-encoded):
+# "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<order><id>123</id></order>"
+```
+
+### Test 3: Verify Error Handling
+
+```bash
+# Trigger an error (send invalid request)
+curl -X POST https://your-workspace.versori.run/your-endpoint \
+  -H "Content-Type: application/xml" \
+  -d '<?xml version="1.0"?><Invalid/>'
+
+# Should return:
+# - Status: 500 (or appropriate error code)
+# - Content-Type: application/xml (same as success)
+# - Body: XML error message
+```
+
+### Test 4: XML Parser Validation
+
+```bash
+# Pipe response through xmllint to validate XML
+curl https://your-workspace.versori.run/your-endpoint | xmllint --format -
+
+# Should format successfully without errors
+```
+
+## Implementation Checklist
+
+When implementing non-JSON webhooks, verify:
+
+- [ ] Webhook configured with `response.mode: 'sync'`
+- [ ] `onSuccess` handler defined and returns `Response` object
+- [ ] `onError` handler defined and returns `Response` object
+- [ ] Both handlers set correct `Content-Type` header
+- [ ] Content-Type includes `charset=utf-8` for text formats
+- [ ] Workflow `.then()` steps return raw strings (not Response objects)
+- [ ] Workflow `.catch()` returns error string in correct format
+- [ ] Status codes are appropriate (200, 400, 500, etc.)
+- [ ] Error handler uses same Content-Type as success handler
+- [ ] Tested with curl to verify raw output (no JSON encoding)
+- [ ] Tested error scenarios return proper format
+- [ ] No `JSON.stringify()` calls in custom handlers
+- [ ] XML validated with parser (if XML response)
+
+
+## Versori Syntax Validation
+
+### Critical: Buffer Import Required
+
+**For Deno/Versori runtime, ALWAYS import Buffer explicitly:**
+
+```typescript
+// ✅ CORRECT - Explicit import required
+import { Buffer } from 'node:buffer';
+
+// Use Buffer for encoding operations
+await sftp.uploadFile('utf8', Buffer.from(xmlContent), '/path/file.xml');
+const decoded = Buffer.from(base64String, 'base64').toString('utf-8');
+```
+
+**Why:** Deno runtime doesn't have `Buffer` as a global (unlike Node.js). Missing this import will cause runtime errors.
+
+### Validated Syntax Patterns for SDK ^0.1.27
+
+#### 1. Webhook Response Configuration
+
+```typescript
+// ✅ CORRECT - Webhook with custom response handlers
+export const endpoint = webhook('name', {
+  response: {
+    mode: 'sync',  // Required for custom handlers
+    onSuccess: (ctx) => new Response(ctx.data, {
+      status: 200,
+      headers: { 'Content-Type': 'application/xml; charset=utf-8' }
+    }),
+    onError: (ctx) => new Response(ctx.data, {
+      status: 500,
+      headers: { 'Content-Type': 'application/xml; charset=utf-8' }
+    })
+  },
+  cors: true  // Optional CORS configuration
+})
+  .then(fn('step', () => '<xml/>'));
+
+// ❌ WRONG - Missing response configuration
+export const endpoint = webhook('name', async (ctx) => {
+  return '<xml/>';  // Will be JSON-encoded!
+});
+```
+
+#### 2. Client Factory Usage
+
+```typescript
+// ✅ CORRECT - Use createClient() factory
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+export const endpoint = webhook('name', {
+  connection: 'fluent_commerce'
+}, async (ctx) => {
+  const client = await createClient(ctx);
+  // Client automatically configured from connection
+});
+
+// ❌ WRONG - Direct instantiation bypasses context detection
+import { FluentClient } from '@fluentcommerce/fc-connect-sdk';
+const client = new FluentClient(config);  // Don't do this in Versori
+```
+
+#### 3. Logging Best Practices
+
+```typescript
+// ✅ CORRECT - Use native log from context
+export const endpoint = webhook('name', {
+  connection: 'fluent_commerce'
+}, async (ctx) => {
+  const { log } = ctx;
+  log('Processing started', { orderId: '123' });
+
+  // SDK client receives log automatically
+  const client = await createClient(ctx);
+});
+
+// ❌ WRONG - Don't use LoggingService in Versori
+import { LoggingService } from '@fluentcommerce/fc-connect-sdk';
+const logger = new LoggingService();  // Not needed in Versori
+```
+
+#### 4. Auto-Pagination Syntax
+
+```typescript
+// ✅ CORRECT - pagination object (NOT config)
+const result = await client.graphql({
+  query,
+  variables: { first: 100 },
+  pagination: {  // Use 'pagination', not 'config'
+    maxPages: 50,
+    pageSize: 100
+  }
+});
+
+// ❌ WRONG - Old syntax with 'config'
+const result = await client.graphql({
+  query,
+  variables: { first: 100 },
+  config: {  // Use 'pagination' parameter instead
+    maxPages: 50
+  }
+});
+```
+
+#### 5. SDK Version Specification
+
+```json
+{
+  "dependencies": {
+    "@fluentcommerce/fc-connect-sdk": "^0.1.39",
+    "@versori/run": "latest",
+    "fast-xml-parser": "^4.3.0"
+  }
+}
+```
+
+#### 6. Workflow Step Return Values
+
+```typescript
+// ✅ CORRECT - Return raw data, let handlers wrap it
+export const endpoint = webhook('name', {
+  response: {
+    mode: 'sync',
+    onSuccess: (ctx) => new Response(ctx.data, {
+      status: 200,
+      headers: { 'Content-Type': 'application/xml; charset=utf-8' }
+    })
+  }
+})
+  .then(fn('generate', () => {
+    return '<xml>data</xml>';  // Return raw string
+  }));
+
+// ❌ WRONG - Don't return Response objects from workflow steps
+export const endpoint = webhook('name', {
+  response: { mode: 'sync', onSuccess: (ctx) => ctx.data }
+})
+  .then(fn('generate', () => {
+    return new Response('<xml>data</xml>');  // Wrong! Handler should do this
+  }));
+```
+
+#### 7. Error Handling Pattern
+
+```typescript
+// ✅ CORRECT - .catch() returns error data, onError wraps it
+export const endpoint = webhook('name', {
+  response: {
+    mode: 'sync',
+    onSuccess: (ctx) => new Response(ctx.data, {
+      status: 200,
+      headers: { 'Content-Type': 'application/xml; charset=utf-8' }
+    }),
+    onError: (ctx) => new Response(ctx.data, {
+      status: 500,
+      headers: { 'Content-Type': 'application/xml; charset=utf-8' }
+    })
+  }
+})
+  .then(fn('process', () => '<success/>'))
+  .catch((error) => {
+    // Return error XML string - onError handler will wrap it
+    return `<error>${error.message}</error>`;
+  });
+
+// ❌ WRONG - Throwing without catch or returning Response
+export const endpoint = webhook('name')
+  .then(fn('process', () => {
+    throw new Error('Failed');  // Will cause 500 with JSON error
+  }));
+```
+
+### Validation Checklist
+
+Before deploying to Versori, verify:
+
+**Syntax:**
+- [ ] Buffer explicitly imported: `import { Buffer } from 'node:buffer';`
+- [ ] webhook() has response.mode: 'sync' for custom handlers
+- [ ] onSuccess and onError both defined
+- [ ] Both handlers return Response objects
+- [ ] Workflow steps return raw data (not Response objects)
+
+**SDK Integration:**
+- [ ] createClient() used (not direct instantiation)
+- [ ] Native ctx.log used (not LoggingService)
+- [ ] Auto-pagination uses 'pagination' object (not 'config')
+- [ ] SDK version is ^0.1.27 or later
+
+**Response Handling:**
+- [ ] Content-Type headers match actual content
+- [ ] charset=utf-8 included for text formats
+- [ ] onError uses same Content-Type as onSuccess
+- [ ] Error .catch() returns proper format string
+
+**Testing:**
+- [ ] Tested with curl to verify raw output
+- [ ] Verified Content-Type header is correct
+- [ ] Tested error scenarios return proper format
+- [ ] Validated XML with parser (if XML)
+
+## Version Compatibility
+
+This pattern works with:
+
+**Versori Runtime:**
+- @versori/run v0.4.4 (latest stable)
+- @versori/run v0.4.3
+- @versori/run v0.4.2
+- @versori/run v0.4.1
+- @versori/run v0.4.0
+- @versori/run v0.4.0-alpha.2
+
+All v0.4.x versions use the same `sendResponse()` implementation that streams Response objects directly.
+
+**FC Connect SDK:**
+- @fluentcommerce/fc-connect-sdk v0.1.27+
+- @fluentcommerce/fc-connect-sdk v0.1.26
+- @fluentcommerce/fc-connect-sdk v0.1.25
+- All v0.1.x versions support Versori platform integration
+
+## Related Guides
+
+- **[Versori Platform Integration](../../../04-REFERENCE/platforms/versori/)** - Complete Versori platform guide
+- **[GraphQL Mutation Mapping Guide](../../../02-CORE-GUIDES/mapping/graphql-mutation-mapping/)** - XML/JSON to GraphQL mutations
+- **[Universal Mapping Guide](../../../02-CORE-GUIDES/mapping/)** - Field transformation patterns
+- **[Webhook Validation Guide](../../../02-CORE-GUIDES/webhook-validation/)** - Webhook signature validation
+
+## Real-World Example Reference
+
+See complete production implementation:
+
+- **File**: `Sandbox Hibbet SFCC to Fluent Order integration (1)/src/workflows/process-order-detail-request.ts`
+- **Pattern**: XML request → GraphQL query → XML response
+- **Features**: Full error handling, extraction mapping, XMLBuilder integration
+
+## Summary
+
+**Golden Rule:** For non-JSON content types in Versori webhooks, **ALWAYS** use custom `onSuccess` and `onError` handlers that return `Response` objects with the correct Content-Type header.
+
+**Why It Matters:**
+
+- Default handlers JSON-encode all responses (breaks XML/HTML/CSV)
+- Custom handlers bypass encoding and stream content directly
+- Proper Content-Type headers ensure correct client behavior
+- Consistent error handling provides better API experience
+
+**Impact:** This pattern saves hours of debugging and ensures proper content delivery for XML APIs, HTML pages, CSV exports, and other non-JSON formats. It's critical for SOAP integrations, enterprise systems, and file downloads.