npm - @fluentcommerce/fc-connect-sdk - Versions diffs - 0.1.53 → 0.1.55 - Mend

@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (495) hide show

package/docs/03-PATTERN-GUIDES/integration-patterns/modules/integration-patterns-01-real-time-processing.md CHANGED Viewed

@@ -1,991 +1,991 @@
-# Module 1: Real-Time Processing
-> **Learning Objective:** Understand real-time event processing patterns, when to use them, and how to implement immediate event handling with the Fluent Connect SDK.
->
-> **Level:** Beginner
-## Table of Contents
-1. [What is Real-Time Processing?](#what-is-real-time-processing)
-2. [When to Use Real-Time Processing](#when-to-use-real-time-processing)
-3. [Real-Time vs Batch: The Decision](#real-time-vs-batch-the-decision)
-4. [Common Real-Time Use Cases](#common-real-time-use-cases)
-5. [SDK Components for Real-Time Processing](#sdk-components-for-real-time-processing)
-6. [Basic Real-Time Workflow](#basic-real-time-workflow)
-7. [Real-Time Pattern: Webhook to GraphQL](#real-time-pattern-webhook-to-graphql)
-8. [Error Handling in Real-Time](#error-handling-in-real-time)
-9. [Next Steps](#next-steps)
----
-## What is Real-Time Processing?
-**Real-time processing** means handling events as they occur, with minimal latency between event trigger and completion.
-### Key Characteristics
-| Characteristic           | Description                         | Example                        |
-| ------------------------ | ----------------------------------- | ------------------------------ |
-| **Immediate Trigger**    | Event triggers processing instantly | HTTP webhook receives order    |
-| **Low Latency**          | Processing completes in seconds     | Order created within 5 seconds |
-| **Event-Driven**         | External events drive execution     | SFCC order placement           |
-| **Synchronous Response** | Caller waits for result             | Webhook returns success/error  |
-### How It Works
-```
-External Event → Webhook Endpoint → Process Data → Call Fluent API → Return Response
-     ↓               ↓                   ↓              ↓                  ↓
-  <1 second     Parse payload      Transform data   Create order      Success/error
-```
-### Visual Flow
-```
-┌─────────────┐
-│ SFCC Order  │ ──① HTTP POST──>  ┌──────────────────┐
-│   Placed    │                    │ Versori Webhook  │
-└─────────────┘                    │   (Your code)    │
-                                   └────────┬─────────┘
-                                            │
-                                   ②Parse XML/JSON
-                                            │
-                                            ▼
-                                   ┌──────────────────┐
-                                   │ GraphQLMutation  │
-                                   │     Mapper       │
-                                   └────────┬─────────┘
-                                            │
-                                   ③Apply field mapping
-                                            │
-                                            ▼
-                                   ┌──────────────────┐
-                                   │  Fluent Client   │
-                                   │  createOrder()   │
-                                   └────────┬─────────┘
-                                            │
-                                   ④GraphQL mutation
-                                            │
-                                            ▼
-                                   ┌──────────────────┐
-                                   │ Fluent Commerce  │
-                                   │   Order Created  │
-                                   └────────┬─────────┘
-                                            │
-                                   ⑤Return response
-                                            │
-                                            ▼
-                                   ┌──────────────────┐
-                                   │  200 OK          │
-                                   │  { orderId }     │
-                                   └──────────────────┘
-```
-**Total latency**: 2-5 seconds from webhook receipt to Fluent order creation.
----
-## When to Use Real-Time Processing
-### ✅ Use Real-Time When:
-| Scenario              | Why Real-Time?                          | SDK Pattern                    |
-| --------------------- | --------------------------------------- | ------------------------------ |
-| **Order Webhooks**    | Customers expect immediate confirmation | Webhook → GraphQL mutation     |
-| **Inventory Updates** | Stock levels must be accurate instantly | Webhook → Batch API (single)   |
-| **Low Volume**        | < 100 events/hour                       | Simple webhook handler         |
-| **Critical Events**   | Payment, shipment, cancellation         | Immediate processing + logging |
-| **External Triggers** | Third-party systems push data           | HTTP endpoint required         |
-### ❌ Avoid Real-Time When:
-| Scenario            | Why Not Real-Time?   | Use Instead                 |
-| ------------------- | -------------------- | --------------------------- |
-| **Large Files**     | 10K+ records         | Batch processing (Module 2) |
-| **High Volume**     | > 1,000 events/hour  | Scheduled batch (Module 2)  |
-| **Long Processing** | > 30 seconds         | Async job queue             |
-| **Bulk Operations** | Daily inventory sync | Batch API (Module 2)        |
-| **Non-Critical**    | Reports, analytics   | Scheduled extraction        |
----
-## Real-Time vs Batch: The Decision
-### Volume-Based Decision Matrix
-```
-Events/Hour │ Pattern
-────────────┼────────────────────────────────
-    < 10    │ Real-Time (Webhook)
-   10-100   │ Real-Time (Webhook)
-  100-500   │ Real-Time OR Micro-batch
-  500-1K    │ Micro-batch (5-minute windows)
-   1K-10K   │ Batch (hourly)
-   > 10K    │ Batch (daily)
-```
-### Latency Requirements
-| Requirement     | Pattern      | Example              |
-| --------------- | ------------ | -------------------- |
-| **< 5 seconds** | Real-Time    | Order confirmation   |
-| **< 5 minutes** | Micro-batch  | Inventory updates    |
-| **< 1 hour**    | Hourly batch | Product catalog sync |
-| **< 24 hours**  | Daily batch  | Full inventory sync  |
-### Example Decisions
-#### ✅ GOOD: Real-Time for Order Webhooks
-```typescript
-// Scenario: SFCC sends 20-50 orders/hour
-// Requirement: Orders visible in Fluent within 5 seconds
-// Volume: Low (<100/hour)
-// Pattern: Real-time webhook
-export default async function processOrder(ctx) {
-  const orderData = ctx.activation.body;
-  const client = await createClient(ctx); // Auto-detects Versori context
-  // Immediate processing
-  const result = await client.graphql({
-    query: CREATE_ORDER_MUTATION,
-    variables: { input: mapOrderData(orderData) },
-  });
-  return { status: 200, body: { orderId: result.id } };
-}
-```
-**Why this works**: Low volume + low latency requirement = perfect for real-time.
-#### ❌ WRONG: Real-Time for Bulk Inventory
-```typescript
-// ❌ BAD: Trying to process 50K inventory records via webhooks
-export default async function processInventory(activation, log, connections) {
-  const inventoryFile = activation.body.fileUrl; // 50K records
-  // This will timeout! Each webhook has 30-second limit
-  for (const record of records) {
-    await client.graphql({ ... }); // 50K sequential API calls = HOURS
-  }
-}
-```
-**Why this fails**:
-- Webhook timeout (30-60 seconds)
-- 50K sequential API calls = 1-2 hours
-- No progress tracking
-- No error recovery
-**✅ Better approach**: Use Batch API (Module 2)
-```typescript
-// Process 50K records in 5-10 minutes via Batch API
-const job = await client.createJob({ name: 'inventory-update' });
-const batch = await client.sendBatch(job.id, { entities: records });
-```
----
-## Common Real-Time Use Cases
-### Use Case 1: SFCC Order Creation
-**Trigger**: Salesforce Commerce Cloud sends order XML via webhook
-**Processing Time**: 3-5 seconds
-**Volume**: 10-100 orders/hour
-**SDK Pattern**: `GraphQLMutationMapper` + `createClient`
-**Complete implementation**: [XML Order Ingestion Guide](../../../01-TEMPLATES/versori/webhooks/template-webhook-xml-order-ingestion.md)
-### Use Case 2: Inventory Adjustment (Single SKU)
-**Trigger**: Warehouse system reports damage/theft
-**Processing Time**: 1-2 seconds
-**Volume**: < 10 events/hour
-**SDK Pattern**: Direct GraphQL mutation
-**Example**:
-```typescript
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-export default async function adjustInventory(activation: any, log: any, connections: any) {
-  const { sku, location, quantity, reason } = activation.body;
-  const client = await createClient({
-    connection: connections.fluent_commerce,
-    logger: log,
-  });
-  const result = await client.graphql({
-    query: `
-      mutation UpdateInventory($input: UpdateInventoryQuantityInput!) {
-        updateInventoryQuantity(input: $input) {
-          id
-          ref
-          quantity
-        }
-      }
-    `,
-    variables: {
-      input: {
-        ref: `${sku}-${location}`,
-        quantity: quantity,
-        attributes: [{ name: 'adjustmentReason', type: 'String', value: reason }],
-      },
-    },
-  });
-  log.info('Inventory adjusted', { sku, location, newQuantity: result.quantity });
-  return {
-    status: 200,
-    body: { success: true, inventoryId: result.id },
-  };
-}
-```
-### Use Case 3: Order Status Update (External System → Fluent)
-**Trigger**: Shipping carrier sends delivery confirmation
-**Processing Time**: 2-3 seconds
-**Volume**: 50-200 events/hour
-**SDK Pattern**: GraphQL mutation with event
-**Example**:
-```typescript
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-export default async function updateOrderStatus(activation: any, log: any, connections: any) {
-  const { orderRef, status, trackingNumber, carrier } = activation.body;
-  const client = await createClient({
-    connection: connections.fluent_commerce,
-    logger: log,
-  });
-  // Send event to Fluent workflow
-  const result = await client.graphql({
-    query: `
-      mutation SendEvent($input: EventInput!) {
-        sendEvent(input: $input) {
-          id
-          status
-        }
-      }
-    `,
-    variables: {
-      input: {
-        entityRef: orderRef,
-        entityType: 'ORDER',
-        name: 'carrier.tracking.update',
-        attributes: [
-          { name: 'trackingNumber', type: 'String', value: trackingNumber },
-          { name: 'carrier', type: 'String', value: carrier },
-          { name: 'status', type: 'String', value: status },
-        ],
-      },
-    },
-  });
-  return {
-    status: 200,
-    body: { success: true, eventId: result.id },
-  };
-}
-```
----
-## SDK Components for Real-Time Processing
-### Component 1: `createClient()`
-**Purpose**: Create authenticated Fluent API client
-**Usage**:
-```typescript
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-// Versori platform (recommended)
-const client = await createClient({
-  connection: connections.fluent_commerce,
-  logger: log,
-});
-// Standalone (Node.js/Deno)
-const client = await createClient({
-  config: {
-    baseUrl: 'https://api.fluentcommerce.com',
-    clientId: process.env.FLUENT_CLIENT_ID,
-    clientSecret: process.env.FLUENT_CLIENT_SECRET,
-    retailerId: process.env.FLUENT_RETAILER_ID,
-  },
-});
-```
-**What it does**:
-- Extracts OAuth2 credentials from connection
-- Manages token refresh automatically
-- Returns ready-to-use `FluentClient` instance
-### Component 2: `GraphQLMutationMapper`
-**Purpose**: Transform external data (XML/JSON) to Fluent GraphQL mutations
-**Usage**:
-```typescript
-import { GraphQLMutationMapper } from '@fluentcommerce/fc-connect-sdk';
-const mapper = new GraphQLMutationMapper(mappingConfig, logger, { fluentClient: client });
-// Process with nodes (for nested/escaped XML)
-const result = await mapper.mapWithNodes(orderData, customResolvers, context);
-// Check success (errors are returned, not thrown)
-if (!result.success) {
-  console.error('Mapping failed:', result.errors);
-  return;
-}
-// Execute (query is auto-generated in result)
-const mutationResult = await client.graphql({
-  query: result.query,
-  variables: result.variables,  // ✅ Use variables (wrapped if fields pattern)
-});
-```
-**Key features**:
-- **Nodes**: Extract and parse nested XML/JSON
-- **Field Mapping**: Transform source fields to target schema
-- **Custom Resolvers**: Apply business logic during transformation
-- **Validation**: Checks required fields and types
-**Complete guide**: [GraphQL Mutation Mapper](../../../02-CORE-GUIDES/api-reference/modules/api-reference-04-graphql-mapping.md)
-### Component 3: `FluentClient` Methods
-**Available methods**:
-```typescript
-// Query (returns data only)
-const orders = await client.graphql({
-  query: GET_ORDERS_QUERY,
-  variables: { status: 'PENDING' },
-});
-// Mutation (returns data only)
-const created = await client.graphql({
-  query: CREATE_ORDER_MUTATION,
-  variables: { input: orderData },
-});
-// Advanced (with pagination, progress, extensions)
-const result = await client.graphql({
-  query: GET_ALL_ORDERS,
-  variables: { first: 100 },
-  pagination: {
-    maxPages: 50,
-    onProgress: (page, total) => log.info(`Page ${page}/${total}`),
-  },
-});
-```
-**When to use each**:
-- `query()` - Simple queries without pagination
-- `mutate()` - Create/update operations
-- `graphql()` - Auto-pagination, progress tracking, extensions
-### Component 4: `UniversalMapper`
-**Purpose**: Field-level transformation for any data format (CSV, JSON, XML, Parquet)
-**Usage**:
-```typescript
-import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-const mappingConfig = {
-  fields: {
-    skuRef: { source: 'sku_id', required: true },
-    qty: { source: 'quantity', resolver: 'sdk.parseInt' },
-    expectedOn: { source: 'date', resolver: 'sdk.formatDate' },
-  },
-};
-const mapper = new UniversalMapper(mappingConfig);
-const result = await mapper.map(sourceData);
-if (result.success) {
-  console.log('Mapped data:', result.data);
-} else {
-  console.error('Mapping errors:', result.errors);
-}
-```
-**Built-in resolvers**:
-- `sdk.parseInt`, `sdk.parseFloat` - Type conversion
-- `sdk.formatDate`, `sdk.parseDate` - Date handling
-- `sdk.uppercase`, `sdk.lowercase`, `sdk.trim` - String manipulation
-- `sdk.boolean`, `sdk.toJson`, `sdk.parseJson` - Type casting
-**Complete guide**: [Universal Mapping](../../../02-CORE-GUIDES/mapping/mapping-readme.md)
----
-## Basic Real-Time Workflow
-### Workflow Pattern
-```typescript
-/**
- * Basic Real-Time Webhook Pattern
- *
- * Steps:
- * 1. Receive webhook payload
- * 2. Validate and parse data
- * 3. Transform to Fluent schema
- * 4. Execute GraphQL mutation
- * 5. Return response
- */
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-export default async function webhookHandler(activation: any, log: any, connections: any) {
-  try {
-    // Step 1: Extract payload
-    const payload = activation.body;
-    log.info('Received webhook', { payload });
-    // Step 2: Validate required fields
-    if (!payload.orderRef) {
-      throw new Error('Missing required field: orderRef');
-    }
-    // Step 3: Create Fluent client
-    const client = await createClient({
-      connection: connections.fluent_commerce,
-      logger: log,
-    });
-    // Step 4: Transform data
-    const fluentInput = {
-      ref: payload.orderRef,
-      type: 'HD',
-      totalPrice: parseFloat(payload.total),
-      currency: payload.currency || 'USD',
-      retailer: { id: '2' },
-    };
-    // Step 5: Execute mutation
-    const result = await client.graphql({
-      query: `
-        mutation CreateOrder($input: CreateOrderInput!) {
-          createOrder(input: $input) {
-            id
-            ref
-            status
-          }
-        }
-      `,
-      variables: { input: fluentInput },
-    });
-    log.info('Order created', { orderId: result.id });
-    // Step 6: Return success
-    return {
-      status: 200,
-      body: {
-        success: true,
-        orderId: result.id,
-        orderRef: result.ref,
-      },
-    };
-  } catch (error: any) {
-    log.error('Webhook processing failed', error);
-    // Step 7: Return error
-    return {
-      status: 500,
-      body: {
-        success: false,
-        error: error.message,
-      },
-    };
-  }
-}
-```
-### Key Steps Explained
-#### Step 1: Extract Payload
-```typescript
-// Versori automatically parses JSON/XML
-const payload = activation.body;
-// For raw strings, use parsers
-import { XMLParserService } from '@fluentcommerce/fc-connect-sdk';
-const parser = new XMLParserService();
-const payload = await parser.parse(activation.body);
-```
-#### Step 2: Validation
-```typescript
-// Required field validation
-const requiredFields = ['orderRef', 'total', 'items'];
-for (const field of requiredFields) {
-  if (!payload[field]) {
-    throw new Error(`Missing required field: ${field}`);
-  }
-}
-// Type validation
-if (typeof payload.total !== 'number') {
-  throw new Error('total must be a number');
-}
-```
-#### Step 3: Client Creation
-```typescript
-// ALWAYS use createClient() - it auto-detects Versori vs standalone
-const client = await createClient({
-  connection: connections.fluent_commerce,
-  logger: log,
-});
-```
-#### Step 4: Data Transformation
-```typescript
-// Simple mapping
-const fluentInput = {
-  ref: payload.orderRef,
-  type: mapOrderType(payload.orderType),
-  totalPrice: parseFloat(payload.total),
-};
-// Complex mapping (use UniversalMapper or GraphQLMutationMapper)
-const mapper = new UniversalMapper(mappingConfig);
-const result = await mapper.map(payload);
-const fluentInput = result.data;
-```
-#### Step 5: Execute Mutation
-```typescript
-// Use mutate() for simple operations
-const result = await client.graphql({
-  query: mutation,
-  variables: { input: fluentInput },
-});
-// Check for errors
-if (!result || !result.id) {
-  throw new Error('Mutation failed: No ID returned');
-}
-```
-#### Step 6-7: Return Response
-```typescript
-// Versori expects { status, body }
-return {
-  status: 200,
-  body: { success: true, orderId: result.id },
-};
-// Error response
-return {
-  status: 500,
-  body: { success: false, error: error.message },
-};
-```
----
-## Real-Time Pattern: Webhook to GraphQL
-### Pattern Overview
-**Purpose**: Transform external webhook data to Fluent GraphQL mutations
-**Flow**:
-```
-Webhook Payload → Parse → Map → Validate → Execute → Response
-```
-### Complete Implementation
-See **[XML Order Ingestion](../../../01-TEMPLATES/versori/webhooks/template-webhook-xml-order-ingestion.md)** for production-ready implementation.
-### Quick Example: JSON Order Webhook
-```typescript
-/**
- * JSON Order Webhook → Fluent Order
- *
- * External system sends JSON order data via POST
- */
-import { createClient, UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-// Mapping configuration
-const ORDER_MAPPING = {
-  fields: {
-    ref: { source: 'order_id', required: true },
-    type: { source: 'order_type', resolver: 'custom.mapOrderType' },
-    totalPrice: { source: 'total', resolver: 'sdk.parseFloat' },
-    currency: { source: 'currency', defaultValue: 'USD' },
-    'retailer.id': { value: '2' },
-    'customer.id': { resolver: 'custom.lookupCustomer' },
-    'items[]': {
-      source: 'line_items',
-      fields: {
-        ref: { source: '$.item_id', resolver: 'sdk.toString' },
-        productRef: { source: '$.sku', required: true },
-        quantity: { source: '$.qty', resolver: 'sdk.parseInt' },
-        price: { source: '$.price', resolver: 'sdk.parseFloat' },
-        currency: { source: '^.currency' }, // Inherit from parent
-      },
-    },
-  },
-};
-// Custom resolvers
-const customResolvers = {
-  'custom.mapOrderType': (value: any) => {
-    const mapping: Record<string, string> = {
-      online: 'HD',
-      store: 'CC',
-    };
-    return mapping[value] || 'HD';
-  },
-  'custom.lookupCustomer': async (value: any, data: any, config: any, helpers: any) => {
-    const email = data.customer_email;
-    // Query for existing customer
-    const result = await helpers.fluentClient.graphql({
-      query: `query GetCustomer($email: String) {
-        customers(primaryEmail: $email, first: 1) {
-          edges { node { id } }
-        }
-      }`,
-      variables: { email },
-    });
-    const existingCustomer = result?.customers?.edges?.[0]?.node;
-    if (existingCustomer) {
-      return existingCustomer.id;
-    }
-    // Create new customer
-    const createResult = await helpers.fluentClient.graphql({
-      query: `mutation CreateCustomer($input: CreateCustomerInput!) {
-        createCustomer(input: $input) { id }
-      }`,
-      variables: {
-        input: {
-          username: email,
-          primaryEmail: email,
-          firstName: data.customer_first_name || 'Guest',
-          lastName: data.customer_last_name || 'Customer',
-          retailer: { id: '2' },
-        },
-      },
-    });
-    return createResult.id;
-  },
-};
-// Webhook handler
-export default async function processJsonOrder(activation: any, log: any, connections: any) {
-  try {
-    const orderData = activation.body;
-    // Create client
-    const client = await createClient({
-      connection: connections.fluent_commerce,
-      logger: log,
-    });
-    // Map data
-    const mapper = new UniversalMapper(ORDER_MAPPING, {
-      customResolvers,
-    });
-    const mapResult = await mapper.map(orderData, {
-      fluentClient: client,
-    });
-    if (!mapResult.success) {
-      throw new Error(`Mapping failed: ${mapResult.errors?.join(', ')}`);
-    }
-    // Execute mutation
-    const result = await client.graphql({
-      query: `
-        mutation CreateOrder($input: CreateOrderInput!) {
-          createOrder(input: $input) {
-            id
-            ref
-            status
-          }
-        }
-      `,
-      variables: { input: mapResult.data },
-    });
-    log.info('Order created', { orderId: result.id });
-    return {
-      status: 200,
-      body: {
-        success: true,
-        orderId: result.id,
-        orderRef: result.ref,
-      },
-    };
-  } catch (error: any) {
-    log.error('Order processing failed', error);
-    return {
-      status: 500,
-      body: {
-        success: false,
-        error: error.message,
-      },
-    };
-  }
-}
-```
-### Example Payload
-**Input** (JSON from external system):
-```json
-{
-  "order_id": "ORD-12345",
-  "order_type": "online",
-  "total": 159.98,
-  "currency": "USD",
-  "customer_email": "john@example.com",
-  "customer_first_name": "John",
-  "customer_last_name": "Doe",
-  "line_items": [
-    {
-      "item_id": "1",
-      "sku": "SKU-001",
-      "qty": 2,
-      "price": 79.99
-    }
-  ]
-}
-```
-**Output** (Fluent GraphQL variables):
-```json
-{
-  "input": {
-    "ref": "ORD-12345",
-    "type": "HD",
-    "totalPrice": 159.98,
-    "currency": "USD",
-    "retailer": { "id": "2" },
-    "customer": { "id": "123456" },
-    "items": [
-      {
-        "ref": "1",
-        "productRef": "SKU-001",
-        "quantity": 2,
-        "price": 79.99,
-        "currency": "USD"
-      }
-    ]
-  }
-}
-```
----
-## Error Handling in Real-Time
-### Error Categories
-| Error Type               | Cause                | HTTP Status | Retry?        |
-| ------------------------ | -------------------- | ----------- | ------------- |
-| **Validation Error**     | Missing/invalid data | 400         | No            |
-| **Authentication Error** | Invalid credentials  | 401         | No            |
-| **Rate Limit**           | Too many requests    | 429         | Yes (backoff) |
-| **Server Error**         | Fluent API down      | 500         | Yes           |
-| **Timeout**              | Processing > 30s     | 504         | Yes           |
-### Error Handling Pattern
-```typescript
-export default async function webhookHandler(activation: any, log: any, connections: any) {
-  try {
-    // Processing logic...
-  } catch (error: any) {
-    // Categorize error
-    if (error.message?.includes('required field')) {
-      // Validation error - don't retry
-      log.error('Validation error', { error: error.message });
-      return {
-        status: 400,
-        body: {
-          success: false,
-          error: 'Validation failed',
-          details: error.message,
-        },
-      };
-    }
-    if (error.message?.includes('rate limit')) {
-      // Rate limit - retry with backoff
-      log.warn('Rate limit hit', { error: error.message });
-      return {
-        status: 429,
-        body: {
-          success: false,
-          error: 'Rate limit exceeded',
-          retryAfter: 60,
-        },
-      };
-    }
-    if (error.message?.includes('timeout')) {
-      // Timeout - log and retry
-      log.error('Request timeout', { error: error.message });
-      return {
-        status: 504,
-        body: {
-          success: false,
-          error: 'Request timeout',
-          retryable: true,
-        },
-      };
-    }
-    // Unknown error
-    log.error('Unexpected error', error);
-    return {
-      status: 500,
-      body: {
-        success: false,
-        error: 'Internal server error',
-      },
-    };
-  }
-}
-```
-### Retry Strategy
-```typescript
-/**
- * Exponential backoff retry wrapper
- */
-async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3, initialDelay = 1000): Promise<T> {
-  let lastError: Error;
-  for (let attempt = 0; attempt < maxRetries; attempt++) {
-    try {
-      return await fn();
-    } catch (error: any) {
-      lastError = error;
-      // Don't retry validation errors
-      if (error.message?.includes('required field')) {
-        throw error;
-      }
-      // Calculate backoff delay
-      const delay = initialDelay * Math.pow(2, attempt);
-      console.log(`Retry attempt ${attempt + 1}/${maxRetries} after ${delay}ms`);
-      await new Promise(resolve => setTimeout(resolve, delay));
-    }
-  }
-  throw lastError!;
-}
-// Usage
-const result = await withRetry(() => client.graphql({ query, variables }));
-```
-### Logging for Debugging
-```typescript
-// Structured logging pattern
-try {
-  log.info('Processing webhook', {
-    eventType: activation.body.type,
-    orderRef: activation.body.order_id,
-  });
-  const result = await client.graphql({ query, variables });
-  log.info('Order created successfully', {
-    orderId: result.id,
-    orderRef: result.ref,
-    processingTime: Date.now() - startTime,
-  });
-} catch (error: any) {
-  log.error('Order creation failed', {
-    error: error.message,
-    stack: error.stack,
-    orderRef: activation.body.order_id,
-    input: JSON.stringify(variables), // Be careful with PII
-  });
-}
-```
----
-## Next Steps
-Now that you understand real-time processing fundamentals, you're ready to learn about batch processing for high-volume scenarios!
-**Continue to:** [Module 2: Batch Processing →](./integration-patterns-02-batch-processing.md)
-Or explore:
-- [Module 4: Webhook Patterns](./integration-patterns-04-webhook-patterns.md) - Advanced webhook handling
-- [Module 5: Error Handling](./integration-patterns-05-error-handling.md) - Resilience strategies
-- [Complete Example: XML Order Ingestion](../../../01-TEMPLATES/versori/webhooks/template-webhook-xml-order-ingestion.md)
----
-## Additional Resources
-- [Fluent GraphQL API Documentation](https://docs.fluentcommerce.com/)
-- [Universal Mapping Guide](../../../02-CORE-GUIDES/mapping/mapping-readme.md)
-- [GraphQL Mutation Mapper API](../../../02-CORE-GUIDES/api-reference/modules/api-reference-04-graphql-mapping.md)
-- [Versori Webhook Patterns](../../../04-REFERENCE/platforms/versori/modules/platforms-versori-04-workflows.md)
----
-[← Back to Index](../integration-patterns-readme.md) | [Next: Batch Processing →](./integration-patterns-02-batch-processing.md)
+# Module 1: Real-Time Processing
+> **Learning Objective:** Understand real-time event processing patterns, when to use them, and how to implement immediate event handling with the Fluent Connect SDK.
+>
+> **Level:** Beginner
+## Table of Contents
+1. [What is Real-Time Processing?](#what-is-real-time-processing)
+2. [When to Use Real-Time Processing](#when-to-use-real-time-processing)
+3. [Real-Time vs Batch: The Decision](#real-time-vs-batch-the-decision)
+4. [Common Real-Time Use Cases](#common-real-time-use-cases)
+5. [SDK Components for Real-Time Processing](#sdk-components-for-real-time-processing)
+6. [Basic Real-Time Workflow](#basic-real-time-workflow)
+7. [Real-Time Pattern: Webhook to GraphQL](#real-time-pattern-webhook-to-graphql)
+8. [Error Handling in Real-Time](#error-handling-in-real-time)
+9. [Next Steps](#next-steps)
+---
+## What is Real-Time Processing?
+**Real-time processing** means handling events as they occur, with minimal latency between event trigger and completion.
+### Key Characteristics
+| Characteristic           | Description                         | Example                        |
+| ------------------------ | ----------------------------------- | ------------------------------ |
+| **Immediate Trigger**    | Event triggers processing instantly | HTTP webhook receives order    |
+| **Low Latency**          | Processing completes in seconds     | Order created within 5 seconds |
+| **Event-Driven**         | External events drive execution     | SFCC order placement           |
+| **Synchronous Response** | Caller waits for result             | Webhook returns success/error  |
+### How It Works
+```
+External Event → Webhook Endpoint → Process Data → Call Fluent API → Return Response
+     ↓               ↓                   ↓              ↓                  ↓
+  <1 second     Parse payload      Transform data   Create order      Success/error
+```
+### Visual Flow
+```
+┌─────────────┐
+│ SFCC Order  │ ──① HTTP POST──>  ┌──────────────────┐
+│   Placed    │                    │ Versori Webhook  │
+└─────────────┘                    │   (Your code)    │
+                                   └────────┬─────────┘
+                                            │
+                                   ②Parse XML/JSON
+                                            │
+                                            ▼
+                                   ┌──────────────────┐
+                                   │ GraphQLMutation  │
+                                   │     Mapper       │
+                                   └────────┬─────────┘
+                                            │
+                                   ③Apply field mapping
+                                            │
+                                            ▼
+                                   ┌──────────────────┐
+                                   │  Fluent Client   │
+                                   │  createOrder()   │
+                                   └────────┬─────────┘
+                                            │
+                                   ④GraphQL mutation
+                                            │
+                                            ▼
+                                   ┌──────────────────┐
+                                   │ Fluent Commerce  │
+                                   │   Order Created  │
+                                   └────────┬─────────┘
+                                            │
+                                   ⑤Return response
+                                            │
+                                            ▼
+                                   ┌──────────────────┐
+                                   │  200 OK          │
+                                   │  { orderId }     │
+                                   └──────────────────┘
+```
+**Total latency**: 2-5 seconds from webhook receipt to Fluent order creation.
+---
+## When to Use Real-Time Processing
+### ✅ Use Real-Time When:
+| Scenario              | Why Real-Time?                          | SDK Pattern                    |
+| --------------------- | --------------------------------------- | ------------------------------ |
+| **Order Webhooks**    | Customers expect immediate confirmation | Webhook → GraphQL mutation     |
+| **Inventory Updates** | Stock levels must be accurate instantly | Webhook → Batch API (single)   |
+| **Low Volume**        | < 100 events/hour                       | Simple webhook handler         |
+| **Critical Events**   | Payment, shipment, cancellation         | Immediate processing + logging |
+| **External Triggers** | Third-party systems push data           | HTTP endpoint required         |
+### ❌ Avoid Real-Time When:
+| Scenario            | Why Not Real-Time?   | Use Instead                 |
+| ------------------- | -------------------- | --------------------------- |
+| **Large Files**     | 10K+ records         | Batch processing (Module 2) |
+| **High Volume**     | > 1,000 events/hour  | Scheduled batch (Module 2)  |
+| **Long Processing** | > 30 seconds         | Async job queue             |
+| **Bulk Operations** | Daily inventory sync | Batch API (Module 2)        |
+| **Non-Critical**    | Reports, analytics   | Scheduled extraction        |
+---
+## Real-Time vs Batch: The Decision
+### Volume-Based Decision Matrix
+```
+Events/Hour │ Pattern
+────────────┼────────────────────────────────
+    < 10    │ Real-Time (Webhook)
+   10-100   │ Real-Time (Webhook)
+  100-500   │ Real-Time OR Micro-batch
+  500-1K    │ Micro-batch (5-minute windows)
+   1K-10K   │ Batch (hourly)
+   > 10K    │ Batch (daily)
+```
+### Latency Requirements
+| Requirement     | Pattern      | Example              |
+| --------------- | ------------ | -------------------- |
+| **< 5 seconds** | Real-Time    | Order confirmation   |
+| **< 5 minutes** | Micro-batch  | Inventory updates    |
+| **< 1 hour**    | Hourly batch | Product catalog sync |
+| **< 24 hours**  | Daily batch  | Full inventory sync  |
+### Example Decisions
+#### ✅ GOOD: Real-Time for Order Webhooks
+```typescript
+// Scenario: SFCC sends 20-50 orders/hour
+// Requirement: Orders visible in Fluent within 5 seconds
+// Volume: Low (<100/hour)
+// Pattern: Real-time webhook
+export default async function processOrder(ctx) {
+  const orderData = ctx.activation.body;
+  const client = await createClient(ctx); // Auto-detects Versori context
+  // Immediate processing
+  const result = await client.graphql({
+    query: CREATE_ORDER_MUTATION,
+    variables: { input: mapOrderData(orderData) },
+  });
+  return { status: 200, body: { orderId: result.id } };
+}
+```
+**Why this works**: Low volume + low latency requirement = perfect for real-time.
+#### ❌ WRONG: Real-Time for Bulk Inventory
+```typescript
+// ❌ BAD: Trying to process 50K inventory records via webhooks
+export default async function processInventory(activation, log, connections) {
+  const inventoryFile = activation.body.fileUrl; // 50K records
+  // This will timeout! Each webhook has 30-second limit
+  for (const record of records) {
+    await client.graphql({ ... }); // 50K sequential API calls = HOURS
+  }
+}
+```
+**Why this fails**:
+- Webhook timeout (30-60 seconds)
+- 50K sequential API calls = 1-2 hours
+- No progress tracking
+- No error recovery
+**✅ Better approach**: Use Batch API (Module 2)
+```typescript
+// Process 50K records in 5-10 minutes via Batch API
+const job = await client.createJob({ name: 'inventory-update' });
+const batch = await client.sendBatch(job.id, { entities: records });
+```
+---
+## Common Real-Time Use Cases
+### Use Case 1: SFCC Order Creation
+**Trigger**: Salesforce Commerce Cloud sends order XML via webhook
+**Processing Time**: 3-5 seconds
+**Volume**: 10-100 orders/hour
+**SDK Pattern**: `GraphQLMutationMapper` + `createClient`
+**Complete implementation**: [XML Order Ingestion Guide](../../../01-TEMPLATES/versori/webhooks/template-webhook-xml-order-ingestion.md)
+### Use Case 2: Inventory Adjustment (Single SKU)
+**Trigger**: Warehouse system reports damage/theft
+**Processing Time**: 1-2 seconds
+**Volume**: < 10 events/hour
+**SDK Pattern**: Direct GraphQL mutation
+**Example**:
+```typescript
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+export default async function adjustInventory(activation: any, log: any, connections: any) {
+  const { sku, location, quantity, reason } = activation.body;
+  const client = await createClient({
+    connection: connections.fluent_commerce,
+    logger: log,
+  });
+  const result = await client.graphql({
+    query: `
+      mutation UpdateInventory($input: UpdateInventoryQuantityInput!) {
+        updateInventoryQuantity(input: $input) {
+          id
+          ref
+          quantity
+        }
+      }
+    `,
+    variables: {
+      input: {
+        ref: `${sku}-${location}`,
+        quantity: quantity,
+        attributes: [{ name: 'adjustmentReason', type: 'String', value: reason }],
+      },
+    },
+  });
+  log.info('Inventory adjusted', { sku, location, newQuantity: result.quantity });
+  return {
+    status: 200,
+    body: { success: true, inventoryId: result.id },
+  };
+}
+```
+### Use Case 3: Order Status Update (External System → Fluent)
+**Trigger**: Shipping carrier sends delivery confirmation
+**Processing Time**: 2-3 seconds
+**Volume**: 50-200 events/hour
+**SDK Pattern**: GraphQL mutation with event
+**Example**:
+```typescript
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+export default async function updateOrderStatus(activation: any, log: any, connections: any) {
+  const { orderRef, status, trackingNumber, carrier } = activation.body;
+  const client = await createClient({
+    connection: connections.fluent_commerce,
+    logger: log,
+  });
+  // Send event to Fluent workflow
+  const result = await client.graphql({
+    query: `
+      mutation SendEvent($input: EventInput!) {
+        sendEvent(input: $input) {
+          id
+          status
+        }
+      }
+    `,
+    variables: {
+      input: {
+        entityRef: orderRef,
+        entityType: 'ORDER',
+        name: 'carrier.tracking.update',
+        attributes: [
+          { name: 'trackingNumber', type: 'String', value: trackingNumber },
+          { name: 'carrier', type: 'String', value: carrier },
+          { name: 'status', type: 'String', value: status },
+        ],
+      },
+    },
+  });
+  return {
+    status: 200,
+    body: { success: true, eventId: result.id },
+  };
+}
+```
+---
+## SDK Components for Real-Time Processing
+### Component 1: `createClient()`
+**Purpose**: Create authenticated Fluent API client
+**Usage**:
+```typescript
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+// Versori platform (recommended)
+const client = await createClient({
+  connection: connections.fluent_commerce,
+  logger: log,
+});
+// Standalone (Node.js/Deno)
+const client = await createClient({
+  config: {
+    baseUrl: 'https://api.fluentcommerce.com',
+    clientId: process.env.FLUENT_CLIENT_ID,
+    clientSecret: process.env.FLUENT_CLIENT_SECRET,
+    retailerId: process.env.FLUENT_RETAILER_ID,
+  },
+});
+```
+**What it does**:
+- Extracts OAuth2 credentials from connection
+- Manages token refresh automatically
+- Returns ready-to-use `FluentClient` instance
+### Component 2: `GraphQLMutationMapper`
+**Purpose**: Transform external data (XML/JSON) to Fluent GraphQL mutations
+**Usage**:
+```typescript
+import { GraphQLMutationMapper } from '@fluentcommerce/fc-connect-sdk';
+const mapper = new GraphQLMutationMapper(mappingConfig, logger, { fluentClient: client });
+// Process with nodes (for nested/escaped XML)
+const result = await mapper.mapWithNodes(orderData, customResolvers, context);
+// Check success (errors are returned, not thrown)
+if (!result.success) {
+  console.error('Mapping failed:', result.errors);
+  return;
+}
+// Execute (query is auto-generated in result)
+const mutationResult = await client.graphql({
+  query: result.query,
+  variables: result.variables,  // ✅ Use variables (wrapped if fields pattern)
+});
+```
+**Key features**:
+- **Nodes**: Extract and parse nested XML/JSON
+- **Field Mapping**: Transform source fields to target schema
+- **Custom Resolvers**: Apply business logic during transformation
+- **Validation**: Checks required fields and types
+**Complete guide**: [GraphQL Mutation Mapper](../../../02-CORE-GUIDES/api-reference/modules/api-reference-04-graphql-mapping.md)
+### Component 3: `FluentClient` Methods
+**Available methods**:
+```typescript
+// Query (returns data only)
+const orders = await client.graphql({
+  query: GET_ORDERS_QUERY,
+  variables: { status: 'PENDING' },
+});
+// Mutation (returns data only)
+const created = await client.graphql({
+  query: CREATE_ORDER_MUTATION,
+  variables: { input: orderData },
+});
+// Advanced (with pagination, progress, extensions)
+const result = await client.graphql({
+  query: GET_ALL_ORDERS,
+  variables: { first: 100 },
+  pagination: {
+    maxPages: 50,
+    onProgress: (page, total) => log.info(`Page ${page}/${total}`),
+  },
+});
+```
+**When to use each**:
+- `query()` - Simple queries without pagination
+- `mutate()` - Create/update operations
+- `graphql()` - Auto-pagination, progress tracking, extensions
+### Component 4: `UniversalMapper`
+**Purpose**: Field-level transformation for any data format (CSV, JSON, XML, Parquet)
+**Usage**:
+```typescript
+import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+const mappingConfig = {
+  fields: {
+    skuRef: { source: 'sku_id', required: true },
+    qty: { source: 'quantity', resolver: 'sdk.parseInt' },
+    expectedOn: { source: 'date', resolver: 'sdk.formatDate' },
+  },
+};
+const mapper = new UniversalMapper(mappingConfig);
+const result = await mapper.map(sourceData);
+if (result.success) {
+  console.log('Mapped data:', result.data);
+} else {
+  console.error('Mapping errors:', result.errors);
+}
+```
+**Built-in resolvers**:
+- `sdk.parseInt`, `sdk.parseFloat` - Type conversion
+- `sdk.formatDate`, `sdk.parseDate` - Date handling
+- `sdk.uppercase`, `sdk.lowercase`, `sdk.trim` - String manipulation
+- `sdk.boolean`, `sdk.toJson`, `sdk.parseJson` - Type casting
+**Complete guide**: [Universal Mapping](../../../02-CORE-GUIDES/mapping/mapping-readme.md)
+---
+## Basic Real-Time Workflow
+### Workflow Pattern
+```typescript
+/**
+ * Basic Real-Time Webhook Pattern
+ *
+ * Steps:
+ * 1. Receive webhook payload
+ * 2. Validate and parse data
+ * 3. Transform to Fluent schema
+ * 4. Execute GraphQL mutation
+ * 5. Return response
+ */
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+export default async function webhookHandler(activation: any, log: any, connections: any) {
+  try {
+    // Step 1: Extract payload
+    const payload = activation.body;
+    log.info('Received webhook', { payload });
+    // Step 2: Validate required fields
+    if (!payload.orderRef) {
+      throw new Error('Missing required field: orderRef');
+    }
+    // Step 3: Create Fluent client
+    const client = await createClient({
+      connection: connections.fluent_commerce,
+      logger: log,
+    });
+    // Step 4: Transform data
+    const fluentInput = {
+      ref: payload.orderRef,
+      type: 'HD',
+      totalPrice: parseFloat(payload.total),
+      currency: payload.currency || 'USD',
+      retailer: { id: '2' },
+    };
+    // Step 5: Execute mutation
+    const result = await client.graphql({
+      query: `
+        mutation CreateOrder($input: CreateOrderInput!) {
+          createOrder(input: $input) {
+            id
+            ref
+            status
+          }
+        }
+      `,
+      variables: { input: fluentInput },
+    });
+    log.info('Order created', { orderId: result.id });
+    // Step 6: Return success
+    return {
+      status: 200,
+      body: {
+        success: true,
+        orderId: result.id,
+        orderRef: result.ref,
+      },
+    };
+  } catch (error: any) {
+    log.error('Webhook processing failed', error);
+    // Step 7: Return error
+    return {
+      status: 500,
+      body: {
+        success: false,
+        error: error.message,
+      },
+    };
+  }
+}
+```
+### Key Steps Explained
+#### Step 1: Extract Payload
+```typescript
+// Versori automatically parses JSON/XML
+const payload = activation.body;
+// For raw strings, use parsers
+import { XMLParserService } from '@fluentcommerce/fc-connect-sdk';
+const parser = new XMLParserService();
+const payload = await parser.parse(activation.body);
+```
+#### Step 2: Validation
+```typescript
+// Required field validation
+const requiredFields = ['orderRef', 'total', 'items'];
+for (const field of requiredFields) {
+  if (!payload[field]) {
+    throw new Error(`Missing required field: ${field}`);
+  }
+}
+// Type validation
+if (typeof payload.total !== 'number') {
+  throw new Error('total must be a number');
+}
+```
+#### Step 3: Client Creation
+```typescript
+// ALWAYS use createClient() - it auto-detects Versori vs standalone
+const client = await createClient({
+  connection: connections.fluent_commerce,
+  logger: log,
+});
+```
+#### Step 4: Data Transformation
+```typescript
+// Simple mapping
+const fluentInput = {
+  ref: payload.orderRef,
+  type: mapOrderType(payload.orderType),
+  totalPrice: parseFloat(payload.total),
+};
+// Complex mapping (use UniversalMapper or GraphQLMutationMapper)
+const mapper = new UniversalMapper(mappingConfig);
+const result = await mapper.map(payload);
+const fluentInput = result.data;
+```
+#### Step 5: Execute Mutation
+```typescript
+// Use mutate() for simple operations
+const result = await client.graphql({
+  query: mutation,
+  variables: { input: fluentInput },
+});
+// Check for errors
+if (!result || !result.id) {
+  throw new Error('Mutation failed: No ID returned');
+}
+```
+#### Step 6-7: Return Response
+```typescript
+// Versori expects { status, body }
+return {
+  status: 200,
+  body: { success: true, orderId: result.id },
+};
+// Error response
+return {
+  status: 500,
+  body: { success: false, error: error.message },
+};
+```
+---
+## Real-Time Pattern: Webhook to GraphQL
+### Pattern Overview
+**Purpose**: Transform external webhook data to Fluent GraphQL mutations
+**Flow**:
+```
+Webhook Payload → Parse → Map → Validate → Execute → Response
+```
+### Complete Implementation
+See **[XML Order Ingestion](../../../01-TEMPLATES/versori/webhooks/template-webhook-xml-order-ingestion.md)** for production-ready implementation.
+### Quick Example: JSON Order Webhook
+```typescript
+/**
+ * JSON Order Webhook → Fluent Order
+ *
+ * External system sends JSON order data via POST
+ */
+import { createClient, UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+// Mapping configuration
+const ORDER_MAPPING = {
+  fields: {
+    ref: { source: 'order_id', required: true },
+    type: { source: 'order_type', resolver: 'custom.mapOrderType' },
+    totalPrice: { source: 'total', resolver: 'sdk.parseFloat' },
+    currency: { source: 'currency', defaultValue: 'USD' },
+    'retailer.id': { value: '2' },
+    'customer.id': { resolver: 'custom.lookupCustomer' },
+    'items[]': {
+      source: 'line_items',
+      fields: {
+        ref: { source: '$.item_id', resolver: 'sdk.toString' },
+        productRef: { source: '$.sku', required: true },
+        quantity: { source: '$.qty', resolver: 'sdk.parseInt' },
+        price: { source: '$.price', resolver: 'sdk.parseFloat' },
+        currency: { source: '^.currency' }, // Inherit from parent
+      },
+    },
+  },
+};
+// Custom resolvers
+const customResolvers = {
+  'custom.mapOrderType': (value: any) => {
+    const mapping: Record<string, string> = {
+      online: 'HD',
+      store: 'CC',
+    };
+    return mapping[value] || 'HD';
+  },
+  'custom.lookupCustomer': async (value: any, data: any, config: any, helpers: any) => {
+    const email = data.customer_email;
+    // Query for existing customer
+    const result = await helpers.fluentClient.graphql({
+      query: `query GetCustomer($email: String) {
+        customers(primaryEmail: $email, first: 1) {
+          edges { node { id } }
+        }
+      }`,
+      variables: { email },
+    });
+    const existingCustomer = result?.customers?.edges?.[0]?.node;
+    if (existingCustomer) {
+      return existingCustomer.id;
+    }
+    // Create new customer
+    const createResult = await helpers.fluentClient.graphql({
+      query: `mutation CreateCustomer($input: CreateCustomerInput!) {
+        createCustomer(input: $input) { id }
+      }`,
+      variables: {
+        input: {
+          username: email,
+          primaryEmail: email,
+          firstName: data.customer_first_name || 'Guest',
+          lastName: data.customer_last_name || 'Customer',
+          retailer: { id: '2' },
+        },
+      },
+    });
+    return createResult.id;
+  },
+};
+// Webhook handler
+export default async function processJsonOrder(activation: any, log: any, connections: any) {
+  try {
+    const orderData = activation.body;
+    // Create client
+    const client = await createClient({
+      connection: connections.fluent_commerce,
+      logger: log,
+    });
+    // Map data
+    const mapper = new UniversalMapper(ORDER_MAPPING, {
+      customResolvers,
+    });
+    const mapResult = await mapper.map(orderData, {
+      fluentClient: client,
+    });
+    if (!mapResult.success) {
+      throw new Error(`Mapping failed: ${mapResult.errors?.join(', ')}`);
+    }
+    // Execute mutation
+    const result = await client.graphql({
+      query: `
+        mutation CreateOrder($input: CreateOrderInput!) {
+          createOrder(input: $input) {
+            id
+            ref
+            status
+          }
+        }
+      `,
+      variables: { input: mapResult.data },
+    });
+    log.info('Order created', { orderId: result.id });
+    return {
+      status: 200,
+      body: {
+        success: true,
+        orderId: result.id,
+        orderRef: result.ref,
+      },
+    };
+  } catch (error: any) {
+    log.error('Order processing failed', error);
+    return {
+      status: 500,
+      body: {
+        success: false,
+        error: error.message,
+      },
+    };
+  }
+}
+```
+### Example Payload
+**Input** (JSON from external system):
+```json
+{
+  "order_id": "ORD-12345",
+  "order_type": "online",
+  "total": 159.98,
+  "currency": "USD",
+  "customer_email": "john@example.com",
+  "customer_first_name": "John",
+  "customer_last_name": "Doe",
+  "line_items": [
+    {
+      "item_id": "1",
+      "sku": "SKU-001",
+      "qty": 2,
+      "price": 79.99
+    }
+  ]
+}
+```
+**Output** (Fluent GraphQL variables):
+```json
+{
+  "input": {
+    "ref": "ORD-12345",
+    "type": "HD",
+    "totalPrice": 159.98,
+    "currency": "USD",
+    "retailer": { "id": "2" },
+    "customer": { "id": "123456" },
+    "items": [
+      {
+        "ref": "1",
+        "productRef": "SKU-001",
+        "quantity": 2,
+        "price": 79.99,
+        "currency": "USD"
+      }
+    ]
+  }
+}
+```
+---
+## Error Handling in Real-Time
+### Error Categories
+| Error Type               | Cause                | HTTP Status | Retry?        |
+| ------------------------ | -------------------- | ----------- | ------------- |
+| **Validation Error**     | Missing/invalid data | 400         | No            |
+| **Authentication Error** | Invalid credentials  | 401         | No            |
+| **Rate Limit**           | Too many requests    | 429         | Yes (backoff) |
+| **Server Error**         | Fluent API down      | 500         | Yes           |
+| **Timeout**              | Processing > 30s     | 504         | Yes           |
+### Error Handling Pattern
+```typescript
+export default async function webhookHandler(activation: any, log: any, connections: any) {
+  try {
+    // Processing logic...
+  } catch (error: any) {
+    // Categorize error
+    if (error.message?.includes('required field')) {
+      // Validation error - don't retry
+      log.error('Validation error', { error: error.message });
+      return {
+        status: 400,
+        body: {
+          success: false,
+          error: 'Validation failed',
+          details: error.message,
+        },
+      };
+    }
+    if (error.message?.includes('rate limit')) {
+      // Rate limit - retry with backoff
+      log.warn('Rate limit hit', { error: error.message });
+      return {
+        status: 429,
+        body: {
+          success: false,
+          error: 'Rate limit exceeded',
+          retryAfter: 60,
+        },
+      };
+    }
+    if (error.message?.includes('timeout')) {
+      // Timeout - log and retry
+      log.error('Request timeout', { error: error.message });
+      return {
+        status: 504,
+        body: {
+          success: false,
+          error: 'Request timeout',
+          retryable: true,
+        },
+      };
+    }
+    // Unknown error
+    log.error('Unexpected error', error);
+    return {
+      status: 500,
+      body: {
+        success: false,
+        error: 'Internal server error',
+      },
+    };
+  }
+}
+```
+### Retry Strategy
+```typescript
+/**
+ * Exponential backoff retry wrapper
+ */
+async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3, initialDelay = 1000): Promise<T> {
+  let lastError: Error;
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (error: any) {
+      lastError = error;
+      // Don't retry validation errors
+      if (error.message?.includes('required field')) {
+        throw error;
+      }
+      // Calculate backoff delay
+      const delay = initialDelay * Math.pow(2, attempt);
+      console.log(`Retry attempt ${attempt + 1}/${maxRetries} after ${delay}ms`);
+      await new Promise(resolve => setTimeout(resolve, delay));
+    }
+  }
+  throw lastError!;
+}
+// Usage
+const result = await withRetry(() => client.graphql({ query, variables }));
+```
+### Logging for Debugging
+```typescript
+// Structured logging pattern
+try {
+  log.info('Processing webhook', {
+    eventType: activation.body.type,
+    orderRef: activation.body.order_id,
+  });
+  const result = await client.graphql({ query, variables });
+  log.info('Order created successfully', {
+    orderId: result.id,
+    orderRef: result.ref,
+    processingTime: Date.now() - startTime,
+  });
+} catch (error: any) {
+  log.error('Order creation failed', {
+    error: error.message,
+    stack: error.stack,
+    orderRef: activation.body.order_id,
+    input: JSON.stringify(variables), // Be careful with PII
+  });
+}
+```
+---
+## Next Steps
+Now that you understand real-time processing fundamentals, you're ready to learn about batch processing for high-volume scenarios!
+**Continue to:** [Module 2: Batch Processing →](./integration-patterns-02-batch-processing.md)
+Or explore:
+- [Module 4: Webhook Patterns](./integration-patterns-04-webhook-patterns.md) - Advanced webhook handling
+- [Module 5: Error Handling](./integration-patterns-05-error-handling.md) - Resilience strategies
+- [Complete Example: XML Order Ingestion](../../../01-TEMPLATES/versori/webhooks/template-webhook-xml-order-ingestion.md)
+---
+## Additional Resources
+- [Fluent GraphQL API Documentation](https://docs.fluentcommerce.com/)
+- [Universal Mapping Guide](../../../02-CORE-GUIDES/mapping/mapping-readme.md)
+- [GraphQL Mutation Mapper API](../../../02-CORE-GUIDES/api-reference/modules/api-reference-04-graphql-mapping.md)
+- [Versori Webhook Patterns](../../../04-REFERENCE/platforms/versori/modules/platforms-versori-04-workflows.md)
+---
+[← Back to Index](../integration-patterns-readme.md) | [Next: Batch Processing →](./integration-patterns-02-batch-processing.md)