@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

package/docs/02-CORE-GUIDES/ingestion/examples/event-driven.ts

@@ -1,501 +1,501 @@
-/**
- * Event-Driven Ingestion Example
- *
- * Demonstrates event-driven inventory ingestion using webhooks and Fluent events.
- * Supports both Versori platform webhooks and standalone webhook handlers.
- *
- * Use Cases:
- * - Real-time inventory updates from WMS
- * - Webhook-triggered ingestion from external systems
- * - Event-based inventory adjustments
- * - Fluent event processing for downstream systems
- *
- * Prerequisites:
- * - npm install @fluentcommerce/fc-connect-sdk
- * - Configure webhook endpoint (Versori or standalone)
- *
- * Usage:
- * npx tsx examples/event-driven.ts
- */
-
-import {
-  createClient,
-  UniversalMapper,
-  StateService,
-  SimpleKVStore,
-  FluentClient,
-} from '@fluentcommerce/fc-connect-sdk';
-
-// ============================================================================
-// Configuration
-// ============================================================================
-
-const config = {
-  fluent: {
-    baseUrl: process.env.FLUENT_BASE_URL!,
-    clientId: process.env.FLUENT_CLIENT_ID!,
-    clientSecret: process.env.FLUENT_CLIENT_SECRET!,
-    retailerId: process.env.FLUENT_RETAILER_ID!,
-  },
-  webhook: {
-    port: parseInt(process.env.WEBHOOK_PORT || '3000'),
-    path: '/webhook/inventory',
-    secret: process.env.WEBHOOK_SECRET || 'your-webhook-secret',
-  },
-};
-
-// Field mapping for inventory updates
-const mappingConfig = {
-  fields: {
-    ref: {
-      source: 'sku',
-      required: true,
-      comment: 'Inventory position reference',
-    },
-    productRef: {
-      source: 'sku',
-      required: true,
-      comment: 'Product SKU reference',
-    },
-    locationRef: {
-      source: 'location',
-      required: true,
-      comment: 'Warehouse location code',
-    },
-    qty: {
-      source: 'quantity',
-      resolver: 'sdk.parseInt',
-      required: true,
-      comment: 'Available quantity',
-    },
-    status: {
-      source: 'status',
-      resolver: 'sdk.uppercase',
-      defaultValue: 'AVAILABLE',
-      comment: 'Inventory status',
-    },
-  },
-};
-
-// ============================================================================
-// Event Handler Functions
-// ============================================================================
-
-/**
- * Process webhook payload for inventory update
- */
-async function handleInventoryWebhook(payload: any): Promise<{
-  success: boolean;
-  jobId?: string;
-  records?: number;
-  errors?: string[];
-}> {
-  console.log('📥 Received inventory webhook event');
-
-  try {
-    // Initialize services
-    const client = await createClient({ config: config.fluent });
-    const mapper = new UniversalMapper(mappingConfig);
-    const state = new StateService(new SimpleKVStore());
-
-    // Extract inventory data from payload
-    const inventoryData = extractInventoryData(payload);
-
-    if (!inventoryData || inventoryData.length === 0) {
-      return {
-        success: false,
-        errors: ['No inventory data found in webhook payload'],
-      };
-    }
-
-    console.log(`  Processing ${inventoryData.length} inventory records`);
-
-    // Generate unique event ID for deduplication
-    const eventId = generateEventId(payload);
-
-    // Check if event already processed
-    if (await state.isFileProcessed(eventId)) {
-      console.log('  ⏭ Event already processed (duplicate webhook)');
-      return {
-        success: true,
-        records: 0,
-      };
-    }
-
-    // Acquire lock to prevent concurrent processing
-    const lock = await state.acquireLock(eventId, 30000); // 30s lock
-
-    if (!lock.acquired) {
-      console.log('  ⏸ Event locked by another process');
-      return {
-        success: false,
-        errors: ['Event is being processed by another worker'],
-      };
-    }
-
-    try {
-      // Transform data with UniversalMapper
-      const result = await mapper.map(inventoryData);
-
-      if (!result.success) {
-        console.error('  ✗ Mapping validation failed:', result.errors);
-        return {
-          success: false,
-          errors: result.errors,
-        };
-      }
-
-      console.log(`  ✓ Mapped ${result.data.length} valid records`);
-
-      // Create batch job
-      const job = await client.createJob({
-        name: `Webhook Import - ${eventId}`,
-        retailerId: config.fluent.retailerId,
-      });
-
-      console.log(`  📝 Created job: ${job.id}`);
-
-      // Send batch to Fluent Commerce
-      await client.sendBatch(job.id, {
-        action: 'UPSERT',
-        entityType: 'INVENTORY',
-        source: 'EVENT_DRIVEN_WEBHOOK',
-        event: 'INVENTORY_UPDATE',
-        entities: result.data,
-      });
-
-      // Mark event as processed
-      await state.markFileProcessed(eventId, {
-        jobId: job.id,
-        records: result.data.length,
-        processedAt: new Date().toISOString(),
-        eventType: payload.eventType || 'inventory.update',
-      });
-
-      console.log(`  ✅ Successfully ingested ${result.data.length} records`);
-
-      return {
-        success: true,
-        jobId: job.id,
-        records: result.data.length,
-      };
-    } finally {
-      // Always release lock
-      await state.releaseLock(eventId);
-    }
-  } catch (error: any) {
-    console.error('  ❌ Webhook processing failed:', error.message);
-    return {
-      success: false,
-      errors: [error.message],
-    };
-  }
-}
-
-/**
- * Process Fluent event for downstream systems
- */
-async function handleFluentEvent(event: any): Promise<void> {
-  console.log('📣 Received Fluent event:', event.type);
-
-  // Example: React to inventory position changes
-  if (event.type === 'INVENTORY_UPDATED' || event.type === 'INVENTORY_POSITION_UPDATED') {
-    const { ref, qty, locationRef } = event.data;
-
-    console.log(`  Inventory updated: ${ref} at ${locationRef} → ${qty} units`);
-
-    // Example: Trigger downstream actions
-    if (qty < 10) {
-      console.log(`  ⚠ Low stock alert for ${ref}`);
-      // Send alert to external system
-    }
-
-    if (qty === 0) {
-      console.log(`  🚫 Out of stock for ${ref}`);
-      // Notify e-commerce platform
-    }
-  }
-
-  // Example: React to batch job completion
-  if (event.type === 'BATCH_JOB_COMPLETED') {
-    const { jobId, status, recordsProcessed } = event.data;
-
-    console.log(`  Batch job ${jobId} completed: ${status}`);
-    console.log(`  Records processed: ${recordsProcessed}`);
-
-    // Update external monitoring system
-  }
-}
-
-/**
- * Extract inventory data from webhook payload
- */
-function extractInventoryData(payload: any): any[] {
-  // Handle different payload formats
-
-  // Format 1: Direct array
-  if (Array.isArray(payload)) {
-    return payload;
-  }
-
-  // Format 2: Nested in 'data' field
-  if (payload.data && Array.isArray(payload.data)) {
-    return payload.data;
-  }
-
-  // Format 3: Single inventory update
-  if (payload.inventory) {
-    return Array.isArray(payload.inventory) ? payload.inventory : [payload.inventory];
-  }
-
-  // Format 4: WMS event structure
-  if (payload.eventType === 'inventory.updated' && payload.items) {
-    return payload.items;
-  }
-
-  return [];
-}
-
-/**
- * Generate unique event ID for deduplication
- */
-function generateEventId(payload: any): string {
-  // Use webhook event ID if provided
-  if (payload.eventId) {
-    return `webhook-${payload.eventId}`;
-  }
-
-  // Use timestamp + hash for custom events
-  const timestamp = payload.timestamp || new Date().toISOString();
-  const hash = hashPayload(payload);
-
-  return `webhook-${timestamp}-${hash}`;
-}
-
-/**
- * Simple hash function for payload deduplication
- */
-function hashPayload(payload: any): string {
-  const str = JSON.stringify(payload);
-  let hash = 0;
-
-  for (let i = 0; i < str.length; i++) {
-    const char = str.charCodeAt(i);
-    hash = (hash << 5) - hash + char;
-    hash = hash & hash; // Convert to 32-bit integer
-  }
-
-  return Math.abs(hash).toString(36);
-}
-
-// ============================================================================
-// Standalone Webhook Server (Express Example)
-// ============================================================================
-
-/**
- * Standalone webhook server for non-Versori deployments
- */
-async function startWebhookServer() {
-  // Note: This requires 'express' package
-  // npm install express
-
-  const express = require('express');
-  const app = express();
-
-  app.use(express.json());
-
-  // Webhook endpoint
-  app.post(config.webhook.path, async (req: any, res: any) => {
-    const startTime = Date.now();
-
-    // Verify webhook signature (optional but recommended)
-    const signature = req.headers['x-webhook-signature'];
-    if (!verifyWebhookSignature(req.body, signature)) {
-      return res.status(401).json({
-        success: false,
-        error: 'Invalid webhook signature',
-      });
-    }
-
-    // Process webhook
-    const result = await handleInventoryWebhook(req.body);
-
-    const duration = Date.now() - startTime;
-
-    if (result.success) {
-      res.status(200).json({
-        success: true,
-        jobId: result.jobId,
-        records: result.records,
-        processingTime: `${duration}ms`,
-      });
-    } else {
-      res.status(400).json({
-        success: false,
-        errors: result.errors,
-        processingTime: `${duration}ms`,
-      });
-    }
-  });
-
-  // Health check endpoint
-  app.get('/health', (req: any, res: any) => {
-    res.status(200).json({
-      status: 'healthy',
-      timestamp: new Date().toISOString(),
-    });
-  });
-
-  // Start server
-  app.listen(config.webhook.port, () => {
-    console.log(`🚀 Webhook server listening on port ${config.webhook.port}`);
-    console.log(
-      `📍 Webhook endpoint: http://localhost:${config.webhook.port}${config.webhook.path}`
-    );
-    console.log(`💚 Health check: http://localhost:${config.webhook.port}/health`);
-  });
-}
-
-/**
- * Verify webhook signature (HMAC SHA256)
- */
-function verifyWebhookSignature(payload: any, signature?: string): boolean {
-  if (!signature) return false;
-
-  const crypto = require('crypto');
-
-  const expectedSignature = crypto
-    .createHmac('sha256', config.webhook.secret)
-    .update(JSON.stringify(payload))
-    .digest('hex');
-
-  return signature === expectedSignature;
-}
-
-// ============================================================================
-// Versori Platform Integration
-// ============================================================================
-
-/**
- * Versori webhook handler
- *
- * Deploy this to Versori platform:
- *
- * import { webhook } from '@versori/run';
- *
- * export const inventoryWebhook = webhook('inventory-update', async ({ data }) => {
- *   const result = await handleInventoryWebhook(data);
- *   return result;
- * });
- */
-
-// ============================================================================
-// Test Utilities
-// ============================================================================
-
-/**
- * Simulate webhook event for testing
- */
-async function testWebhookEvent() {
-  console.log('🧪 Testing webhook event handler\n');
-
-  const testPayload = {
-    eventId: 'test-event-001',
-    eventType: 'inventory.updated',
-    timestamp: new Date().toISOString(),
-    items: [
-      {
-        sku: 'SKU-001',
-        location: 'WH-001',
-        quantity: '150',
-        status: 'available',
-      },
-      {
-        sku: 'SKU-002',
-        location: 'WH-001',
-        quantity: '75',
-        status: 'available',
-      },
-      {
-        sku: 'SKU-003',
-        location: 'WH-002',
-        quantity: '200',
-        status: 'available',
-      },
-    ],
-  };
-
-  const result = await handleInventoryWebhook(testPayload);
-
-  console.log('\n📊 Test Results:');
-  console.log('  Success:', result.success);
-  console.log('  Job ID:', result.jobId);
-  console.log('  Records:', result.records);
-
-  if (result.errors) {
-    console.log('  Errors:', result.errors);
-  }
-}
-
-/**
- * Simulate Fluent event for testing
- */
-async function testFluentEvent() {
-  console.log('\n🧪 Testing Fluent event handler\n');
-
-  const testEvent = {
-    type: 'INVENTORY_POSITION_UPDATED',
-    timestamp: new Date().toISOString(),
-    data: {
-      ref: 'SKU-001',
-      locationRef: 'WH-001',
-      qty: 5,
-      previousQty: 150,
-    },
-  };
-
-  await handleFluentEvent(testEvent);
-}
-
-// ============================================================================
-// Main Entry Point
-// ============================================================================
-
-async function main() {
-  const mode = process.argv[2] || 'test';
-
-  switch (mode) {
-    case 'server':
-      // Start webhook server
-      await startWebhookServer();
-      break;
-
-    case 'test':
-      // Run tests
-      await testWebhookEvent();
-      await testFluentEvent();
-      break;
-
-    default:
-      console.log('Usage:');
-      console.log('  npx tsx examples/event-driven.ts test    # Test webhook handlers');
-      console.log('  npx tsx examples/event-driven.ts server  # Start webhook server');
-  }
-}
-
-// Run if executed directly
-if (require.main === module) {
-  main().catch(error => {
-    console.error('Fatal error:', error);
-    process.exit(1);
-  });
-}
-
-// Export for use in other modules
-export {
-  handleInventoryWebhook,
-  handleFluentEvent,
-  extractInventoryData,
-  generateEventId,
-  verifyWebhookSignature,
-};
+/**
+ * Event-Driven Ingestion Example
+ *
+ * Demonstrates event-driven inventory ingestion using webhooks and Fluent events.
+ * Supports both Versori platform webhooks and standalone webhook handlers.
+ *
+ * Use Cases:
+ * - Real-time inventory updates from WMS
+ * - Webhook-triggered ingestion from external systems
+ * - Event-based inventory adjustments
+ * - Fluent event processing for downstream systems
+ *
+ * Prerequisites:
+ * - npm install @fluentcommerce/fc-connect-sdk
+ * - Configure webhook endpoint (Versori or standalone)
+ *
+ * Usage:
+ * npx tsx examples/event-driven.ts
+ */
+
+import {
+  createClient,
+  UniversalMapper,
+  StateService,
+  SimpleKVStore,
+  FluentClient,
+} from '@fluentcommerce/fc-connect-sdk';
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+const config = {
+  fluent: {
+    baseUrl: process.env.FLUENT_BASE_URL!,
+    clientId: process.env.FLUENT_CLIENT_ID!,
+    clientSecret: process.env.FLUENT_CLIENT_SECRET!,
+    retailerId: process.env.FLUENT_RETAILER_ID!,
+  },
+  webhook: {
+    port: parseInt(process.env.WEBHOOK_PORT || '3000'),
+    path: '/webhook/inventory',
+    secret: process.env.WEBHOOK_SECRET || 'your-webhook-secret',
+  },
+};
+
+// Field mapping for inventory updates
+const mappingConfig = {
+  fields: {
+    ref: {
+      source: 'sku',
+      required: true,
+      comment: 'Inventory position reference',
+    },
+    productRef: {
+      source: 'sku',
+      required: true,
+      comment: 'Product SKU reference',
+    },
+    locationRef: {
+      source: 'location',
+      required: true,
+      comment: 'Warehouse location code',
+    },
+    qty: {
+      source: 'quantity',
+      resolver: 'sdk.parseInt',
+      required: true,
+      comment: 'Available quantity',
+    },
+    status: {
+      source: 'status',
+      resolver: 'sdk.uppercase',
+      defaultValue: 'AVAILABLE',
+      comment: 'Inventory status',
+    },
+  },
+};
+
+// ============================================================================
+// Event Handler Functions
+// ============================================================================
+
+/**
+ * Process webhook payload for inventory update
+ */
+async function handleInventoryWebhook(payload: any): Promise<{
+  success: boolean;
+  jobId?: string;
+  records?: number;
+  errors?: string[];
+}> {
+  console.log('📥 Received inventory webhook event');
+
+  try {
+    // Initialize services
+    const client = await createClient({ config: config.fluent });
+    const mapper = new UniversalMapper(mappingConfig);
+    const state = new StateService(new SimpleKVStore());
+
+    // Extract inventory data from payload
+    const inventoryData = extractInventoryData(payload);
+
+    if (!inventoryData || inventoryData.length === 0) {
+      return {
+        success: false,
+        errors: ['No inventory data found in webhook payload'],
+      };
+    }
+
+    console.log(`  Processing ${inventoryData.length} inventory records`);
+
+    // Generate unique event ID for deduplication
+    const eventId = generateEventId(payload);
+
+    // Check if event already processed
+    if (await state.isFileProcessed(eventId)) {
+      console.log('  ⏭ Event already processed (duplicate webhook)');
+      return {
+        success: true,
+        records: 0,
+      };
+    }
+
+    // Acquire lock to prevent concurrent processing
+    const lock = await state.acquireLock(eventId, 30000); // 30s lock
+
+    if (!lock.acquired) {
+      console.log('  ⏸ Event locked by another process');
+      return {
+        success: false,
+        errors: ['Event is being processed by another worker'],
+      };
+    }
+
+    try {
+      // Transform data with UniversalMapper
+      const result = await mapper.map(inventoryData);
+
+      if (!result.success) {
+        console.error('  ✗ Mapping validation failed:', result.errors);
+        return {
+          success: false,
+          errors: result.errors,
+        };
+      }
+
+      console.log(`  ✓ Mapped ${result.data.length} valid records`);
+
+      // Create batch job
+      const job = await client.createJob({
+        name: `Webhook Import - ${eventId}`,
+        retailerId: config.fluent.retailerId,
+      });
+
+      console.log(`  📝 Created job: ${job.id}`);
+
+      // Send batch to Fluent Commerce
+      await client.sendBatch(job.id, {
+        action: 'UPSERT',
+        entityType: 'INVENTORY',
+        source: 'EVENT_DRIVEN_WEBHOOK',
+        event: 'INVENTORY_UPDATE',
+        entities: result.data,
+      });
+
+      // Mark event as processed
+      await state.markFileProcessed(eventId, {
+        jobId: job.id,
+        records: result.data.length,
+        processedAt: new Date().toISOString(),
+        eventType: payload.eventType || 'inventory.update',
+      });
+
+      console.log(`  ✅ Successfully ingested ${result.data.length} records`);
+
+      return {
+        success: true,
+        jobId: job.id,
+        records: result.data.length,
+      };
+    } finally {
+      // Always release lock
+      await state.releaseLock(eventId);
+    }
+  } catch (error: any) {
+    console.error('  ❌ Webhook processing failed:', error.message);
+    return {
+      success: false,
+      errors: [error.message],
+    };
+  }
+}
+
+/**
+ * Process Fluent event for downstream systems
+ */
+async function handleFluentEvent(event: any): Promise<void> {
+  console.log('📣 Received Fluent event:', event.type);
+
+  // Example: React to inventory position changes
+  if (event.type === 'INVENTORY_UPDATED' || event.type === 'INVENTORY_POSITION_UPDATED') {
+    const { ref, qty, locationRef } = event.data;
+
+    console.log(`  Inventory updated: ${ref} at ${locationRef} → ${qty} units`);
+
+    // Example: Trigger downstream actions
+    if (qty < 10) {
+      console.log(`  ⚠ Low stock alert for ${ref}`);
+      // Send alert to external system
+    }
+
+    if (qty === 0) {
+      console.log(`  🚫 Out of stock for ${ref}`);
+      // Notify e-commerce platform
+    }
+  }
+
+  // Example: React to batch job completion
+  if (event.type === 'BATCH_JOB_COMPLETED') {
+    const { jobId, status, recordsProcessed } = event.data;
+
+    console.log(`  Batch job ${jobId} completed: ${status}`);
+    console.log(`  Records processed: ${recordsProcessed}`);
+
+    // Update external monitoring system
+  }
+}
+
+/**
+ * Extract inventory data from webhook payload
+ */
+function extractInventoryData(payload: any): any[] {
+  // Handle different payload formats
+
+  // Format 1: Direct array
+  if (Array.isArray(payload)) {
+    return payload;
+  }
+
+  // Format 2: Nested in 'data' field
+  if (payload.data && Array.isArray(payload.data)) {
+    return payload.data;
+  }
+
+  // Format 3: Single inventory update
+  if (payload.inventory) {
+    return Array.isArray(payload.inventory) ? payload.inventory : [payload.inventory];
+  }
+
+  // Format 4: WMS event structure
+  if (payload.eventType === 'inventory.updated' && payload.items) {
+    return payload.items;
+  }
+
+  return [];
+}
+
+/**
+ * Generate unique event ID for deduplication
+ */
+function generateEventId(payload: any): string {
+  // Use webhook event ID if provided
+  if (payload.eventId) {
+    return `webhook-${payload.eventId}`;
+  }
+
+  // Use timestamp + hash for custom events
+  const timestamp = payload.timestamp || new Date().toISOString();
+  const hash = hashPayload(payload);
+
+  return `webhook-${timestamp}-${hash}`;
+}
+
+/**
+ * Simple hash function for payload deduplication
+ */
+function hashPayload(payload: any): string {
+  const str = JSON.stringify(payload);
+  let hash = 0;
+
+  for (let i = 0; i < str.length; i++) {
+    const char = str.charCodeAt(i);
+    hash = (hash << 5) - hash + char;
+    hash = hash & hash; // Convert to 32-bit integer
+  }
+
+  return Math.abs(hash).toString(36);
+}
+
+// ============================================================================
+// Standalone Webhook Server (Express Example)
+// ============================================================================
+
+/**
+ * Standalone webhook server for non-Versori deployments
+ */
+async function startWebhookServer() {
+  // Note: This requires 'express' package
+  // npm install express
+
+  const express = require('express');
+  const app = express();
+
+  app.use(express.json());
+
+  // Webhook endpoint
+  app.post(config.webhook.path, async (req: any, res: any) => {
+    const startTime = Date.now();
+
+    // Verify webhook signature (optional but recommended)
+    const signature = req.headers['x-webhook-signature'];
+    if (!verifyWebhookSignature(req.body, signature)) {
+      return res.status(401).json({
+        success: false,
+        error: 'Invalid webhook signature',
+      });
+    }
+
+    // Process webhook
+    const result = await handleInventoryWebhook(req.body);
+
+    const duration = Date.now() - startTime;
+
+    if (result.success) {
+      res.status(200).json({
+        success: true,
+        jobId: result.jobId,
+        records: result.records,
+        processingTime: `${duration}ms`,
+      });
+    } else {
+      res.status(400).json({
+        success: false,
+        errors: result.errors,
+        processingTime: `${duration}ms`,
+      });
+    }
+  });
+
+  // Health check endpoint
+  app.get('/health', (req: any, res: any) => {
+    res.status(200).json({
+      status: 'healthy',
+      timestamp: new Date().toISOString(),
+    });
+  });
+
+  // Start server
+  app.listen(config.webhook.port, () => {
+    console.log(`🚀 Webhook server listening on port ${config.webhook.port}`);
+    console.log(
+      `📍 Webhook endpoint: http://localhost:${config.webhook.port}${config.webhook.path}`
+    );
+    console.log(`💚 Health check: http://localhost:${config.webhook.port}/health`);
+  });
+}
+
+/**
+ * Verify webhook signature (HMAC SHA256)
+ */
+function verifyWebhookSignature(payload: any, signature?: string): boolean {
+  if (!signature) return false;
+
+  const crypto = require('crypto');
+
+  const expectedSignature = crypto
+    .createHmac('sha256', config.webhook.secret)
+    .update(JSON.stringify(payload))
+    .digest('hex');
+
+  return signature === expectedSignature;
+}
+
+// ============================================================================
+// Versori Platform Integration
+// ============================================================================
+
+/**
+ * Versori webhook handler
+ *
+ * Deploy this to Versori platform:
+ *
+ * import { webhook } from '@versori/run';
+ *
+ * export const inventoryWebhook = webhook('inventory-update', async ({ data }) => {
+ *   const result = await handleInventoryWebhook(data);
+ *   return result;
+ * });
+ */
+
+// ============================================================================
+// Test Utilities
+// ============================================================================
+
+/**
+ * Simulate webhook event for testing
+ */
+async function testWebhookEvent() {
+  console.log('🧪 Testing webhook event handler\n');
+
+  const testPayload = {
+    eventId: 'test-event-001',
+    eventType: 'inventory.updated',
+    timestamp: new Date().toISOString(),
+    items: [
+      {
+        sku: 'SKU-001',
+        location: 'WH-001',
+        quantity: '150',
+        status: 'available',
+      },
+      {
+        sku: 'SKU-002',
+        location: 'WH-001',
+        quantity: '75',
+        status: 'available',
+      },
+      {
+        sku: 'SKU-003',
+        location: 'WH-002',
+        quantity: '200',
+        status: 'available',
+      },
+    ],
+  };
+
+  const result = await handleInventoryWebhook(testPayload);
+
+  console.log('\n📊 Test Results:');
+  console.log('  Success:', result.success);
+  console.log('  Job ID:', result.jobId);
+  console.log('  Records:', result.records);
+
+  if (result.errors) {
+    console.log('  Errors:', result.errors);
+  }
+}
+
+/**
+ * Simulate Fluent event for testing
+ */
+async function testFluentEvent() {
+  console.log('\n🧪 Testing Fluent event handler\n');
+
+  const testEvent = {
+    type: 'INVENTORY_POSITION_UPDATED',
+    timestamp: new Date().toISOString(),
+    data: {
+      ref: 'SKU-001',
+      locationRef: 'WH-001',
+      qty: 5,
+      previousQty: 150,
+    },
+  };
+
+  await handleFluentEvent(testEvent);
+}
+
+// ============================================================================
+// Main Entry Point
+// ============================================================================
+
+async function main() {
+  const mode = process.argv[2] || 'test';
+
+  switch (mode) {
+    case 'server':
+      // Start webhook server
+      await startWebhookServer();
+      break;
+
+    case 'test':
+      // Run tests
+      await testWebhookEvent();
+      await testFluentEvent();
+      break;
+
+    default:
+      console.log('Usage:');
+      console.log('  npx tsx examples/event-driven.ts test    # Test webhook handlers');
+      console.log('  npx tsx examples/event-driven.ts server  # Start webhook server');
+  }
+}
+
+// Run if executed directly
+if (require.main === module) {
+  main().catch(error => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+  });
+}
+
+// Export for use in other modules
+export {
+  handleInventoryWebhook,
+  handleFluentEvent,
+  extractInventoryData,
+  generateEventId,
+  verifyWebhookSignature,
+};