@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/01-TEMPLATES/standalone/standalone-webhook-payload-processing.md

@@ -1,688 +1,688 @@
-# Standalone: Webhook Payload Processing
-
-**FC Connect SDK Use Case Guide**
-
-> **SDK**: [@fluentcommerce/fc-connect-sdk](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk)
-> **Version**: Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
-
-**Context**: Node.js script that processes webhook payloads from external systems (3PL, WMS, marketplaces) and creates/updates entities in Fluent Commerce
-
-**Complexity**: Low-Medium
-
-**Runtime**: Node.js ≥18 / Deno
-
-**Estimated Lines**: ~250 lines
-
-## What You'll Build
-
-- Simple webhook payload processor (not a server)
-- Webhook signature validation using SDK
-- Payload parsing with SDK utilities
-- Data transformation using UniversalMapper
-- Entity creation/update via GraphQL mutations
-- File-based webhook queue (for testing/debugging)
-- Error handling and logging
-
-**Use Cases**:
-- Processing stored webhook payloads from a message queue
-- Testing webhook integrations offline
-- Batch processing of webhook files
-- Debugging webhook data transformations
-
-## SDK Methods Used
-
-```typescript
-// FC Connect SDK+
-// Install: npm install @fluentcommerce/fc-connect-sdk@latest
-// Docs: https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk
-// GitHub: https://github.com/fluentcommerce/fc-connect-sdk
-
-import {
-  createClient,
-  WebhookValidationService,
-  XMLParserService,
-  JSONParserService,
-  GraphQLMutationMapper,
-  UniversalMapper,
-  createConsoleLogger,
-  toStructuredLogger
-} from '@fluentcommerce/fc-connect-sdk';
-
-// Key SDK methods
-const client = await createClient({...})               // OAuth2 client
-const validator = new WebhookValidationService(...)    // Signature validation
-await validator.validateWebhook(body, headers, key)   // Validate webhook
-const xmlParser = new XMLParserService()               // Parse XML webhooks
-const jsonParser = new JSONParserService()             // Parse JSON webhooks
-const mapper = new GraphQLMutationMapper(...)          // Map to GraphQL
-await client.graphql({ query, variables })             // Execute mutation
-```
-
----
-
-## Complete Working Implementation
-
-### 1. Project Setup
-
-```bash
-mkdir webhook-payload-processor
-cd webhook-payload-processor
-
-npm init -y
-npm install @fluentcommerce/fc-connect-sdk dotenv
-```
-
-### 2. Environment Configuration (.env)
-
-```env
-# Fluent Commerce OAuth2
-FLUENT_BASE_URL=https://api.fluentcommerce.com
-FLUENT_CLIENT_ID=your-oauth2-client-id
-FLUENT_CLIENT_SECRET=your-oauth2-client-secret
-FLUENT_RETAILER_ID=your-retailer-id
-
-# Webhook Validation
-WEBHOOK_PUBLIC_KEY=-----BEGIN PUBLIC KEY-----\nMIIBIjAN...\n-----END PUBLIC KEY-----
-
-# Processing
-WEBHOOK_FORMAT=json
-WEBHOOK_INPUT_DIR=./webhooks/incoming
-WEBHOOK_PROCESSED_DIR=./webhooks/processed
-WEBHOOK_ERROR_DIR=./webhooks/errors
-
-# Logging
-LOG_LEVEL=info
-```
-
-### 3. Main Script Implementation (src/webhook-processor.ts)
-
-```typescript
-import 'dotenv/config';
-// FC Connect SDK+
-import {
-  createClient,
-  WebhookValidationService,
-  XMLParserService,
-  JSONParserService,
-  GraphQLMutationMapper,
-  type FluentClient,
-  type StructuredLogger,
-  createConsoleLogger,
-  toStructuredLogger
-} from '@fluentcommerce/fc-connect-sdk';
-
-import { readFileSync, readdirSync, renameSync, mkdirSync, existsSync } from 'fs';
-import { join } from 'path';
-
-// ============================================================================
-// 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: {
-    publicKey: process.env.WEBHOOK_PUBLIC_KEY!,
-    format: (process.env.WEBHOOK_FORMAT || 'json') as 'json' | 'xml',
-    inputDir: process.env.WEBHOOK_INPUT_DIR || './webhooks/incoming',
-    processedDir: process.env.WEBHOOK_PROCESSED_DIR || './webhooks/processed',
-    errorDir: process.env.WEBHOOK_ERROR_DIR || './webhooks/errors',
-  },
-};
-
-// ============================================================================
-// GRAPHQL MAPPING CONFIGURATION
-// ============================================================================
-
-const orderWebhookMapping = {
-  version: '1.0',
-  name: 'External Order Webhook to Fluent',
-  mutation: 'createOrder',
-  sourceFormat: 'json',
-  arguments: {
-    input: {
-      _type: 'CreateOrderInput!',
-      ref: { source: 'order_id', required: true },
-      type: { value: 'HD' },
-      retailer: {
-        id: { value: config.fluent.retailerId },
-      },
-      customer: {
-        firstName: { source: 'customer.first_name', required: true },
-        lastName: { source: 'customer.last_name', required: true },
-        email: { source: 'customer.email', transform: 'toLowerCase', required: true },
-      },
-      items: {
-        _array: true,
-        source: 'line_items',
-        ref: { source: 'line_item_id', required: true },
-        productRef: { source: 'sku', required: true },
-        quantity: { source: 'quantity', transform: 'parseInt', required: true },
-        price: { source: 'unit_price', transform: 'parseFloat', required: true },
-      },
-      totalPrice: { source: 'total_amount', transform: 'parseFloat', required: true },
-    },
-  },
-  returnFields: ['id', 'ref', 'status', 'totalPrice'],
-};
-
-// ============================================================================
-// WEBHOOK PROCESSOR
-// ============================================================================
-
-class WebhookProcessor {
-  private client: FluentClient;
-  private logger: StructuredLogger;
-  private validator: WebhookValidationService;
-  private xmlParser: XMLParserService;
-  private jsonParser: JSONParserService;
-  private mutationMapper: GraphQLMutationMapper;
-
-  constructor() {
-    this.logger = toStructuredLogger(createConsoleLogger(), { logLevel: 'info' });
-  }
-
-  async initialize(): Promise<void> {
-    this.logger.info('Initializing webhook processor');
-
-    // Initialize Fluent client
-    this.client = await createClient({ config: config.fluent });
-
-    // Initialize webhook validator
-    this.validator = new WebhookValidationService(
-      { strictValidation: true },
-      this.logger
-    );
-
-    // Initialize parsers
-    this.xmlParser = new XMLParserService();
-    this.jsonParser = new JSONParserService();
-
-    // Initialize mutation mapper
-    this.mutationMapper = new GraphQLMutationMapper(
-      orderWebhookMapping,
-      this.client,
-      this.logger
-    );
-
-    // Ensure directories exist
-    for (const dir of [config.webhook.inputDir, config.webhook.processedDir, config.webhook.errorDir]) {
-      if (!existsSync(dir)) {
-        mkdirSync(dir, { recursive: true });
-      }
-    }
-
-    this.logger.info('Webhook processor initialized');
-  }
-
-  async processWebhooks(): Promise<void> {
-    this.logger.info('Starting webhook processing cycle');
-
-    // List webhook files
-    const files = readdirSync(config.webhook.inputDir);
-    const webhookFiles = files.filter(f =>
-      f.endsWith('.json') || f.endsWith('.xml') || f.endsWith('.txt')
-    );
-
-    this.logger.info(`Found ${webhookFiles.length} webhook files`);
-
-    let processed = 0;
-    let failed = 0;
-
-    for (const file of webhookFiles) {
-      try {
-        await this.processWebhookFile(file);
-        processed++;
-      } catch (error: any) {
-        this.logger.error(`Failed to process webhook file: ${file}`, error);
-        failed++;
-
-        // Move to error directory
-        const errorPath = join(config.webhook.errorDir, file);
-        renameSync(join(config.webhook.inputDir, file), errorPath);
-      }
-    }
-
-    this.logger.info('Webhook processing complete', {
-      processed,
-      failed,
-      total: webhookFiles.length,
-    });
-  }
-
-  private async processWebhookFile(fileName: string): Promise<void> {
-    this.logger.info(`Processing webhook file: ${fileName}`);
-
-    const filePath = join(config.webhook.inputDir, fileName);
-
-    // Read file
-    const content = readFileSync(filePath, 'utf8');
-
-    // Parse webhook metadata and payload
-    // Expected format: HEADERS\n\n<headers JSON>\n\nBODY\n\n<payload>
-    const { headers, body } = this.parseWebhookFile(content);
-
-    // Validate webhook signature (if headers present)
-    if (headers && config.webhook.publicKey) {
-      const validationResult = await this.validator.validateWebhook(
-        body,
-        headers,
-        config.webhook.publicKey
-      );
-
-      if (!validationResult.isValid) {
-        throw new Error(`Webhook signature validation failed: ${validationResult.error}`);
-      }
-
-      this.logger.debug('Webhook signature validated', {
-        algorithm: validationResult.algorithm,
-      });
-    }
-
-    // Parse webhook payload
-    let parsedPayload: any;
-    if (config.webhook.format === 'xml') {
-      parsedPayload = await this.xmlParser.parse(body, {
-        includeAttributes: true,
-        parseNumbers: true,
-      });
-    } else {
-      parsedPayload = await this.jsonParser.parse(body);
-    }
-
-    this.logger.debug('Webhook payload parsed', {
-      rootKeys: Object.keys(parsedPayload),
-    });
-
-    // Map to GraphQL mutation
-    const mutationPayload = await this.mutationMapper.map(parsedPayload);
-
-    this.logger.debug('Mapped to GraphQL mutation', {
-      variables: mutationPayload.variables,
-    });
-
-    // Execute mutation
-    const result = await this.client.graphql(mutationPayload);
-
-    if (result.errors) {
-      throw new Error(`GraphQL errors: ${JSON.stringify(result.errors)}`);
-    }
-
-    this.logger.info('Webhook processed successfully', {
-      file: fileName,
-      orderId: (result.data as any)?.createOrder?.id,
-      orderRef: (result.data as any)?.createOrder?.ref,
-    });
-
-    // Move to processed directory
-    const processedPath = join(config.webhook.processedDir, fileName);
-    renameSync(filePath, processedPath);
-  }
-
-  private parseWebhookFile(content: string): { headers?: Record<string, string>; body: string } {
-    // Check if file contains headers
-    if (content.startsWith('HEADERS\n')) {
-      const parts = content.split('\n\nBODY\n\n');
-      if (parts.length === 2) {
-        const headersJson = parts[0].replace('HEADERS\n\n', '');
-        const headers = JSON.parse(headersJson);
-        const body = parts[1];
-        return { headers, body };
-      }
-    }
-
-    // No headers, entire file is body
-    return { body: content };
-  }
-}
-
-// ============================================================================
-// MAIN ENTRY POINT
-// ============================================================================
-
-async function main() {
-  const processor = new WebhookProcessor();
-
-  try {
-    await processor.initialize();
-    await processor.processWebhooks();
-
-    console.log('Webhook processing completed successfully');
-    process.exit(0);
-  } catch (error: any) {
-    console.error('Fatal error:', error);
-    process.exit(1);
-  }
-}
-
-// Run if executed directly
-if (require.main === module) {
-  main();
-}
-
-export { WebhookProcessor };
-```
-
----
-
-## Key Patterns Explained
-
-### Pattern 1: Webhook Signature Validation
-
-**Purpose**: Verify webhook authenticity using cryptographic signatures
-
-```typescript
-// Initialize validator
-const validator = new WebhookValidationService(
-  { strictValidation: true },  // Enforce signature validation
-  logger
-);
-
-// Validate webhook
-const result = await validator.validateWebhook(
-  rawBody,         // Raw webhook body (string)
-  headers,         // HTTP headers (contains signature)
-  publicKey        // Public key from webhook provider
-);
-
-if (!result.isValid) {
-  throw new Error(`Validation failed: ${result.error}`);
-}
-
-// Signature valid - safe to process
-console.log(`Validated with ${result.algorithm}`);
-```
-
-**Supported Algorithms**:
-- `sha256`: HMAC-SHA256 signatures
-- `rsa-sha256`: RSA-SHA256 signatures
-- Auto-detection from headers
-
-### Pattern 2: Webhook File Format
-
-**With Headers** (for signature validation):
-```
-HEADERS
-
-{"x-webhook-signature":"sha256=abc123...","content-type":"application/json"}
-
-BODY
-
-{"order_id":"ORD-123","customer":{"first_name":"John"...}}
-```
-
-**Without Headers** (no validation):
-```json
-{"order_id":"ORD-123","customer":{"first_name":"John"...}}
-```
-
-### Pattern 3: XML vs JSON Parsing
-
-```typescript
-// Detect format and parse accordingly
-let parsedPayload: any;
-
-if (config.webhook.format === 'xml') {
-  parsedPayload = await xmlParser.parse(body, {
-    includeAttributes: true,    // Parse @id, @type attributes
-    parseNumbers: true,           // Auto-convert numbers
-    parseBooleans: true,          // Auto-convert booleans
-  });
-} else {
-  parsedPayload = await jsonParser.parse(body);
-}
-
-// Now parsedPayload is a JavaScript object ready for mapping
-```
-
-### Pattern 4: GraphQL Mutation Mapping
-
-```typescript
-// Configure mapping once
-const mapping = {
-  mutation: 'createOrder',
-  sourceFormat: 'json',
-  arguments: {
-    input: {
-      ref: { source: 'order_id', required: true },
-      customer: {
-        firstName: { source: 'customer.first_name' },
-        email: { source: 'customer.email', transform: 'toLowerCase' },
-      },
-      items: {
-        _array: true,
-        source: 'line_items',
-        productRef: { source: 'sku' },
-        quantity: { source: 'quantity', transform: 'parseInt' },
-      },
-    },
-  },
-};
-
-// Map webhook data to GraphQL mutation
-const mapper = new GraphQLMutationMapper(mapping, logger, { fluentClient: client });
-const payload = await mapper.map(parsedPayload);
-
-// Execute mutation
-const result = await client.graphql(payload);
-```
-
----
-
-## Testing
-
-### 1. Create Test Webhook Files
-
-**Test Order (webhooks/incoming/order-001.json)**:
-```json
-{
-  "order_id": "TEST-001",
-  "customer": {
-    "first_name": "John",
-    "last_name": "Doe",
-    "email": "JOHN.DOE@EXAMPLE.COM"
-  },
-  "line_items": [
-    {"line_item_id": "1", "sku": "PROD-001", "quantity": 2, "unit_price": 29.99},
-    {"line_item_id": "2", "sku": "PROD-002", "quantity": 1, "unit_price": 49.99}
-  ],
-  "total_amount": 109.97
-}
-```
-
-**With Signature Validation (webhooks/incoming/order-002.json)**:
-```
-HEADERS
-
-{"x-webhook-signature":"sha256=abc123def456...","content-type":"application/json"}
-
-BODY
-
-{"order_id":"TEST-002","customer":{"first_name":"Jane","last_name":"Smith","email":"jane@example.com"},"line_items":[{"line_item_id":"1","sku":"PROD-003","quantity":1,"unit_price":99.99}],"total_amount":99.99}
-```
-
-### 2. Run Processor
-
-```bash
-# Process all webhooks in incoming directory
-npm run dev
-
-# Check processed webhooks
-ls webhooks/processed/
-
-# Check errors
-ls webhooks/errors/
-```
-
-### 3. Manual Testing
-
-```bash
-# Test single webhook
-cat webhooks/incoming/order-001.json | node dist/webhook-processor.js
-
-# Test with debug logging
-LOG_LEVEL=debug npm run dev
-```
-
----
-
-## Deployment Options
-
-### Option 1: Cron Job (Scheduled Processing)
-
-```bash
-# Run every 5 minutes
-*/5 * * * * cd /opt/webhook-processor && npm start >> /var/log/webhook-processor.log 2>&1
-```
-
-### Option 2: Message Queue Consumer
-
-```typescript
-// Integrate with SQS, RabbitMQ, etc.
-import { SQS } from '@aws-sdk/client-sqs';
-
-const sqs = new SQS({ region: 'us-east-1' });
-
-while (true) {
-  const messages = await sqs.receiveMessage({
-    QueueUrl: process.env.QUEUE_URL,
-    MaxNumberOfMessages: 10,
-  });
-
-  for (const message of messages.Messages || []) {
-    // Save to file
-    const fileName = `webhook-${Date.now()}.json`;
-    writeFileSync(
-      join(config.webhook.inputDir, fileName),
-      message.Body
-    );
-
-    // Process
-    await processor.processWebhooks();
-
-    // Delete from queue
-    await sqs.deleteMessage({
-      QueueUrl: process.env.QUEUE_URL,
-      ReceiptHandle: message.ReceiptHandle,
-    });
-  }
-
-  await new Promise(resolve => setTimeout(resolve, 1000));
-}
-```
-
-### Option 3: AWS Lambda with S3 Trigger
-
-```typescript
-import { S3Event } from 'aws-lambda';
-
-export const handler = async (event: S3Event) => {
-  const processor = new WebhookProcessor();
-  await processor.initialize();
-
-  for (const record of event.Records) {
-    const bucket = record.s3.bucket.name;
-    const key = record.s3.object.key;
-
-    // Download from S3 to input directory
-    // Process
-    // Move to processed S3 folder
-  }
-};
-```
-
----
-
-## Common Issues
-
-### Issue 1: Signature Validation Fails
-
-**Symptom**: `Webhook signature validation failed`
-
-**Solution**:
-```typescript
-// Ensure raw body is used (no JSON parsing beforehand)
-const rawBody = readFileSync(filePath, 'utf8');
-
-// Check public key format
-const publicKey = `-----BEGIN PUBLIC KEY-----
-MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
------END PUBLIC KEY-----`;
-
-// Verify header name matches webhook provider
-const signatureHeader = headers['x-webhook-signature'] ||
-                        headers['x-signature'] ||
-                        headers['signature'];
-```
-
-### Issue 2: Mapping Errors
-
-**Symptom**: `Required field 'ref' is missing`
-
-**Solution**:
-```typescript
-// Debug parsed payload structure
-console.log('Parsed payload:', JSON.stringify(parsedPayload, null, 2));
-
-// Check source path matches actual structure
-ref: { source: 'order_id' }  // ✅ Correct if payload has {order_id: "..."}
-ref: { source: 'orderId' }    // ❌ Wrong if payload uses snake_case
-```
-
-### Issue 3: XML Attribute Not Found
-
-**Symptom**: `Cannot read property '@id' of undefined`
-
-**Solution**:
-```typescript
-// Enable attribute parsing
-const parsedXml = await xmlParser.parse(body, {
-  includeAttributes: true,  // REQUIRED for @attributes
-});
-
-// Access attributes with @ prefix
-ref: { source: 'order.@id' }  // For <order id="123">
-```
-
----
-
-## Related Guides
-
-- **[SFTP XML → GraphQL](./sftp-xml-graphql.md)** - Similar pattern with SFTP polling
-- **[S3 CSV → Batch API](./s3-csv-batch-api.md)** - Batch processing pattern
-- **[GraphQL Mutation Mapping](../../02-CORE-GUIDES/mapping/graphql-mutation-mapping/)** - Complete mapping reference
-- **[Webhook Validation](../../02-CORE-GUIDES/advanced-services/advanced-services-readme.md)** - Security best practices
-
----
-
-## Production Checklist
-
-- [ ] Webhook signature validation enabled
-- [ ] Public key secured (secrets manager, not hardcoded)
-- [ ] Error webhooks moved to error directory (not deleted)
-- [ ] Processed webhooks archived with retention policy
-- [ ] Monitoring configured (file counts, processing rate)
-- [ ] Dead letter queue for failed webhooks
-- [ ] Retry logic for transient failures
-- [ ] Logging includes correlation IDs
-- [ ] Alerts configured for high error rates
-- [ ] Documentation updated with webhook format examples
-
----
-
-**Next Steps**:
-
-1. Customize `orderWebhookMapping` for your webhook format
-2. Add more mapping configurations for different webhook types
-3. Integrate with message queue (SQS, RabbitMQ, Kafka)
-4. Set up monitoring and alerting
-5. Deploy to production environment
-
-**Support**:
-
-- SDK Issues: https://github.com/fluentcommerce/fc-connect-sdk/issues
-- Fluent Commerce API: https://docs.fluentcommerce.com
+# Standalone: Webhook Payload Processing
+
+**FC Connect SDK Use Case Guide**
+
+> **SDK**: [@fluentcommerce/fc-connect-sdk](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk)
+> **Version**: Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
+
+**Context**: Node.js script that processes webhook payloads from external systems (3PL, WMS, marketplaces) and creates/updates entities in Fluent Commerce
+
+**Complexity**: Low-Medium
+
+**Runtime**: Node.js ≥18 / Deno
+
+**Estimated Lines**: ~250 lines
+
+## What You'll Build
+
+- Simple webhook payload processor (not a server)
+- Webhook signature validation using SDK
+- Payload parsing with SDK utilities
+- Data transformation using UniversalMapper
+- Entity creation/update via GraphQL mutations
+- File-based webhook queue (for testing/debugging)
+- Error handling and logging
+
+**Use Cases**:
+- Processing stored webhook payloads from a message queue
+- Testing webhook integrations offline
+- Batch processing of webhook files
+- Debugging webhook data transformations
+
+## SDK Methods Used
+
+```typescript
+// FC Connect SDK+
+// Install: npm install @fluentcommerce/fc-connect-sdk@latest
+// Docs: https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk
+// GitHub: https://github.com/fluentcommerce/fc-connect-sdk
+
+import {
+  createClient,
+  WebhookValidationService,
+  XMLParserService,
+  JSONParserService,
+  GraphQLMutationMapper,
+  UniversalMapper,
+  createConsoleLogger,
+  toStructuredLogger
+} from '@fluentcommerce/fc-connect-sdk';
+
+// Key SDK methods
+const client = await createClient({...})               // OAuth2 client
+const validator = new WebhookValidationService(...)    // Signature validation
+await validator.validateWebhook(body, headers, key)   // Validate webhook
+const xmlParser = new XMLParserService()               // Parse XML webhooks
+const jsonParser = new JSONParserService()             // Parse JSON webhooks
+const mapper = new GraphQLMutationMapper(...)          // Map to GraphQL
+await client.graphql({ query, variables })             // Execute mutation
+```
+
+---
+
+## Complete Working Implementation
+
+### 1. Project Setup
+
+```bash
+mkdir webhook-payload-processor
+cd webhook-payload-processor
+
+npm init -y
+npm install @fluentcommerce/fc-connect-sdk dotenv
+```
+
+### 2. Environment Configuration (.env)
+
+```env
+# Fluent Commerce OAuth2
+FLUENT_BASE_URL=https://api.fluentcommerce.com
+FLUENT_CLIENT_ID=your-oauth2-client-id
+FLUENT_CLIENT_SECRET=your-oauth2-client-secret
+FLUENT_RETAILER_ID=your-retailer-id
+
+# Webhook Validation
+WEBHOOK_PUBLIC_KEY=-----BEGIN PUBLIC KEY-----\nMIIBIjAN...\n-----END PUBLIC KEY-----
+
+# Processing
+WEBHOOK_FORMAT=json
+WEBHOOK_INPUT_DIR=./webhooks/incoming
+WEBHOOK_PROCESSED_DIR=./webhooks/processed
+WEBHOOK_ERROR_DIR=./webhooks/errors
+
+# Logging
+LOG_LEVEL=info
+```
+
+### 3. Main Script Implementation (src/webhook-processor.ts)
+
+```typescript
+import 'dotenv/config';
+// FC Connect SDK+
+import {
+  createClient,
+  WebhookValidationService,
+  XMLParserService,
+  JSONParserService,
+  GraphQLMutationMapper,
+  type FluentClient,
+  type StructuredLogger,
+  createConsoleLogger,
+  toStructuredLogger
+} from '@fluentcommerce/fc-connect-sdk';
+
+import { readFileSync, readdirSync, renameSync, mkdirSync, existsSync } from 'fs';
+import { join } from 'path';
+
+// ============================================================================
+// 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: {
+    publicKey: process.env.WEBHOOK_PUBLIC_KEY!,
+    format: (process.env.WEBHOOK_FORMAT || 'json') as 'json' | 'xml',
+    inputDir: process.env.WEBHOOK_INPUT_DIR || './webhooks/incoming',
+    processedDir: process.env.WEBHOOK_PROCESSED_DIR || './webhooks/processed',
+    errorDir: process.env.WEBHOOK_ERROR_DIR || './webhooks/errors',
+  },
+};
+
+// ============================================================================
+// GRAPHQL MAPPING CONFIGURATION
+// ============================================================================
+
+const orderWebhookMapping = {
+  version: '1.0',
+  name: 'External Order Webhook to Fluent',
+  mutation: 'createOrder',
+  sourceFormat: 'json',
+  arguments: {
+    input: {
+      _type: 'CreateOrderInput!',
+      ref: { source: 'order_id', required: true },
+      type: { value: 'HD' },
+      retailer: {
+        id: { value: config.fluent.retailerId },
+      },
+      customer: {
+        firstName: { source: 'customer.first_name', required: true },
+        lastName: { source: 'customer.last_name', required: true },
+        email: { source: 'customer.email', transform: 'toLowerCase', required: true },
+      },
+      items: {
+        _array: true,
+        source: 'line_items',
+        ref: { source: 'line_item_id', required: true },
+        productRef: { source: 'sku', required: true },
+        quantity: { source: 'quantity', transform: 'parseInt', required: true },
+        price: { source: 'unit_price', transform: 'parseFloat', required: true },
+      },
+      totalPrice: { source: 'total_amount', transform: 'parseFloat', required: true },
+    },
+  },
+  returnFields: ['id', 'ref', 'status', 'totalPrice'],
+};
+
+// ============================================================================
+// WEBHOOK PROCESSOR
+// ============================================================================
+
+class WebhookProcessor {
+  private client: FluentClient;
+  private logger: StructuredLogger;
+  private validator: WebhookValidationService;
+  private xmlParser: XMLParserService;
+  private jsonParser: JSONParserService;
+  private mutationMapper: GraphQLMutationMapper;
+
+  constructor() {
+    this.logger = toStructuredLogger(createConsoleLogger(), { logLevel: 'info' });
+  }
+
+  async initialize(): Promise<void> {
+    this.logger.info('Initializing webhook processor');
+
+    // Initialize Fluent client
+    this.client = await createClient({ config: config.fluent });
+
+    // Initialize webhook validator
+    this.validator = new WebhookValidationService(
+      { strictValidation: true },
+      this.logger
+    );
+
+    // Initialize parsers
+    this.xmlParser = new XMLParserService();
+    this.jsonParser = new JSONParserService();
+
+    // Initialize mutation mapper
+    this.mutationMapper = new GraphQLMutationMapper(
+      orderWebhookMapping,
+      this.client,
+      this.logger
+    );
+
+    // Ensure directories exist
+    for (const dir of [config.webhook.inputDir, config.webhook.processedDir, config.webhook.errorDir]) {
+      if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+      }
+    }
+
+    this.logger.info('Webhook processor initialized');
+  }
+
+  async processWebhooks(): Promise<void> {
+    this.logger.info('Starting webhook processing cycle');
+
+    // List webhook files
+    const files = readdirSync(config.webhook.inputDir);
+    const webhookFiles = files.filter(f =>
+      f.endsWith('.json') || f.endsWith('.xml') || f.endsWith('.txt')
+    );
+
+    this.logger.info(`Found ${webhookFiles.length} webhook files`);
+
+    let processed = 0;
+    let failed = 0;
+
+    for (const file of webhookFiles) {
+      try {
+        await this.processWebhookFile(file);
+        processed++;
+      } catch (error: any) {
+        this.logger.error(`Failed to process webhook file: ${file}`, error);
+        failed++;
+
+        // Move to error directory
+        const errorPath = join(config.webhook.errorDir, file);
+        renameSync(join(config.webhook.inputDir, file), errorPath);
+      }
+    }
+
+    this.logger.info('Webhook processing complete', {
+      processed,
+      failed,
+      total: webhookFiles.length,
+    });
+  }
+
+  private async processWebhookFile(fileName: string): Promise<void> {
+    this.logger.info(`Processing webhook file: ${fileName}`);
+
+    const filePath = join(config.webhook.inputDir, fileName);
+
+    // Read file
+    const content = readFileSync(filePath, 'utf8');
+
+    // Parse webhook metadata and payload
+    // Expected format: HEADERS\n\n<headers JSON>\n\nBODY\n\n<payload>
+    const { headers, body } = this.parseWebhookFile(content);
+
+    // Validate webhook signature (if headers present)
+    if (headers && config.webhook.publicKey) {
+      const validationResult = await this.validator.validateWebhook(
+        body,
+        headers,
+        config.webhook.publicKey
+      );
+
+      if (!validationResult.isValid) {
+        throw new Error(`Webhook signature validation failed: ${validationResult.error}`);
+      }
+
+      this.logger.debug('Webhook signature validated', {
+        algorithm: validationResult.algorithm,
+      });
+    }
+
+    // Parse webhook payload
+    let parsedPayload: any;
+    if (config.webhook.format === 'xml') {
+      parsedPayload = await this.xmlParser.parse(body, {
+        includeAttributes: true,
+        parseNumbers: true,
+      });
+    } else {
+      parsedPayload = await this.jsonParser.parse(body);
+    }
+
+    this.logger.debug('Webhook payload parsed', {
+      rootKeys: Object.keys(parsedPayload),
+    });
+
+    // Map to GraphQL mutation
+    const mutationPayload = await this.mutationMapper.map(parsedPayload);
+
+    this.logger.debug('Mapped to GraphQL mutation', {
+      variables: mutationPayload.variables,
+    });
+
+    // Execute mutation
+    const result = await this.client.graphql(mutationPayload);
+
+    if (result.errors) {
+      throw new Error(`GraphQL errors: ${JSON.stringify(result.errors)}`);
+    }
+
+    this.logger.info('Webhook processed successfully', {
+      file: fileName,
+      orderId: (result.data as any)?.createOrder?.id,
+      orderRef: (result.data as any)?.createOrder?.ref,
+    });
+
+    // Move to processed directory
+    const processedPath = join(config.webhook.processedDir, fileName);
+    renameSync(filePath, processedPath);
+  }
+
+  private parseWebhookFile(content: string): { headers?: Record<string, string>; body: string } {
+    // Check if file contains headers
+    if (content.startsWith('HEADERS\n')) {
+      const parts = content.split('\n\nBODY\n\n');
+      if (parts.length === 2) {
+        const headersJson = parts[0].replace('HEADERS\n\n', '');
+        const headers = JSON.parse(headersJson);
+        const body = parts[1];
+        return { headers, body };
+      }
+    }
+
+    // No headers, entire file is body
+    return { body: content };
+  }
+}
+
+// ============================================================================
+// MAIN ENTRY POINT
+// ============================================================================
+
+async function main() {
+  const processor = new WebhookProcessor();
+
+  try {
+    await processor.initialize();
+    await processor.processWebhooks();
+
+    console.log('Webhook processing completed successfully');
+    process.exit(0);
+  } catch (error: any) {
+    console.error('Fatal error:', error);
+    process.exit(1);
+  }
+}
+
+// Run if executed directly
+if (require.main === module) {
+  main();
+}
+
+export { WebhookProcessor };
+```
+
+---
+
+## Key Patterns Explained
+
+### Pattern 1: Webhook Signature Validation
+
+**Purpose**: Verify webhook authenticity using cryptographic signatures
+
+```typescript
+// Initialize validator
+const validator = new WebhookValidationService(
+  { strictValidation: true },  // Enforce signature validation
+  logger
+);
+
+// Validate webhook
+const result = await validator.validateWebhook(
+  rawBody,         // Raw webhook body (string)
+  headers,         // HTTP headers (contains signature)
+  publicKey        // Public key from webhook provider
+);
+
+if (!result.isValid) {
+  throw new Error(`Validation failed: ${result.error}`);
+}
+
+// Signature valid - safe to process
+console.log(`Validated with ${result.algorithm}`);
+```
+
+**Supported Algorithms**:
+- `sha256`: HMAC-SHA256 signatures
+- `rsa-sha256`: RSA-SHA256 signatures
+- Auto-detection from headers
+
+### Pattern 2: Webhook File Format
+
+**With Headers** (for signature validation):
+```
+HEADERS
+
+{"x-webhook-signature":"sha256=abc123...","content-type":"application/json"}
+
+BODY
+
+{"order_id":"ORD-123","customer":{"first_name":"John"...}}
+```
+
+**Without Headers** (no validation):
+```json
+{"order_id":"ORD-123","customer":{"first_name":"John"...}}
+```
+
+### Pattern 3: XML vs JSON Parsing
+
+```typescript
+// Detect format and parse accordingly
+let parsedPayload: any;
+
+if (config.webhook.format === 'xml') {
+  parsedPayload = await xmlParser.parse(body, {
+    includeAttributes: true,    // Parse @id, @type attributes
+    parseNumbers: true,           // Auto-convert numbers
+    parseBooleans: true,          // Auto-convert booleans
+  });
+} else {
+  parsedPayload = await jsonParser.parse(body);
+}
+
+// Now parsedPayload is a JavaScript object ready for mapping
+```
+
+### Pattern 4: GraphQL Mutation Mapping
+
+```typescript
+// Configure mapping once
+const mapping = {
+  mutation: 'createOrder',
+  sourceFormat: 'json',
+  arguments: {
+    input: {
+      ref: { source: 'order_id', required: true },
+      customer: {
+        firstName: { source: 'customer.first_name' },
+        email: { source: 'customer.email', transform: 'toLowerCase' },
+      },
+      items: {
+        _array: true,
+        source: 'line_items',
+        productRef: { source: 'sku' },
+        quantity: { source: 'quantity', transform: 'parseInt' },
+      },
+    },
+  },
+};
+
+// Map webhook data to GraphQL mutation
+const mapper = new GraphQLMutationMapper(mapping, logger, { fluentClient: client });
+const payload = await mapper.map(parsedPayload);
+
+// Execute mutation
+const result = await client.graphql(payload);
+```
+
+---
+
+## Testing
+
+### 1. Create Test Webhook Files
+
+**Test Order (webhooks/incoming/order-001.json)**:
+```json
+{
+  "order_id": "TEST-001",
+  "customer": {
+    "first_name": "John",
+    "last_name": "Doe",
+    "email": "JOHN.DOE@EXAMPLE.COM"
+  },
+  "line_items": [
+    {"line_item_id": "1", "sku": "PROD-001", "quantity": 2, "unit_price": 29.99},
+    {"line_item_id": "2", "sku": "PROD-002", "quantity": 1, "unit_price": 49.99}
+  ],
+  "total_amount": 109.97
+}
+```
+
+**With Signature Validation (webhooks/incoming/order-002.json)**:
+```
+HEADERS
+
+{"x-webhook-signature":"sha256=abc123def456...","content-type":"application/json"}
+
+BODY
+
+{"order_id":"TEST-002","customer":{"first_name":"Jane","last_name":"Smith","email":"jane@example.com"},"line_items":[{"line_item_id":"1","sku":"PROD-003","quantity":1,"unit_price":99.99}],"total_amount":99.99}
+```
+
+### 2. Run Processor
+
+```bash
+# Process all webhooks in incoming directory
+npm run dev
+
+# Check processed webhooks
+ls webhooks/processed/
+
+# Check errors
+ls webhooks/errors/
+```
+
+### 3. Manual Testing
+
+```bash
+# Test single webhook
+cat webhooks/incoming/order-001.json | node dist/webhook-processor.js
+
+# Test with debug logging
+LOG_LEVEL=debug npm run dev
+```
+
+---
+
+## Deployment Options
+
+### Option 1: Cron Job (Scheduled Processing)
+
+```bash
+# Run every 5 minutes
+*/5 * * * * cd /opt/webhook-processor && npm start >> /var/log/webhook-processor.log 2>&1
+```
+
+### Option 2: Message Queue Consumer
+
+```typescript
+// Integrate with SQS, RabbitMQ, etc.
+import { SQS } from '@aws-sdk/client-sqs';
+
+const sqs = new SQS({ region: 'us-east-1' });
+
+while (true) {
+  const messages = await sqs.receiveMessage({
+    QueueUrl: process.env.QUEUE_URL,
+    MaxNumberOfMessages: 10,
+  });
+
+  for (const message of messages.Messages || []) {
+    // Save to file
+    const fileName = `webhook-${Date.now()}.json`;
+    writeFileSync(
+      join(config.webhook.inputDir, fileName),
+      message.Body
+    );
+
+    // Process
+    await processor.processWebhooks();
+
+    // Delete from queue
+    await sqs.deleteMessage({
+      QueueUrl: process.env.QUEUE_URL,
+      ReceiptHandle: message.ReceiptHandle,
+    });
+  }
+
+  await new Promise(resolve => setTimeout(resolve, 1000));
+}
+```
+
+### Option 3: AWS Lambda with S3 Trigger
+
+```typescript
+import { S3Event } from 'aws-lambda';
+
+export const handler = async (event: S3Event) => {
+  const processor = new WebhookProcessor();
+  await processor.initialize();
+
+  for (const record of event.Records) {
+    const bucket = record.s3.bucket.name;
+    const key = record.s3.object.key;
+
+    // Download from S3 to input directory
+    // Process
+    // Move to processed S3 folder
+  }
+};
+```
+
+---
+
+## Common Issues
+
+### Issue 1: Signature Validation Fails
+
+**Symptom**: `Webhook signature validation failed`
+
+**Solution**:
+```typescript
+// Ensure raw body is used (no JSON parsing beforehand)
+const rawBody = readFileSync(filePath, 'utf8');
+
+// Check public key format
+const publicKey = `-----BEGIN PUBLIC KEY-----
+MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
+-----END PUBLIC KEY-----`;
+
+// Verify header name matches webhook provider
+const signatureHeader = headers['x-webhook-signature'] ||
+                        headers['x-signature'] ||
+                        headers['signature'];
+```
+
+### Issue 2: Mapping Errors
+
+**Symptom**: `Required field 'ref' is missing`
+
+**Solution**:
+```typescript
+// Debug parsed payload structure
+console.log('Parsed payload:', JSON.stringify(parsedPayload, null, 2));
+
+// Check source path matches actual structure
+ref: { source: 'order_id' }  // ✅ Correct if payload has {order_id: "..."}
+ref: { source: 'orderId' }    // ❌ Wrong if payload uses snake_case
+```
+
+### Issue 3: XML Attribute Not Found
+
+**Symptom**: `Cannot read property '@id' of undefined`
+
+**Solution**:
+```typescript
+// Enable attribute parsing
+const parsedXml = await xmlParser.parse(body, {
+  includeAttributes: true,  // REQUIRED for @attributes
+});
+
+// Access attributes with @ prefix
+ref: { source: 'order.@id' }  // For <order id="123">
+```
+
+---
+
+## Related Guides
+
+- **[SFTP XML → GraphQL](./sftp-xml-graphql.md)** - Similar pattern with SFTP polling
+- **[S3 CSV → Batch API](./s3-csv-batch-api.md)** - Batch processing pattern
+- **[GraphQL Mutation Mapping](../../02-CORE-GUIDES/mapping/graphql-mutation-mapping/)** - Complete mapping reference
+- **[Webhook Validation](../../02-CORE-GUIDES/advanced-services/advanced-services-readme.md)** - Security best practices
+
+---
+
+## Production Checklist
+
+- [ ] Webhook signature validation enabled
+- [ ] Public key secured (secrets manager, not hardcoded)
+- [ ] Error webhooks moved to error directory (not deleted)
+- [ ] Processed webhooks archived with retention policy
+- [ ] Monitoring configured (file counts, processing rate)
+- [ ] Dead letter queue for failed webhooks
+- [ ] Retry logic for transient failures
+- [ ] Logging includes correlation IDs
+- [ ] Alerts configured for high error rates
+- [ ] Documentation updated with webhook format examples
+
+---
+
+**Next Steps**:
+
+1. Customize `orderWebhookMapping` for your webhook format
+2. Add more mapping configurations for different webhook types
+3. Integrate with message queue (SQS, RabbitMQ, Kafka)
+4. Set up monitoring and alerting
+5. Deploy to production environment
+
+**Support**:
+
+- SDK Issues: https://github.com/fluentcommerce/fc-connect-sdk/issues
+- Fluent Commerce API: https://docs.fluentcommerce.com