@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/01-TEMPLATES/versori/workflows/ingestion/event-api/template-ingestion-payload-xml-order-cancel-event.md

@@ -1,1170 +1,1170 @@
----
-template_id: tpl-ingest-payload-xml-to-order-cancel-event
-canonical_filename: template-ingestion-payload-xml-order-cancel-event.md
-sdk_version: latest
-runtime: versori
-direction: ingestion
-source: payload-xml
-destination: fluent-event-api
-entity: order
-format: xml
-logging: versori
-status: stable
-features:
-  - direct-payload-processing
-  - xml-parsing
-  - event-api-integration
-  - error-handling
----
-
-# Template: Ingestion - Payload XML to Order Cancel Event
-
-**SDK Version:** @fluentcommerce/fc-connect-sdk@latest
-**Last Updated:** 2025-01-24
-**Deployment Target:** Versori Platform
-
----
-
-## 📋 Implementation Prompt
-
-```
-I need a Versori webhook ingestion that:
-
-1) Receives XML payload directly in webhook request body
-2) Parses XML to extract order reference (handles Versori $ format for attributes)
-3) Builds OrderCancel event payload with retailerId, name, entityRef, entityType
-4) Sends event to Fluent Commerce Event API (async)
-5) Returns success/error response
-6) Uses native Versori log from context
-
-Use the loaded docs to fill in SDK specifics and best practices.
-Keep the structure identical to the template; only adapt where needed.
-```
-
----
-
-## 📋 Template Overview
-
-This connector runs on the Versori platform. It receives XML payloads directly via webhook, extracts the order reference, and sends OrderCancel events to Fluent Commerce Event API. Most operational settings (Fluent account/connection) are configured via activation variables.
-
-### What This Template Does
-
-```
-┌────────────────────────────────────────────────────────────────┐
-│          INGESTION WORKFLOW              │
-└────────────────────────────────────────────────────────────────┘
-
-1. TRIGGER
-  └─ Webhook: HTTP POST endpoint receives XML payload
-
-2. RECEIVE PAYLOAD
-  ├─ Extract XML from request body (ctx.data or ctx.request)
-  ├─ Validate payload structure
-  └─ Log incoming request
-
-3. PARSE XML
-  ├─ Parse XML payload (Versori auto-parses with $ format)
-  ├─ Extract order reference (handles $ for attributes, _ for text)
-  └─ Validate required fields
-
-4. BUILD EVENT
-  ├─ Construct OrderCancel event payload
-  ├─ Set retailerId (from config or payload)
-  ├─ Set name: "OrderCancel"
-  ├─ Set entityRef: order reference
-  └─ Set entityType: "ORDER"
-
-5. SEND EVENT (Event API)
-  ├─ Send event to Fluent Commerce Event API (async)
-  ├─ Handle success/error responses
-  └─ Log event result
-
-6. RETURN RESPONSE
-  ├─ Return success with event details
-  └─ Return error with details if failed
-```
-
-### Key Features
-
-- **Direct Payload Processing**: Receives XML payload directly in webhook request body
-- **XML Parsing**: Handles Versori auto-parsed XML format ($ for attributes, _ for text)
-- **Event API Integration**: Sends OrderCancel events to Fluent Commerce
-- **Error Handling**: Comprehensive error handling with detailed logging
-- **Native Versori Logging**: Uses Versori log from context
-- **Flexible Order Reference Extraction**: Supports multiple XML element patterns
-
-### 📦 Package Information
-
-**SDK:** [@fluentcommerce/fc-connect-sdk](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk) `latest`
-
-```bash
-npm install @fluentcommerce/fc-connect-sdk@latest
-```
-
----
-
-**Templates are designed for direct deployment; customize via activation variables.**
-
----
-
-## 📦 SDK Imports (Verified - Versori Optimized)
-
-```typescript
-// ✅ VERIFIED IMPORTS - These match actual SDK exports
-import { Buffer } from 'node:buffer'; // Required for Versori/Deno runtime
-import {
-  createClient, // Universal client factory
-  XMLParserService, // XML parsing utility
-} from '@fluentcommerce/fc-connect-sdk';
-
-import type { FluentClient } from '@fluentcommerce/fc-connect-sdk';
-
-// Versori platform imports
-import { webhook, http } from '@versori/run';
-```
-
-**Note:** All imports are from actual SDK exports - this code compiles and runs as-is.
-
-**⚠️ CRITICAL - Buffer Import Required:**
-
-The `Buffer` import from `node:buffer` is **required** for Versori/Deno runtime compatibility:
-- Versori and Deno do NOT have `Buffer` as a global (unlike Node.js)
-- Without this import, code will crash with `ReferenceError: Buffer is not defined`
-- Always include this import in Versori templates, even if not directly used in the template code
-- Required for SDK internal operations and any Buffer usage in your code
-
-**✅ VERSORI PLATFORM - Use Native Logs:**
-
-- Use `log` from context: `const { log } = ctx;`
-- Native Versori logs are simpler and automatically integrated with platform monitoring
-
-**✅ VERSORI XML PARSING:**
-
-Versori automatically parses XML payloads when `Content-Type: application/xml` is set:
-- Attributes accessed via `$` (e.g., `element.$?.attributeName`)
-- Text content accessed via `_` (e.g., `element._`)
-- Nested elements accessed directly (e.g., `element.childElement`)
-
----
-
-## 🔐 Fluent Commerce Connection Setup
-
-**✅ BEST PRACTICE:** Store Fluent Commerce credentials in a Versori connection object:
-
-**Connection Configuration:**
-
-1. **Create Connection in Versori:**
-   - Name: `fluent_commerce`
-   - Type: HTTP Basic Auth or OAuth2
-   - Credentials: Fluent Commerce API credentials
-
-2. **Connection Variables:**
-   - `FLUENT_BASE_URL` - Fluent Commerce API base URL (e.g., `https://api.fluentcommerce.com`)
-   - `FLUENT_RETAILER_ID` - Your retailer ID
-   - `FLUENT_CLIENT_ID` - OAuth client ID (if using OAuth2)
-   - `FLUENT_CLIENT_SECRET` - OAuth client secret (if using OAuth2)
-
-**Benefits:**
-- ✅ Credentials stored securely in Versori vault
-- ✅ Connection can be reused across workflows
-- ✅ No sensitive data in activation variables
-- ✅ Easier credential rotation
-
----
-
-## 📄 Expected XML Payload Format
-
-The webhook accepts XML payloads with order reference information. Multiple formats are supported:
-
-### Format 1: Simple Order Reference
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<orderCancel>
-  <orderRef>ORD-12345</orderRef>
-</orderCancel>
-```
-
-### Format 2: With Attributes
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<orderCancel>
-  <order ref="ORD-12345"/>
-</orderCancel>
-```
-
-### Format 3: Nested Structure
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<orderCancel>
-  <order>
-    <reference>ORD-12345</reference>
-    <reason>Customer requested cancellation</reason>
-  </order>
-</orderCancel>
-```
-
-### Format 4: Root Element with Attributes
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<orderCancel orderRef="ORD-12345">
-  <reason>Customer requested cancellation</reason>
-</orderCancel>
-```
-
-**Note:** The template extracts order reference from various XML patterns. Customize the extraction logic in the service if your payload uses different element names.
-
-**Versori XML Parsing Format (CRITICAL):**
-
-When Versori receives XML with `Content-Type: application/xml`, it **automatically parses** the XML into a JavaScript object. You do NOT need to manually parse XML - Versori handles it automatically.
-
-**Access Patterns:**
-- **Attributes**: `element.$?.attributeName` (e.g., `<order ref="ORD-12345"/>` → `order.$?.ref`)
-- **Text content**: `element._` or direct property access (e.g., `<orderRef>ORD-12345</orderRef>` → `orderRef._` or `orderRef`)
-- **Nested elements**: Direct property access (e.g., `<orderCancel><orderRef>...</orderRef></orderCancel>` → `orderCancel.orderRef`)
-
-**Examples:**
-
-```typescript
-// XML: <order ref="ORD-12345"/>
-// Versori auto-parsed: { order: { $: { ref: "ORD-12345" } } }
-const orderRef = parsed.order?.$?.ref; // ✅ "ORD-12345"
-
-// XML: <orderRef>ORD-12345</orderRef>
-// Versori auto-parsed: { orderRef: { _: "ORD-12345" } } OR { orderRef: "ORD-12345" }
-const orderRef = parsed.orderRef?._ || parsed.orderRef; // ✅ "ORD-12345"
-
-// XML: <orderCancel><order ref="ORD-12345"/></orderCancel>
-// Versori auto-parsed: { orderCancel: { order: { $: { ref: "ORD-12345" } } } }
-const orderRef = parsed.orderCancel?.order?.$?.ref; // ✅ "ORD-12345"
-```
-
-**Key Point:** Versori automatically parses XML when `Content-Type: application/xml` is set. Your webhook receives `ctx.data` as a pre-parsed JavaScript object - no manual XML parsing needed!
-
----
-
-## Event Payload Structure
-
-The template builds and sends this event structure:
-
-```json
-{
-  "retailerId": "{{retailer_id}}",
-  "name": "OrderCancel",
-  "entityRef": "{{order_ref}}",
-  "entityType": "ORDER"
-}
-```
-
-**Fields:**
-- `retailerId`: Retrieved from Fluent Commerce connection or activation variable
-- `name`: Fixed as "OrderCancel"
-- `entityRef`: Extracted from incoming XML payload
-- `entityType`: Fixed as "ORDER"
-
----
-
-## 🔧 Complete Production Code
-
-### 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
-
-**Execution Steps (chained to triggers):**
-- **`http()`** → External API calls (chained from webhook)
-
-### Recommended Project Structure
-
-```
-order-cancel-webhook/
-├── index.ts                              # Entry point - exports all workflows
-└── src/
-    ├── workflows/
-    │   └── webhook/
-    │       └── order-cancel.ts           # Webhook: Order cancel handler
-    │
-    ├── services/
-    │   └── order-cancel.service.ts       # Shared orchestration logic
-    │
-    └── types/
-        └── order-cancel.types.ts         # Type definitions
-```
-
-**Benefits:**
-- ✅ Clear structure (webhook handlers in `webhook/`)
-- ✅ Descriptive file names (easy to browse and understand)
-- ✅ Reusable code in `services/` (DRY principle)
-- ✅ Centralized type definitions
-
----
-
-## Workflow Files
-
-### 1. Webhook Workflow (`src/workflows/webhook/order-cancel.ts`)
-
-**Purpose**: Handle order cancel requests via webhook
-**Trigger**: HTTP POST
-**Endpoint**: `POST https://{workspace}.versori.run/order-cancel`
-**Use Cases**: Order cancellation from external systems, manual cancellations
-
-```typescript
-import { webhook, http } from '@versori/run';
-import { executeOrderCancel } from '../../services/order-cancel.service';
-
-/**
- * Webhook: Order Cancel Handler
- *
- * Endpoint: POST https://{workspace}.versori.run/order-cancel
- * Request body: XML payload with order reference
- * Content-Type: application/xml
- *
- * Pattern: webhook().then(http()) - needs Fluent API access
- * Uses shared service: order-cancel.service.ts
- *
- * SECURITY: Authentication handled via connection parameter
- * No manual API key validation needed - Versori manages this via connection auth
- */
-export const orderCancelWebhook = webhook('order-cancel', {
-  // ✅ Webhook response mode: 'sync'
-  //    - HTTP response sent when handler completes
-  //    - Returns event ID and success status immediately after Fluent accepts event
-  //    - Alternative: 'async' mode would return immediately (before processing)
-  response: { mode: 'sync' },
-  connection: 'order-cancel-webhook', // Versori validates API key
-}).then(
-  http('process-order-cancel', { connection: 'fluent_commerce' }, async ctx => {
-    const { log, data } = ctx;
-
-    log.info('🚀 [WEBHOOK] Order cancel request received', {
-      timestamp: new Date().toISOString(),
-      hasPayload: !!data,
-      contentType: ctx.request?.headers?.get('content-type'),
-    });
-
-    try {
-      // Reuse shared orchestration logic
-      const result = await executeOrderCancel(ctx);
-
-      log.info('✅ [WEBHOOK] Order cancel completed successfully', {
-        orderRef: result.orderRef,
-        eventId: result.eventId,
-      });
-
-      return {
-        success: true,
-        orderRef: result.orderRef,
-        eventId: result.eventId,
-        message: 'Order cancel event sent successfully',
-      };
-    } catch (e: any) {
-      log.error('❌ [WEBHOOK] Order cancel failed', {
-        message: e?.message,
-        stack: e?.stack,
-      });
-
-      return {
-        success: false,
-        error: e?.message || 'Unknown error occurred',
-      };
-    }
-  })
-);
-```
-
----
-
-### 2. Entry Point (`index.ts`)
-
-**Purpose**: Register all workflows with Versori platform
-
-```typescript
-/**
- * Entry Point - Registers all workflows with Versori platform
- *
- * Versori automatically discovers and registers exported workflows
- *
- * File Structure:
- * - src/workflows/webhook/   → HTTP-based triggers (webhooks)
- * - src/services/            → Shared service logic (reusable across workflows)
- */
-
-// Import webhook workflows
-import { orderCancelWebhook } from './src/workflows/webhook/order-cancel';
-
-// Register all workflows with Versori platform
-export {
-  // Webhooks (HTTP-based triggers)
-  orderCancelWebhook,
-};
-```
-
-**What Gets Exposed:**
-- ✅ `orderCancelWebhook` → `https://{workspace}.versori.run/order-cancel`
-
----
-
-## 3. Type Definitions (`src/types/order-cancel.types.ts`)
-
-```typescript
-/**
- * Type Definitions for Order Cancel Ingestion
- *
- * Centralized type definitions for order cancel workflow
- */
-
-/**
- * Versori XML parsed format
- * Attributes accessed via $, text content via _
- */
-export interface VersoriXMLParsed {
-  [key: string]: unknown;
-  $?: Record<string, unknown>; // Attributes
-  _?: string; // Text content
-}
-
-/**
- * Order cancel request payload (XML parsed format)
- */
-export interface OrderCancelPayload {
-  orderCancel?: {
-    orderRef?: VersoriXMLParsed | string;
-    order?: {
-      $?: {
-        ref?: string;
-      };
-      reference?: VersoriXMLParsed | string;
-      ref?: VersoriXMLParsed | string;
-    };
-    $?: {
-      orderRef?: string;
-    };
-  };
-  order?: {
-    $?: {
-      ref?: string;
-    };
-    reference?: VersoriXMLParsed | string;
-    ref?: VersoriXMLParsed | string;
-  };
-  [key: string]: unknown; // Allow additional fields
-}
-
-/**
- * Order cancel event payload
- */
-export interface OrderCancelEvent {
-  retailerId: string;
-  name: 'OrderCancel';
-  entityRef: string;
-  entityType: 'ORDER';
-}
-
-/**
- * Order cancel result
- */
-export interface OrderCancelResult {
-  success: boolean;
-  orderRef: string;
-  eventId?: string;
-  error?: string;
-}
-
-/**
- * Versori Context Interface
- * Represents the Versori runtime context passed to workflow functions
- */
-export interface VersoriContext {
-  log: {
-    info: (message: string, data?: Record<string, unknown>) => void;
-    warn: (message: string, data?: Record<string, unknown>) => void;
-    error: (message: string, data?: Record<string, unknown>) => void;
-    debug?: (message: string, data?: Record<string, unknown>) => void;
-  };
-  data?: unknown;
-  request?: Request;
-  activation: {
-    getVariable: (name: string) => string | undefined;
-    connections?: Record<string, unknown>;
-  };
-  connections?: Record<string, unknown>;
-}
-```
-
----
-
-## 4. Service: Order Cancel Processor (`src/services/order-cancel.service.ts`)
-
-```typescript
-/**
- * Order Cancel Service
- *
- * Processes order cancel requests: extracts order reference from XML payload,
- * builds OrderCancel event, and sends to Fluent Commerce Event API.
- * Handles Versori XML parsing format ($ for attributes, _ for text).
- */
-
-import {
-  createClient,
-  XMLParserService,
-} from '@fluentcommerce/fc-connect-sdk';
-import type { FluentClient } from '@fluentcommerce/fc-connect-sdk';
-import type {
-  OrderCancelPayload,
-  OrderCancelResult,
-  VersoriContext,
-  VersoriXMLParsed,
-} from '../types/order-cancel.types';
-
-/**
- * Extract text content from Versori XML parsed format
- * Handles both object format ({ _: "text" }) and direct string
- */
-function extractTextContent(value: VersoriXMLParsed | string | undefined): string | null {
-  if (!value) {
-    return null;
-  }
-
-  if (typeof value === 'string') {
-    return value;
-  }
-
-  if (typeof value === 'object' && '_' in value) {
-    const text = value._;
-    return typeof text === 'string' ? text : null;
-  }
-
-  return null;
-}
-
-/**
- * Extract order reference from XML payload
- *
- * Supports multiple XML formats:
- * - <orderCancel><orderRef>ORD-12345</orderRef></orderCancel>
- * - <orderCancel><order ref="ORD-12345"/></orderCancel>
- * - <orderCancel><order><reference>ORD-12345</reference></order></orderCancel>
- * - <orderCancel orderRef="ORD-12345"/>
- */
-function extractOrderRef(payload: OrderCancelPayload): string | null {
-  // Try orderCancel.orderRef (text content)
-  if (payload.orderCancel) {
-    const orderCancel = payload.orderCancel;
-
-    // Try orderCancel.orderRef as text
-    if (orderCancel.orderRef) {
-      const ref = extractTextContent(orderCancel.orderRef);
-      if (ref) {
-        return ref;
-      }
-      // Try as direct string
-      if (typeof orderCancel.orderRef === 'string') {
-        return orderCancel.orderRef;
-      }
-    }
-
-    // Try orderCancel.order.$?.ref (attribute)
-    if (
-      orderCancel.order &&
-      typeof orderCancel.order === 'object' &&
-      '$' in orderCancel.order
-    ) {
-      const attrs = orderCancel.order.$ as Record<string, unknown>;
-      if (attrs && typeof attrs.ref === 'string') {
-        return attrs.ref;
-      }
-    }
-
-    // Try orderCancel.order.reference (text content)
-    if (
-      orderCancel.order &&
-      typeof orderCancel.order === 'object' &&
-      'reference' in orderCancel.order
-    ) {
-      const ref = extractTextContent(orderCancel.order.reference as VersoriXMLParsed);
-      if (ref) {
-        return ref;
-      }
-    }
-
-    // Try orderCancel.order.ref (text content)
-    if (
-      orderCancel.order &&
-      typeof orderCancel.order === 'object' &&
-      'ref' in orderCancel.order
-    ) {
-      const ref = extractTextContent(orderCancel.order.ref as VersoriXMLParsed);
-      if (ref) {
-        return ref;
-      }
-    }
-
-    // Try orderCancel.$?.orderRef (root attribute)
-    if ('$' in orderCancel && orderCancel.$) {
-      const attrs = orderCancel.$ as Record<string, unknown>;
-      if (attrs && typeof attrs.orderRef === 'string') {
-        return attrs.orderRef;
-      }
-    }
-  }
-
-  // Try direct order element
-  if (payload.order) {
-    const order = payload.order;
-
-    // Try order.$?.ref (attribute)
-    if (typeof order === 'object' && '$' in order && order.$) {
-      const attrs = order.$ as Record<string, unknown>;
-      if (attrs && typeof attrs.ref === 'string') {
-        return attrs.ref;
-      }
-    }
-
-    // Try order.reference (text content)
-    if (typeof order === 'object' && 'reference' in order) {
-      const ref = extractTextContent(order.reference as VersoriXMLParsed);
-      if (ref) {
-        return ref;
-      }
-    }
-
-    // Try order.ref (text content)
-    if (typeof order === 'object' && 'ref' in order) {
-      const ref = extractTextContent(order.ref as VersoriXMLParsed);
-      if (ref) {
-        return ref;
-      }
-    }
-  }
-
-  return null;
-}
-
-/**
- * Parse webhook payload from Versori context
- *
- * CRITICAL: Versori automatically parses XML when Content-Type: application/xml is set.
- * The ctx.data will be a pre-parsed JavaScript object - no manual parsing needed!
- *
- * Handles both pre-parsed XML (ctx.data) and raw request body (ctx.request) as fallback
- */
-async function parseWebhookPayload(
-  ctx: VersoriContext
-): Promise<OrderCancelPayload | null> {
-  const { log, data, request } = ctx;
-
-  // ✅ Scenario 1: Pre-parsed XML (Versori auto-parsed when Content-Type: application/xml)
-  // This is the PRIMARY path - Versori handles XML parsing automatically
-  if (data && typeof data === 'object' && data !== null) {
-    log.info('📥 [PARSE] Using Versori auto-parsed XML payload', {
-      hasData: true,
-      dataKeys: Object.keys(data),
-      contentType: request?.headers?.get('content-type'),
-    });
-    return data as OrderCancelPayload;
-  }
-
-  // ⚠️ Scenario 2: Raw request body (fallback - should rarely be needed)
-  // Only used if Versori didn't auto-parse (e.g., wrong Content-Type header)
-  if (request && typeof request.text === 'function') {
-    log.warn('📥 [PARSE] Falling back to manual XML parsing (Content-Type may be incorrect)');
-    try {
-      const rawBody = await request.text();
-      if (!rawBody || rawBody.trim() === '') {
-        log.error('❌ [PARSE] Request body is empty');
-        return null;
-      }
-
-      const parser = new XMLParserService(log);
-      const parsed = await parser.parse(rawBody);
-      
-      log.info('📥 [PARSE] Successfully parsed XML payload', {
-        parsedKeys: Object.keys(parsed),
-      });
-      
-      return parsed as OrderCancelPayload;
-    } catch (parseError: unknown) {
-      const errorMessage =
-        parseError instanceof Error ? parseError.message : String(parseError);
-      log.error('❌ [PARSE] Failed to parse XML payload', {
-        error: errorMessage,
-      });
-      return null;
-    }
-  }
-
-  log.error('❌ [PARSE] No valid payload found in context');
-  return null;
-}
-
-/**
- * Build OrderCancel event payload
- */
-function buildOrderCancelEvent(
-  orderRef: string,
-  retailerId: string
-): {
-  retailerId: string;
-  name: 'OrderCancel';
-  entityRef: string;
-  entityType: 'ORDER';
-} {
-  return {
-    retailerId,
-    name: 'OrderCancel',
-    entityRef: orderRef,
-    entityType: 'ORDER',
-  };
-}
-
-/**
- * Execute order cancel workflow
- *
- * Main orchestration function:
- * 1. Parse webhook payload
- * 2. Extract order reference
- * 3. Create Fluent client
- * 4. Build event payload
- * 5. Send event to Fluent Commerce
- */
-export async function executeOrderCancel(
-  ctx: VersoriContext
-): Promise<OrderCancelResult> {
-  const { log, activation } = ctx;
-
-  log.info('🚀 [SERVICE] Starting order cancel processing');
-
-  // STEP 1: Parse webhook payload
-  // ✅ Versori automatically parses XML when Content-Type: application/xml is set
-  // ctx.data will be a pre-parsed JavaScript object - no manual parsing needed!
-  const payload = await parseWebhookPayload(ctx);
-  if (!payload) {
-    throw new Error(
-      'Failed to parse webhook payload. Ensure Content-Type: application/xml is set in request headers.'
-    );
-  }
-
-  log.info('📥 [SERVICE] Payload parsed successfully (Versori auto-parsed XML)', {
-    payloadKeys: Object.keys(payload),
-    note: 'Versori automatically parses XML when Content-Type: application/xml is set',
-  });
-
-  // STEP 2: Extract order reference
-  const orderRef = extractOrderRef(payload);
-  if (!orderRef) {
-    log.error('❌ [SERVICE] Order reference not found in XML payload', {
-      payloadKeys: Object.keys(payload),
-      expectedPatterns: [
-        'orderCancel.orderRef',
-        'orderCancel.order[@ref]',
-        'orderCancel.order.reference',
-        'orderCancel[@orderRef]',
-      ],
-    });
-    throw new Error(
-      'Order reference not found in XML payload. Expected patterns: orderCancel.orderRef, orderCancel.order[@ref], orderCancel.order.reference, or orderCancel[@orderRef]'
-    );
-  }
-
-  log.info('✅ [SERVICE] Order reference extracted', { orderRef });
-
-  // STEP 3: Get retailer ID from activation variable or connection
-  const retailerId =
-    activation.getVariable('FLUENT_RETAILER_ID') ||
-    (activation.connections?.fluent_commerce as any)?.retailerId;
-
-  if (!retailerId) {
-    log.error('❌ [SERVICE] Retailer ID not found', {
-      checkedVariables: ['FLUENT_RETAILER_ID'],
-      hasConnection: !!activation.connections?.fluent_commerce,
-    });
-    throw new Error(
-      'Retailer ID not found. Set FLUENT_RETAILER_ID activation variable or configure in connection.'
-    );
-  }
-
-  log.info('✅ [SERVICE] Retailer ID retrieved', { retailerId });
-
-  // STEP 4: Create Fluent client
-  // ✅ Pass ctx directly - createClient auto-detects Versori context
-  const client = await createClient(ctx);
-
-  log.info('✅ [SERVICE] Fluent client created');
-
-  // STEP 5: Build event payload
-  const eventPayload = buildOrderCancelEvent(orderRef, retailerId);
-
-  log.info('📤 [SERVICE] Sending OrderCancel event', {
-    orderRef,
-    retailerId,
-  });
-
-  // STEP 6: Send event to Fluent Commerce
-  // ✅ Using 'async' mode (recommended):
-  //    - Fluent accepts event immediately and processes in background
-  //    - Returns event ID quickly (non-blocking)
-  //    - Better performance for webhook responses
-  //    - Alternative: 'sync' mode waits for event processing (slower, blocking)
-  //      - Sync mode success: { eventId: "...", eventStatus: "COMPLETE" }
-  //      - Sync mode failure: { eventStatus: "FAILED" }
-  //      - Sync mode no match: { eventId: "...", eventStatus: "NO_MATCH" }
-  const response = await client.sendEvent(eventPayload, 'async');
-
-  // Extract event ID from Fluent response
-  // Async mode response format: { id: "evt_abc123", ... }
-  // Sync mode response format (success): { eventId: "...", eventStatus: "COMPLETE" }
-  // Sync mode response format (failure): { eventStatus: "FAILED" }
-  // Sync mode response format (no match): { eventId: "...", eventStatus: "NO_MATCH" }
-  let eventId: string | undefined;
-  
-  if (response && typeof response === 'object') {
-    // Extract event ID first (needed for error messages)
-    if ('id' in response) {
-      eventId = response.id as string;
-    } else if ('eventId' in response) {
-      eventId = response.eventId as string;
-    }
-    
-    // Check for sync mode failure statuses
-    if ('eventStatus' in response) {
-      const eventStatus = response.eventStatus as string;
-      
-      if (eventStatus === 'FAILED') {
-        log.error('❌ [SERVICE] OrderCancel event failed (sync mode)', {
-          orderRef,
-          eventId,
-          eventStatus,
-          response,
-        });
-        throw new Error('Order cancel event failed. Event status: FAILED');
-      }
-      
-      if (eventStatus === 'NO_MATCH') {
-        log.error('❌ [SERVICE] OrderCancel event no match (sync mode)', {
-          orderRef,
-          eventId,
-          eventStatus,
-          response,
-        });
-        throw new Error(
-          'Order cancel event did not match any workflow. Possible causes: incorrect event name, status mismatch, or entity not found. Event status: NO_MATCH'
-        );
-      }
-      
-      if (eventStatus === 'COMPLETE') {
-        log.info('✅ [SERVICE] OrderCancel event completed (sync mode)', {
-          orderRef,
-          eventId,
-          eventStatus,
-        });
-      }
-    }
-  }
-
-  log.info('✅ [SERVICE] OrderCancel event sent successfully', {
-    orderRef,
-    eventId,
-  });
-
-  return {
-    success: true,
-    orderRef,
-    eventId,
-  };
-}
-```
-
----
-
-## 5. Configuration
-
-### Activation Variables
-
-Configure these variables in Versori activation settings:
-
-```json
-{
-  "FLUENT_RETAILER_ID": "your-retailer-id"
-}
-```
-
-**Note:** If using Versori connection for Fluent Commerce, retailer ID can also be configured in the connection settings.
-
-### Webhook Connection
-
-Create a Versori connection for webhook authentication:
-
-1. **Connection Name:** `order-cancel-webhook`
-2. **Type:** API Key or Basic Auth
-3. **Purpose:** Authenticate incoming webhook requests
-
-**Example webhook call:**
-
-```bash
-curl -X POST https://{workspace}.versori.run/order-cancel \
-  -H "Content-Type: application/xml" \
-  -H "X-API-Key: your-api-key" \
-  --data-binary @order-cancel.xml
-```
-
-**Example XML file (`order-cancel.xml`):**
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<orderCancel>
-  <orderRef>ORD-12345</orderRef>
-</orderCancel>
-```
-
-**CRITICAL: Content-Type Header**
-
-The `Content-Type: application/xml` header is **required** for Versori to automatically parse the XML. Without this header, Versori will not parse the XML and you'll need to manually parse using `XMLParserService`.
-
-**✅ CORRECT:**
-```bash
-curl -X POST https://{workspace}.versori.run/order-cancel \
-  -H "Content-Type: application/xml" \  # ✅ Required!
-  -H "X-API-Key: your-api-key" \
-  --data-binary @order-cancel.xml
-```
-
-**❌ WRONG:**
-```bash
-curl -X POST https://{workspace}.versori.run/order-cancel \
-  -H "Content-Type: text/plain" \  # ❌ Wrong Content-Type
-  -H "X-API-Key: your-api-key" \
-  --data-binary @order-cancel.xml
-```
-
----
-
-## 6. Error Handling
-
-The template includes comprehensive error handling:
-
-### Payload Parsing Errors
-
-- **Empty payload:** Returns error response
-- **Invalid XML:** Returns error with parse details
-- **Missing order reference:** Returns error with expected patterns
-
-### Event Sending Errors
-
-- **Network errors:** Logged and returned in error response
-- **API errors:** Logged with full error details
-- **Validation errors:** Logged with validation message
-
-### Error Response Format
-
-```json
-{
-  "success": false,
-  "error": "Order reference not found in XML payload. Expected patterns: orderCancel.orderRef, orderCancel.order[@ref], orderCancel.order.reference, or orderCancel[@orderRef]"
-}
-```
-
----
-
-## 7. Testing
-
-### Test with cURL
-
-```bash
-# Test order cancel webhook with XML file
-curl -X POST https://{workspace}.versori.run/order-cancel \
-  -H "Content-Type: application/xml" \
-  -H "X-API-Key: your-api-key" \
-  --data-binary @order-cancel.xml
-```
-
-### Test with Inline XML
-
-```bash
-curl -X POST https://{workspace}.versori.run/order-cancel \
-  -H "Content-Type: application/xml" \
-  -H "X-API-Key: your-api-key" \
-  -d '<?xml version="1.0" encoding="UTF-8"?><orderCancel><orderRef>ORD-12345</orderRef></orderCancel>'
-```
-
-### Expected Success Response
-
-```json
-{
-  "success": true,
-  "orderRef": "ORD-12345",
-  "eventId": "evt_abc123",
-  "message": "Order cancel event sent successfully"
-}
-```
-
-**Response Details:**
-- `success`: `true` indicates webhook processed successfully
-- `orderRef`: The order reference that was cancelled
-- `eventId`: Fluent Commerce event ID (returned from Event API async endpoint)
-- `message`: Human-readable success message
-
-**Event API Mode: `async` (recommended)**
-- Fluent accepts the event immediately and returns an event ID
-- Event processing happens in the background
-- Webhook response includes the event ID for tracking
-- Response format: `{ id: "evt_abc123" }`
-
-**Alternative: `sync` mode**
-- Fluent processes the event synchronously before responding
-- Slower response time (waits for event processing)
-- Success response: `{ eventId: "...", eventStatus: "COMPLETE" }`
-- Failure response: `{ eventStatus: "FAILED" }`
-- No match response: `{ eventId: "...", eventStatus: "NO_MATCH" }` (incorrect event name, status mismatch, or entity not found)
-- Use only if you need immediate confirmation of event processing
-
-### Expected Error Response
-
-**Webhook Processing Errors:**
-```json
-{
-  "success": false,
-  "error": "Order reference not found in XML payload"
-}
-```
-
-**Event API Sync Mode Responses:**
-
-**Success (sync mode):**
-```json
-{
-  "eventId": "421d1709-d0af-4d8a-b7b6-75e40c5fc038",
-  "eventStatus": "COMPLETE"
-}
-```
-
-**Failure (sync mode):**
-```json
-{
-  "eventStatus": "FAILED"
-}
-```
-
-**No Match (sync mode):**
-Occurs when event name is incorrect, status mismatch, or entity not found:
-```json
-{
-  "eventId": "9782c552-033c-47c7-89ea-2b0068fbdd0a",
-  "eventStatus": "NO_MATCH"
-}
-```
-
-The webhook will catch failures and return:
-```json
-{
-  "success": false,
-  "error": "Order cancel event failed. Event status: FAILED"
-}
-```
-
-Or for NO_MATCH:
-```json
-{
-  "success": false,
-  "error": "Order cancel event did not match any workflow. Possible causes: incorrect event name, status mismatch, or entity not found. Event status: NO_MATCH"
-}
-```
-
----
-
-## 8. Customization
-
-### Custom Order Reference Element
-
-If your XML uses different element names, modify `extractOrderRef()` in `order-cancel.service.ts`:
-
-```typescript
-function extractOrderRef(payload: OrderCancelPayload): string | null {
-  // Add your custom element extraction logic
-  if (payload.customCancel && typeof payload.customCancel === 'object') {
-    const cancel = payload.customCancel;
-    if ('$' in cancel && cancel.$) {
-      const attrs = cancel.$ as Record<string, unknown>;
-      if (attrs && typeof attrs.orderId === 'string') {
-        return attrs.orderId;
-      }
-    }
-  }
-  // ... existing logic
-}
-```
-
-### Custom Event Name
-
-To use a different event name, modify `buildOrderCancelEvent()`:
-
-```typescript
-function buildOrderCancelEvent(
-  orderRef: string,
-  retailerId: string
-) {
-  return {
-    retailerId,
-    name: 'CustomOrderCancel', // Change event name
-    entityRef: orderRef,
-    entityType: 'ORDER',
-  };
-}
-```
-
-### Additional Event Data
-
-To include additional data in the event:
-
-```typescript
-function buildOrderCancelEvent(
-  orderRef: string,
-  retailerId: string,
-  additionalData?: Record<string, unknown>
-) {
-  return {
-    retailerId,
-    name: 'OrderCancel',
-    entityRef: orderRef,
-    entityType: 'ORDER',
-    data: additionalData, // Add custom data
-  };
-}
-```
-
----
-
-## Summary
-
-✅ **DO:**
-- Use Versori connection for Fluent Commerce credentials
-- Handle both pre-parsed and raw XML payloads
-- Extract order reference with multiple fallback patterns
-- Handle Versori XML format ($ for attributes, _ for text)
-- Log all steps for debugging
-- Return clear error messages
-
-❌ **DON'T:**
-- Hardcode credentials in code
-- Assume payload format without validation
-- Skip error handling
-- Use `sync` mode for Event API (use `async` for better performance and faster webhook responses)
-- Ignore Versori XML parsing format ($ and _)
-
----
-
-## Next Steps
-
-1. **Deploy:** Copy code to your Versori project
-2. **Configure:** Set up Fluent Commerce connection and activation variables
-3. **Test:** Test webhook with sample XML payloads
-4. **Monitor:** Check Versori logs for event processing
-
-For more templates, see:
-- [JSON Payload Template](./template-ingestion-payload-json-order-cancel-event.md)
-- [Other Event API Templates](./event-api-guide.md)
-
+---
+template_id: tpl-ingest-payload-xml-to-order-cancel-event
+canonical_filename: template-ingestion-payload-xml-order-cancel-event.md
+sdk_version: latest
+runtime: versori
+direction: ingestion
+source: payload-xml
+destination: fluent-event-api
+entity: order
+format: xml
+logging: versori
+status: stable
+features:
+  - direct-payload-processing
+  - xml-parsing
+  - event-api-integration
+  - error-handling
+---
+
+# Template: Ingestion - Payload XML to Order Cancel Event
+
+**SDK Version:** @fluentcommerce/fc-connect-sdk@latest
+**Last Updated:** 2025-01-24
+**Deployment Target:** Versori Platform
+
+---
+
+## 📋 Implementation Prompt
+
+```
+I need a Versori webhook ingestion that:
+
+1) Receives XML payload directly in webhook request body
+2) Parses XML to extract order reference (handles Versori $ format for attributes)
+3) Builds OrderCancel event payload with retailerId, name, entityRef, entityType
+4) Sends event to Fluent Commerce Event API (async)
+5) Returns success/error response
+6) Uses native Versori log from context
+
+Use the loaded docs to fill in SDK specifics and best practices.
+Keep the structure identical to the template; only adapt where needed.
+```
+
+---
+
+## 📋 Template Overview
+
+This connector runs on the Versori platform. It receives XML payloads directly via webhook, extracts the order reference, and sends OrderCancel events to Fluent Commerce Event API. Most operational settings (Fluent account/connection) are configured via activation variables.
+
+### What This Template Does
+
+```
+┌────────────────────────────────────────────────────────────────┐
+│          INGESTION WORKFLOW              │
+└────────────────────────────────────────────────────────────────┘
+
+1. TRIGGER
+  └─ Webhook: HTTP POST endpoint receives XML payload
+
+2. RECEIVE PAYLOAD
+  ├─ Extract XML from request body (ctx.data or ctx.request)
+  ├─ Validate payload structure
+  └─ Log incoming request
+
+3. PARSE XML
+  ├─ Parse XML payload (Versori auto-parses with $ format)
+  ├─ Extract order reference (handles $ for attributes, _ for text)
+  └─ Validate required fields
+
+4. BUILD EVENT
+  ├─ Construct OrderCancel event payload
+  ├─ Set retailerId (from config or payload)
+  ├─ Set name: "OrderCancel"
+  ├─ Set entityRef: order reference
+  └─ Set entityType: "ORDER"
+
+5. SEND EVENT (Event API)
+  ├─ Send event to Fluent Commerce Event API (async)
+  ├─ Handle success/error responses
+  └─ Log event result
+
+6. RETURN RESPONSE
+  ├─ Return success with event details
+  └─ Return error with details if failed
+```
+
+### Key Features
+
+- **Direct Payload Processing**: Receives XML payload directly in webhook request body
+- **XML Parsing**: Handles Versori auto-parsed XML format ($ for attributes, _ for text)
+- **Event API Integration**: Sends OrderCancel events to Fluent Commerce
+- **Error Handling**: Comprehensive error handling with detailed logging
+- **Native Versori Logging**: Uses Versori log from context
+- **Flexible Order Reference Extraction**: Supports multiple XML element patterns
+
+### 📦 Package Information
+
+**SDK:** [@fluentcommerce/fc-connect-sdk](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk) `latest`
+
+```bash
+npm install @fluentcommerce/fc-connect-sdk@latest
+```
+
+---
+
+**Templates are designed for direct deployment; customize via activation variables.**
+
+---
+
+## 📦 SDK Imports (Verified - Versori Optimized)
+
+```typescript
+// ✅ VERIFIED IMPORTS - These match actual SDK exports
+import { Buffer } from 'node:buffer'; // Required for Versori/Deno runtime
+import {
+  createClient, // Universal client factory
+  XMLParserService, // XML parsing utility
+} from '@fluentcommerce/fc-connect-sdk';
+
+import type { FluentClient } from '@fluentcommerce/fc-connect-sdk';
+
+// Versori platform imports
+import { webhook, http } from '@versori/run';
+```
+
+**Note:** All imports are from actual SDK exports - this code compiles and runs as-is.
+
+**⚠️ CRITICAL - Buffer Import Required:**
+
+The `Buffer` import from `node:buffer` is **required** for Versori/Deno runtime compatibility:
+- Versori and Deno do NOT have `Buffer` as a global (unlike Node.js)
+- Without this import, code will crash with `ReferenceError: Buffer is not defined`
+- Always include this import in Versori templates, even if not directly used in the template code
+- Required for SDK internal operations and any Buffer usage in your code
+
+**✅ VERSORI PLATFORM - Use Native Logs:**
+
+- Use `log` from context: `const { log } = ctx;`
+- Native Versori logs are simpler and automatically integrated with platform monitoring
+
+**✅ VERSORI XML PARSING:**
+
+Versori automatically parses XML payloads when `Content-Type: application/xml` is set:
+- Attributes accessed via `$` (e.g., `element.$?.attributeName`)
+- Text content accessed via `_` (e.g., `element._`)
+- Nested elements accessed directly (e.g., `element.childElement`)
+
+---
+
+## 🔐 Fluent Commerce Connection Setup
+
+**✅ BEST PRACTICE:** Store Fluent Commerce credentials in a Versori connection object:
+
+**Connection Configuration:**
+
+1. **Create Connection in Versori:**
+   - Name: `fluent_commerce`
+   - Type: HTTP Basic Auth or OAuth2
+   - Credentials: Fluent Commerce API credentials
+
+2. **Connection Variables:**
+   - `FLUENT_BASE_URL` - Fluent Commerce API base URL (e.g., `https://api.fluentcommerce.com`)
+   - `FLUENT_RETAILER_ID` - Your retailer ID
+   - `FLUENT_CLIENT_ID` - OAuth client ID (if using OAuth2)
+   - `FLUENT_CLIENT_SECRET` - OAuth client secret (if using OAuth2)
+
+**Benefits:**
+- ✅ Credentials stored securely in Versori vault
+- ✅ Connection can be reused across workflows
+- ✅ No sensitive data in activation variables
+- ✅ Easier credential rotation
+
+---
+
+## 📄 Expected XML Payload Format
+
+The webhook accepts XML payloads with order reference information. Multiple formats are supported:
+
+### Format 1: Simple Order Reference
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<orderCancel>
+  <orderRef>ORD-12345</orderRef>
+</orderCancel>
+```
+
+### Format 2: With Attributes
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<orderCancel>
+  <order ref="ORD-12345"/>
+</orderCancel>
+```
+
+### Format 3: Nested Structure
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<orderCancel>
+  <order>
+    <reference>ORD-12345</reference>
+    <reason>Customer requested cancellation</reason>
+  </order>
+</orderCancel>
+```
+
+### Format 4: Root Element with Attributes
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<orderCancel orderRef="ORD-12345">
+  <reason>Customer requested cancellation</reason>
+</orderCancel>
+```
+
+**Note:** The template extracts order reference from various XML patterns. Customize the extraction logic in the service if your payload uses different element names.
+
+**Versori XML Parsing Format (CRITICAL):**
+
+When Versori receives XML with `Content-Type: application/xml`, it **automatically parses** the XML into a JavaScript object. You do NOT need to manually parse XML - Versori handles it automatically.
+
+**Access Patterns:**
+- **Attributes**: `element.$?.attributeName` (e.g., `<order ref="ORD-12345"/>` → `order.$?.ref`)
+- **Text content**: `element._` or direct property access (e.g., `<orderRef>ORD-12345</orderRef>` → `orderRef._` or `orderRef`)
+- **Nested elements**: Direct property access (e.g., `<orderCancel><orderRef>...</orderRef></orderCancel>` → `orderCancel.orderRef`)
+
+**Examples:**
+
+```typescript
+// XML: <order ref="ORD-12345"/>
+// Versori auto-parsed: { order: { $: { ref: "ORD-12345" } } }
+const orderRef = parsed.order?.$?.ref; // ✅ "ORD-12345"
+
+// XML: <orderRef>ORD-12345</orderRef>
+// Versori auto-parsed: { orderRef: { _: "ORD-12345" } } OR { orderRef: "ORD-12345" }
+const orderRef = parsed.orderRef?._ || parsed.orderRef; // ✅ "ORD-12345"
+
+// XML: <orderCancel><order ref="ORD-12345"/></orderCancel>
+// Versori auto-parsed: { orderCancel: { order: { $: { ref: "ORD-12345" } } } }
+const orderRef = parsed.orderCancel?.order?.$?.ref; // ✅ "ORD-12345"
+```
+
+**Key Point:** Versori automatically parses XML when `Content-Type: application/xml` is set. Your webhook receives `ctx.data` as a pre-parsed JavaScript object - no manual XML parsing needed!
+
+---
+
+## Event Payload Structure
+
+The template builds and sends this event structure:
+
+```json
+{
+  "retailerId": "{{retailer_id}}",
+  "name": "OrderCancel",
+  "entityRef": "{{order_ref}}",
+  "entityType": "ORDER"
+}
+```
+
+**Fields:**
+- `retailerId`: Retrieved from Fluent Commerce connection or activation variable
+- `name`: Fixed as "OrderCancel"
+- `entityRef`: Extracted from incoming XML payload
+- `entityType`: Fixed as "ORDER"
+
+---
+
+## 🔧 Complete Production Code
+
+### 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
+
+**Execution Steps (chained to triggers):**
+- **`http()`** → External API calls (chained from webhook)
+
+### Recommended Project Structure
+
+```
+order-cancel-webhook/
+├── index.ts                              # Entry point - exports all workflows
+└── src/
+    ├── workflows/
+    │   └── webhook/
+    │       └── order-cancel.ts           # Webhook: Order cancel handler
+    │
+    ├── services/
+    │   └── order-cancel.service.ts       # Shared orchestration logic
+    │
+    └── types/
+        └── order-cancel.types.ts         # Type definitions
+```
+
+**Benefits:**
+- ✅ Clear structure (webhook handlers in `webhook/`)
+- ✅ Descriptive file names (easy to browse and understand)
+- ✅ Reusable code in `services/` (DRY principle)
+- ✅ Centralized type definitions
+
+---
+
+## Workflow Files
+
+### 1. Webhook Workflow (`src/workflows/webhook/order-cancel.ts`)
+
+**Purpose**: Handle order cancel requests via webhook
+**Trigger**: HTTP POST
+**Endpoint**: `POST https://{workspace}.versori.run/order-cancel`
+**Use Cases**: Order cancellation from external systems, manual cancellations
+
+```typescript
+import { webhook, http } from '@versori/run';
+import { executeOrderCancel } from '../../services/order-cancel.service';
+
+/**
+ * Webhook: Order Cancel Handler
+ *
+ * Endpoint: POST https://{workspace}.versori.run/order-cancel
+ * Request body: XML payload with order reference
+ * Content-Type: application/xml
+ *
+ * Pattern: webhook().then(http()) - needs Fluent API access
+ * Uses shared service: order-cancel.service.ts
+ *
+ * SECURITY: Authentication handled via connection parameter
+ * No manual API key validation needed - Versori manages this via connection auth
+ */
+export const orderCancelWebhook = webhook('order-cancel', {
+  // ✅ Webhook response mode: 'sync'
+  //    - HTTP response sent when handler completes
+  //    - Returns event ID and success status immediately after Fluent accepts event
+  //    - Alternative: 'async' mode would return immediately (before processing)
+  response: { mode: 'sync' },
+  connection: 'order-cancel-webhook', // Versori validates API key
+}).then(
+  http('process-order-cancel', { connection: 'fluent_commerce' }, async ctx => {
+    const { log, data } = ctx;
+
+    log.info('🚀 [WEBHOOK] Order cancel request received', {
+      timestamp: new Date().toISOString(),
+      hasPayload: !!data,
+      contentType: ctx.request?.headers?.get('content-type'),
+    });
+
+    try {
+      // Reuse shared orchestration logic
+      const result = await executeOrderCancel(ctx);
+
+      log.info('✅ [WEBHOOK] Order cancel completed successfully', {
+        orderRef: result.orderRef,
+        eventId: result.eventId,
+      });
+
+      return {
+        success: true,
+        orderRef: result.orderRef,
+        eventId: result.eventId,
+        message: 'Order cancel event sent successfully',
+      };
+    } catch (e: any) {
+      log.error('❌ [WEBHOOK] Order cancel failed', {
+        message: e?.message,
+        stack: e?.stack,
+      });
+
+      return {
+        success: false,
+        error: e?.message || 'Unknown error occurred',
+      };
+    }
+  })
+);
+```
+
+---
+
+### 2. Entry Point (`index.ts`)
+
+**Purpose**: Register all workflows with Versori platform
+
+```typescript
+/**
+ * Entry Point - Registers all workflows with Versori platform
+ *
+ * Versori automatically discovers and registers exported workflows
+ *
+ * File Structure:
+ * - src/workflows/webhook/   → HTTP-based triggers (webhooks)
+ * - src/services/            → Shared service logic (reusable across workflows)
+ */
+
+// Import webhook workflows
+import { orderCancelWebhook } from './src/workflows/webhook/order-cancel';
+
+// Register all workflows with Versori platform
+export {
+  // Webhooks (HTTP-based triggers)
+  orderCancelWebhook,
+};
+```
+
+**What Gets Exposed:**
+- ✅ `orderCancelWebhook` → `https://{workspace}.versori.run/order-cancel`
+
+---
+
+## 3. Type Definitions (`src/types/order-cancel.types.ts`)
+
+```typescript
+/**
+ * Type Definitions for Order Cancel Ingestion
+ *
+ * Centralized type definitions for order cancel workflow
+ */
+
+/**
+ * Versori XML parsed format
+ * Attributes accessed via $, text content via _
+ */
+export interface VersoriXMLParsed {
+  [key: string]: unknown;
+  $?: Record<string, unknown>; // Attributes
+  _?: string; // Text content
+}
+
+/**
+ * Order cancel request payload (XML parsed format)
+ */
+export interface OrderCancelPayload {
+  orderCancel?: {
+    orderRef?: VersoriXMLParsed | string;
+    order?: {
+      $?: {
+        ref?: string;
+      };
+      reference?: VersoriXMLParsed | string;
+      ref?: VersoriXMLParsed | string;
+    };
+    $?: {
+      orderRef?: string;
+    };
+  };
+  order?: {
+    $?: {
+      ref?: string;
+    };
+    reference?: VersoriXMLParsed | string;
+    ref?: VersoriXMLParsed | string;
+  };
+  [key: string]: unknown; // Allow additional fields
+}
+
+/**
+ * Order cancel event payload
+ */
+export interface OrderCancelEvent {
+  retailerId: string;
+  name: 'OrderCancel';
+  entityRef: string;
+  entityType: 'ORDER';
+}
+
+/**
+ * Order cancel result
+ */
+export interface OrderCancelResult {
+  success: boolean;
+  orderRef: string;
+  eventId?: string;
+  error?: string;
+}
+
+/**
+ * Versori Context Interface
+ * Represents the Versori runtime context passed to workflow functions
+ */
+export interface VersoriContext {
+  log: {
+    info: (message: string, data?: Record<string, unknown>) => void;
+    warn: (message: string, data?: Record<string, unknown>) => void;
+    error: (message: string, data?: Record<string, unknown>) => void;
+    debug?: (message: string, data?: Record<string, unknown>) => void;
+  };
+  data?: unknown;
+  request?: Request;
+  activation: {
+    getVariable: (name: string) => string | undefined;
+    connections?: Record<string, unknown>;
+  };
+  connections?: Record<string, unknown>;
+}
+```
+
+---
+
+## 4. Service: Order Cancel Processor (`src/services/order-cancel.service.ts`)
+
+```typescript
+/**
+ * Order Cancel Service
+ *
+ * Processes order cancel requests: extracts order reference from XML payload,
+ * builds OrderCancel event, and sends to Fluent Commerce Event API.
+ * Handles Versori XML parsing format ($ for attributes, _ for text).
+ */
+
+import {
+  createClient,
+  XMLParserService,
+} from '@fluentcommerce/fc-connect-sdk';
+import type { FluentClient } from '@fluentcommerce/fc-connect-sdk';
+import type {
+  OrderCancelPayload,
+  OrderCancelResult,
+  VersoriContext,
+  VersoriXMLParsed,
+} from '../types/order-cancel.types';
+
+/**
+ * Extract text content from Versori XML parsed format
+ * Handles both object format ({ _: "text" }) and direct string
+ */
+function extractTextContent(value: VersoriXMLParsed | string | undefined): string | null {
+  if (!value) {
+    return null;
+  }
+
+  if (typeof value === 'string') {
+    return value;
+  }
+
+  if (typeof value === 'object' && '_' in value) {
+    const text = value._;
+    return typeof text === 'string' ? text : null;
+  }
+
+  return null;
+}
+
+/**
+ * Extract order reference from XML payload
+ *
+ * Supports multiple XML formats:
+ * - <orderCancel><orderRef>ORD-12345</orderRef></orderCancel>
+ * - <orderCancel><order ref="ORD-12345"/></orderCancel>
+ * - <orderCancel><order><reference>ORD-12345</reference></order></orderCancel>
+ * - <orderCancel orderRef="ORD-12345"/>
+ */
+function extractOrderRef(payload: OrderCancelPayload): string | null {
+  // Try orderCancel.orderRef (text content)
+  if (payload.orderCancel) {
+    const orderCancel = payload.orderCancel;
+
+    // Try orderCancel.orderRef as text
+    if (orderCancel.orderRef) {
+      const ref = extractTextContent(orderCancel.orderRef);
+      if (ref) {
+        return ref;
+      }
+      // Try as direct string
+      if (typeof orderCancel.orderRef === 'string') {
+        return orderCancel.orderRef;
+      }
+    }
+
+    // Try orderCancel.order.$?.ref (attribute)
+    if (
+      orderCancel.order &&
+      typeof orderCancel.order === 'object' &&
+      '$' in orderCancel.order
+    ) {
+      const attrs = orderCancel.order.$ as Record<string, unknown>;
+      if (attrs && typeof attrs.ref === 'string') {
+        return attrs.ref;
+      }
+    }
+
+    // Try orderCancel.order.reference (text content)
+    if (
+      orderCancel.order &&
+      typeof orderCancel.order === 'object' &&
+      'reference' in orderCancel.order
+    ) {
+      const ref = extractTextContent(orderCancel.order.reference as VersoriXMLParsed);
+      if (ref) {
+        return ref;
+      }
+    }
+
+    // Try orderCancel.order.ref (text content)
+    if (
+      orderCancel.order &&
+      typeof orderCancel.order === 'object' &&
+      'ref' in orderCancel.order
+    ) {
+      const ref = extractTextContent(orderCancel.order.ref as VersoriXMLParsed);
+      if (ref) {
+        return ref;
+      }
+    }
+
+    // Try orderCancel.$?.orderRef (root attribute)
+    if ('$' in orderCancel && orderCancel.$) {
+      const attrs = orderCancel.$ as Record<string, unknown>;
+      if (attrs && typeof attrs.orderRef === 'string') {
+        return attrs.orderRef;
+      }
+    }
+  }
+
+  // Try direct order element
+  if (payload.order) {
+    const order = payload.order;
+
+    // Try order.$?.ref (attribute)
+    if (typeof order === 'object' && '$' in order && order.$) {
+      const attrs = order.$ as Record<string, unknown>;
+      if (attrs && typeof attrs.ref === 'string') {
+        return attrs.ref;
+      }
+    }
+
+    // Try order.reference (text content)
+    if (typeof order === 'object' && 'reference' in order) {
+      const ref = extractTextContent(order.reference as VersoriXMLParsed);
+      if (ref) {
+        return ref;
+      }
+    }
+
+    // Try order.ref (text content)
+    if (typeof order === 'object' && 'ref' in order) {
+      const ref = extractTextContent(order.ref as VersoriXMLParsed);
+      if (ref) {
+        return ref;
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Parse webhook payload from Versori context
+ *
+ * CRITICAL: Versori automatically parses XML when Content-Type: application/xml is set.
+ * The ctx.data will be a pre-parsed JavaScript object - no manual parsing needed!
+ *
+ * Handles both pre-parsed XML (ctx.data) and raw request body (ctx.request) as fallback
+ */
+async function parseWebhookPayload(
+  ctx: VersoriContext
+): Promise<OrderCancelPayload | null> {
+  const { log, data, request } = ctx;
+
+  // ✅ Scenario 1: Pre-parsed XML (Versori auto-parsed when Content-Type: application/xml)
+  // This is the PRIMARY path - Versori handles XML parsing automatically
+  if (data && typeof data === 'object' && data !== null) {
+    log.info('📥 [PARSE] Using Versori auto-parsed XML payload', {
+      hasData: true,
+      dataKeys: Object.keys(data),
+      contentType: request?.headers?.get('content-type'),
+    });
+    return data as OrderCancelPayload;
+  }
+
+  // ⚠️ Scenario 2: Raw request body (fallback - should rarely be needed)
+  // Only used if Versori didn't auto-parse (e.g., wrong Content-Type header)
+  if (request && typeof request.text === 'function') {
+    log.warn('📥 [PARSE] Falling back to manual XML parsing (Content-Type may be incorrect)');
+    try {
+      const rawBody = await request.text();
+      if (!rawBody || rawBody.trim() === '') {
+        log.error('❌ [PARSE] Request body is empty');
+        return null;
+      }
+
+      const parser = new XMLParserService(log);
+      const parsed = await parser.parse(rawBody);
+      
+      log.info('📥 [PARSE] Successfully parsed XML payload', {
+        parsedKeys: Object.keys(parsed),
+      });
+      
+      return parsed as OrderCancelPayload;
+    } catch (parseError: unknown) {
+      const errorMessage =
+        parseError instanceof Error ? parseError.message : String(parseError);
+      log.error('❌ [PARSE] Failed to parse XML payload', {
+        error: errorMessage,
+      });
+      return null;
+    }
+  }
+
+  log.error('❌ [PARSE] No valid payload found in context');
+  return null;
+}
+
+/**
+ * Build OrderCancel event payload
+ */
+function buildOrderCancelEvent(
+  orderRef: string,
+  retailerId: string
+): {
+  retailerId: string;
+  name: 'OrderCancel';
+  entityRef: string;
+  entityType: 'ORDER';
+} {
+  return {
+    retailerId,
+    name: 'OrderCancel',
+    entityRef: orderRef,
+    entityType: 'ORDER',
+  };
+}
+
+/**
+ * Execute order cancel workflow
+ *
+ * Main orchestration function:
+ * 1. Parse webhook payload
+ * 2. Extract order reference
+ * 3. Create Fluent client
+ * 4. Build event payload
+ * 5. Send event to Fluent Commerce
+ */
+export async function executeOrderCancel(
+  ctx: VersoriContext
+): Promise<OrderCancelResult> {
+  const { log, activation } = ctx;
+
+  log.info('🚀 [SERVICE] Starting order cancel processing');
+
+  // STEP 1: Parse webhook payload
+  // ✅ Versori automatically parses XML when Content-Type: application/xml is set
+  // ctx.data will be a pre-parsed JavaScript object - no manual parsing needed!
+  const payload = await parseWebhookPayload(ctx);
+  if (!payload) {
+    throw new Error(
+      'Failed to parse webhook payload. Ensure Content-Type: application/xml is set in request headers.'
+    );
+  }
+
+  log.info('📥 [SERVICE] Payload parsed successfully (Versori auto-parsed XML)', {
+    payloadKeys: Object.keys(payload),
+    note: 'Versori automatically parses XML when Content-Type: application/xml is set',
+  });
+
+  // STEP 2: Extract order reference
+  const orderRef = extractOrderRef(payload);
+  if (!orderRef) {
+    log.error('❌ [SERVICE] Order reference not found in XML payload', {
+      payloadKeys: Object.keys(payload),
+      expectedPatterns: [
+        'orderCancel.orderRef',
+        'orderCancel.order[@ref]',
+        'orderCancel.order.reference',
+        'orderCancel[@orderRef]',
+      ],
+    });
+    throw new Error(
+      'Order reference not found in XML payload. Expected patterns: orderCancel.orderRef, orderCancel.order[@ref], orderCancel.order.reference, or orderCancel[@orderRef]'
+    );
+  }
+
+  log.info('✅ [SERVICE] Order reference extracted', { orderRef });
+
+  // STEP 3: Get retailer ID from activation variable or connection
+  const retailerId =
+    activation.getVariable('FLUENT_RETAILER_ID') ||
+    (activation.connections?.fluent_commerce as any)?.retailerId;
+
+  if (!retailerId) {
+    log.error('❌ [SERVICE] Retailer ID not found', {
+      checkedVariables: ['FLUENT_RETAILER_ID'],
+      hasConnection: !!activation.connections?.fluent_commerce,
+    });
+    throw new Error(
+      'Retailer ID not found. Set FLUENT_RETAILER_ID activation variable or configure in connection.'
+    );
+  }
+
+  log.info('✅ [SERVICE] Retailer ID retrieved', { retailerId });
+
+  // STEP 4: Create Fluent client
+  // ✅ Pass ctx directly - createClient auto-detects Versori context
+  const client = await createClient(ctx);
+
+  log.info('✅ [SERVICE] Fluent client created');
+
+  // STEP 5: Build event payload
+  const eventPayload = buildOrderCancelEvent(orderRef, retailerId);
+
+  log.info('📤 [SERVICE] Sending OrderCancel event', {
+    orderRef,
+    retailerId,
+  });
+
+  // STEP 6: Send event to Fluent Commerce
+  // ✅ Using 'async' mode (recommended):
+  //    - Fluent accepts event immediately and processes in background
+  //    - Returns event ID quickly (non-blocking)
+  //    - Better performance for webhook responses
+  //    - Alternative: 'sync' mode waits for event processing (slower, blocking)
+  //      - Sync mode success: { eventId: "...", eventStatus: "COMPLETE" }
+  //      - Sync mode failure: { eventStatus: "FAILED" }
+  //      - Sync mode no match: { eventId: "...", eventStatus: "NO_MATCH" }
+  const response = await client.sendEvent(eventPayload, 'async');
+
+  // Extract event ID from Fluent response
+  // Async mode response format: { id: "evt_abc123", ... }
+  // Sync mode response format (success): { eventId: "...", eventStatus: "COMPLETE" }
+  // Sync mode response format (failure): { eventStatus: "FAILED" }
+  // Sync mode response format (no match): { eventId: "...", eventStatus: "NO_MATCH" }
+  let eventId: string | undefined;
+  
+  if (response && typeof response === 'object') {
+    // Extract event ID first (needed for error messages)
+    if ('id' in response) {
+      eventId = response.id as string;
+    } else if ('eventId' in response) {
+      eventId = response.eventId as string;
+    }
+    
+    // Check for sync mode failure statuses
+    if ('eventStatus' in response) {
+      const eventStatus = response.eventStatus as string;
+      
+      if (eventStatus === 'FAILED') {
+        log.error('❌ [SERVICE] OrderCancel event failed (sync mode)', {
+          orderRef,
+          eventId,
+          eventStatus,
+          response,
+        });
+        throw new Error('Order cancel event failed. Event status: FAILED');
+      }
+      
+      if (eventStatus === 'NO_MATCH') {
+        log.error('❌ [SERVICE] OrderCancel event no match (sync mode)', {
+          orderRef,
+          eventId,
+          eventStatus,
+          response,
+        });
+        throw new Error(
+          'Order cancel event did not match any workflow. Possible causes: incorrect event name, status mismatch, or entity not found. Event status: NO_MATCH'
+        );
+      }
+      
+      if (eventStatus === 'COMPLETE') {
+        log.info('✅ [SERVICE] OrderCancel event completed (sync mode)', {
+          orderRef,
+          eventId,
+          eventStatus,
+        });
+      }
+    }
+  }
+
+  log.info('✅ [SERVICE] OrderCancel event sent successfully', {
+    orderRef,
+    eventId,
+  });
+
+  return {
+    success: true,
+    orderRef,
+    eventId,
+  };
+}
+```
+
+---
+
+## 5. Configuration
+
+### Activation Variables
+
+Configure these variables in Versori activation settings:
+
+```json
+{
+  "FLUENT_RETAILER_ID": "your-retailer-id"
+}
+```
+
+**Note:** If using Versori connection for Fluent Commerce, retailer ID can also be configured in the connection settings.
+
+### Webhook Connection
+
+Create a Versori connection for webhook authentication:
+
+1. **Connection Name:** `order-cancel-webhook`
+2. **Type:** API Key or Basic Auth
+3. **Purpose:** Authenticate incoming webhook requests
+
+**Example webhook call:**
+
+```bash
+curl -X POST https://{workspace}.versori.run/order-cancel \
+  -H "Content-Type: application/xml" \
+  -H "X-API-Key: your-api-key" \
+  --data-binary @order-cancel.xml
+```
+
+**Example XML file (`order-cancel.xml`):**
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<orderCancel>
+  <orderRef>ORD-12345</orderRef>
+</orderCancel>
+```
+
+**CRITICAL: Content-Type Header**
+
+The `Content-Type: application/xml` header is **required** for Versori to automatically parse the XML. Without this header, Versori will not parse the XML and you'll need to manually parse using `XMLParserService`.
+
+**✅ CORRECT:**
+```bash
+curl -X POST https://{workspace}.versori.run/order-cancel \
+  -H "Content-Type: application/xml" \  # ✅ Required!
+  -H "X-API-Key: your-api-key" \
+  --data-binary @order-cancel.xml
+```
+
+**❌ WRONG:**
+```bash
+curl -X POST https://{workspace}.versori.run/order-cancel \
+  -H "Content-Type: text/plain" \  # ❌ Wrong Content-Type
+  -H "X-API-Key: your-api-key" \
+  --data-binary @order-cancel.xml
+```
+
+---
+
+## 6. Error Handling
+
+The template includes comprehensive error handling:
+
+### Payload Parsing Errors
+
+- **Empty payload:** Returns error response
+- **Invalid XML:** Returns error with parse details
+- **Missing order reference:** Returns error with expected patterns
+
+### Event Sending Errors
+
+- **Network errors:** Logged and returned in error response
+- **API errors:** Logged with full error details
+- **Validation errors:** Logged with validation message
+
+### Error Response Format
+
+```json
+{
+  "success": false,
+  "error": "Order reference not found in XML payload. Expected patterns: orderCancel.orderRef, orderCancel.order[@ref], orderCancel.order.reference, or orderCancel[@orderRef]"
+}
+```
+
+---
+
+## 7. Testing
+
+### Test with cURL
+
+```bash
+# Test order cancel webhook with XML file
+curl -X POST https://{workspace}.versori.run/order-cancel \
+  -H "Content-Type: application/xml" \
+  -H "X-API-Key: your-api-key" \
+  --data-binary @order-cancel.xml
+```
+
+### Test with Inline XML
+
+```bash
+curl -X POST https://{workspace}.versori.run/order-cancel \
+  -H "Content-Type: application/xml" \
+  -H "X-API-Key: your-api-key" \
+  -d '<?xml version="1.0" encoding="UTF-8"?><orderCancel><orderRef>ORD-12345</orderRef></orderCancel>'
+```
+
+### Expected Success Response
+
+```json
+{
+  "success": true,
+  "orderRef": "ORD-12345",
+  "eventId": "evt_abc123",
+  "message": "Order cancel event sent successfully"
+}
+```
+
+**Response Details:**
+- `success`: `true` indicates webhook processed successfully
+- `orderRef`: The order reference that was cancelled
+- `eventId`: Fluent Commerce event ID (returned from Event API async endpoint)
+- `message`: Human-readable success message
+
+**Event API Mode: `async` (recommended)**
+- Fluent accepts the event immediately and returns an event ID
+- Event processing happens in the background
+- Webhook response includes the event ID for tracking
+- Response format: `{ id: "evt_abc123" }`
+
+**Alternative: `sync` mode**
+- Fluent processes the event synchronously before responding
+- Slower response time (waits for event processing)
+- Success response: `{ eventId: "...", eventStatus: "COMPLETE" }`
+- Failure response: `{ eventStatus: "FAILED" }`
+- No match response: `{ eventId: "...", eventStatus: "NO_MATCH" }` (incorrect event name, status mismatch, or entity not found)
+- Use only if you need immediate confirmation of event processing
+
+### Expected Error Response
+
+**Webhook Processing Errors:**
+```json
+{
+  "success": false,
+  "error": "Order reference not found in XML payload"
+}
+```
+
+**Event API Sync Mode Responses:**
+
+**Success (sync mode):**
+```json
+{
+  "eventId": "421d1709-d0af-4d8a-b7b6-75e40c5fc038",
+  "eventStatus": "COMPLETE"
+}
+```
+
+**Failure (sync mode):**
+```json
+{
+  "eventStatus": "FAILED"
+}
+```
+
+**No Match (sync mode):**
+Occurs when event name is incorrect, status mismatch, or entity not found:
+```json
+{
+  "eventId": "9782c552-033c-47c7-89ea-2b0068fbdd0a",
+  "eventStatus": "NO_MATCH"
+}
+```
+
+The webhook will catch failures and return:
+```json
+{
+  "success": false,
+  "error": "Order cancel event failed. Event status: FAILED"
+}
+```
+
+Or for NO_MATCH:
+```json
+{
+  "success": false,
+  "error": "Order cancel event did not match any workflow. Possible causes: incorrect event name, status mismatch, or entity not found. Event status: NO_MATCH"
+}
+```
+
+---
+
+## 8. Customization
+
+### Custom Order Reference Element
+
+If your XML uses different element names, modify `extractOrderRef()` in `order-cancel.service.ts`:
+
+```typescript
+function extractOrderRef(payload: OrderCancelPayload): string | null {
+  // Add your custom element extraction logic
+  if (payload.customCancel && typeof payload.customCancel === 'object') {
+    const cancel = payload.customCancel;
+    if ('$' in cancel && cancel.$) {
+      const attrs = cancel.$ as Record<string, unknown>;
+      if (attrs && typeof attrs.orderId === 'string') {
+        return attrs.orderId;
+      }
+    }
+  }
+  // ... existing logic
+}
+```
+
+### Custom Event Name
+
+To use a different event name, modify `buildOrderCancelEvent()`:
+
+```typescript
+function buildOrderCancelEvent(
+  orderRef: string,
+  retailerId: string
+) {
+  return {
+    retailerId,
+    name: 'CustomOrderCancel', // Change event name
+    entityRef: orderRef,
+    entityType: 'ORDER',
+  };
+}
+```
+
+### Additional Event Data
+
+To include additional data in the event:
+
+```typescript
+function buildOrderCancelEvent(
+  orderRef: string,
+  retailerId: string,
+  additionalData?: Record<string, unknown>
+) {
+  return {
+    retailerId,
+    name: 'OrderCancel',
+    entityRef: orderRef,
+    entityType: 'ORDER',
+    data: additionalData, // Add custom data
+  };
+}
+```
+
+---
+
+## Summary
+
+✅ **DO:**
+- Use Versori connection for Fluent Commerce credentials
+- Handle both pre-parsed and raw XML payloads
+- Extract order reference with multiple fallback patterns
+- Handle Versori XML format ($ for attributes, _ for text)
+- Log all steps for debugging
+- Return clear error messages
+
+❌ **DON'T:**
+- Hardcode credentials in code
+- Assume payload format without validation
+- Skip error handling
+- Use `sync` mode for Event API (use `async` for better performance and faster webhook responses)
+- Ignore Versori XML parsing format ($ and _)
+
+---
+
+## Next Steps
+
+1. **Deploy:** Copy code to your Versori project
+2. **Configure:** Set up Fluent Commerce connection and activation variables
+3. **Test:** Test webhook with sample XML payloads
+4. **Monitor:** Check Versori logs for event processing
+
+For more templates, see:
+- [JSON Payload Template](./template-ingestion-payload-json-order-cancel-event.md)
+- [Other Event API Templates](./event-api-guide.md)
+