@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/03-PATTERN-GUIDES/enterprise-integration-patterns.md

@@ -1,1528 +1,1528 @@
-# Enterprise Integration Patterns with Fluent Connect SDK
-
-**Status:** Production Ready
-**Last Updated:** 2025-11-05
-**SDK Version:** 0.1.39
-
----
-
-## Table of Contents
-
-1. [Introduction](#introduction)
-2. [Understanding the SDK as a Toolkit](#understanding-the-sdk-as-a-toolkit)
-3. [Pattern Categories](#pattern-categories)
-4. [Routing Patterns](#routing-patterns)
-5. [Transformation Patterns](#transformation-patterns)
-6. [Endpoint Patterns](#endpoint-patterns)
-7. [System Management Patterns](#system-management-patterns)
-8. [Pattern Summary Matrix](#pattern-summary-matrix)
-9. [Additional Resources](#additional-resources)
-
----
-
-## Introduction
-
-### What is Enterprise Integration Patterns (EIP)?
-
-**Enterprise Integration Patterns (EIP)** are a collection of 65 proven design patterns for building enterprise application integration solutions. Originally documented by Gregor Hohpe and Bobby Woolf in their book ["Enterprise Integration Patterns"](https://www.enterpriseintegrationpatterns.com/), these patterns provide reusable solutions to common integration challenges.
-
-**What EIP Means in TypeScript Context:**
-
-In TypeScript/JavaScript applications, EIP patterns translate to:
-- **Composable functions and services** - Building blocks you combine to solve integration problems
-- **Message transformation** - Converting data between different formats (XML, JSON, CSV)
-- **Routing logic** - Directing messages to appropriate destinations based on content
-- **Error handling** - Managing failures and retries in distributed systems
-- **State management** - Tracking processed messages and maintaining idempotency
-
-**Key Concepts:**
-- **Patterns are solutions**, not libraries - You implement them using your toolkit
-- **SDK provides building blocks** - You compose them to create patterns
-- **TypeScript enables composition** - Functions, classes, and async/await make patterns natural
-
-**Learn More:**
-- 📚 [Enterprise Integration Patterns Book](https://www.enterpriseintegrationpatterns.com/)
-- 🌐 [EIP Pattern Catalog](https://www.enterpriseintegrationpatterns.com/patterns/messaging/)
-- 📖 [EIP Wikipedia](https://en.wikipedia.org/wiki/Enterprise_Integration_Patterns)
-
----
-
-**Enterprise Integration Patterns (EIP)** are proven solutions to common integration challenges. This guide shows how to build these patterns using the Fluent Connect SDK's composable building blocks.
-
-### What This Guide Covers
-
-- **10 Essential EIP Patterns** with real Fluent Commerce use cases
-- **Practical SDK Implementation** using actual client methods and services
-- **Order & Inventory Domain Examples** - the two primary Fluent Commerce domains
-- **Support Status** - Whether each pattern can be built with SDK building blocks
-- **Use-Case-Driven Approach** - Real-world scenarios for each pattern
-
-### Prerequisites
-
-- Understanding of SDK architecture (see `docs/00-START-HERE/SDK-PHILOSOPHY.md`)
-- Familiarity with Fluent Commerce entities (Order, Fulfilment, Inventory)
-- Basic knowledge of GraphQL and Batch API concepts
-
----
-
-## Understanding the SDK as a Toolkit
-
-> **The SDK provides services with methods. YOU build the workflow.**
-
-The FC Connect SDK is **not an opinionated framework** - it's a **toolkit of composable primitives**. Enterprise Integration Patterns are YOUR orchestration logic built on top of SDK services.
-
-### Core Building Blocks
-
-```
-Data Sources               Parsers                    Transformation
-├── S3DataSource          ├── CSVParserService       ├── UniversalMapper
-├── SftpDataSource        ├── XMLParserService       ├── GraphQLMutationMapper
-└── InventoryDataSource   ├── JSONParserService      └── sdkResolvers
-                          └── ParquetParserService
-
-Client                     Services                   State Management
-├── FluentClient          ├── BatchAPIClient         ├── StateService
-├── createClient()        ├── S3PresignService       ├── VersoriKVAdapter
-├── graphql()             ├── WebhookValidationService
-├── sendEvent()           └── SchemaValidationService
-├── createJob()
-├── sendBatch()
-└── getJobStatus()
-```
-
-### The Fundamental Pattern
-
-```
-Read → Parse → Map → YOUR LOGIC → Send/Archive
-```
-
-Enterprise Integration Patterns sit in the **"YOUR LOGIC"** layer - they define HOW you orchestrate these primitives.
-
----
-
-## Pattern Categories
-
-We organize EIP patterns into four categories based on their primary purpose:
-
-1. **Routing Patterns** - Direct messages to appropriate destinations
-2. **Transformation Patterns** - Convert data between formats
-3. **Endpoint Patterns** - Connect to external systems
-4. **System Management Patterns** - Handle reliability and state
-
----
-
-## Routing Patterns
-
-### 1. Message Router
-
-**Pattern:** Route messages to different destinations based on message content or type.
-
-**Support Status:** ✅ **Fully Supported** - Can be built using SDK client methods
-
-**SDK Building Blocks:**
-- `FluentClient.sendEvent()` - Send to Event API
-- `FluentClient.createJob()` + `sendBatch()` - Send to Batch API
-- `FluentClient.graphql()` - Send to GraphQL API
-
-#### Use Case: Order Routing Based on Type
-
-**Business Problem:** Different order types require different processing workflows. Click & Collect orders need immediate workflow triggers, while Home Delivery orders can be batched for efficiency.
-
-Route orders to different workflows based on order type:
-- Click & Collect → Event API (trigger Rubix workflow)
-- Home Delivery → Batch API (bulk processing)
-- Store Pickup → GraphQL mutation (immediate processing)
-
-```typescript
-import { createClient, FluentEvent, FluentBatchPayload } from '@fluentcommerce/fc-connect-sdk';
-
-async function routeOrders(orders: any[], ctx: any, log: any) {
-  const client = await createClient({ ...ctx, log });
-
-  for (const order of orders) {
-    const orderType = order.attributes?.find((a: any) => a.name === 'type')?.value;
-
-    // ROUTING LOGIC
-    switch (orderType) {
-      case 'CLICK_AND_COLLECT':
-        // Route to Event API → Triggers Rubix workflow
-        const event: FluentEvent = {
-          name: 'order.created',
-          entityType: 'ORDER',
-          entityRef: order.ref,
-          retailerId: order.retailerId,
-          attributes: order.attributes
-        };
-        await client.sendEvent(event, 'async');
-        log.info('Order routed to Event API', { ref: order.ref, type: orderType });
-        break;
-
-      case 'HOME_DELIVERY':
-        // Route to Event API → Trigger workflow (Batch API only supports INVENTORY)
-        const event: FluentEvent = {
-          name: 'order.created',
-          entityType: 'ORDER',
-          entityRef: order.ref,
-          retailerId: order.retailerId,
-          attributes: order.attributes
-        };
-        await client.sendEvent(event, 'async');
-        log.info('Order routed to Event API', { ref: order.ref, type: orderType });
-        break;
-
-      case 'STORE_PICKUP':
-        // Route to GraphQL → Immediate processing
-        const mutation = `
-          mutation CreateOrder($input: CreateOrderInput!) {
-            createOrder(input: $input) {
-              id
-              ref
-              status
-            }
-          }
-        `;
-
-        await client.mutate(mutation, { input: order });
-        log.info('Order routed to GraphQL', { ref: order.ref });
-        break;
-
-      default:
-        log.warn('Unknown order type - routing to default Event API', { ref: order.ref, type: orderType });
-        // Default route to Event API (Batch API only supports INVENTORY)
-        const defaultEvent: FluentEvent = {
-          name: 'order.created',
-          entityType: 'ORDER',
-          entityRef: order.ref,
-          retailerId: order.retailerId,
-          attributes: order.attributes
-        };
-        await client.sendEvent(defaultEvent, 'async');
-    }
-  }
-}
-```
-
-**When to Use:**
-- Multiple destination APIs for different message types
-- Order type dictates processing workflow (express, standard, backorder)
-- Inventory updates need different handling by location type (store, warehouse, virtual)
-
----
-
-### 2. Content-Based Router
-
-**Pattern:** Route messages based on content inspection (attributes, fields, computed values).
-
-**Support Status:** ✅ **Fully Supported** - Can be built using `UniversalMapper` and application logic
-
-**SDK Building Blocks:**
-- `UniversalMapper` - Extract and transform routing criteria
-- Conditional logic based on extracted values
-
-#### Use Case: Inventory Distribution by Quantity
-
-**Business Problem:** High-volume inventory updates should use Batch API for efficiency, while low-quantity alerts need immediate processing via GraphQL to trigger restocking workflows.
-
-Route inventory updates based on available quantity:
-- High quantity (>1000) → Batch API (efficient bulk updates)
-- Medium quantity (100-1000) → Event API (standard processing)
-- Low quantity (<100) → GraphQL + Event (immediate alert + workflow trigger)
-
-```typescript
-import { createClient, UniversalMapper, FluentBatchPayload } from '@fluentcommerce/fc-connect-sdk';
-
-async function routeInventoryUpdates(inventoryData: any[], ctx: any, log: any) {
-  const client = await createClient({ ...ctx, log });
-
-  // Extract routing criteria using UniversalMapper
-  const mapper = new UniversalMapper({
-    fields: {
-      skuRef: { source: 'sku', required: true },
-      locationRef: { source: 'location', required: true },
-      qty: { source: 'quantity', resolver: 'sdk.parseInt', required: true },
-      availableQty: { source: 'available', resolver: 'sdk.parseInt' }
-    }
-  });
-
-  const highQtyBatch: any[] = [];
-  const mediumQtyEvents: any[] = [];
-  const lowQtyAlerts: any[] = [];
-
-  // Content-based routing logic
-  for (const item of inventoryData) {
-    const mapped = await mapper.map(item);
-    if (!mapped.success) {
-      log.error('Mapping failed', { item, errors: mapped.errors });
-      continue;
-    }
-
-    const qty = mapped.data.qty;
-
-    if (qty > 1000) {
-      // HIGH QUANTITY → Batch API
-      highQtyBatch.push({
-        ref: `${mapped.data.locationRef}:${mapped.data.skuRef}`,
-        type: 'INVENTORY',
-        locationRef: mapped.data.locationRef,
-        skuRef: mapped.data.skuRef,
-        qty,
-        status: 'ACTIVE'
-      });
-    } else if (qty >= 100) {
-      // MEDIUM QUANTITY → Event API
-      mediumQtyEvents.push({
-        name: 'inventory.updated',
-        entityType: 'INVENTORY_QUANTITY',
-        entityRef: `${mapped.data.locationRef}:${mapped.data.skuRef}`,
-        retailerId: ctx.activation.getVariable('fluentRetailerId'),
-        attributes: [
-          { name: 'qty', type: 'INTEGER', value: qty },
-          { name: 'locationRef', type: 'STRING', value: mapped.data.locationRef }
-        ]
-      });
-    } else {
-      // LOW QUANTITY → GraphQL + Event (alert)
-      lowQtyAlerts.push(mapped.data);
-    }
-  }
-
-  // Execute routing destinations
-  if (highQtyBatch.length > 0) {
-    const job = await client.createJob({
-      name: `high-qty-inventory-${Date.now()}`,
-      retailerId: ctx.activation.getVariable('fluentRetailerId')
-    });
-
-    await client.sendBatch(job.id, {
-      entityType: 'INVENTORY',
-      entities: highQtyBatch,
-      action: 'UPSERT'
-    });
-
-    log.info('High quantity inventory routed to Batch API', { count: highQtyBatch.length });
-  }
-
-  if (mediumQtyEvents.length > 0) {
-    for (const event of mediumQtyEvents) {
-      await client.sendEvent(event, 'async');
-    }
-    log.info('Medium quantity inventory routed to Event API', { count: mediumQtyEvents.length });
-  }
-
-  if (lowQtyAlerts.length > 0) {
-    // Send low stock alert via GraphQL + Event
-    for (const alert of lowQtyAlerts) {
-      const mutation = `
-        mutation TriggerLowStockAlert($locationRef: String!, $skuRef: String!, $qty: Int!) {
-          createEvent(input: {
-            name: "inventory.low_stock_alert"
-            entityType: INVENTORY_QUANTITY
-            entityRef: $locationRef
-            attributes: [
-              { name: "skuRef", type: STRING, value: $skuRef }
-              { name: "qty", type: INTEGER, value: $qty }
-            ]
-          }) {
-            id
-          }
-        }
-      `;
-
-      await client.graphql({
-        query: mutation,
-        variables: {
-          locationRef: alert.locationRef,
-          skuRef: alert.skuRef,
-          qty: alert.qty
-        }
-      });
-    }
-    log.warn('Low quantity alerts sent', { count: lowQtyAlerts.length });
-  }
-}
-```
-
-**When to Use:**
-- Routing depends on data values (quantity thresholds, priority levels)
-- Different SLAs based on order value or customer tier
-- Inventory allocation strategies based on location characteristics
-
----
-
-## Transformation Patterns
-
-### 3. Content Enricher
-
-**Pattern:** Enhance message with additional data from external sources.
-
-**Support Status:** ✅ **Fully Supported** - Can be built using `FluentClient.graphql()` and `UniversalMapper` with custom resolvers
-
-**SDK Building Blocks:**
-- `FluentClient.graphql()` - Fetch enrichment data
-- `UniversalMapper` - Merge enriched data
-- Custom resolvers - Complex enrichment logic
-
-#### Use Case: Enrich Order Data with Product Details
-
-**Business Problem:** Order webhooks from external systems contain only SKU references. Fulfilment workflows need product names, weights, and categories for shipping calculations and packaging decisions.
-
-Enrich order line items with product information (name, category, weight) fetched from Fluent GraphQL.
-
-```typescript
-import { createClient, UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-
-async function enrichOrdersWithProductData(orders: any[], ctx: any, log: any) {
-  const client = await createClient({ ...ctx, log });
-
-  // STEP 1: Fetch all product data in one GraphQL query
-  const skuRefs = [...new Set(
-    orders.flatMap(o => o.items?.map((i: any) => i.skuRef) || [])
-  )];
-
-  const query = `
-    query GetProducts($skuRefs: [String!]!) {
-      products(skuRefs: $skuRefs) {
-        edges {
-          node {
-            ref
-            name
-            attributes {
-              name
-              type
-              value
-            }
-          }
-        }
-      }
-    }
-  `;
-
-  const response = await client.graphql({ query, variables: { skuRefs } });
-
-  // Build lookup map for fast enrichment
-  const productMap = new Map();
-  response.data?.products?.edges?.forEach((edge: any) => {
-    const product = edge.node;
-    productMap.set(product.ref, {
-      name: product.name,
-      category: product.attributes?.find((a: any) => a.name === 'category')?.value || 'UNCATEGORIZED',
-      weight: parseFloat(product.attributes?.find((a: any) => a.name === 'weight')?.value || '0')
-    });
-  });
-
-  // STEP 2: Enrich order items with product data
-  const enrichedOrders = orders.map(order => {
-    const enrichedItems = order.items?.map((item: any) => {
-      const productData = productMap.get(item.skuRef);
-
-      return {
-        ...item,
-        // ENRICHMENT: Add product details
-        productName: productData?.name || 'Unknown Product',
-        productCategory: productData?.category || 'UNCATEGORIZED',
-        productWeight: productData?.weight || 0,
-        // Computed fields based on enriched data
-        lineWeight: (productData?.weight || 0) * (item.quantity || 1),
-        isHeavyItem: (productData?.weight || 0) > 10 // kg
-      };
-    });
-
-    return {
-      ...order,
-      items: enrichedItems,
-      // Order-level computed fields
-      totalWeight: enrichedItems.reduce((sum: number, item: any) => sum + (item.lineWeight || 0), 0),
-      hasHeavyItems: enrichedItems.some((item: any) => item.isHeavyItem)
-    };
-  });
-
-  log.info('Orders enriched with product data', {
-    orderCount: orders.length,
-    productCount: productMap.size
-  });
-
-  return enrichedOrders;
-}
-```
-
-**When to Use:**
-- Order processing needs product details (dimensions, weight, hazmat flags)
-- Inventory updates require location metadata (type, capacity, zone)
-- Fulfilment workflows need customer preferences or address validation
-
----
-
-### 4. Message Translator
-
-**Pattern:** Convert message format from one schema to another.
-
-**Support Status:** ✅ **Fully Supported** - Core SDK capability via Parsers + `UniversalMapper` + Builders
-
-**SDK Building Blocks:**
-- `XMLParserService` - Parse XML input
-- `CSVParserService` - Parse CSV input
-- `JSONParserService` - Parse JSON input
-- `UniversalMapper` - Transform to Fluent schema
-- `XMLBuilder` / `CSVBuilder` - Build output format
-
-#### Use Case: Translate External Inventory CSV to Fluent Batch Format
-
-**Business Problem:** Supplier systems export inventory data in custom CSV formats with different field names (e.g., `supplier_sku`, `warehouse_code`, `on_hand`). Fluent Commerce requires standard field names (`skuRef`, `locationRef`, `qty`).
-
-Translate supplier CSV format to Fluent Batch API format.
-
-```typescript
-import {
-  SftpDataSource,
-  CSVParserService,
-  UniversalMapper,
-  createClient,
-  FluentBatchPayload
-} from '@fluentcommerce/fc-connect-sdk';
-
-async function translateInventoryCsvToBatch(ctx: any, log: any) {
-  const client = await createClient({ ...ctx, log });
-
-  // STEP 1: Read source data (supplier CSV format)
-  const sftp = new SftpDataSource({
-    type: 'SFTP_CSV',
-    settings: {
-      host: ctx.activation.getVariable('sftpHost'),
-      username: ctx.activation.getVariable('sftpUsername'),
-      password: ctx.activation.getVariable('sftpPassword'),
-      remotePath: '/inbound/inventory',
-      filePattern: '*.csv'
-    }
-  }, log);
-
-  try {
-    const files = await sftp.listFiles();
-    if (files.length === 0) {
-      log.info('No files to process');
-      return;
-    }
-
-    const csvContent = await sftp.downloadFile(files[0].name, { encoding: 'utf8' }) as string;
-
-    // STEP 2: Parse source format
-    const csvParser = new CSVParserService(log);
-    const parsedData = await csvParser.parse(csvContent, {
-      delimiter: ',',
-      columns: true,
-      skip_empty_lines: true
-    });
-
-    // Source format: supplier_sku, warehouse_code, on_hand, available, reserved
-    log.info('Parsed supplier CSV', { recordCount: parsedData.length });
-
-    // STEP 3: Translate to Fluent schema using UniversalMapper
-    const mapper = new UniversalMapper({
-      fields: {
-        // TRANSLATION RULES
-        ref: {
-          resolver: 'custom.buildCompositeKey',
-          required: true
-        },
-        type: {
-          value: 'INVENTORY_QUANTITY', // Static value for Batch API
-          required: true
-        },
-        locationRef: {
-          source: 'warehouse_code',
-          resolver: 'sdk.uppercase', // Normalize location ref
-          required: true
-        },
-        skuRef: {
-          source: 'supplier_sku',
-          resolver: 'sdk.trim', // Clean whitespace
-          required: true
-        },
-        qty: {
-          source: 'available', // Map 'available' → 'qty'
-          resolver: 'sdk.parseInt',
-          required: true
-        },
-        onHand: {
-          source: 'on_hand',
-          resolver: 'sdk.parseInt'
-        },
-        reserved: {
-          source: 'reserved',
-          resolver: 'sdk.parseInt',
-          defaultValue: 0 // Default if missing
-        }
-      }
-    }, {
-      customResolvers: {
-        // Custom resolver to build composite key
-        'custom.buildCompositeKey': (value: any, context: any) => {
-          return `${context.warehouse_code}:${context.supplier_sku}`;
-        }
-      }
-    });
-
-    const translatedEntities = [];
-    for (const record of parsedData) {
-      const result = await mapper.map(record);
-      if (result.success) {
-        translatedEntities.push(result.data);
-      } else {
-        log.error('Translation failed', { record, errors: result.errors });
-      }
-    }
-
-    // STEP 4: Send translated data to Fluent Batch API
-    if (translatedEntities.length > 0) {
-      const job = await client.createJob({
-        name: `inventory-translation-${Date.now()}`,
-        retailerId: ctx.activation.getVariable('fluentRetailerId')
-      });
-
-      const batch: FluentBatchPayload = {
-        entityType: 'INVENTORY',
-        entities: translatedEntities,
-        action: 'UPSERT'
-      };
-
-      await client.sendBatch(job.id, batch);
-
-      log.info('Inventory translated and sent to Batch API', {
-        sourceRecords: parsedData.length,
-        translatedEntities: translatedEntities.length,
-        jobId: job.id
-      });
-    }
-  } finally {
-    await sftp.dispose();
-  }
-}
-```
-
-**When to Use:**
-- Supplier data formats differ from Fluent schema
-- Multiple source systems with different CSV/XML structures
-- Legacy system integration with non-standard formats
-
----
-
-### 5. Splitter
-
-**Pattern:** Break a single message into multiple messages for parallel processing.
-
-**Support Status:** ✅ **Fully Supported** - Can be built using Parsers (automatic splitting) + `Promise.all()` for parallel processing
-
-**SDK Building Blocks:**
-- `FluentClient.sendBatch()` - Split into multiple batches
-- `Promise.all()` - Parallel execution
-- `UniversalMapper` with array handling
-- Parsers automatically split files into records
-
-#### Use Case: Split Large Inventory File into Parallel Batches
-
-**Business Problem:** Daily inventory export files contain 50,000+ inventory positions. Processing sequentially would take hours. Need to split into chunks and process in parallel to meet SLA requirements.
-
-**Note:** Batch API only supports `INVENTORY` entities. For orders, use GraphQL mutations with parallel processing instead.
-
-Process a large inventory file by splitting into chunks and sending parallel batches.
-
-```typescript
-import {
-  S3DataSource,
-  XMLParserService,
-  UniversalMapper,
-  createClient,
-  FluentBatchPayload
-} from '@fluentcommerce/fc-connect-sdk';
-
-async function splitOrdersIntoParallelBatches(ctx: any, log: any) {
-  const client = await createClient({ ...ctx, log });
-
-  // STEP 1: Read large inventory file from S3
-  const s3 = new S3DataSource({
-    type: 'S3_XML',
-    s3Config: {
-      bucket: ctx.activation.getVariable('s3Bucket'),
-      region: ctx.activation.getVariable('awsRegion'),
-      accessKeyId: ctx.activation.getVariable('awsAccessKeyId'),
-      secretAccessKey: ctx.activation.getVariable('awsSecretAccessKey')
-    }
-  }, log);
-
-  const xmlContent = await s3.downloadFile('inventory/inventory-batch-large.xml', { encoding: 'utf8' }) as string;
-
-  // STEP 2: Parse XML
-  const xmlParser = new XMLParserService(log);
-  const parsed = await xmlParser.parse(xmlContent);
-
-  const rawInventory = Array.isArray(parsed.inventory?.position)
-    ? parsed.inventory.position
-    : [parsed.inventory?.position];
-
-  log.info('Parsed large inventory file', { totalPositions: rawInventory.length });
-
-  // STEP 3: Map inventory positions to Fluent format
-  const mapper = new UniversalMapper({
-    fields: {
-      ref: {
-        resolver: 'custom.buildRef',
-        required: true
-      },
-      locationRef: { source: '@location', required: true },
-      skuRef: { source: 'sku', required: true },
-      qty: { source: 'quantity', resolver: 'sdk.parseInt', required: true },
-      status: { source: 'status', defaultValue: 'ACTIVE' }
-    }
-  }, {
-    customResolvers: {
-      // Custom resolver to build composite key from location and SKU
-      'custom.buildRef': (value: any, context: any) => {
-        const location = context['@location'] || context.location;
-        const sku = context.sku;
-        return `${location}:${sku}`;
-      }
-    }
-  });
-
-  const mappedInventory = [];
-  for (const position of rawInventory) {
-    const result = await mapper.map(position);
-    if (result.success) {
-      mappedInventory.push(result.data);
-    }
-  }
-
-  // STEP 4: SPLIT into chunks (batches of 500)
-  const BATCH_SIZE = 500;
-  const chunks = [];
-  for (let i = 0; i < mappedInventory.length; i += BATCH_SIZE) {
-    chunks.push(mappedInventory.slice(i, i + BATCH_SIZE));
-  }
-
-  log.info('Split inventory into chunks', {
-    totalPositions: mappedInventory.length,
-    chunkCount: chunks.length,
-    batchSize: BATCH_SIZE
-  });
-
-  // STEP 5: Create job for all batches
-  // Note: Batch API only supports INVENTORY entities, not ORDER
-  // For orders, use GraphQL mutations instead (see below)
-  // This example shows splitting for inventory entities
-  const job = await client.createJob({
-    name: `inventory-split-${Date.now()}`,
-    retailerId: ctx.activation.getVariable('fluentRetailerId')
-  });
-
-  // STEP 6: Send chunks in parallel
-  const batchPromises = chunks.map(async (chunk, index) => {
-    const batch: FluentBatchPayload = {
-      entityType: 'INVENTORY',
-      entities: chunk,
-      action: 'UPSERT'
-    };
-
-    const batchResponse = await client.sendBatch(job.id, batch);
-    log.info(`Batch ${index + 1}/${chunks.length} sent`, {
-      batchId: batchResponse.id,
-      entityCount: chunk.length
-    });
-
-    return batchResponse;
-  });
-
-  // Wait for all batches to complete
-  const batchResponses = await Promise.all(batchPromises);
-
-  log.info('All inventory batches sent successfully', {
-    jobId: job.id,
-    totalBatches: batchResponses.length,
-    totalPositions: mappedInventory.length
-  });
-
-  return { jobId: job.id, batchCount: batchResponses.length };
-}
-```
-
-**When to Use:**
-- Large inventory files exceed single batch limits (>10K records)
-- Parallel processing improves throughput
-- Different chunks need different processing strategies
-
-**Note:** For orders, use GraphQL mutations with `Promise.all()` for parallel processing instead of Batch API.
-
----
-
-### 6. Aggregator
-
-**Pattern:** Combine multiple related messages into a single message.
-
-**Support Status:** ✅ **Fully Supported** - Can be built using `FluentClient.graphql()` with pagination + application aggregation logic
-
-**SDK Building Blocks:**
-- `FluentClient.graphql()` with pagination - Fetch multiple pages
-- `StateService` - Track aggregation state
-- Array aggregation logic
-
-#### Use Case: Aggregate Virtual Position Data from Multiple Locations
-
-**Business Problem:** Inventory positions are stored per location (warehouse, store, virtual). Reporting dashboard needs aggregated view showing total quantity across all locations for each SKU.
-
-Aggregate inventory positions across all locations for a single SKU view.
-
-```typescript
-import { createClient, StateService, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
-
-async function aggregateVirtualPositions(skuRefs: string[], ctx: any, log: any) {
-  const client = await createClient({ ...ctx, log });
-
-  // STEP 1: Query virtual positions across all locations (with pagination)
-  const query = `
-    query GetVirtualPositions($skuRefs: [String!]!, $first: Int!, $after: String) {
-      virtualPositions(skuRefs: $skuRefs, first: $first, after: $after) {
-        edges {
-          node {
-            ref
-            quantity
-            groupRef
-            productRef
-            virtualCatalogueRef
-          }
-          cursor
-        }
-        pageInfo {
-          hasNextPage
-          endCursor
-        }
-      }
-    }
-  `;
-
-  const response = await client.graphql({
-    query,
-    variables: { skuRefs, first: 1000 },
-    pagination: {
-      enabled: true,
-      maxPages: 10,
-      direction: 'forward'
-    }
-  });
-
-  const allPositions = response.data?.virtualPositions?.edges?.map((e: any) => e.node) || [];
-
-  log.info('Fetched virtual positions', {
-    totalPositions: allPositions.length,
-    skuCount: skuRefs.length,
-    paginationStats: response.extensions?.autoPagination
-  });
-
-  // STEP 2: AGGREGATE positions by SKU
-  const aggregatedBySku = new Map<string, {
-    skuRef: string;
-    totalQuantity: number;
-    locations: string[];
-    catalogues: string[];
-  }>();
-
-  for (const position of allPositions) {
-    const skuRef = position.productRef;
-
-    if (!aggregatedBySku.has(skuRef)) {
-      aggregatedBySku.set(skuRef, {
-        skuRef,
-        totalQuantity: 0,
-        locations: [],
-        catalogues: []
-      });
-    }
-
-    const agg = aggregatedBySku.get(skuRef)!;
-    agg.totalQuantity += position.quantity || 0;
-
-    if (position.groupRef && !agg.locations.includes(position.groupRef)) {
-      agg.locations.push(position.groupRef);
-    }
-
-    if (position.virtualCatalogueRef && !agg.catalogues.includes(position.virtualCatalogueRef)) {
-      agg.catalogues.push(position.virtualCatalogueRef);
-    }
-  }
-
-  // STEP 3: Convert to array and compute metrics
-  const aggregatedResults = Array.from(aggregatedBySku.values()).map(agg => ({
-    ...agg,
-    locationCount: agg.locations.length,
-    catalogueCount: agg.catalogues.length,
-    avgQuantityPerLocation: agg.totalQuantity / agg.locations.length
-  }));
-
-  log.info('Aggregation complete', {
-    totalSKUs: aggregatedResults.length,
-    totalQuantity: aggregatedResults.reduce((sum, r) => sum + r.totalQuantity, 0)
-  });
-
-  // STEP 4: Store aggregated results in KV for later retrieval
-  const kv = ctx.openKv(':project:');
-  const stateService = new StateService(log);
-
-  for (const result of aggregatedResults) {
-    await kv.set(['aggregated_inventory', result.skuRef], result);
-  }
-
-  log.info('Aggregated results stored in KV', { skuCount: aggregatedResults.length });
-
-  return aggregatedResults;
-}
-```
-
-**When to Use:**
-- Inventory views need multi-location aggregation
-- Order totals calculated from multiple line items
-- Reporting requires data from multiple API calls
-
----
-
-## Endpoint Patterns
-
-### 7. Polling Consumer
-
-**Pattern:** Periodically poll an endpoint for new messages.
-
-**Support Status:** ✅ **Fully Supported** - Can be built using Versori `schedule()` + `Data Sources` + `StateService` for tracking
-
-**SDK Building Blocks:**
-- `schedule()` from `@versori/run` - Scheduled execution
-- `StateService` - Track last poll time
-- `SftpDataSource.listFiles()` - Poll for new files
-- `S3DataSource.listFiles()` - Poll S3 buckets
-
-#### Use Case: Poll SFTP for New Inventory Files
-
-**Business Problem:** Supplier systems don't support webhooks. They drop CSV files to SFTP every 2 hours. Need to check for new files periodically and process them without duplicate processing.
-
-Check SFTP every 2 hours for new inventory files, process only new files.
-
-```typescript
-import { schedule } from '@versori/run';
-import {
-  SftpDataSource,
-  CSVParserService,
-  UniversalMapper,
-  createClient,
-  StateService,
-  FluentBatchPayload
-} from '@fluentcommerce/fc-connect-sdk';
-
-export const pollSftpInventory = schedule('poll-sftp-inventory', '0 */2 * * *', async (ctx) => {
-  const { log, openKv, activation } = ctx;
-  const client = await createClient({ ...ctx, log });
-
-  // STEP 1: Connect to SFTP
-  const sftp = new SftpDataSource({
-    type: 'SFTP_CSV',
-    settings: {
-      host: activation.getVariable('sftpHost'),
-      username: activation.getVariable('sftpUsername'),
-      password: activation.getVariable('sftpPassword'),
-      remotePath: '/outbound/inventory',
-      filePattern: 'inventory_*.csv'
-    }
-  }, log);
-
-  try {
-    // STEP 2: Poll for files
-    const files = await sftp.listFiles();
-    log.info('Polled SFTP for inventory files', { fileCount: files.length });
-
-    if (files.length === 0) {
-      log.info('No new files found');
-      return { status: 'no_files' };
-    }
-
-    // STEP 3: Check state to identify new files
-    const kv = openKv(':project:');
-    const stateService = new StateService(log);
-
-    const newFiles = [];
-    for (const file of files) {
-      const isProcessed = await kv.get(['processed_files', file.name]);
-      if (!isProcessed) {
-        newFiles.push(file);
-      }
-    }
-
-    log.info('Identified new files', { newFileCount: newFiles.length });
-
-    if (newFiles.length === 0) {
-      return { status: 'no_new_files' };
-    }
-
-    // STEP 4: Process new files
-    const csvParser = new CSVParserService(log);
-    const mapper = new UniversalMapper({
-      fields: {
-        ref: { source: 'location_sku', required: true },
-        type: { value: 'INVENTORY_QUANTITY', required: true },
-        locationRef: { source: 'location', required: true },
-        skuRef: { source: 'sku', required: true },
-        qty: { source: 'quantity', resolver: 'sdk.parseInt', required: true }
-      }
-    });
-
-    let totalEntities = 0;
-
-    for (const file of newFiles) {
-      try {
-        const csvContent = await sftp.downloadFile(file.name, { encoding: 'utf8' }) as string;
-        const parsed = await csvParser.parse(csvContent, { columns: true });
-
-        const entities = [];
-        for (const record of parsed) {
-          const result = await mapper.map(record);
-          if (result.success) {
-            entities.push(result.data);
-          }
-        }
-
-        if (entities.length > 0) {
-          const job = await client.createJob({
-            name: `inventory-poll-${file.name}-${Date.now()}`,
-            retailerId: activation.getVariable('fluentRetailerId')
-          });
-
-          await client.sendBatch(job.id, {
-            entityType: 'INVENTORY',
-            entities,
-            action: 'UPSERT'
-          });
-
-          totalEntities += entities.length;
-        }
-
-        // Mark file as processed
-        await kv.set(['processed_files', file.name], {
-          processedAt: new Date().toISOString(),
-          entityCount: entities.length
-        });
-
-        log.info('File processed successfully', { file: file.name, entities: entities.length });
-      } catch (error) {
-        log.error(`Failed to process file: ${file.name}`, error as Error);
-      }
-    }
-
-    return {
-      status: 'success',
-      filesProcessed: newFiles.length,
-      totalEntities
-    };
-  } finally {
-    await sftp.dispose();
-  }
-});
-```
-
-**When to Use:**
-- Supplier systems don't support webhooks (push notifications)
-- Scheduled file drops to SFTP/S3 (daily inventory snapshots)
-- Periodic API polling for new orders/fulfilments
-
----
-
-### 8. Idempotent Receiver
-
-**Pattern:** Ensure messages are processed exactly once, even if received multiple times.
-
-**Support Status:** ✅ **Fully Supported** - Can be built using KV Store + `StateService` for idempotency tracking
-
-**SDK Building Blocks:**
-- `StateService` - Track processed message IDs
-- `VersoriKVAdapter` - Distributed state storage
-- KV Store (`openKv`) - Persistent state storage
-- Atomic operations for race-free checks
-
-#### Use Case: Prevent Duplicate Order Processing
-
-**Business Problem:** Webhook endpoints may receive duplicate deliveries due to network retries or webhook provider retry logic. Need to ensure each order is processed exactly once, even if webhook fires multiple times.
-
-Ensure each order is processed only once, even with webhook retries.
-
-```typescript
-import { webhook } from '@versori/run';
-import {
-  createClient,
-  StateService,
-  parseWebhookRequest,
-  FluentEvent
-} from '@fluentcommerce/fc-connect-sdk';
-
-export const processOrderWebhook = webhook('process-order', {
-  response: { mode: 'sync' }
-}, async (ctx) => {
-  const { log, openKv, request } = ctx;
-  const client = await createClient({ ...ctx, log });
-
-  // STEP 1: Parse webhook payload
-  const webhookPayload = await parseWebhookRequest(request);
-  const orderRef = webhookPayload.entityRef;
-  const eventId = webhookPayload.id;
-
-  log.info('Received order webhook', { orderRef, eventId });
-
-  // STEP 2: IDEMPOTENCY CHECK - Has this event been processed?
-  const kv = openKv(':project:');
-  const processingKey = ['processed_events', eventId];
-
-  const existingRecord = await kv.get(processingKey);
-  if (existingRecord?.value) {
-    log.warn('Event already processed - skipping', {
-      eventId,
-      orderRef,
-      processedAt: (existingRecord.value as any).processedAt
-    });
-
-    return new Response(JSON.stringify({
-      status: 'already_processed',
-      eventId,
-      processedAt: (existingRecord.value as any).processedAt
-    }), {
-      status: 200,
-      headers: { 'Content-Type': 'application/json' }
-    });
-  }
-
-  // STEP 3: Process order (business logic)
-  try {
-    // Fetch order details
-    const query = `
-      query GetOrder($ref: String!) {
-        order(ref: $ref) {
-          id
-          ref
-          status
-          totalPrice
-          items {
-            edges {
-              node {
-                ref
-                quantity
-                product {
-                  ref
-                  name
-                }
-              }
-            }
-          }
-        }
-      }
-    `;
-
-    const response = await client.graphql({
-      query,
-      variables: { ref: orderRef }
-    });
-
-    const order = response.data?.order;
-
-    if (!order) {
-      throw new Error(`Order not found: ${orderRef}`);
-    }
-
-    // Business logic: Send fulfilment event if order is confirmed
-    if (order.status === 'CONFIRMED') {
-      const event: FluentEvent = {
-        name: 'order.ready_for_fulfilment',
-        entityType: 'ORDER',
-        entityRef: orderRef,
-        retailerId: webhookPayload.retailerId,
-        attributes: [
-          { name: 'totalPrice', type: 'FLOAT', value: order.totalPrice },
-          { name: 'itemCount', type: 'INTEGER', value: order.items?.edges?.length || 0 }
-        ]
-      };
-
-      await client.sendEvent(event, 'async');
-    }
-
-    // STEP 4: Mark event as processed (IDEMPOTENCY RECORD)
-    await kv.set(processingKey, {
-      processedAt: new Date().toISOString(),
-      orderRef,
-      eventId,
-      status: 'success'
-    });
-
-    log.info('Order processed successfully', { orderRef, eventId });
-
-    return new Response(JSON.stringify({
-      status: 'processed',
-      orderRef,
-      eventId
-    }), {
-      status: 200,
-      headers: { 'Content-Type': 'application/json' }
-    });
-  } catch (error) {
-    log.error('Order processing failed', error as Error, { orderRef, eventId });
-
-    // Don't mark as processed on failure - allow retry
-    return new Response(JSON.stringify({
-      status: 'error',
-      message: (error as Error).message
-    }), {
-      status: 500,
-      headers: { 'Content-Type': 'application/json' }
-    });
-  }
-});
-```
-
-**When to Use:**
-- Webhook endpoints that may receive duplicate deliveries
-- File processing where same file might be reprocessed
-- Distributed workflows with at-least-once delivery guarantees
-
----
-
-## System Management Patterns
-
-### 9. Dead Letter Channel
-
-**Pattern:** Route failed messages to a separate channel for inspection and reprocessing.
-
-**Support Status:** ✅ **Fully Supported** - Can be built using `S3DataSource` or `SftpDataSource` for failed message storage
-
-**SDK Building Blocks:**
-- `S3DataSource.uploadFile()` - Write failed messages to S3
-- `SftpDataSource.writeFile()` - Write failed messages to SFTP
-- `StateService` - Track failure counts
-- Error handling with try/catch
-
-#### Use Case: Route Failed Inventory Updates to Dead Letter S3 Bucket
-
-**Business Problem:** Some inventory records fail validation (missing SKU, invalid quantity, etc.). Need to capture these failures for manual review and potential reprocessing without blocking successful records.
-
-Capture failed inventory records for manual review and reprocessing.
-
-```typescript
-import {
-  SftpDataSource,
-  CSVParserService,
-  UniversalMapper,
-  S3DataSource,
-  createClient,
-  FluentBatchPayload
-} from '@fluentcommerce/fc-connect-sdk';
-import { Buffer } from 'node:buffer';
-
-async function processInventoryWithDeadLetterChannel(ctx: any, log: any) {
-  const client = await createClient({ ...ctx, log });
-
-  // Setup: SFTP source, S3 dead letter destination
-  const sftp = new SftpDataSource({
-    type: 'SFTP_CSV',
-    settings: {
-      host: ctx.activation.getVariable('sftpHost'),
-      username: ctx.activation.getVariable('sftpUsername'),
-      password: ctx.activation.getVariable('sftpPassword'),
-      remotePath: '/inbound/inventory',
-      filePattern: '*.csv'
-    }
-  }, log);
-
-  const deadLetterS3 = new S3DataSource({
-    type: 'S3_JSON',
-    s3Config: {
-      bucket: ctx.activation.getVariable('deadLetterBucket'),
-      region: ctx.activation.getVariable('awsRegion'),
-      accessKeyId: ctx.activation.getVariable('awsAccessKeyId'),
-      secretAccessKey: ctx.activation.getVariable('awsSecretAccessKey')
-    }
-  }, log);
-
-  try {
-    const files = await sftp.listFiles();
-    if (files.length === 0) {
-      log.info('No files to process');
-      return;
-    }
-
-    const csvContent = await sftp.downloadFile(files[0].name, { encoding: 'utf8' }) as string;
-    const csvParser = new CSVParserService(log);
-    const parsed = await csvParser.parse(csvContent, { columns: true });
-
-    // Map inventory records
-    const mapper = new UniversalMapper({
-      fields: {
-        ref: { source: 'location_sku', required: true },
-        type: { value: 'INVENTORY_QUANTITY', required: true },
-        locationRef: { source: 'location', required: true },
-        skuRef: { source: 'sku', required: true },
-        qty: { source: 'quantity', resolver: 'sdk.parseInt', required: true }
-      }
-    });
-
-    const successfulEntities = [];
-    const failedRecords = [];
-
-    // Process records with error tracking
-    for (const record of parsed) {
-      try {
-        const result = await mapper.map(record);
-        if (result.success) {
-          successfulEntities.push(result.data);
-        } else {
-          // DEAD LETTER: Mapping validation failed
-          failedRecords.push({
-            sourceRecord: record,
-            errors: result.errors,
-            failureReason: 'mapping_validation_failed',
-            failedAt: new Date().toISOString()
-          });
-        }
-      } catch (error) {
-        // DEAD LETTER: Unexpected error during mapping
-        failedRecords.push({
-          sourceRecord: record,
-          errors: [(error as Error).message],
-          failureReason: 'mapping_error',
-          failedAt: new Date().toISOString(),
-          errorStack: (error as Error).stack
-        });
-      }
-    }
-
-    // Send successful records to Batch API
-    if (successfulEntities.length > 0) {
-      const job = await client.createJob({
-        name: `inventory-with-dlq-${Date.now()}`,
-        retailerId: ctx.activation.getVariable('fluentRetailerId')
-      });
-
-      await client.sendBatch(job.id, {
-        entityType: 'INVENTORY',
-        entities: successfulEntities,
-        action: 'UPSERT'
-      });
-
-      log.info('Successful entities sent to Batch API', {
-        count: successfulEntities.length,
-        jobId: job.id
-      });
-    }
-
-    // DEAD LETTER CHANNEL: Write failed records to S3
-    if (failedRecords.length > 0) {
-      const deadLetterKey = `failed-inventory/${files[0].name}-failures-${Date.now()}.json`;
-      const deadLetterContent = JSON.stringify({
-        sourceFile: files[0].name,
-        failedAt: new Date().toISOString(),
-        totalFailed: failedRecords.length,
-        records: failedRecords
-      }, null, 2);
-
-      await deadLetterS3.uploadFile(
-        deadLetterKey,
-        Buffer.from(deadLetterContent, 'utf-8')
-      );
-
-      log.warn('Failed records written to Dead Letter S3', {
-        count: failedRecords.length,
-        deadLetterKey
-      });
-    }
-
-    return {
-      successful: successfulEntities.length,
-      failed: failedRecords.length,
-      deadLetterKey: failedRecords.length > 0 ? `failed-inventory/${files[0].name}-failures-${Date.now()}.json` : null
-    };
-  } finally {
-    await sftp.dispose();
-  }
-}
-```
-
-**When to Use:**
-- Data validation failures need manual review
-- Partial batch failures require reprocessing
-- Audit trail for failed messages is required
-
----
-
-### 10. Wire Tap
-
-**Pattern:** Inspect messages passing through without altering them (audit logging).
-
-**Support Status:** ✅ **Fully Supported** - Can be built using `S3DataSource` or logging for audit trail
-
-**SDK Building Blocks:**
-- `S3DataSource.uploadFile()` - Archive message copies
-- Logging for message inspection
-- No modification to message flow
-
-#### Use Case: Audit All Order Events Sent to Event API
-
-**Business Problem:** Compliance requirements mandate audit trail of all order events sent to Fluent Commerce. Need to log message contents without affecting processing performance or modifying message flow.
-
-Log all order events to S3 for compliance auditing.
-
-```typescript
-import {
-  createClient,
-  FluentEvent,
-  S3DataSource
-} from '@fluentcommerce/fc-connect-sdk';
-import { Buffer } from 'node:buffer';
-
-async function sendOrderEventWithAudit(orderEvent: FluentEvent, ctx: any, log: any) {
-  const client = await createClient({ ...ctx, log });
-
-  // Setup audit S3 bucket
-  const auditS3 = new S3DataSource({
-    type: 'S3_JSON',
-    s3Config: {
-      bucket: ctx.activation.getVariable('auditBucket'),
-      region: ctx.activation.getVariable('awsRegion'),
-      accessKeyId: ctx.activation.getVariable('awsAccessKeyId'),
-      secretAccessKey: ctx.activation.getVariable('awsSecretAccessKey')
-    }
-  }, log);
-
-  try {
-    // WIRE TAP: Capture message before sending (NO MODIFICATION)
-    const auditRecord = {
-      timestamp: new Date().toISOString(),
-      eventType: 'order_event',
-      direction: 'outbound',
-      destination: 'fluent_event_api',
-      payload: orderEvent,
-      metadata: {
-        entityRef: orderEvent.entityRef,
-        eventName: orderEvent.name,
-        retailerId: orderEvent.retailerId
-      }
-    };
-
-    // Write audit record to S3 (asynchronously, don't block main flow)
-    const auditKey = `audit/order-events/${orderEvent.entityRef}-${Date.now()}.json`;
-    const auditPromise = auditS3.uploadFile(
-      auditKey,
-      Buffer.from(JSON.stringify(auditRecord, null, 2), 'utf-8')
-    ).catch((error) => {
-      // Audit failure should NOT break main flow
-      log.error('Audit logging failed', error as Error, { auditKey });
-    });
-
-    // Send event to Fluent (main flow continues)
-    const eventResponse = await client.sendEvent(orderEvent, 'async');
-
-    // Wait for audit to complete (optional - for testing)
-    await auditPromise;
-
-    log.info('Order event sent with audit', {
-      entityRef: orderEvent.entityRef,
-      eventId: eventResponse,
-      auditKey
-    });
-
-    return eventResponse;
-  } finally {
-    // No disposal needed - audit is fire-and-forget
-  }
-}
-
-// Usage example
-async function processOrder(order: any, ctx: any, log: any) {
-  const orderEvent: FluentEvent = {
-    name: 'order.created',
-    entityType: 'ORDER',
-    entityRef: order.ref,
-    retailerId: order.retailerId,
-    attributes: [
-      { name: 'totalPrice', type: 'FLOAT', value: order.totalPrice },
-      { name: 'customerEmail', type: 'STRING', value: order.customer.email }
-    ]
-  };
-
-  // WIRE TAP in action - event is audited without modification
-  await sendOrderEventWithAudit(orderEvent, ctx, log);
-}
-```
-
-**When to Use:**
-- Compliance requires message audit trails
-- Debugging integration flows (inspect message contents)
-- Performance monitoring (message throughput, latency)
-
----
-
-## Pattern Summary Matrix
-
-| Pattern | Support Status | Primary Purpose | SDK Building Blocks | Fluent Use Case |
-|---------|---------------|----------------|-------------------|----------------|
-| **Message Router** | ✅ Fully Supported | Route to different APIs | `sendEvent()`, `createJob()`, `graphql()` | Route orders by type to Event/Batch/GraphQL |
-| **Content-Based Router** | ✅ Fully Supported | Route based on data values | `UniversalMapper`, conditional logic | Route inventory by quantity threshold |
-| **Content Enricher** | ✅ Fully Supported | Add data from external sources | `graphql()`, `UniversalMapper` | Enrich orders with product details |
-| **Message Translator** | ✅ Fully Supported | Convert between formats | `CSVParserService`, `UniversalMapper`, `XMLBuilder` | Translate supplier CSV to Fluent Batch format |
-| **Splitter** | ✅ Fully Supported | Break message into parts | `sendBatch()`, `Promise.all()`, Parsers | Split large order file into parallel batches |
-| **Aggregator** | ✅ Fully Supported | Combine multiple messages | `graphql()` with pagination, Map/Set | Aggregate inventory across locations |
-| **Polling Consumer** | ✅ Fully Supported | Periodic endpoint polling | `schedule()`, `SftpDataSource.listFiles()` | Poll SFTP every 2 hours for inventory files |
-| **Idempotent Receiver** | ✅ Fully Supported | Prevent duplicate processing | `StateService`, KV Store, atomic ops | Prevent duplicate webhook order processing |
-| **Dead Letter Channel** | ✅ Fully Supported | Route failed messages | `S3DataSource.uploadFile()`, error handling | Failed inventory updates to S3 for review |
-| **Wire Tap** | ✅ Fully Supported | Audit messages (no modification) | `S3DataSource.uploadFile()`, logging | Audit all order events to S3 for compliance |
-
-**Support Status Legend:**
-- ✅ **Fully Supported** - Can be built using SDK building blocks with complete examples
-- ⚠️ **Partially Supported** - Requires additional custom code beyond SDK
-- ❌ **Not Supported** - Not achievable with current SDK capabilities
-
----
-
-## Additional Resources
-
-### SDK Documentation
-- **Architecture**: `docs/04-REFERENCE/architecture/readme.md` - System design and data flow
-- **Decision Tree**: `docs/00-START-HERE/DECISION-TREE.md` - Which approach to use?
-- **Troubleshooting**: `docs/00-START-HERE/troubleshooting-quick-reference.md` - Common issues
-
-### Core Guides
-- **Ingestion**: `docs/02-CORE-GUIDES/ingestion/readme.md` - Data into Fluent
-- **Extraction**: `docs/02-CORE-GUIDES/extraction/readme.md` - Data from Fluent
-- **Mapping**: `docs/02-CORE-GUIDES/mapping/modules/` - Field transformation
-- **Webhook Validation**: `docs/02-CORE-GUIDES/webhook-validation/readme.md` - Signature validation
-
-### Pattern Guides
-- **Error Handling**: `docs/03-PATTERN-GUIDES/error-handling/readme.md` - Retry, circuit breakers
-- **File Operations**: `docs/03-PATTERN-GUIDES/file-operations/readme.md` - S3/SFTP patterns
-- **Integration Patterns**: `docs/03-PATTERN-GUIDES/integration-patterns/readme.md` - Real-time, batch, delta sync
-
-### Templates
-- **Ingestion Templates**: `docs/01-TEMPLATES/versori/scheduled/ingestion/` - Complete examples
-- **Extraction Templates**: `docs/01-TEMPLATES/versori/scheduled/extraction/` - GraphQL extraction patterns
-
----
-
-## Summary
-
-This guide demonstrated how to build 10 essential Enterprise Integration Patterns using Fluent Connect SDK building blocks:
-
-**Key Takeaways:**
-
-1. **SDK is a Toolkit** - Patterns are YOUR orchestration logic, not framework-imposed
-2. **Composable Primitives** - Combine clients, parsers, mappers, data sources to build patterns
-3. **Real Fluent Domains** - All examples use actual Order and Inventory entities
-4. **Production-Ready Code** - Every example uses real SDK methods and types
-
-**Next Steps:**
-
-- Review `docs/00-START-HERE/DECISION-TREE.md` for pattern selection guidance
-- Explore `docs/01-TEMPLATES/` for complete working implementations
-- See `docs/03-PATTERN-GUIDES/integration-patterns/` for additional pattern details
-
-**Remember:** The SDK provides the tools. YOU define the integration patterns.
-
----
-
-**Document Version:** 1.0.0
-**SDK Version:** 0.1.39
-**Last Verified:** 2025-11-05
+# Enterprise Integration Patterns with Fluent Connect SDK
+
+**Status:** Production Ready
+**Last Updated:** 2025-11-05
+**SDK Version:** 0.1.39
+
+---
+
+## Table of Contents
+
+1. [Introduction](#introduction)
+2. [Understanding the SDK as a Toolkit](#understanding-the-sdk-as-a-toolkit)
+3. [Pattern Categories](#pattern-categories)
+4. [Routing Patterns](#routing-patterns)
+5. [Transformation Patterns](#transformation-patterns)
+6. [Endpoint Patterns](#endpoint-patterns)
+7. [System Management Patterns](#system-management-patterns)
+8. [Pattern Summary Matrix](#pattern-summary-matrix)
+9. [Additional Resources](#additional-resources)
+
+---
+
+## Introduction
+
+### What is Enterprise Integration Patterns (EIP)?
+
+**Enterprise Integration Patterns (EIP)** are a collection of 65 proven design patterns for building enterprise application integration solutions. Originally documented by Gregor Hohpe and Bobby Woolf in their book ["Enterprise Integration Patterns"](https://www.enterpriseintegrationpatterns.com/), these patterns provide reusable solutions to common integration challenges.
+
+**What EIP Means in TypeScript Context:**
+
+In TypeScript/JavaScript applications, EIP patterns translate to:
+- **Composable functions and services** - Building blocks you combine to solve integration problems
+- **Message transformation** - Converting data between different formats (XML, JSON, CSV)
+- **Routing logic** - Directing messages to appropriate destinations based on content
+- **Error handling** - Managing failures and retries in distributed systems
+- **State management** - Tracking processed messages and maintaining idempotency
+
+**Key Concepts:**
+- **Patterns are solutions**, not libraries - You implement them using your toolkit
+- **SDK provides building blocks** - You compose them to create patterns
+- **TypeScript enables composition** - Functions, classes, and async/await make patterns natural
+
+**Learn More:**
+- 📚 [Enterprise Integration Patterns Book](https://www.enterpriseintegrationpatterns.com/)
+- 🌐 [EIP Pattern Catalog](https://www.enterpriseintegrationpatterns.com/patterns/messaging/)
+- 📖 [EIP Wikipedia](https://en.wikipedia.org/wiki/Enterprise_Integration_Patterns)
+
+---
+
+**Enterprise Integration Patterns (EIP)** are proven solutions to common integration challenges. This guide shows how to build these patterns using the Fluent Connect SDK's composable building blocks.
+
+### What This Guide Covers
+
+- **10 Essential EIP Patterns** with real Fluent Commerce use cases
+- **Practical SDK Implementation** using actual client methods and services
+- **Order & Inventory Domain Examples** - the two primary Fluent Commerce domains
+- **Support Status** - Whether each pattern can be built with SDK building blocks
+- **Use-Case-Driven Approach** - Real-world scenarios for each pattern
+
+### Prerequisites
+
+- Understanding of SDK architecture (see `docs/00-START-HERE/SDK-PHILOSOPHY.md`)
+- Familiarity with Fluent Commerce entities (Order, Fulfilment, Inventory)
+- Basic knowledge of GraphQL and Batch API concepts
+
+---
+
+## Understanding the SDK as a Toolkit
+
+> **The SDK provides services with methods. YOU build the workflow.**
+
+The FC Connect SDK is **not an opinionated framework** - it's a **toolkit of composable primitives**. Enterprise Integration Patterns are YOUR orchestration logic built on top of SDK services.
+
+### Core Building Blocks
+
+```
+Data Sources               Parsers                    Transformation
+├── S3DataSource          ├── CSVParserService       ├── UniversalMapper
+├── SftpDataSource        ├── XMLParserService       ├── GraphQLMutationMapper
+└── InventoryDataSource   ├── JSONParserService      └── sdkResolvers
+                          └── ParquetParserService
+
+Client                     Services                   State Management
+├── FluentClient          ├── BatchAPIClient         ├── StateService
+├── createClient()        ├── S3PresignService       ├── VersoriKVAdapter
+├── graphql()             ├── WebhookValidationService
+├── sendEvent()           └── SchemaValidationService
+├── createJob()
+├── sendBatch()
+└── getJobStatus()
+```
+
+### The Fundamental Pattern
+
+```
+Read → Parse → Map → YOUR LOGIC → Send/Archive
+```
+
+Enterprise Integration Patterns sit in the **"YOUR LOGIC"** layer - they define HOW you orchestrate these primitives.
+
+---
+
+## Pattern Categories
+
+We organize EIP patterns into four categories based on their primary purpose:
+
+1. **Routing Patterns** - Direct messages to appropriate destinations
+2. **Transformation Patterns** - Convert data between formats
+3. **Endpoint Patterns** - Connect to external systems
+4. **System Management Patterns** - Handle reliability and state
+
+---
+
+## Routing Patterns
+
+### 1. Message Router
+
+**Pattern:** Route messages to different destinations based on message content or type.
+
+**Support Status:** ✅ **Fully Supported** - Can be built using SDK client methods
+
+**SDK Building Blocks:**
+- `FluentClient.sendEvent()` - Send to Event API
+- `FluentClient.createJob()` + `sendBatch()` - Send to Batch API
+- `FluentClient.graphql()` - Send to GraphQL API
+
+#### Use Case: Order Routing Based on Type
+
+**Business Problem:** Different order types require different processing workflows. Click & Collect orders need immediate workflow triggers, while Home Delivery orders can be batched for efficiency.
+
+Route orders to different workflows based on order type:
+- Click & Collect → Event API (trigger Rubix workflow)
+- Home Delivery → Batch API (bulk processing)
+- Store Pickup → GraphQL mutation (immediate processing)
+
+```typescript
+import { createClient, FluentEvent, FluentBatchPayload } from '@fluentcommerce/fc-connect-sdk';
+
+async function routeOrders(orders: any[], ctx: any, log: any) {
+  const client = await createClient({ ...ctx, log });
+
+  for (const order of orders) {
+    const orderType = order.attributes?.find((a: any) => a.name === 'type')?.value;
+
+    // ROUTING LOGIC
+    switch (orderType) {
+      case 'CLICK_AND_COLLECT':
+        // Route to Event API → Triggers Rubix workflow
+        const event: FluentEvent = {
+          name: 'order.created',
+          entityType: 'ORDER',
+          entityRef: order.ref,
+          retailerId: order.retailerId,
+          attributes: order.attributes
+        };
+        await client.sendEvent(event, 'async');
+        log.info('Order routed to Event API', { ref: order.ref, type: orderType });
+        break;
+
+      case 'HOME_DELIVERY':
+        // Route to Event API → Trigger workflow (Batch API only supports INVENTORY)
+        const event: FluentEvent = {
+          name: 'order.created',
+          entityType: 'ORDER',
+          entityRef: order.ref,
+          retailerId: order.retailerId,
+          attributes: order.attributes
+        };
+        await client.sendEvent(event, 'async');
+        log.info('Order routed to Event API', { ref: order.ref, type: orderType });
+        break;
+
+      case 'STORE_PICKUP':
+        // Route to GraphQL → Immediate processing
+        const mutation = `
+          mutation CreateOrder($input: CreateOrderInput!) {
+            createOrder(input: $input) {
+              id
+              ref
+              status
+            }
+          }
+        `;
+
+        await client.mutate(mutation, { input: order });
+        log.info('Order routed to GraphQL', { ref: order.ref });
+        break;
+
+      default:
+        log.warn('Unknown order type - routing to default Event API', { ref: order.ref, type: orderType });
+        // Default route to Event API (Batch API only supports INVENTORY)
+        const defaultEvent: FluentEvent = {
+          name: 'order.created',
+          entityType: 'ORDER',
+          entityRef: order.ref,
+          retailerId: order.retailerId,
+          attributes: order.attributes
+        };
+        await client.sendEvent(defaultEvent, 'async');
+    }
+  }
+}
+```
+
+**When to Use:**
+- Multiple destination APIs for different message types
+- Order type dictates processing workflow (express, standard, backorder)
+- Inventory updates need different handling by location type (store, warehouse, virtual)
+
+---
+
+### 2. Content-Based Router
+
+**Pattern:** Route messages based on content inspection (attributes, fields, computed values).
+
+**Support Status:** ✅ **Fully Supported** - Can be built using `UniversalMapper` and application logic
+
+**SDK Building Blocks:**
+- `UniversalMapper` - Extract and transform routing criteria
+- Conditional logic based on extracted values
+
+#### Use Case: Inventory Distribution by Quantity
+
+**Business Problem:** High-volume inventory updates should use Batch API for efficiency, while low-quantity alerts need immediate processing via GraphQL to trigger restocking workflows.
+
+Route inventory updates based on available quantity:
+- High quantity (>1000) → Batch API (efficient bulk updates)
+- Medium quantity (100-1000) → Event API (standard processing)
+- Low quantity (<100) → GraphQL + Event (immediate alert + workflow trigger)
+
+```typescript
+import { createClient, UniversalMapper, FluentBatchPayload } from '@fluentcommerce/fc-connect-sdk';
+
+async function routeInventoryUpdates(inventoryData: any[], ctx: any, log: any) {
+  const client = await createClient({ ...ctx, log });
+
+  // Extract routing criteria using UniversalMapper
+  const mapper = new UniversalMapper({
+    fields: {
+      skuRef: { source: 'sku', required: true },
+      locationRef: { source: 'location', required: true },
+      qty: { source: 'quantity', resolver: 'sdk.parseInt', required: true },
+      availableQty: { source: 'available', resolver: 'sdk.parseInt' }
+    }
+  });
+
+  const highQtyBatch: any[] = [];
+  const mediumQtyEvents: any[] = [];
+  const lowQtyAlerts: any[] = [];
+
+  // Content-based routing logic
+  for (const item of inventoryData) {
+    const mapped = await mapper.map(item);
+    if (!mapped.success) {
+      log.error('Mapping failed', { item, errors: mapped.errors });
+      continue;
+    }
+
+    const qty = mapped.data.qty;
+
+    if (qty > 1000) {
+      // HIGH QUANTITY → Batch API
+      highQtyBatch.push({
+        ref: `${mapped.data.locationRef}:${mapped.data.skuRef}`,
+        type: 'INVENTORY',
+        locationRef: mapped.data.locationRef,
+        skuRef: mapped.data.skuRef,
+        qty,
+        status: 'ACTIVE'
+      });
+    } else if (qty >= 100) {
+      // MEDIUM QUANTITY → Event API
+      mediumQtyEvents.push({
+        name: 'inventory.updated',
+        entityType: 'INVENTORY_QUANTITY',
+        entityRef: `${mapped.data.locationRef}:${mapped.data.skuRef}`,
+        retailerId: ctx.activation.getVariable('fluentRetailerId'),
+        attributes: [
+          { name: 'qty', type: 'INTEGER', value: qty },
+          { name: 'locationRef', type: 'STRING', value: mapped.data.locationRef }
+        ]
+      });
+    } else {
+      // LOW QUANTITY → GraphQL + Event (alert)
+      lowQtyAlerts.push(mapped.data);
+    }
+  }
+
+  // Execute routing destinations
+  if (highQtyBatch.length > 0) {
+    const job = await client.createJob({
+      name: `high-qty-inventory-${Date.now()}`,
+      retailerId: ctx.activation.getVariable('fluentRetailerId')
+    });
+
+    await client.sendBatch(job.id, {
+      entityType: 'INVENTORY',
+      entities: highQtyBatch,
+      action: 'UPSERT'
+    });
+
+    log.info('High quantity inventory routed to Batch API', { count: highQtyBatch.length });
+  }
+
+  if (mediumQtyEvents.length > 0) {
+    for (const event of mediumQtyEvents) {
+      await client.sendEvent(event, 'async');
+    }
+    log.info('Medium quantity inventory routed to Event API', { count: mediumQtyEvents.length });
+  }
+
+  if (lowQtyAlerts.length > 0) {
+    // Send low stock alert via GraphQL + Event
+    for (const alert of lowQtyAlerts) {
+      const mutation = `
+        mutation TriggerLowStockAlert($locationRef: String!, $skuRef: String!, $qty: Int!) {
+          createEvent(input: {
+            name: "inventory.low_stock_alert"
+            entityType: INVENTORY_QUANTITY
+            entityRef: $locationRef
+            attributes: [
+              { name: "skuRef", type: STRING, value: $skuRef }
+              { name: "qty", type: INTEGER, value: $qty }
+            ]
+          }) {
+            id
+          }
+        }
+      `;
+
+      await client.graphql({
+        query: mutation,
+        variables: {
+          locationRef: alert.locationRef,
+          skuRef: alert.skuRef,
+          qty: alert.qty
+        }
+      });
+    }
+    log.warn('Low quantity alerts sent', { count: lowQtyAlerts.length });
+  }
+}
+```
+
+**When to Use:**
+- Routing depends on data values (quantity thresholds, priority levels)
+- Different SLAs based on order value or customer tier
+- Inventory allocation strategies based on location characteristics
+
+---
+
+## Transformation Patterns
+
+### 3. Content Enricher
+
+**Pattern:** Enhance message with additional data from external sources.
+
+**Support Status:** ✅ **Fully Supported** - Can be built using `FluentClient.graphql()` and `UniversalMapper` with custom resolvers
+
+**SDK Building Blocks:**
+- `FluentClient.graphql()` - Fetch enrichment data
+- `UniversalMapper` - Merge enriched data
+- Custom resolvers - Complex enrichment logic
+
+#### Use Case: Enrich Order Data with Product Details
+
+**Business Problem:** Order webhooks from external systems contain only SKU references. Fulfilment workflows need product names, weights, and categories for shipping calculations and packaging decisions.
+
+Enrich order line items with product information (name, category, weight) fetched from Fluent GraphQL.
+
+```typescript
+import { createClient, UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+
+async function enrichOrdersWithProductData(orders: any[], ctx: any, log: any) {
+  const client = await createClient({ ...ctx, log });
+
+  // STEP 1: Fetch all product data in one GraphQL query
+  const skuRefs = [...new Set(
+    orders.flatMap(o => o.items?.map((i: any) => i.skuRef) || [])
+  )];
+
+  const query = `
+    query GetProducts($skuRefs: [String!]!) {
+      products(skuRefs: $skuRefs) {
+        edges {
+          node {
+            ref
+            name
+            attributes {
+              name
+              type
+              value
+            }
+          }
+        }
+      }
+    }
+  `;
+
+  const response = await client.graphql({ query, variables: { skuRefs } });
+
+  // Build lookup map for fast enrichment
+  const productMap = new Map();
+  response.data?.products?.edges?.forEach((edge: any) => {
+    const product = edge.node;
+    productMap.set(product.ref, {
+      name: product.name,
+      category: product.attributes?.find((a: any) => a.name === 'category')?.value || 'UNCATEGORIZED',
+      weight: parseFloat(product.attributes?.find((a: any) => a.name === 'weight')?.value || '0')
+    });
+  });
+
+  // STEP 2: Enrich order items with product data
+  const enrichedOrders = orders.map(order => {
+    const enrichedItems = order.items?.map((item: any) => {
+      const productData = productMap.get(item.skuRef);
+
+      return {
+        ...item,
+        // ENRICHMENT: Add product details
+        productName: productData?.name || 'Unknown Product',
+        productCategory: productData?.category || 'UNCATEGORIZED',
+        productWeight: productData?.weight || 0,
+        // Computed fields based on enriched data
+        lineWeight: (productData?.weight || 0) * (item.quantity || 1),
+        isHeavyItem: (productData?.weight || 0) > 10 // kg
+      };
+    });
+
+    return {
+      ...order,
+      items: enrichedItems,
+      // Order-level computed fields
+      totalWeight: enrichedItems.reduce((sum: number, item: any) => sum + (item.lineWeight || 0), 0),
+      hasHeavyItems: enrichedItems.some((item: any) => item.isHeavyItem)
+    };
+  });
+
+  log.info('Orders enriched with product data', {
+    orderCount: orders.length,
+    productCount: productMap.size
+  });
+
+  return enrichedOrders;
+}
+```
+
+**When to Use:**
+- Order processing needs product details (dimensions, weight, hazmat flags)
+- Inventory updates require location metadata (type, capacity, zone)
+- Fulfilment workflows need customer preferences or address validation
+
+---
+
+### 4. Message Translator
+
+**Pattern:** Convert message format from one schema to another.
+
+**Support Status:** ✅ **Fully Supported** - Core SDK capability via Parsers + `UniversalMapper` + Builders
+
+**SDK Building Blocks:**
+- `XMLParserService` - Parse XML input
+- `CSVParserService` - Parse CSV input
+- `JSONParserService` - Parse JSON input
+- `UniversalMapper` - Transform to Fluent schema
+- `XMLBuilder` / `CSVBuilder` - Build output format
+
+#### Use Case: Translate External Inventory CSV to Fluent Batch Format
+
+**Business Problem:** Supplier systems export inventory data in custom CSV formats with different field names (e.g., `supplier_sku`, `warehouse_code`, `on_hand`). Fluent Commerce requires standard field names (`skuRef`, `locationRef`, `qty`).
+
+Translate supplier CSV format to Fluent Batch API format.
+
+```typescript
+import {
+  SftpDataSource,
+  CSVParserService,
+  UniversalMapper,
+  createClient,
+  FluentBatchPayload
+} from '@fluentcommerce/fc-connect-sdk';
+
+async function translateInventoryCsvToBatch(ctx: any, log: any) {
+  const client = await createClient({ ...ctx, log });
+
+  // STEP 1: Read source data (supplier CSV format)
+  const sftp = new SftpDataSource({
+    type: 'SFTP_CSV',
+    settings: {
+      host: ctx.activation.getVariable('sftpHost'),
+      username: ctx.activation.getVariable('sftpUsername'),
+      password: ctx.activation.getVariable('sftpPassword'),
+      remotePath: '/inbound/inventory',
+      filePattern: '*.csv'
+    }
+  }, log);
+
+  try {
+    const files = await sftp.listFiles();
+    if (files.length === 0) {
+      log.info('No files to process');
+      return;
+    }
+
+    const csvContent = await sftp.downloadFile(files[0].name, { encoding: 'utf8' }) as string;
+
+    // STEP 2: Parse source format
+    const csvParser = new CSVParserService(log);
+    const parsedData = await csvParser.parse(csvContent, {
+      delimiter: ',',
+      columns: true,
+      skip_empty_lines: true
+    });
+
+    // Source format: supplier_sku, warehouse_code, on_hand, available, reserved
+    log.info('Parsed supplier CSV', { recordCount: parsedData.length });
+
+    // STEP 3: Translate to Fluent schema using UniversalMapper
+    const mapper = new UniversalMapper({
+      fields: {
+        // TRANSLATION RULES
+        ref: {
+          resolver: 'custom.buildCompositeKey',
+          required: true
+        },
+        type: {
+          value: 'INVENTORY_QUANTITY', // Static value for Batch API
+          required: true
+        },
+        locationRef: {
+          source: 'warehouse_code',
+          resolver: 'sdk.uppercase', // Normalize location ref
+          required: true
+        },
+        skuRef: {
+          source: 'supplier_sku',
+          resolver: 'sdk.trim', // Clean whitespace
+          required: true
+        },
+        qty: {
+          source: 'available', // Map 'available' → 'qty'
+          resolver: 'sdk.parseInt',
+          required: true
+        },
+        onHand: {
+          source: 'on_hand',
+          resolver: 'sdk.parseInt'
+        },
+        reserved: {
+          source: 'reserved',
+          resolver: 'sdk.parseInt',
+          defaultValue: 0 // Default if missing
+        }
+      }
+    }, {
+      customResolvers: {
+        // Custom resolver to build composite key
+        'custom.buildCompositeKey': (value: any, context: any) => {
+          return `${context.warehouse_code}:${context.supplier_sku}`;
+        }
+      }
+    });
+
+    const translatedEntities = [];
+    for (const record of parsedData) {
+      const result = await mapper.map(record);
+      if (result.success) {
+        translatedEntities.push(result.data);
+      } else {
+        log.error('Translation failed', { record, errors: result.errors });
+      }
+    }
+
+    // STEP 4: Send translated data to Fluent Batch API
+    if (translatedEntities.length > 0) {
+      const job = await client.createJob({
+        name: `inventory-translation-${Date.now()}`,
+        retailerId: ctx.activation.getVariable('fluentRetailerId')
+      });
+
+      const batch: FluentBatchPayload = {
+        entityType: 'INVENTORY',
+        entities: translatedEntities,
+        action: 'UPSERT'
+      };
+
+      await client.sendBatch(job.id, batch);
+
+      log.info('Inventory translated and sent to Batch API', {
+        sourceRecords: parsedData.length,
+        translatedEntities: translatedEntities.length,
+        jobId: job.id
+      });
+    }
+  } finally {
+    await sftp.dispose();
+  }
+}
+```
+
+**When to Use:**
+- Supplier data formats differ from Fluent schema
+- Multiple source systems with different CSV/XML structures
+- Legacy system integration with non-standard formats
+
+---
+
+### 5. Splitter
+
+**Pattern:** Break a single message into multiple messages for parallel processing.
+
+**Support Status:** ✅ **Fully Supported** - Can be built using Parsers (automatic splitting) + `Promise.all()` for parallel processing
+
+**SDK Building Blocks:**
+- `FluentClient.sendBatch()` - Split into multiple batches
+- `Promise.all()` - Parallel execution
+- `UniversalMapper` with array handling
+- Parsers automatically split files into records
+
+#### Use Case: Split Large Inventory File into Parallel Batches
+
+**Business Problem:** Daily inventory export files contain 50,000+ inventory positions. Processing sequentially would take hours. Need to split into chunks and process in parallel to meet SLA requirements.
+
+**Note:** Batch API only supports `INVENTORY` entities. For orders, use GraphQL mutations with parallel processing instead.
+
+Process a large inventory file by splitting into chunks and sending parallel batches.
+
+```typescript
+import {
+  S3DataSource,
+  XMLParserService,
+  UniversalMapper,
+  createClient,
+  FluentBatchPayload
+} from '@fluentcommerce/fc-connect-sdk';
+
+async function splitOrdersIntoParallelBatches(ctx: any, log: any) {
+  const client = await createClient({ ...ctx, log });
+
+  // STEP 1: Read large inventory file from S3
+  const s3 = new S3DataSource({
+    type: 'S3_XML',
+    s3Config: {
+      bucket: ctx.activation.getVariable('s3Bucket'),
+      region: ctx.activation.getVariable('awsRegion'),
+      accessKeyId: ctx.activation.getVariable('awsAccessKeyId'),
+      secretAccessKey: ctx.activation.getVariable('awsSecretAccessKey')
+    }
+  }, log);
+
+  const xmlContent = await s3.downloadFile('inventory/inventory-batch-large.xml', { encoding: 'utf8' }) as string;
+
+  // STEP 2: Parse XML
+  const xmlParser = new XMLParserService(log);
+  const parsed = await xmlParser.parse(xmlContent);
+
+  const rawInventory = Array.isArray(parsed.inventory?.position)
+    ? parsed.inventory.position
+    : [parsed.inventory?.position];
+
+  log.info('Parsed large inventory file', { totalPositions: rawInventory.length });
+
+  // STEP 3: Map inventory positions to Fluent format
+  const mapper = new UniversalMapper({
+    fields: {
+      ref: {
+        resolver: 'custom.buildRef',
+        required: true
+      },
+      locationRef: { source: '@location', required: true },
+      skuRef: { source: 'sku', required: true },
+      qty: { source: 'quantity', resolver: 'sdk.parseInt', required: true },
+      status: { source: 'status', defaultValue: 'ACTIVE' }
+    }
+  }, {
+    customResolvers: {
+      // Custom resolver to build composite key from location and SKU
+      'custom.buildRef': (value: any, context: any) => {
+        const location = context['@location'] || context.location;
+        const sku = context.sku;
+        return `${location}:${sku}`;
+      }
+    }
+  });
+
+  const mappedInventory = [];
+  for (const position of rawInventory) {
+    const result = await mapper.map(position);
+    if (result.success) {
+      mappedInventory.push(result.data);
+    }
+  }
+
+  // STEP 4: SPLIT into chunks (batches of 500)
+  const BATCH_SIZE = 500;
+  const chunks = [];
+  for (let i = 0; i < mappedInventory.length; i += BATCH_SIZE) {
+    chunks.push(mappedInventory.slice(i, i + BATCH_SIZE));
+  }
+
+  log.info('Split inventory into chunks', {
+    totalPositions: mappedInventory.length,
+    chunkCount: chunks.length,
+    batchSize: BATCH_SIZE
+  });
+
+  // STEP 5: Create job for all batches
+  // Note: Batch API only supports INVENTORY entities, not ORDER
+  // For orders, use GraphQL mutations instead (see below)
+  // This example shows splitting for inventory entities
+  const job = await client.createJob({
+    name: `inventory-split-${Date.now()}`,
+    retailerId: ctx.activation.getVariable('fluentRetailerId')
+  });
+
+  // STEP 6: Send chunks in parallel
+  const batchPromises = chunks.map(async (chunk, index) => {
+    const batch: FluentBatchPayload = {
+      entityType: 'INVENTORY',
+      entities: chunk,
+      action: 'UPSERT'
+    };
+
+    const batchResponse = await client.sendBatch(job.id, batch);
+    log.info(`Batch ${index + 1}/${chunks.length} sent`, {
+      batchId: batchResponse.id,
+      entityCount: chunk.length
+    });
+
+    return batchResponse;
+  });
+
+  // Wait for all batches to complete
+  const batchResponses = await Promise.all(batchPromises);
+
+  log.info('All inventory batches sent successfully', {
+    jobId: job.id,
+    totalBatches: batchResponses.length,
+    totalPositions: mappedInventory.length
+  });
+
+  return { jobId: job.id, batchCount: batchResponses.length };
+}
+```
+
+**When to Use:**
+- Large inventory files exceed single batch limits (>10K records)
+- Parallel processing improves throughput
+- Different chunks need different processing strategies
+
+**Note:** For orders, use GraphQL mutations with `Promise.all()` for parallel processing instead of Batch API.
+
+---
+
+### 6. Aggregator
+
+**Pattern:** Combine multiple related messages into a single message.
+
+**Support Status:** ✅ **Fully Supported** - Can be built using `FluentClient.graphql()` with pagination + application aggregation logic
+
+**SDK Building Blocks:**
+- `FluentClient.graphql()` with pagination - Fetch multiple pages
+- `StateService` - Track aggregation state
+- Array aggregation logic
+
+#### Use Case: Aggregate Virtual Position Data from Multiple Locations
+
+**Business Problem:** Inventory positions are stored per location (warehouse, store, virtual). Reporting dashboard needs aggregated view showing total quantity across all locations for each SKU.
+
+Aggregate inventory positions across all locations for a single SKU view.
+
+```typescript
+import { createClient, StateService, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
+
+async function aggregateVirtualPositions(skuRefs: string[], ctx: any, log: any) {
+  const client = await createClient({ ...ctx, log });
+
+  // STEP 1: Query virtual positions across all locations (with pagination)
+  const query = `
+    query GetVirtualPositions($skuRefs: [String!]!, $first: Int!, $after: String) {
+      virtualPositions(skuRefs: $skuRefs, first: $first, after: $after) {
+        edges {
+          node {
+            ref
+            quantity
+            groupRef
+            productRef
+            virtualCatalogueRef
+          }
+          cursor
+        }
+        pageInfo {
+          hasNextPage
+          endCursor
+        }
+      }
+    }
+  `;
+
+  const response = await client.graphql({
+    query,
+    variables: { skuRefs, first: 1000 },
+    pagination: {
+      enabled: true,
+      maxPages: 10,
+      direction: 'forward'
+    }
+  });
+
+  const allPositions = response.data?.virtualPositions?.edges?.map((e: any) => e.node) || [];
+
+  log.info('Fetched virtual positions', {
+    totalPositions: allPositions.length,
+    skuCount: skuRefs.length,
+    paginationStats: response.extensions?.autoPagination
+  });
+
+  // STEP 2: AGGREGATE positions by SKU
+  const aggregatedBySku = new Map<string, {
+    skuRef: string;
+    totalQuantity: number;
+    locations: string[];
+    catalogues: string[];
+  }>();
+
+  for (const position of allPositions) {
+    const skuRef = position.productRef;
+
+    if (!aggregatedBySku.has(skuRef)) {
+      aggregatedBySku.set(skuRef, {
+        skuRef,
+        totalQuantity: 0,
+        locations: [],
+        catalogues: []
+      });
+    }
+
+    const agg = aggregatedBySku.get(skuRef)!;
+    agg.totalQuantity += position.quantity || 0;
+
+    if (position.groupRef && !agg.locations.includes(position.groupRef)) {
+      agg.locations.push(position.groupRef);
+    }
+
+    if (position.virtualCatalogueRef && !agg.catalogues.includes(position.virtualCatalogueRef)) {
+      agg.catalogues.push(position.virtualCatalogueRef);
+    }
+  }
+
+  // STEP 3: Convert to array and compute metrics
+  const aggregatedResults = Array.from(aggregatedBySku.values()).map(agg => ({
+    ...agg,
+    locationCount: agg.locations.length,
+    catalogueCount: agg.catalogues.length,
+    avgQuantityPerLocation: agg.totalQuantity / agg.locations.length
+  }));
+
+  log.info('Aggregation complete', {
+    totalSKUs: aggregatedResults.length,
+    totalQuantity: aggregatedResults.reduce((sum, r) => sum + r.totalQuantity, 0)
+  });
+
+  // STEP 4: Store aggregated results in KV for later retrieval
+  const kv = ctx.openKv(':project:');
+  const stateService = new StateService(log);
+
+  for (const result of aggregatedResults) {
+    await kv.set(['aggregated_inventory', result.skuRef], result);
+  }
+
+  log.info('Aggregated results stored in KV', { skuCount: aggregatedResults.length });
+
+  return aggregatedResults;
+}
+```
+
+**When to Use:**
+- Inventory views need multi-location aggregation
+- Order totals calculated from multiple line items
+- Reporting requires data from multiple API calls
+
+---
+
+## Endpoint Patterns
+
+### 7. Polling Consumer
+
+**Pattern:** Periodically poll an endpoint for new messages.
+
+**Support Status:** ✅ **Fully Supported** - Can be built using Versori `schedule()` + `Data Sources` + `StateService` for tracking
+
+**SDK Building Blocks:**
+- `schedule()` from `@versori/run` - Scheduled execution
+- `StateService` - Track last poll time
+- `SftpDataSource.listFiles()` - Poll for new files
+- `S3DataSource.listFiles()` - Poll S3 buckets
+
+#### Use Case: Poll SFTP for New Inventory Files
+
+**Business Problem:** Supplier systems don't support webhooks. They drop CSV files to SFTP every 2 hours. Need to check for new files periodically and process them without duplicate processing.
+
+Check SFTP every 2 hours for new inventory files, process only new files.
+
+```typescript
+import { schedule } from '@versori/run';
+import {
+  SftpDataSource,
+  CSVParserService,
+  UniversalMapper,
+  createClient,
+  StateService,
+  FluentBatchPayload
+} from '@fluentcommerce/fc-connect-sdk';
+
+export const pollSftpInventory = schedule('poll-sftp-inventory', '0 */2 * * *', async (ctx) => {
+  const { log, openKv, activation } = ctx;
+  const client = await createClient({ ...ctx, log });
+
+  // STEP 1: Connect to SFTP
+  const sftp = new SftpDataSource({
+    type: 'SFTP_CSV',
+    settings: {
+      host: activation.getVariable('sftpHost'),
+      username: activation.getVariable('sftpUsername'),
+      password: activation.getVariable('sftpPassword'),
+      remotePath: '/outbound/inventory',
+      filePattern: 'inventory_*.csv'
+    }
+  }, log);
+
+  try {
+    // STEP 2: Poll for files
+    const files = await sftp.listFiles();
+    log.info('Polled SFTP for inventory files', { fileCount: files.length });
+
+    if (files.length === 0) {
+      log.info('No new files found');
+      return { status: 'no_files' };
+    }
+
+    // STEP 3: Check state to identify new files
+    const kv = openKv(':project:');
+    const stateService = new StateService(log);
+
+    const newFiles = [];
+    for (const file of files) {
+      const isProcessed = await kv.get(['processed_files', file.name]);
+      if (!isProcessed) {
+        newFiles.push(file);
+      }
+    }
+
+    log.info('Identified new files', { newFileCount: newFiles.length });
+
+    if (newFiles.length === 0) {
+      return { status: 'no_new_files' };
+    }
+
+    // STEP 4: Process new files
+    const csvParser = new CSVParserService(log);
+    const mapper = new UniversalMapper({
+      fields: {
+        ref: { source: 'location_sku', required: true },
+        type: { value: 'INVENTORY_QUANTITY', required: true },
+        locationRef: { source: 'location', required: true },
+        skuRef: { source: 'sku', required: true },
+        qty: { source: 'quantity', resolver: 'sdk.parseInt', required: true }
+      }
+    });
+
+    let totalEntities = 0;
+
+    for (const file of newFiles) {
+      try {
+        const csvContent = await sftp.downloadFile(file.name, { encoding: 'utf8' }) as string;
+        const parsed = await csvParser.parse(csvContent, { columns: true });
+
+        const entities = [];
+        for (const record of parsed) {
+          const result = await mapper.map(record);
+          if (result.success) {
+            entities.push(result.data);
+          }
+        }
+
+        if (entities.length > 0) {
+          const job = await client.createJob({
+            name: `inventory-poll-${file.name}-${Date.now()}`,
+            retailerId: activation.getVariable('fluentRetailerId')
+          });
+
+          await client.sendBatch(job.id, {
+            entityType: 'INVENTORY',
+            entities,
+            action: 'UPSERT'
+          });
+
+          totalEntities += entities.length;
+        }
+
+        // Mark file as processed
+        await kv.set(['processed_files', file.name], {
+          processedAt: new Date().toISOString(),
+          entityCount: entities.length
+        });
+
+        log.info('File processed successfully', { file: file.name, entities: entities.length });
+      } catch (error) {
+        log.error(`Failed to process file: ${file.name}`, error as Error);
+      }
+    }
+
+    return {
+      status: 'success',
+      filesProcessed: newFiles.length,
+      totalEntities
+    };
+  } finally {
+    await sftp.dispose();
+  }
+});
+```
+
+**When to Use:**
+- Supplier systems don't support webhooks (push notifications)
+- Scheduled file drops to SFTP/S3 (daily inventory snapshots)
+- Periodic API polling for new orders/fulfilments
+
+---
+
+### 8. Idempotent Receiver
+
+**Pattern:** Ensure messages are processed exactly once, even if received multiple times.
+
+**Support Status:** ✅ **Fully Supported** - Can be built using KV Store + `StateService` for idempotency tracking
+
+**SDK Building Blocks:**
+- `StateService` - Track processed message IDs
+- `VersoriKVAdapter` - Distributed state storage
+- KV Store (`openKv`) - Persistent state storage
+- Atomic operations for race-free checks
+
+#### Use Case: Prevent Duplicate Order Processing
+
+**Business Problem:** Webhook endpoints may receive duplicate deliveries due to network retries or webhook provider retry logic. Need to ensure each order is processed exactly once, even if webhook fires multiple times.
+
+Ensure each order is processed only once, even with webhook retries.
+
+```typescript
+import { webhook } from '@versori/run';
+import {
+  createClient,
+  StateService,
+  parseWebhookRequest,
+  FluentEvent
+} from '@fluentcommerce/fc-connect-sdk';
+
+export const processOrderWebhook = webhook('process-order', {
+  response: { mode: 'sync' }
+}, async (ctx) => {
+  const { log, openKv, request } = ctx;
+  const client = await createClient({ ...ctx, log });
+
+  // STEP 1: Parse webhook payload
+  const webhookPayload = await parseWebhookRequest(request);
+  const orderRef = webhookPayload.entityRef;
+  const eventId = webhookPayload.id;
+
+  log.info('Received order webhook', { orderRef, eventId });
+
+  // STEP 2: IDEMPOTENCY CHECK - Has this event been processed?
+  const kv = openKv(':project:');
+  const processingKey = ['processed_events', eventId];
+
+  const existingRecord = await kv.get(processingKey);
+  if (existingRecord?.value) {
+    log.warn('Event already processed - skipping', {
+      eventId,
+      orderRef,
+      processedAt: (existingRecord.value as any).processedAt
+    });
+
+    return new Response(JSON.stringify({
+      status: 'already_processed',
+      eventId,
+      processedAt: (existingRecord.value as any).processedAt
+    }), {
+      status: 200,
+      headers: { 'Content-Type': 'application/json' }
+    });
+  }
+
+  // STEP 3: Process order (business logic)
+  try {
+    // Fetch order details
+    const query = `
+      query GetOrder($ref: String!) {
+        order(ref: $ref) {
+          id
+          ref
+          status
+          totalPrice
+          items {
+            edges {
+              node {
+                ref
+                quantity
+                product {
+                  ref
+                  name
+                }
+              }
+            }
+          }
+        }
+      }
+    `;
+
+    const response = await client.graphql({
+      query,
+      variables: { ref: orderRef }
+    });
+
+    const order = response.data?.order;
+
+    if (!order) {
+      throw new Error(`Order not found: ${orderRef}`);
+    }
+
+    // Business logic: Send fulfilment event if order is confirmed
+    if (order.status === 'CONFIRMED') {
+      const event: FluentEvent = {
+        name: 'order.ready_for_fulfilment',
+        entityType: 'ORDER',
+        entityRef: orderRef,
+        retailerId: webhookPayload.retailerId,
+        attributes: [
+          { name: 'totalPrice', type: 'FLOAT', value: order.totalPrice },
+          { name: 'itemCount', type: 'INTEGER', value: order.items?.edges?.length || 0 }
+        ]
+      };
+
+      await client.sendEvent(event, 'async');
+    }
+
+    // STEP 4: Mark event as processed (IDEMPOTENCY RECORD)
+    await kv.set(processingKey, {
+      processedAt: new Date().toISOString(),
+      orderRef,
+      eventId,
+      status: 'success'
+    });
+
+    log.info('Order processed successfully', { orderRef, eventId });
+
+    return new Response(JSON.stringify({
+      status: 'processed',
+      orderRef,
+      eventId
+    }), {
+      status: 200,
+      headers: { 'Content-Type': 'application/json' }
+    });
+  } catch (error) {
+    log.error('Order processing failed', error as Error, { orderRef, eventId });
+
+    // Don't mark as processed on failure - allow retry
+    return new Response(JSON.stringify({
+      status: 'error',
+      message: (error as Error).message
+    }), {
+      status: 500,
+      headers: { 'Content-Type': 'application/json' }
+    });
+  }
+});
+```
+
+**When to Use:**
+- Webhook endpoints that may receive duplicate deliveries
+- File processing where same file might be reprocessed
+- Distributed workflows with at-least-once delivery guarantees
+
+---
+
+## System Management Patterns
+
+### 9. Dead Letter Channel
+
+**Pattern:** Route failed messages to a separate channel for inspection and reprocessing.
+
+**Support Status:** ✅ **Fully Supported** - Can be built using `S3DataSource` or `SftpDataSource` for failed message storage
+
+**SDK Building Blocks:**
+- `S3DataSource.uploadFile()` - Write failed messages to S3
+- `SftpDataSource.writeFile()` - Write failed messages to SFTP
+- `StateService` - Track failure counts
+- Error handling with try/catch
+
+#### Use Case: Route Failed Inventory Updates to Dead Letter S3 Bucket
+
+**Business Problem:** Some inventory records fail validation (missing SKU, invalid quantity, etc.). Need to capture these failures for manual review and potential reprocessing without blocking successful records.
+
+Capture failed inventory records for manual review and reprocessing.
+
+```typescript
+import {
+  SftpDataSource,
+  CSVParserService,
+  UniversalMapper,
+  S3DataSource,
+  createClient,
+  FluentBatchPayload
+} from '@fluentcommerce/fc-connect-sdk';
+import { Buffer } from 'node:buffer';
+
+async function processInventoryWithDeadLetterChannel(ctx: any, log: any) {
+  const client = await createClient({ ...ctx, log });
+
+  // Setup: SFTP source, S3 dead letter destination
+  const sftp = new SftpDataSource({
+    type: 'SFTP_CSV',
+    settings: {
+      host: ctx.activation.getVariable('sftpHost'),
+      username: ctx.activation.getVariable('sftpUsername'),
+      password: ctx.activation.getVariable('sftpPassword'),
+      remotePath: '/inbound/inventory',
+      filePattern: '*.csv'
+    }
+  }, log);
+
+  const deadLetterS3 = new S3DataSource({
+    type: 'S3_JSON',
+    s3Config: {
+      bucket: ctx.activation.getVariable('deadLetterBucket'),
+      region: ctx.activation.getVariable('awsRegion'),
+      accessKeyId: ctx.activation.getVariable('awsAccessKeyId'),
+      secretAccessKey: ctx.activation.getVariable('awsSecretAccessKey')
+    }
+  }, log);
+
+  try {
+    const files = await sftp.listFiles();
+    if (files.length === 0) {
+      log.info('No files to process');
+      return;
+    }
+
+    const csvContent = await sftp.downloadFile(files[0].name, { encoding: 'utf8' }) as string;
+    const csvParser = new CSVParserService(log);
+    const parsed = await csvParser.parse(csvContent, { columns: true });
+
+    // Map inventory records
+    const mapper = new UniversalMapper({
+      fields: {
+        ref: { source: 'location_sku', required: true },
+        type: { value: 'INVENTORY_QUANTITY', required: true },
+        locationRef: { source: 'location', required: true },
+        skuRef: { source: 'sku', required: true },
+        qty: { source: 'quantity', resolver: 'sdk.parseInt', required: true }
+      }
+    });
+
+    const successfulEntities = [];
+    const failedRecords = [];
+
+    // Process records with error tracking
+    for (const record of parsed) {
+      try {
+        const result = await mapper.map(record);
+        if (result.success) {
+          successfulEntities.push(result.data);
+        } else {
+          // DEAD LETTER: Mapping validation failed
+          failedRecords.push({
+            sourceRecord: record,
+            errors: result.errors,
+            failureReason: 'mapping_validation_failed',
+            failedAt: new Date().toISOString()
+          });
+        }
+      } catch (error) {
+        // DEAD LETTER: Unexpected error during mapping
+        failedRecords.push({
+          sourceRecord: record,
+          errors: [(error as Error).message],
+          failureReason: 'mapping_error',
+          failedAt: new Date().toISOString(),
+          errorStack: (error as Error).stack
+        });
+      }
+    }
+
+    // Send successful records to Batch API
+    if (successfulEntities.length > 0) {
+      const job = await client.createJob({
+        name: `inventory-with-dlq-${Date.now()}`,
+        retailerId: ctx.activation.getVariable('fluentRetailerId')
+      });
+
+      await client.sendBatch(job.id, {
+        entityType: 'INVENTORY',
+        entities: successfulEntities,
+        action: 'UPSERT'
+      });
+
+      log.info('Successful entities sent to Batch API', {
+        count: successfulEntities.length,
+        jobId: job.id
+      });
+    }
+
+    // DEAD LETTER CHANNEL: Write failed records to S3
+    if (failedRecords.length > 0) {
+      const deadLetterKey = `failed-inventory/${files[0].name}-failures-${Date.now()}.json`;
+      const deadLetterContent = JSON.stringify({
+        sourceFile: files[0].name,
+        failedAt: new Date().toISOString(),
+        totalFailed: failedRecords.length,
+        records: failedRecords
+      }, null, 2);
+
+      await deadLetterS3.uploadFile(
+        deadLetterKey,
+        Buffer.from(deadLetterContent, 'utf-8')
+      );
+
+      log.warn('Failed records written to Dead Letter S3', {
+        count: failedRecords.length,
+        deadLetterKey
+      });
+    }
+
+    return {
+      successful: successfulEntities.length,
+      failed: failedRecords.length,
+      deadLetterKey: failedRecords.length > 0 ? `failed-inventory/${files[0].name}-failures-${Date.now()}.json` : null
+    };
+  } finally {
+    await sftp.dispose();
+  }
+}
+```
+
+**When to Use:**
+- Data validation failures need manual review
+- Partial batch failures require reprocessing
+- Audit trail for failed messages is required
+
+---
+
+### 10. Wire Tap
+
+**Pattern:** Inspect messages passing through without altering them (audit logging).
+
+**Support Status:** ✅ **Fully Supported** - Can be built using `S3DataSource` or logging for audit trail
+
+**SDK Building Blocks:**
+- `S3DataSource.uploadFile()` - Archive message copies
+- Logging for message inspection
+- No modification to message flow
+
+#### Use Case: Audit All Order Events Sent to Event API
+
+**Business Problem:** Compliance requirements mandate audit trail of all order events sent to Fluent Commerce. Need to log message contents without affecting processing performance or modifying message flow.
+
+Log all order events to S3 for compliance auditing.
+
+```typescript
+import {
+  createClient,
+  FluentEvent,
+  S3DataSource
+} from '@fluentcommerce/fc-connect-sdk';
+import { Buffer } from 'node:buffer';
+
+async function sendOrderEventWithAudit(orderEvent: FluentEvent, ctx: any, log: any) {
+  const client = await createClient({ ...ctx, log });
+
+  // Setup audit S3 bucket
+  const auditS3 = new S3DataSource({
+    type: 'S3_JSON',
+    s3Config: {
+      bucket: ctx.activation.getVariable('auditBucket'),
+      region: ctx.activation.getVariable('awsRegion'),
+      accessKeyId: ctx.activation.getVariable('awsAccessKeyId'),
+      secretAccessKey: ctx.activation.getVariable('awsSecretAccessKey')
+    }
+  }, log);
+
+  try {
+    // WIRE TAP: Capture message before sending (NO MODIFICATION)
+    const auditRecord = {
+      timestamp: new Date().toISOString(),
+      eventType: 'order_event',
+      direction: 'outbound',
+      destination: 'fluent_event_api',
+      payload: orderEvent,
+      metadata: {
+        entityRef: orderEvent.entityRef,
+        eventName: orderEvent.name,
+        retailerId: orderEvent.retailerId
+      }
+    };
+
+    // Write audit record to S3 (asynchronously, don't block main flow)
+    const auditKey = `audit/order-events/${orderEvent.entityRef}-${Date.now()}.json`;
+    const auditPromise = auditS3.uploadFile(
+      auditKey,
+      Buffer.from(JSON.stringify(auditRecord, null, 2), 'utf-8')
+    ).catch((error) => {
+      // Audit failure should NOT break main flow
+      log.error('Audit logging failed', error as Error, { auditKey });
+    });
+
+    // Send event to Fluent (main flow continues)
+    const eventResponse = await client.sendEvent(orderEvent, 'async');
+
+    // Wait for audit to complete (optional - for testing)
+    await auditPromise;
+
+    log.info('Order event sent with audit', {
+      entityRef: orderEvent.entityRef,
+      eventId: eventResponse,
+      auditKey
+    });
+
+    return eventResponse;
+  } finally {
+    // No disposal needed - audit is fire-and-forget
+  }
+}
+
+// Usage example
+async function processOrder(order: any, ctx: any, log: any) {
+  const orderEvent: FluentEvent = {
+    name: 'order.created',
+    entityType: 'ORDER',
+    entityRef: order.ref,
+    retailerId: order.retailerId,
+    attributes: [
+      { name: 'totalPrice', type: 'FLOAT', value: order.totalPrice },
+      { name: 'customerEmail', type: 'STRING', value: order.customer.email }
+    ]
+  };
+
+  // WIRE TAP in action - event is audited without modification
+  await sendOrderEventWithAudit(orderEvent, ctx, log);
+}
+```
+
+**When to Use:**
+- Compliance requires message audit trails
+- Debugging integration flows (inspect message contents)
+- Performance monitoring (message throughput, latency)
+
+---
+
+## Pattern Summary Matrix
+
+| Pattern | Support Status | Primary Purpose | SDK Building Blocks | Fluent Use Case |
+|---------|---------------|----------------|-------------------|----------------|
+| **Message Router** | ✅ Fully Supported | Route to different APIs | `sendEvent()`, `createJob()`, `graphql()` | Route orders by type to Event/Batch/GraphQL |
+| **Content-Based Router** | ✅ Fully Supported | Route based on data values | `UniversalMapper`, conditional logic | Route inventory by quantity threshold |
+| **Content Enricher** | ✅ Fully Supported | Add data from external sources | `graphql()`, `UniversalMapper` | Enrich orders with product details |
+| **Message Translator** | ✅ Fully Supported | Convert between formats | `CSVParserService`, `UniversalMapper`, `XMLBuilder` | Translate supplier CSV to Fluent Batch format |
+| **Splitter** | ✅ Fully Supported | Break message into parts | `sendBatch()`, `Promise.all()`, Parsers | Split large order file into parallel batches |
+| **Aggregator** | ✅ Fully Supported | Combine multiple messages | `graphql()` with pagination, Map/Set | Aggregate inventory across locations |
+| **Polling Consumer** | ✅ Fully Supported | Periodic endpoint polling | `schedule()`, `SftpDataSource.listFiles()` | Poll SFTP every 2 hours for inventory files |
+| **Idempotent Receiver** | ✅ Fully Supported | Prevent duplicate processing | `StateService`, KV Store, atomic ops | Prevent duplicate webhook order processing |
+| **Dead Letter Channel** | ✅ Fully Supported | Route failed messages | `S3DataSource.uploadFile()`, error handling | Failed inventory updates to S3 for review |
+| **Wire Tap** | ✅ Fully Supported | Audit messages (no modification) | `S3DataSource.uploadFile()`, logging | Audit all order events to S3 for compliance |
+
+**Support Status Legend:**
+- ✅ **Fully Supported** - Can be built using SDK building blocks with complete examples
+- ⚠️ **Partially Supported** - Requires additional custom code beyond SDK
+- ❌ **Not Supported** - Not achievable with current SDK capabilities
+
+---
+
+## Additional Resources
+
+### SDK Documentation
+- **Architecture**: `docs/04-REFERENCE/architecture/readme.md` - System design and data flow
+- **Decision Tree**: `docs/00-START-HERE/DECISION-TREE.md` - Which approach to use?
+- **Troubleshooting**: `docs/00-START-HERE/troubleshooting-quick-reference.md` - Common issues
+
+### Core Guides
+- **Ingestion**: `docs/02-CORE-GUIDES/ingestion/readme.md` - Data into Fluent
+- **Extraction**: `docs/02-CORE-GUIDES/extraction/readme.md` - Data from Fluent
+- **Mapping**: `docs/02-CORE-GUIDES/mapping/modules/` - Field transformation
+- **Webhook Validation**: `docs/02-CORE-GUIDES/webhook-validation/readme.md` - Signature validation
+
+### Pattern Guides
+- **Error Handling**: `docs/03-PATTERN-GUIDES/error-handling/readme.md` - Retry, circuit breakers
+- **File Operations**: `docs/03-PATTERN-GUIDES/file-operations/readme.md` - S3/SFTP patterns
+- **Integration Patterns**: `docs/03-PATTERN-GUIDES/integration-patterns/readme.md` - Real-time, batch, delta sync
+
+### Templates
+- **Ingestion Templates**: `docs/01-TEMPLATES/versori/scheduled/ingestion/` - Complete examples
+- **Extraction Templates**: `docs/01-TEMPLATES/versori/scheduled/extraction/` - GraphQL extraction patterns
+
+---
+
+## Summary
+
+This guide demonstrated how to build 10 essential Enterprise Integration Patterns using Fluent Connect SDK building blocks:
+
+**Key Takeaways:**
+
+1. **SDK is a Toolkit** - Patterns are YOUR orchestration logic, not framework-imposed
+2. **Composable Primitives** - Combine clients, parsers, mappers, data sources to build patterns
+3. **Real Fluent Domains** - All examples use actual Order and Inventory entities
+4. **Production-Ready Code** - Every example uses real SDK methods and types
+
+**Next Steps:**
+
+- Review `docs/00-START-HERE/DECISION-TREE.md` for pattern selection guidance
+- Explore `docs/01-TEMPLATES/` for complete working implementations
+- See `docs/03-PATTERN-GUIDES/integration-patterns/` for additional pattern details
+
+**Remember:** The SDK provides the tools. YOU define the integration patterns.
+
+---
+
+**Document Version:** 1.0.0
+**SDK Version:** 0.1.39
+**Last Verified:** 2025-11-05