@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/03-PATTERN-GUIDES/integration-patterns/modules/integration-patterns-06-advanced-integration-services.md

@@ -1,1547 +1,1547 @@
-# Module 6: Advanced Integration Services
-
-> **Learning Objective:** Master advanced SDK services for webhook validation, partial batch recovery, job tracking, and pre-flight validation.
->
-> **Level:** Advanced
-
-## Table of Contents
-
-1. [Overview](#overview)
-2. [Webhook Validation Service](#webhook-validation-service)
-3. [Partial Batch Recovery](#partial-batch-recovery)
-4. [Job Tracker](#job-tracker)
-5. [Preflight Validator](#preflight-validator)
-6. [Integration Patterns](#integration-patterns)
-7. [Production Examples](#production-examples)
-8. [Summary](#summary)
-
----
-
-## Overview
-
-### What These Services Solve
-
-| Service | Problem | Solution | Benefits |
-|---------|---------|----------|----------|
-| **Webhook Validation** | Unverified webhooks | Cryptographic signature validation | Security, authenticity |
-| **Partial Batch Recovery** | Entire batch fails when one record fails | Retry only failed records | Efficiency, data integrity |
-| **Job Tracker** | No visibility into job status | Track job lifecycle in KV store | Observability, debugging |
-| **Preflight Validator** | API quota wasted on invalid data | Validate before API calls | Cost savings, faster feedback |
-
-### When to Use
-
-```
-Production Integration Checklist:
-✅ Webhook Validation - ALL webhook endpoints (security)
-✅ Partial Batch Recovery - Batch API ingestion (reliability)
-✅ Job Tracker - Async scheduled workflows (observability)
-✅ Preflight Validator - Large batch operations (cost optimization)
-```
-
----
-
-## Webhook Validation Service
-
-### What It Does
-
-**Validates webhook signatures from Fluent Commerce Rubix workflows** using RSA-based cryptographic verification.
-
-> ⚠️ **IMPORTANT:** This service is **ONLY for Fluent Commerce webhooks**. Do not use for Shopify, GitHub, Stripe, or other third-party webhooks. For those systems, implement manual HMAC validation (see Module 4: Webhook Patterns).
-
-### Key Features
-
-- ✅ **SHA512withRSA** (fluent-signature) - Recommended for Fluent Commerce webhooks
-- ✅ **MD5withRSA** (flex.signature) - Support for older Fluent Commerce webhooks
-- ✅ Automatic algorithm detection from Fluent Commerce headers
-- ✅ Public key caching for performance
-- ✅ Fallback algorithm support for Fluent Commerce
-- ✅ Integrated with FluentClient.validateWebhook()
-- ❌ **NOT for Shopify/GitHub/Stripe webhooks** (use manual HMAC - see Module 4)
-
-### Basic Usage
-
-#### Using FluentClient (Recommended)
-
-```typescript
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-const client = await createClient({
-  baseUrl: 'https://api.fluentcommerce.com',
-  clientId: process.env.FLUENT_CLIENT_ID,
-  clientSecret: process.env.FLUENT_CLIENT_SECRET,
-  username: process.env.FLUENT_USERNAME,
-  password: process.env.FLUENT_PASSWORD,
-  retailerId: process.env.FLUENT_RETAILER_ID,
-  publicKey: process.env.FLUENT_WEBHOOK_PUBLIC_KEY // For webhook validation
-});
-
-// In webhook handler
-export async function handleWebhook(request: Request) {
-  const rawBody = await request.text(); // CRITICAL: Must be raw body
-  const payload = JSON.parse(rawBody);
-  const signature = request.headers.get('fluent-signature');
-
-  // Validate webhook signature
-  const isValid = await client.validateWebhook(
-    payload,
-    signature,
-    rawBody  // Pass raw string, not parsed JSON
-  );
-
-  if (!isValid) {
-    return new Response('Invalid signature', { status: 401 });
-  }
-
-  // Process webhook...
-  return new Response('OK', { status: 200 });
-}
-```
-
-#### Using WebhookValidationService Directly
-
-```typescript
-import {
-  WebhookValidationService,
-  SignatureAlgorithm,
-  createConsoleLogger
-} from '@fluentcommerce/fc-connect-sdk';
-
-const logger = createConsoleLogger();
-const validator = new WebhookValidationService({
-  algorithm: SignatureAlgorithm.SHA512_WITH_RSA,
-  strictValidation: true // Throw on validation failure
-}, logger);
-
-// Validate webhook
-const result = await validator.validateWebhookSignature(
-  rawPayload,                      // Raw request body as string
-  headers['fluent-signature'],     // Signature from header
-  publicKey,                        // Public key from env
-  SignatureAlgorithm.SHA512_WITH_RSA
-);
-
-if (!result.isValid) {
-  console.error('Validation failed:', result.error);
-  throw new Error('Invalid webhook signature');
-}
-```
-
-### Versori Platform Integration
-
-```typescript
-import { webhook, fn } from '@versori/run';
-import { FluentClient } from '@fluentcommerce/fc-connect-sdk';
-
-export const fluentWebhook = webhook('fluent-order', {
-  response: {
-    mode: 'sync',
-    onSuccess: (ctx) => new Response(JSON.stringify({ success: true }), {
-      status: 200,
-      headers: { 'Content-Type': 'application/json' }
-    }),
-    onError: (ctx) => new Response(JSON.stringify({ error: ctx.error.message }), {
-      status: 500,
-      headers: { 'Content-Type': 'application/json' }
-    })
-  }
-})
-  .then(fn('validate', async (ctx) => {
-    const { request, vars, log } = ctx;
-
-    // Get raw body (Versori v0.2.29+)
-    const rawBody = await request.text();
-    const payload = JSON.parse(rawBody);
-
-    // Get signature from headers
-    const signature = request.headers.get('fluent-signature') ||
-                      request.headers.get('x-fluent-signature');
-
-    if (!signature) {
-      throw new Error('Missing webhook signature header');
-    }
-
-    // Validate using FluentClient
-    const client = new FluentClient({
-      baseUrl: vars.FLUENT_BASE_URL,
-      clientId: vars.FLUENT_CLIENT_ID,
-      clientSecret: vars.FLUENT_CLIENT_SECRET,
-      username: vars.FLUENT_USERNAME,
-      password: vars.FLUENT_PASSWORD,
-      retailerId: vars.FLUENT_RETAILER_ID,
-      publicKey: vars.FLUENT_WEBHOOK_PUBLIC_KEY
-    }, log);
-
-    const isValid = await client.validateWebhook(payload, signature, rawBody);
-
-    if (!isValid) {
-      throw new Error('Invalid webhook signature - not from Fluent Commerce');
-    }
-
-    log.info('Webhook signature validated', { eventName: payload.name });
-
-    return payload;
-  }))
-  .then(fn('process', async ({ data, log }) => {
-    // Process validated webhook...
-    log.info('Processing webhook', { orderId: data.entityRef });
-
-    return { success: true, orderId: data.entityRef };
-  }));
-```
-
-### Signature Header Detection
-
-The service automatically detects signature algorithm:
-
-| Header | Algorithm | Status |
-|--------|-----------|--------|
-| `fluent-signature` | SHA512withRSA | **Recommended** |
-| `x-fluent-signature` | SHA512withRSA | Supported |
-| `flex.signature` | MD5withRSA | **Older algorithm** |
-| `flex-signature` | MD5withRSA | Supported |
-
-```typescript
-// Auto-detection (recommended)
-const result = await validator.validateWebhook(
-  rawPayload,
-  headers, // Pass all headers
-  publicKey
-);
-
-// Manual algorithm selection
-const result = await validator.validateWebhookSignature(
-  rawPayload,
-  headers['fluent-signature'],
-  publicKey,
-  SignatureAlgorithm.SHA512_WITH_RSA
-);
-```
-
-### Common Pitfalls
-
-#### ❌ WRONG: Validating parsed JSON
-
-```typescript
-// ❌ This will FAIL - signature is for raw body
-const payload = await request.json();
-const isValid = await validator.validateWebhookSignature(
-  JSON.stringify(payload), // Serialization changes order/whitespace
-  signature,
-  publicKey
-);
-```
-
-#### ✅ CORRECT: Validate raw body
-
-```typescript
-// ✅ Correct - validate raw body
-const rawBody = await request.text();
-const isValid = await validator.validateWebhookSignature(
-  rawBody,  // Exact bytes received
-  signature,
-  publicKey
-);
-
-// Then parse for processing
-const payload = JSON.parse(rawBody);
-```
-
-### Production Factory Methods
-
-```typescript
-import { WebhookValidationFactory } from '@fluentcommerce/fc-connect-sdk';
-
-// Production: strict validation, throws on failure
-const validator = WebhookValidationFactory.createProduction(logger);
-
-// Development: lenient validation, logs but doesn't throw
-const validator = WebhookValidationFactory.createDevelopment(logger);
-
-// With fallback: try SHA512, fallback to MD5
-const validator = WebhookValidationFactory.createWithFallback(logger);
-```
-
----
-
-## Partial Batch Recovery
-
-### What It Does
-
-**Tracks per-record success/failure** in batch operations and enables:
-- Retrying only failed records instead of entire batch
-- Checkpoint/resume functionality
-- Detailed error reporting per record
-- Progress tracking
-
-### Key Features
-
-- ✅ **Per-record tracking** - Know exactly which records failed
-- ✅ **Selective retry** - Retry only failures, not successes
-- ✅ **Checkpoint support** - Resume from failure point
-- ✅ **Exponential backoff** - Configurable retry delays
-- ✅ **Custom retry logic** - Override retry decisions
-
-### Basic Usage
-
-```typescript
-import { PartialBatchRecovery } from '@fluentcommerce/fc-connect-sdk';
-
-const recovery = new PartialBatchRecovery(logger);
-
-// Process batch with automatic recovery
-const result = await recovery.processBatchWithRecovery(
-  records,
-  async (batch) => {
-    // Your batch processing logic
-    return await client.sendBatch(jobId, {
-      action: 'UPSERT',
-      entityType: 'INVENTORY',
-      entities: batch
-    });
-  },
-  {
-    maxRetries: 3,
-    retryOnlyFailed: true,  // Only retry failed records
-    retryDelayMs: 1000,     // Start with 1 second
-    retryBatchSize: 100,    // Process 100 at a time
-    checkpointKey: 'inventory-sync-2025-01-24'
-  }
-);
-
-console.log(`✓ Success: ${result.successCount}/${result.totalRecords}`);
-console.log(`✗ Failed: ${result.failedCount} records`);
-
-if (result.failedCount > 0) {
-  console.error('Failed records:', result.failedRecords);
-  console.log(`Checkpoint saved: ${result.checkpointId}`);
-}
-```
-
-### Integration with Batch API
-
-```typescript
-import {
-  createClient,
-  PartialBatchRecovery
-} from '@fluentcommerce/fc-connect-sdk';
-
-async function batchIngestionWithRecovery(records: any[]) {
-  const client = await createClient({ config });
-  const recovery = new PartialBatchRecovery(logger);
-
-  // Create job
-  const job = await client.createJob({
-    name: 'Inventory Ingestion with Recovery',
-    retailerId: 'my-retailer'
-  });
-
-  // Process with recovery
-  const result = await recovery.processBatchWithRecovery(
-    records,
-    async (batch) => {
-      const response = await client.sendBatch(job.id, {
-        action: 'UPSERT',
-        entityType: 'INVENTORY',
-        entities: batch
-      });
-
-      logger.info('Batch sent', {
-        batchId: response.id,
-        recordCount: batch.length
-      });
-
-      return response;
-    },
-    {
-      maxRetries: 3,
-      retryOnlyFailed: true,
-      checkpointKey: `job-${job.id}`
-    }
-  );
-
-  // Check job status
-  const status = await client.getJobStatus(job.id);
-
-  return {
-    jobId: job.id,
-    jobStatus: status.status,
-    ...result
-  };
-}
-```
-
-### Checkpoint and Resume
-
-```typescript
-// Process batch and save checkpoint
-const result = await recovery.processBatchWithRecovery(
-  records,
-  processBatch,
-  {
-    maxRetries: 3,
-    checkpointKey: 'daily-inventory-sync'
-  }
-);
-
-if (result.failedCount > 0) {
-  console.log(`Checkpoint created: ${result.checkpointId}`);
-  console.log(`Failed records saved for later retry`);
-}
-
-// Later: Resume from checkpoint
-const checkpointId = result.checkpointId;
-const resumeResult = await recovery.resumeFromCheckpoint(
-  checkpointId,
-  processBatch,
-  {
-    maxRetries: 5  // More retries on resume
-  }
-);
-
-console.log(`Resume: ${resumeResult.successCount} recovered`);
-```
-
-### Custom Retry Logic
-
-```typescript
-const result = await recovery.processBatchWithRecovery(
-  records,
-  processBatch,
-  {
-    maxRetries: 5,
-    retryDelayMs: 2000,
-    // Custom retry decision
-    shouldRetry: (error, attemptCount) => {
-      // Don't retry validation errors
-      if (error.message.includes('validation')) {
-        return false;
-      }
-
-      // Don't retry after 3 attempts for rate limits
-      if (error.message.includes('rate limit') && attemptCount > 3) {
-        return false;
-      }
-
-      // Retry all other errors
-      return true;
-    }
-  }
-);
-```
-
-### Record Failure Details
-
-```typescript
-// Access detailed failure information
-if (result.failedCount > 0) {
-  result.failedRecords.forEach(failure => {
-    console.error(`Record ${failure.index} failed:`, {
-      record: failure.record,
-      error: failure.error.message,
-      attempts: failure.attemptCount,
-      timestamp: failure.timestamp
-    });
-  });
-
-  // Export failures for manual review
-  await fs.writeFile(
-    'failed-records.json',
-    JSON.stringify(result.failedRecords, null, 2)
-  );
-}
-```
-
----
-
-## Job Tracker
-
-### What It Does
-
-**Tracks job status** in Versori KV store for async workflows:
-- Job lifecycle tracking (queued → processing → completed/failed)
-- Stage-based progress tracking
-- Error capture with stack traces
-- Automatic timestamp management
-- TTL-based cleanup
-
-### Key Features
-
-- ✅ **Lifecycle tracking** - queued, processing, completed, failed
-- ✅ **Stage tracking** - Custom stages for your workflow
-- ✅ **Metadata storage** - Store job-specific context
-- ✅ **TTL support** - Automatic cleanup after 7 days
-- ✅ **Error capture** - Store errors with stack traces
-
-### Basic Usage
-
-```typescript
-import { JobTracker, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
-// ✅ CORRECT: Access openKv from Versori context
-// import { openKv } from '@versori/run'; // ❌ WRONG - Not a direct export
-
-// In Versori workflow handler:
-const { openKv } = ctx;
-const kvAdapter = new VersoriKVAdapter(openKv(':project:'));
-const tracker = new JobTracker(kvAdapter, logger);
-
-// Create job
-const jobId = `scheduled_${Date.now()}`;
-
-await tracker.createJob(jobId, {
-  triggeredBy: 'schedule',
-  stage: 'initialization',
-  details: {
-    catalogueRef: 'DEFAULT:1',
-    fileName: 'inventory.csv'
-  }
-});
-
-// Update progress
-await tracker.updateJob(jobId, {
-  status: 'processing',
-  stage: 'extraction',
-  message: 'Extracting records from S3'
-});
-
-await tracker.updateJob(jobId, {
-  stage: 'transformation',
-  message: 'Mapping 1000 records',
-  details: { recordCount: 1000 }
-});
-
-// Mark as completed
-await tracker.markCompleted(jobId, {
-  recordCount: 1000,
-  successCount: 998,
-  failedCount: 2
-});
-
-// Or mark as failed
-try {
-  // ... job logic ...
-} catch (error) {
-  await tracker.markFailed(jobId, error);
-}
-```
-
-### Scheduled Workflow Integration
-
-```typescript
-import { schedule } from '@versori/run';
-import { JobTracker, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
-
-export const dailyInventorySync = schedule('daily-inventory', '0 2 * * *')
-  .execute(async ({ log, connections, vars, kv }) => {
-    const jobId = `inventory_${Date.now()}`;
-    const tracker = new JobTracker(new VersoriKVAdapter(kv), log);
-
-    try {
-      // Create job
-      await tracker.createJob(jobId, {
-        triggeredBy: 'schedule',
-        stage: 'start',
-        details: { schedule: 'daily 2am' }
-      });
-
-      // Stage 1: Extraction
-      await tracker.updateJob(jobId, {
-        status: 'processing',
-        stage: 'extraction',
-        message: 'Querying virtual positions'
-      });
-
-      const data = await extractFromFluent();
-
-      // Stage 2: Transformation
-      await tracker.updateJob(jobId, {
-        stage: 'transformation',
-        message: `Processing ${data.length} records`
-      });
-
-      const transformed = await transformData(data);
-
-      // Stage 3: Upload
-      await tracker.updateJob(jobId, {
-        stage: 'upload',
-        message: 'Uploading to SFTP'
-      });
-
-      await uploadToSFTP(transformed);
-
-      // Completed
-      await tracker.markCompleted(jobId, {
-        recordCount: data.length,
-        fileName: `inventory_${jobId}.xml`
-      });
-
-      log.info('Job completed successfully', { jobId });
-
-    } catch (error) {
-      await tracker.markFailed(jobId, error);
-      log.error('Job failed', error);
-      throw error;
-    }
-  });
-```
-
-### Webhook Workflow Integration
-
-```typescript
-import { webhook, fn } from '@versori/run';
-import { JobTracker, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
-
-export const orderWebhook = webhook('order-webhook')
-  .then(fn('track-start', async ({ request, kv, log }) => {
-    const jobId = request.headers.get('x-request-id') || crypto.randomUUID();
-    const tracker = new JobTracker(new VersoriKVAdapter(kv), log);
-
-    await tracker.createJob(jobId, {
-      triggeredBy: 'webhook',
-      stage: 'validation',
-      details: {
-        source: request.headers.get('user-agent')
-      }
-    });
-
-    return { jobId };
-  }))
-  .then(fn('process', async ({ data, kv, log }) => {
-    const tracker = new JobTracker(new VersoriKVAdapter(kv), log);
-
-    await tracker.updateJob(data.jobId, {
-      status: 'processing',
-      stage: 'transformation'
-    });
-
-    // Process order...
-    const result = await processOrder(data);
-
-    await tracker.markCompleted(data.jobId, {
-      orderId: result.orderId
-    });
-
-    return result;
-  }))
-  .catch(async ({ error, data, kv, log }) => {
-    const tracker = new JobTracker(new VersoriKVAdapter(kv), log);
-
-    if (data?.jobId) {
-      await tracker.markFailed(data.jobId, error);
-    }
-
-    throw error;
-  });
-```
-
-### Querying Job Status
-
-```typescript
-// Get job status
-const status = await tracker.getJob(jobId);
-
-if (status) {
-  console.log(`Job ${jobId}:`, {
-    status: status.status,
-    stage: status.stage,
-    message: status.message,
-    createdAt: status.createdAt,
-    completedAt: status.completedAt
-  });
-}
-
-// Check if job is still running
-if (status.status === 'processing') {
-  console.log(`Job in progress: ${status.stage}`);
-}
-
-// Check for errors
-if (status.status === 'failed') {
-  console.error('Job failed:', {
-    error: status.error,
-    stack: status.errorStack
-  });
-}
-```
-
-### Custom TTL Configuration
-
-```typescript
-// Default TTL: 7 days
-const tracker = new JobTracker(kvAdapter, logger);
-
-// Custom TTL: 24 hours
-const shortTracker = new JobTracker(
-  kvAdapter,
-  logger,
-  86400 // 24 hours in seconds
-);
-
-// Custom TTL: 30 days
-const longTracker = new JobTracker(
-  kvAdapter,
-  logger,
-  2592000 // 30 days in seconds
-);
-```
-
----
-
-## Preflight Validator
-
-### What It Does
-
-**Validates data BEFORE sending to Fluent API** to:
-- Catch errors early and save API quota
-- Validate against GraphQL schema requirements
-- Check for duplicates and data quality issues
-- Provide actionable error messages
-
-### Key Features
-
-- ✅ **Required field validation** - Ensure mandatory fields present
-- ✅ **Type validation** - Check field types (string, number, etc.)
-- ✅ **Duplicate detection** - Find duplicate refs in batch
-- ✅ **Batch size limits** - Enforce max batch size
-- ✅ **Custom validators** - Add domain-specific rules
-- ✅ **Detailed error reports** - Per-record error details
-
-### Basic Usage
-
-```typescript
-import { PreflightValidator } from '@fluentcommerce/fc-connect-sdk';
-
-const validator = new PreflightValidator(logger);
-
-// Validate batch before sending
-const result = await validator.validateBatch(records, {
-  entityType: 'INVENTORY',
-  requiredFields: ['ref', 'qty', 'productRef', 'locationRef'],
-  checkDuplicates: true,
-  maxBatchSize: 5000,
-  validateTypes: true
-});
-
-if (!result.isValid) {
-  console.error(`Validation failed: ${result.errors.length} errors`);
-
-  // Log first 10 errors
-  result.errors.slice(0, 10).forEach(err => {
-    console.error(`Record ${err.index}: ${err.message}`, {
-      field: err.field,
-      value: err.value
-    });
-  });
-
-  // Don't send to API - save quota
-  throw new Error(`Validation failed: ${result.summary}`);
-}
-
-console.log(`✓ Validation passed: ${result.summary}`);
-
-// Safe to send to API
-await sendToFluentAPI(records);
-```
-
-### Integration with Batch API
-
-```typescript
-import {
-  createClient,
-  PreflightValidator
-} from '@fluentcommerce/fc-connect-sdk';
-
-async function batchIngestionWithValidation(records: any[]) {
-  const validator = new PreflightValidator(logger);
-  const client = await createClient({ config });
-
-  // Step 1: Preflight validation
-  logger.info('Running preflight validation', { recordCount: records.length });
-
-  const validationResult = await validator.validateBatch(records, {
-    entityType: 'INVENTORY',
-    requiredFields: ['ref', 'qty', 'productRef', 'locationRef'],
-    checkDuplicates: true,
-    maxBatchSize: 5000,
-    validateTypes: true
-  });
-
-  if (!validationResult.isValid) {
-    logger.error('Preflight validation failed', {
-      errorCount: validationResult.errors.length,
-      validRecords: validationResult.validRecords
-    });
-
-    // Export validation errors
-    await fs.writeFile(
-      'validation-errors.json',
-      JSON.stringify(validationResult.errors, null, 2)
-    );
-
-    throw new Error(`Validation failed: ${validationResult.summary}`);
-  }
-
-  logger.info('Preflight validation passed', {
-    validRecords: validationResult.validRecords,
-    warnings: validationResult.warnings.length
-  });
-
-  // Step 2: Send to API (data is valid)
-  const job = await client.createJob({
-    name: 'Validated Inventory Ingestion',
-    retailerId: 'my-retailer'
-  });
-
-  await client.sendBatch(job.id, {
-    action: 'UPSERT',
-    entityType: 'INVENTORY',
-    entities: records
-  });
-
-  return { jobId: job.id, validationResult };
-}
-```
-
-### Custom Validation Rules
-
-```typescript
-const result = await validator.validateBatch(records, {
-  entityType: 'INVENTORY',
-  requiredFields: ['ref', 'qty'],
-  validateTypes: true,
-  // Custom validation function
-  customValidator: (record, index) => {
-    // Business rule: qty must be >= 0
-    if (record.qty < 0) {
-      return `Quantity cannot be negative (got ${record.qty})`;
-    }
-
-    // Business rule: ref must follow pattern
-    if (!/^[A-Z0-9-]+$/.test(record.ref)) {
-      return `Invalid ref format (must be alphanumeric with hyphens)`;
-    }
-
-    // Business rule: locationRef must be valid
-    if (!isValidLocation(record.locationRef)) {
-      return `Invalid locationRef: ${record.locationRef}`;
-    }
-
-    return null; // Validation passed
-  }
-});
-```
-
-### Quick Validation (Fast Mode)
-
-```typescript
-// Quick validation - checks first record only
-const quickResult = await validator.validateQuick(records, {
-  entityType: 'INVENTORY',
-  requiredFields: ['ref', 'qty'],
-  maxBatchSize: 5000
-});
-
-if (!quickResult.isValid) {
-  console.error('Quick validation failed:', quickResult.error);
-  throw new Error(`Data format invalid: ${quickResult.error}`);
-}
-
-// Optionally do full validation
-const fullResult = await validator.validateBatch(records, options);
-```
-
-### Duplicate Detection
-
-```typescript
-const result = await validator.validateBatch(records, {
-  entityType: 'INVENTORY',
-  requiredFields: ['ref'],
-  checkDuplicates: true  // Enable duplicate detection
-});
-
-if (result.warnings.length > 0) {
-  console.warn('Validation warnings:', result.warnings);
-}
-
-if (result.duplicates && result.duplicates.length > 0) {
-  console.warn('Duplicate refs found:', result.duplicates);
-
-  // Option 1: Remove duplicates
-  const uniqueRecords = records.filter((r, i, arr) =>
-    arr.findIndex(x => x.ref === r.ref) === i
-  );
-
-  // Option 2: Fail on duplicates
-  if (result.duplicates.length > 10) {
-    throw new Error(`Too many duplicates: ${result.duplicates.length}`);
-  }
-}
-```
-
-### Error Reporting
-
-```typescript
-const result = await validator.validateBatch(records, options);
-
-if (!result.isValid) {
-  // Generate detailed error report
-  const report = {
-    summary: result.summary,
-    totalRecords: result.totalRecords,
-    validRecords: result.validRecords,
-    errorCount: result.errors.length,
-    errors: result.errors.map(err => ({
-      record: err.index,
-      field: err.field,
-      message: err.message,
-      value: err.value,
-      severity: err.severity
-    }))
-  };
-
-  // Export to file
-  await fs.writeFile(
-    `validation-report-${Date.now()}.json`,
-    JSON.stringify(report, null, 2)
-  );
-
-  // Send to monitoring
-  logger.error('Validation failed', report);
-}
-```
-
----
-
-## Integration Patterns
-
-### Pattern 1: Secure Webhook Endpoint
-
-**Webhook validation + Job tracking + Error handling**
-
-```typescript
-import {
-  webhook,
-  fn
-} from '@versori/run';
-import {
-  FluentClient,
-  JobTracker,
-  VersoriKVAdapter
-} from '@fluentcommerce/fc-connect-sdk';
-
-export const secureWebhook = webhook('secure-order', {
-  response: {
-    mode: 'sync',
-    onSuccess: (ctx) => new Response(JSON.stringify({ success: true }), {
-      status: 200,
-      headers: { 'Content-Type': 'application/json' }
-    }),
-    onError: (ctx) => new Response(JSON.stringify({
-      error: ctx.error.message
-    }), {
-      status: ctx.error.message.includes('signature') ? 401 : 500,
-      headers: { 'Content-Type': 'application/json' }
-    })
-  }
-})
-  .then(fn('validate-signature', async ({ request, vars, log, kv }) => {
-    const jobId = request.headers.get('x-request-id') || crypto.randomUUID();
-    const tracker = new JobTracker(new VersoriKVAdapter(kv), log);
-
-    // Track job start
-    await tracker.createJob(jobId, {
-      triggeredBy: 'webhook',
-      stage: 'validation'
-    });
-
-    // Get raw body
-    const rawBody = await request.text();
-    const payload = JSON.parse(rawBody);
-    const signature = request.headers.get('fluent-signature');
-
-    if (!signature) {
-      await tracker.markFailed(jobId, new Error('Missing signature'));
-      throw new Error('Missing fluent-signature header');
-    }
-
-    // Validate signature
-    const client = new FluentClient({
-      baseUrl: vars.FLUENT_BASE_URL,
-      clientId: vars.FLUENT_CLIENT_ID,
-      clientSecret: vars.FLUENT_CLIENT_SECRET,
-      username: vars.FLUENT_USERNAME,
-      password: vars.FLUENT_PASSWORD,
-      retailerId: vars.FLUENT_RETAILER_ID,
-      publicKey: vars.FLUENT_WEBHOOK_PUBLIC_KEY
-    }, log);
-
-    const isValid = await client.validateWebhook(payload, signature, rawBody);
-
-    if (!isValid) {
-      await tracker.markFailed(jobId, new Error('Invalid signature'));
-      throw new Error('Invalid webhook signature');
-    }
-
-    await tracker.updateJob(jobId, {
-      status: 'processing',
-      stage: 'processing',
-      message: 'Signature validated'
-    });
-
-    return { jobId, payload };
-  }))
-  .then(fn('process-order', async ({ data, kv, log }) => {
-    const tracker = new JobTracker(new VersoriKVAdapter(kv), log);
-
-    await tracker.updateJob(data.jobId, {
-      stage: 'transformation',
-      message: `Processing order ${data.payload.entityRef}`
-    });
-
-    // Process order...
-    const result = await processOrder(data.payload);
-
-    await tracker.markCompleted(data.jobId, {
-      orderId: result.orderId
-    });
-
-    return { success: true, orderId: result.orderId };
-  }));
-```
-
-### Pattern 2: Validated Batch Ingestion with Recovery
-
-**Preflight validation + Partial batch recovery + Job tracking**
-
-```typescript
-import {
-  createClient,
-  PreflightValidator,
-  PartialBatchRecovery,
-  JobTracker,
-  VersoriKVAdapter
-} from '@fluentcommerce/fc-connect-sdk';
-
-async function validatedBatchIngestion(
-  records: any[],
-  config: any,
-  logger: any,
-  kv: any
-) {
-  const client = await createClient({ config });
-  const validator = new PreflightValidator(logger);
-  const recovery = new PartialBatchRecovery(logger);
-  const tracker = new JobTracker(new VersoriKVAdapter(kv), logger);
-
-  const jobId = `batch_${Date.now()}`;
-
-  try {
-    // Track job
-    await tracker.createJob(jobId, {
-      triggeredBy: 'schedule',
-      stage: 'validation',
-      details: { recordCount: records.length }
-    });
-
-    // Step 1: Preflight validation
-    await tracker.updateJob(jobId, {
-      status: 'processing',
-      stage: 'preflight-validation',
-      message: `Validating ${records.length} records`
-    });
-
-    const validationResult = await validator.validateBatch(records, {
-      entityType: 'INVENTORY',
-      requiredFields: ['ref', 'qty', 'productRef', 'locationRef'],
-      checkDuplicates: true,
-      maxBatchSize: 5000,
-      validateTypes: true,
-      customValidator: (record) => {
-        if (record.qty < 0) return 'Quantity cannot be negative';
-        return null;
-      }
-    });
-
-    if (!validationResult.isValid) {
-      await tracker.markFailed(jobId, new Error(validationResult.summary));
-      throw new Error(`Validation failed: ${validationResult.summary}`);
-    }
-
-    // Step 2: Create Fluent job
-    await tracker.updateJob(jobId, {
-      stage: 'batch-creation',
-      message: 'Creating Fluent batch job'
-    });
-
-    const fluentJob = await client.createJob({
-      name: `Validated Ingestion ${jobId}`,
-      retailerId: config.retailerId
-    });
-
-    // Step 3: Send with recovery
-    await tracker.updateJob(jobId, {
-      stage: 'batch-processing',
-      message: `Sending ${records.length} records with recovery`
-    });
-
-    const recoveryResult = await recovery.processBatchWithRecovery(
-      records,
-      async (batch) => {
-        return await client.sendBatch(fluentJob.id, {
-          action: 'UPSERT',
-          entityType: 'INVENTORY',
-          entities: batch
-        });
-      },
-      {
-        maxRetries: 3,
-        retryOnlyFailed: true,
-        checkpointKey: jobId,
-        retryBatchSize: 100
-      }
-    );
-
-    // Step 4: Complete
-    await tracker.markCompleted(jobId, {
-      fluentJobId: fluentJob.id,
-      totalRecords: recoveryResult.totalRecords,
-      successCount: recoveryResult.successCount,
-      failedCount: recoveryResult.failedCount,
-      checkpointId: recoveryResult.checkpointId
-    });
-
-    return {
-      jobId,
-      fluentJobId: fluentJob.id,
-      validation: validationResult,
-      recovery: recoveryResult
-    };
-
-  } catch (error) {
-    await tracker.markFailed(jobId, error);
-    throw error;
-  }
-}
-```
-
-### Pattern 3: Scheduled Extraction with Tracking
-
-**Job tracking + Error handling**
-
-```typescript
-import { schedule } from '@versori/run';
-import {
-  createClient,
-  ExtractionOrchestrator,
-  JobTracker,
-  VersoriKVAdapter,
-  SftpDataSource
-} from '@fluentcommerce/fc-connect-sdk';
-
-export const dailyExtraction = schedule('daily-extraction', '0 3 * * *')
-  .execute(async ({ log, connections, vars, kv }) => {
-    const jobId = `extraction_${Date.now()}`;
-    const tracker = new JobTracker(new VersoriKVAdapter(kv), log);
-
-    try {
-      await tracker.createJob(jobId, {
-        triggeredBy: 'schedule',
-        stage: 'initialization',
-        details: { schedule: 'daily 3am' }
-      });
-
-      // Stage 1: Extraction
-      await tracker.updateJob(jobId, {
-        status: 'processing',
-        stage: 'extraction',
-        message: 'Querying Fluent API'
-      });
-
-      const client = await createClient(ctx); // Auto-detects Versori context
-      const orchestrator = new ExtractionOrchestrator(client, log);
-
-      const data = await orchestrator.extract({
-        entityType: 'virtualPositions',
-        fields: ['ref', 'type', 'quantity', 'productRef', 'groupRef'],
-        pagination: { pageSize: 1000 }
-      });
-
-      // Stage 2: Transformation
-      await tracker.updateJob(jobId, {
-        stage: 'transformation',
-        message: `Transforming ${data.length} records`
-      });
-
-      const xml = transformToXML(data);
-
-      // Stage 3: Upload
-      await tracker.updateJob(jobId, {
-        stage: 'upload',
-        message: 'Uploading to SFTP'
-      });
-
-      const sftp = new SftpDataSource({
-        host: vars.SFTP_HOST,
-        username: vars.SFTP_USERNAME,
-        privateKey: vars.SFTP_PRIVATE_KEY
-      }, log);
-
-      const fileName = `inventory_${jobId}.xml`;
-      await sftp.writeFile(`/uploads/${fileName}`, xml);
-
-      // Complete
-      await tracker.markCompleted(jobId, {
-        recordCount: data.length,
-        fileName,
-        fileSize: xml.length
-      });
-
-      log.info('Extraction completed', { jobId, recordCount: data.length });
-
-    } catch (error) {
-      await tracker.markFailed(jobId, error);
-      log.error('Extraction failed', error);
-      throw error;
-    }
-  });
-```
-
----
-
-## Production Examples
-
-### Complete Production Workflow
-
-```typescript
-/**
- * Production-ready inventory ingestion with all advanced services
- */
-
-import { schedule } from '@versori/run';
-import {
-  createClient,
-  PreflightValidator,
-  PartialBatchRecovery,
-  JobTracker,
-  VersoriKVAdapter,
-  S3DataSource,
-  CSVParserService,
-  UniversalMapper
-} from '@fluentcommerce/fc-connect-sdk';
-
-export const productionInventorySync = schedule('inventory-sync', '0 */6 * * *')
-  .execute(async ({ log, connections, vars, kv }) => {
-    const jobId = `inventory_${Date.now()}`;
-    const tracker = new JobTracker(new VersoriKVAdapter(kv), log, 2592000); // 30 day TTL
-    const validator = new PreflightValidator(log);
-    const recovery = new PartialBatchRecovery(log);
-
-    try {
-      // ========================================
-      // Stage 1: Job Initialization
-      // ========================================
-      await tracker.createJob(jobId, {
-        triggeredBy: 'schedule',
-        stage: 'initialization',
-        details: {
-          schedule: 'every 6 hours',
-          bucket: vars.S3_BUCKET
-        }
-      });
-
-      log.info('Starting production inventory sync', { jobId });
-
-      // ========================================
-      // Stage 2: Data Extraction
-      // ========================================
-      await tracker.updateJob(jobId, {
-        status: 'processing',
-        stage: 'extraction',
-        message: 'Reading CSV from S3'
-      });
-
-      const s3 = new S3DataSource({
-        region: vars.AWS_REGION,
-        accessKeyId: vars.AWS_ACCESS_KEY_ID,
-        secretAccessKey: vars.AWS_SECRET_ACCESS_KEY
-      }, log);
-
-      const csvContent = await s3.readFile(vars.S3_BUCKET, 'inventory/latest.csv');
-
-      const parser = new CSVParserService({ hasHeaders: true }, log);
-      const rawRecords = await parser.parseToArray(csvContent);
-
-      log.info('CSV parsed', { recordCount: rawRecords.length });
-
-      // ========================================
-      // Stage 3: Data Transformation
-      // ========================================
-      await tracker.updateJob(jobId, {
-        stage: 'transformation',
-        message: `Mapping ${rawRecords.length} records`
-      });
-
-      const mapper = new UniversalMapper({
-        fields: {
-          ref: { source: 'sku', required: true },
-          type: { resolver: () => 'INVENTORY_POSITION' },
-          qty: { source: 'quantity', resolver: 'sdk.parseInt', required: true },
-          productRef: { source: 'product_id', required: true },
-          locationRef: { source: 'location_id', required: true },
-          condition: { source: 'condition', defaultValue: 'NEW' }
-        }
-      });
-
-      const mappedRecords = [];
-      const mappingErrors = [];
-
-      for (let i = 0; i < rawRecords.length; i++) {
-        const result = await mapper.map(rawRecords[i]);
-        if (result.success) {
-          mappedRecords.push(result.data);
-        } else {
-          mappingErrors.push({ index: i, errors: result.errors });
-        }
-      }
-
-      if (mappingErrors.length > 0) {
-        log.warn('Mapping errors', {
-          errorCount: mappingErrors.length,
-          totalRecords: rawRecords.length
-        });
-      }
-
-      // ========================================
-      // Stage 4: Preflight Validation
-      // ========================================
-      await tracker.updateJob(jobId, {
-        stage: 'validation',
-        message: `Validating ${mappedRecords.length} records`
-      });
-
-      const validationResult = await validator.validateBatch(mappedRecords, {
-        entityType: 'INVENTORY',
-        requiredFields: ['ref', 'qty', 'productRef', 'locationRef'],
-        checkDuplicates: true,
-        maxBatchSize: 5000,
-        validateTypes: true,
-        customValidator: (record) => {
-          if (record.qty < 0) {
-            return 'Quantity cannot be negative';
-          }
-          if (!record.ref.match(/^[A-Z0-9-]+$/)) {
-            return 'Invalid ref format';
-          }
-          return null;
-        }
-      });
-
-      if (!validationResult.isValid) {
-        await tracker.markFailed(jobId, new Error(validationResult.summary));
-
-        // Export validation errors
-        await s3.writeFile(
-          vars.S3_BUCKET,
-          `errors/validation-${jobId}.json`,
-          JSON.stringify(validationResult.errors, null, 2)
-        );
-
-        throw new Error(`Validation failed: ${validationResult.summary}`);
-      }
-
-      log.info('Validation passed', {
-        validRecords: validationResult.validRecords,
-        warnings: validationResult.warnings.length
-      });
-
-      // ========================================
-      // Stage 5: Fluent API Ingestion
-      // ========================================
-      await tracker.updateJob(jobId, {
-        stage: 'ingestion',
-        message: 'Creating Fluent batch job'
-      });
-
-      const client = await createClient({
-        connection: connections.fluent_commerce,
-        logger: log
-      });
-
-      const fluentJob = await client.createJob({
-        name: `Production Inventory Sync ${jobId}`,
-        retailerId: vars.FLUENT_RETAILER_ID,
-        meta: {
-          preprocessing: 'default', // Enable BPP
-          source: 's3-csv',
-          jobId
-        }
-      });
-
-      log.info('Fluent job created', { fluentJobId: fluentJob.id });
-
-      // ========================================
-      // Stage 6: Batch Processing with Recovery
-      // ========================================
-      await tracker.updateJob(jobId, {
-        stage: 'batch-processing',
-        message: `Sending ${mappedRecords.length} records`
-      });
-
-      const recoveryResult = await recovery.processBatchWithRecovery(
-        mappedRecords,
-        async (batch) => {
-          log.info('Sending batch', { batchSize: batch.length });
-
-          return await client.sendBatch(fluentJob.id, {
-            action: 'UPSERT',
-            entityType: 'INVENTORY',
-            entities: batch
-          });
-        },
-        {
-          maxRetries: 5,
-          retryOnlyFailed: true,
-          retryDelayMs: 2000,
-          retryBatchSize: 100,
-          checkpointKey: jobId,
-          shouldRetry: (error, attemptCount) => {
-            // Don't retry validation errors
-            if (error.message.includes('validation')) {
-              return false;
-            }
-            // Max 5 attempts
-            return attemptCount <= 5;
-          }
-        }
-      );
-
-      log.info('Batch processing complete', {
-        successCount: recoveryResult.successCount,
-        failedCount: recoveryResult.failedCount,
-        checkpointId: recoveryResult.checkpointId
-      });
-
-      // ========================================
-      // Stage 7: Job Status Verification
-      // ========================================
-      await tracker.updateJob(jobId, {
-        stage: 'verification',
-        message: 'Verifying Fluent job status'
-      });
-
-      // Poll for completion
-      let attempts = 0;
-      const maxAttempts = 30;
-      let fluentStatus;
-
-      while (attempts < maxAttempts) {
-        fluentStatus = await client.getJobStatus(fluentJob.id);
-
-        if (fluentStatus.status === 'COMPLETED' || fluentStatus.status === 'FAILED') {
-          break;
-        }
-
-        await new Promise(resolve => setTimeout(resolve, 10000)); // Wait 10s
-        attempts++;
-      }
-
-      log.info('Fluent job status', {
-        status: fluentStatus.status,
-        errorSummary: fluentStatus.errorSummary
-      });
-
-      // ========================================
-      // Stage 8: Completion
-      // ========================================
-      const finalDetails = {
-        fluentJobId: fluentJob.id,
-        fluentJobStatus: fluentStatus.status,
-        sourceRecords: rawRecords.length,
-        mappedRecords: mappedRecords.length,
-        mappingErrors: mappingErrors.length,
-        validationResult: {
-          validRecords: validationResult.validRecords,
-          warnings: validationResult.warnings.length
-        },
-        recoveryResult: {
-          successCount: recoveryResult.successCount,
-          failedCount: recoveryResult.failedCount,
-          checkpointId: recoveryResult.checkpointId
-        },
-        fluentErrors: fluentStatus.errorSummary?.totalErrors || 0
-      };
-
-      if (recoveryResult.failedCount > 0 || (fluentStatus.errorSummary?.totalErrors || 0) > 0) {
-        await tracker.updateJob(jobId, {
-          status: 'completed',
-          stage: 'completed-with-errors',
-          message: `Completed with ${recoveryResult.failedCount} recovery errors, ${fluentStatus.errorSummary?.totalErrors || 0} Fluent errors`,
-          details: finalDetails
-        });
-      } else {
-        await tracker.markCompleted(jobId, finalDetails);
-      }
-
-      return {
-        success: true,
-        jobId,
-        ...finalDetails
-      };
-
-    } catch (error) {
-      await tracker.markFailed(jobId, error);
-      log.error('Production sync failed', error);
-      throw error;
-    }
-  });
-```
-
----
-
-## Summary
-
-### Key Takeaways
-
-1. **Webhook Validation** - ALWAYS validate Fluent Commerce webhook signatures
-2. **Partial Batch Recovery** - Retry only failed records, not entire batch
-3. **Job Tracker** - Track async workflow progress in KV store
-4. **Preflight Validator** - Validate before API calls to save quota
-
-### Service Comparison
-
-| Service | Primary Benefit | When to Use | Complexity |
-|---------|----------------|-------------|------------|
-| **Webhook Validation** | Security | All webhook endpoints | Low |
-| **Partial Batch Recovery** | Reliability | Batch ingestion | Medium |
-| **Job Tracker** | Observability | Scheduled workflows | Low |
-| **Preflight Validator** | Cost savings | Large batch operations | Low |
-
-### Integration Checklist
-
-Production integration should include:
-
-- [ ] **Webhook Validation** - Verify all incoming webhooks
-- [ ] **Preflight Validator** - Validate before API submission
-- [ ] **Partial Batch Recovery** - Handle batch failures gracefully
-- [ ] **Job Tracker** - Track workflow lifecycle
-- [ ] **Structured Logging** - Log all stages with context
-- [ ] **Error Handling** - Catch and log all errors
-- [ ] **Monitoring** - Track metrics and job status
-
----
-
-## Next Steps
-
-Continue your learning journey:
-
-- [Quick Reference](../integration-patterns-quick-reference.md) - All patterns at a glance
-- [Use Cases](../../../01-TEMPLATES/readme.md) - Complete production examples
-- [Error Handling](./integration-patterns-05-error-handling.md) - Comprehensive error patterns
-
-Or explore related guides:
-- [Auto-Pagination](../../../02-CORE-GUIDES/auto-pagination/auto-pagination-readme.md)
-- [Universal Mapping](../../../02-CORE-GUIDES/mapping/mapping-readme.md)
-- [Batch API Guide](../../../02-CORE-GUIDES/ingestion/modules/02-core-guides-ingestion-06-batch-api.md)
-
----
-
-[← Back to Index](../integration-patterns-readme.md) | [Previous: Error Handling](./integration-patterns-05-error-handling.md)
+# Module 6: Advanced Integration Services
+
+> **Learning Objective:** Master advanced SDK services for webhook validation, partial batch recovery, job tracking, and pre-flight validation.
+>
+> **Level:** Advanced
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Webhook Validation Service](#webhook-validation-service)
+3. [Partial Batch Recovery](#partial-batch-recovery)
+4. [Job Tracker](#job-tracker)
+5. [Preflight Validator](#preflight-validator)
+6. [Integration Patterns](#integration-patterns)
+7. [Production Examples](#production-examples)
+8. [Summary](#summary)
+
+---
+
+## Overview
+
+### What These Services Solve
+
+| Service | Problem | Solution | Benefits |
+|---------|---------|----------|----------|
+| **Webhook Validation** | Unverified webhooks | Cryptographic signature validation | Security, authenticity |
+| **Partial Batch Recovery** | Entire batch fails when one record fails | Retry only failed records | Efficiency, data integrity |
+| **Job Tracker** | No visibility into job status | Track job lifecycle in KV store | Observability, debugging |
+| **Preflight Validator** | API quota wasted on invalid data | Validate before API calls | Cost savings, faster feedback |
+
+### When to Use
+
+```
+Production Integration Checklist:
+✅ Webhook Validation - ALL webhook endpoints (security)
+✅ Partial Batch Recovery - Batch API ingestion (reliability)
+✅ Job Tracker - Async scheduled workflows (observability)
+✅ Preflight Validator - Large batch operations (cost optimization)
+```
+
+---
+
+## Webhook Validation Service
+
+### What It Does
+
+**Validates webhook signatures from Fluent Commerce Rubix workflows** using RSA-based cryptographic verification.
+
+> ⚠️ **IMPORTANT:** This service is **ONLY for Fluent Commerce webhooks**. Do not use for Shopify, GitHub, Stripe, or other third-party webhooks. For those systems, implement manual HMAC validation (see Module 4: Webhook Patterns).
+
+### Key Features
+
+- ✅ **SHA512withRSA** (fluent-signature) - Recommended for Fluent Commerce webhooks
+- ✅ **MD5withRSA** (flex.signature) - Support for older Fluent Commerce webhooks
+- ✅ Automatic algorithm detection from Fluent Commerce headers
+- ✅ Public key caching for performance
+- ✅ Fallback algorithm support for Fluent Commerce
+- ✅ Integrated with FluentClient.validateWebhook()
+- ❌ **NOT for Shopify/GitHub/Stripe webhooks** (use manual HMAC - see Module 4)
+
+### Basic Usage
+
+#### Using FluentClient (Recommended)
+
+```typescript
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+const client = await createClient({
+  baseUrl: 'https://api.fluentcommerce.com',
+  clientId: process.env.FLUENT_CLIENT_ID,
+  clientSecret: process.env.FLUENT_CLIENT_SECRET,
+  username: process.env.FLUENT_USERNAME,
+  password: process.env.FLUENT_PASSWORD,
+  retailerId: process.env.FLUENT_RETAILER_ID,
+  publicKey: process.env.FLUENT_WEBHOOK_PUBLIC_KEY // For webhook validation
+});
+
+// In webhook handler
+export async function handleWebhook(request: Request) {
+  const rawBody = await request.text(); // CRITICAL: Must be raw body
+  const payload = JSON.parse(rawBody);
+  const signature = request.headers.get('fluent-signature');
+
+  // Validate webhook signature
+  const isValid = await client.validateWebhook(
+    payload,
+    signature,
+    rawBody  // Pass raw string, not parsed JSON
+  );
+
+  if (!isValid) {
+    return new Response('Invalid signature', { status: 401 });
+  }
+
+  // Process webhook...
+  return new Response('OK', { status: 200 });
+}
+```
+
+#### Using WebhookValidationService Directly
+
+```typescript
+import {
+  WebhookValidationService,
+  SignatureAlgorithm,
+  createConsoleLogger
+} from '@fluentcommerce/fc-connect-sdk';
+
+const logger = createConsoleLogger();
+const validator = new WebhookValidationService({
+  algorithm: SignatureAlgorithm.SHA512_WITH_RSA,
+  strictValidation: true // Throw on validation failure
+}, logger);
+
+// Validate webhook
+const result = await validator.validateWebhookSignature(
+  rawPayload,                      // Raw request body as string
+  headers['fluent-signature'],     // Signature from header
+  publicKey,                        // Public key from env
+  SignatureAlgorithm.SHA512_WITH_RSA
+);
+
+if (!result.isValid) {
+  console.error('Validation failed:', result.error);
+  throw new Error('Invalid webhook signature');
+}
+```
+
+### Versori Platform Integration
+
+```typescript
+import { webhook, fn } from '@versori/run';
+import { FluentClient } from '@fluentcommerce/fc-connect-sdk';
+
+export const fluentWebhook = webhook('fluent-order', {
+  response: {
+    mode: 'sync',
+    onSuccess: (ctx) => new Response(JSON.stringify({ success: true }), {
+      status: 200,
+      headers: { 'Content-Type': 'application/json' }
+    }),
+    onError: (ctx) => new Response(JSON.stringify({ error: ctx.error.message }), {
+      status: 500,
+      headers: { 'Content-Type': 'application/json' }
+    })
+  }
+})
+  .then(fn('validate', async (ctx) => {
+    const { request, vars, log } = ctx;
+
+    // Get raw body (Versori v0.2.29+)
+    const rawBody = await request.text();
+    const payload = JSON.parse(rawBody);
+
+    // Get signature from headers
+    const signature = request.headers.get('fluent-signature') ||
+                      request.headers.get('x-fluent-signature');
+
+    if (!signature) {
+      throw new Error('Missing webhook signature header');
+    }
+
+    // Validate using FluentClient
+    const client = new FluentClient({
+      baseUrl: vars.FLUENT_BASE_URL,
+      clientId: vars.FLUENT_CLIENT_ID,
+      clientSecret: vars.FLUENT_CLIENT_SECRET,
+      username: vars.FLUENT_USERNAME,
+      password: vars.FLUENT_PASSWORD,
+      retailerId: vars.FLUENT_RETAILER_ID,
+      publicKey: vars.FLUENT_WEBHOOK_PUBLIC_KEY
+    }, log);
+
+    const isValid = await client.validateWebhook(payload, signature, rawBody);
+
+    if (!isValid) {
+      throw new Error('Invalid webhook signature - not from Fluent Commerce');
+    }
+
+    log.info('Webhook signature validated', { eventName: payload.name });
+
+    return payload;
+  }))
+  .then(fn('process', async ({ data, log }) => {
+    // Process validated webhook...
+    log.info('Processing webhook', { orderId: data.entityRef });
+
+    return { success: true, orderId: data.entityRef };
+  }));
+```
+
+### Signature Header Detection
+
+The service automatically detects signature algorithm:
+
+| Header | Algorithm | Status |
+|--------|-----------|--------|
+| `fluent-signature` | SHA512withRSA | **Recommended** |
+| `x-fluent-signature` | SHA512withRSA | Supported |
+| `flex.signature` | MD5withRSA | **Older algorithm** |
+| `flex-signature` | MD5withRSA | Supported |
+
+```typescript
+// Auto-detection (recommended)
+const result = await validator.validateWebhook(
+  rawPayload,
+  headers, // Pass all headers
+  publicKey
+);
+
+// Manual algorithm selection
+const result = await validator.validateWebhookSignature(
+  rawPayload,
+  headers['fluent-signature'],
+  publicKey,
+  SignatureAlgorithm.SHA512_WITH_RSA
+);
+```
+
+### Common Pitfalls
+
+#### ❌ WRONG: Validating parsed JSON
+
+```typescript
+// ❌ This will FAIL - signature is for raw body
+const payload = await request.json();
+const isValid = await validator.validateWebhookSignature(
+  JSON.stringify(payload), // Serialization changes order/whitespace
+  signature,
+  publicKey
+);
+```
+
+#### ✅ CORRECT: Validate raw body
+
+```typescript
+// ✅ Correct - validate raw body
+const rawBody = await request.text();
+const isValid = await validator.validateWebhookSignature(
+  rawBody,  // Exact bytes received
+  signature,
+  publicKey
+);
+
+// Then parse for processing
+const payload = JSON.parse(rawBody);
+```
+
+### Production Factory Methods
+
+```typescript
+import { WebhookValidationFactory } from '@fluentcommerce/fc-connect-sdk';
+
+// Production: strict validation, throws on failure
+const validator = WebhookValidationFactory.createProduction(logger);
+
+// Development: lenient validation, logs but doesn't throw
+const validator = WebhookValidationFactory.createDevelopment(logger);
+
+// With fallback: try SHA512, fallback to MD5
+const validator = WebhookValidationFactory.createWithFallback(logger);
+```
+
+---
+
+## Partial Batch Recovery
+
+### What It Does
+
+**Tracks per-record success/failure** in batch operations and enables:
+- Retrying only failed records instead of entire batch
+- Checkpoint/resume functionality
+- Detailed error reporting per record
+- Progress tracking
+
+### Key Features
+
+- ✅ **Per-record tracking** - Know exactly which records failed
+- ✅ **Selective retry** - Retry only failures, not successes
+- ✅ **Checkpoint support** - Resume from failure point
+- ✅ **Exponential backoff** - Configurable retry delays
+- ✅ **Custom retry logic** - Override retry decisions
+
+### Basic Usage
+
+```typescript
+import { PartialBatchRecovery } from '@fluentcommerce/fc-connect-sdk';
+
+const recovery = new PartialBatchRecovery(logger);
+
+// Process batch with automatic recovery
+const result = await recovery.processBatchWithRecovery(
+  records,
+  async (batch) => {
+    // Your batch processing logic
+    return await client.sendBatch(jobId, {
+      action: 'UPSERT',
+      entityType: 'INVENTORY',
+      entities: batch
+    });
+  },
+  {
+    maxRetries: 3,
+    retryOnlyFailed: true,  // Only retry failed records
+    retryDelayMs: 1000,     // Start with 1 second
+    retryBatchSize: 100,    // Process 100 at a time
+    checkpointKey: 'inventory-sync-2025-01-24'
+  }
+);
+
+console.log(`✓ Success: ${result.successCount}/${result.totalRecords}`);
+console.log(`✗ Failed: ${result.failedCount} records`);
+
+if (result.failedCount > 0) {
+  console.error('Failed records:', result.failedRecords);
+  console.log(`Checkpoint saved: ${result.checkpointId}`);
+}
+```
+
+### Integration with Batch API
+
+```typescript
+import {
+  createClient,
+  PartialBatchRecovery
+} from '@fluentcommerce/fc-connect-sdk';
+
+async function batchIngestionWithRecovery(records: any[]) {
+  const client = await createClient({ config });
+  const recovery = new PartialBatchRecovery(logger);
+
+  // Create job
+  const job = await client.createJob({
+    name: 'Inventory Ingestion with Recovery',
+    retailerId: 'my-retailer'
+  });
+
+  // Process with recovery
+  const result = await recovery.processBatchWithRecovery(
+    records,
+    async (batch) => {
+      const response = await client.sendBatch(job.id, {
+        action: 'UPSERT',
+        entityType: 'INVENTORY',
+        entities: batch
+      });
+
+      logger.info('Batch sent', {
+        batchId: response.id,
+        recordCount: batch.length
+      });
+
+      return response;
+    },
+    {
+      maxRetries: 3,
+      retryOnlyFailed: true,
+      checkpointKey: `job-${job.id}`
+    }
+  );
+
+  // Check job status
+  const status = await client.getJobStatus(job.id);
+
+  return {
+    jobId: job.id,
+    jobStatus: status.status,
+    ...result
+  };
+}
+```
+
+### Checkpoint and Resume
+
+```typescript
+// Process batch and save checkpoint
+const result = await recovery.processBatchWithRecovery(
+  records,
+  processBatch,
+  {
+    maxRetries: 3,
+    checkpointKey: 'daily-inventory-sync'
+  }
+);
+
+if (result.failedCount > 0) {
+  console.log(`Checkpoint created: ${result.checkpointId}`);
+  console.log(`Failed records saved for later retry`);
+}
+
+// Later: Resume from checkpoint
+const checkpointId = result.checkpointId;
+const resumeResult = await recovery.resumeFromCheckpoint(
+  checkpointId,
+  processBatch,
+  {
+    maxRetries: 5  // More retries on resume
+  }
+);
+
+console.log(`Resume: ${resumeResult.successCount} recovered`);
+```
+
+### Custom Retry Logic
+
+```typescript
+const result = await recovery.processBatchWithRecovery(
+  records,
+  processBatch,
+  {
+    maxRetries: 5,
+    retryDelayMs: 2000,
+    // Custom retry decision
+    shouldRetry: (error, attemptCount) => {
+      // Don't retry validation errors
+      if (error.message.includes('validation')) {
+        return false;
+      }
+
+      // Don't retry after 3 attempts for rate limits
+      if (error.message.includes('rate limit') && attemptCount > 3) {
+        return false;
+      }
+
+      // Retry all other errors
+      return true;
+    }
+  }
+);
+```
+
+### Record Failure Details
+
+```typescript
+// Access detailed failure information
+if (result.failedCount > 0) {
+  result.failedRecords.forEach(failure => {
+    console.error(`Record ${failure.index} failed:`, {
+      record: failure.record,
+      error: failure.error.message,
+      attempts: failure.attemptCount,
+      timestamp: failure.timestamp
+    });
+  });
+
+  // Export failures for manual review
+  await fs.writeFile(
+    'failed-records.json',
+    JSON.stringify(result.failedRecords, null, 2)
+  );
+}
+```
+
+---
+
+## Job Tracker
+
+### What It Does
+
+**Tracks job status** in Versori KV store for async workflows:
+- Job lifecycle tracking (queued → processing → completed/failed)
+- Stage-based progress tracking
+- Error capture with stack traces
+- Automatic timestamp management
+- TTL-based cleanup
+
+### Key Features
+
+- ✅ **Lifecycle tracking** - queued, processing, completed, failed
+- ✅ **Stage tracking** - Custom stages for your workflow
+- ✅ **Metadata storage** - Store job-specific context
+- ✅ **TTL support** - Automatic cleanup after 7 days
+- ✅ **Error capture** - Store errors with stack traces
+
+### Basic Usage
+
+```typescript
+import { JobTracker, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
+// ✅ CORRECT: Access openKv from Versori context
+// import { openKv } from '@versori/run'; // ❌ WRONG - Not a direct export
+
+// In Versori workflow handler:
+const { openKv } = ctx;
+const kvAdapter = new VersoriKVAdapter(openKv(':project:'));
+const tracker = new JobTracker(kvAdapter, logger);
+
+// Create job
+const jobId = `scheduled_${Date.now()}`;
+
+await tracker.createJob(jobId, {
+  triggeredBy: 'schedule',
+  stage: 'initialization',
+  details: {
+    catalogueRef: 'DEFAULT:1',
+    fileName: 'inventory.csv'
+  }
+});
+
+// Update progress
+await tracker.updateJob(jobId, {
+  status: 'processing',
+  stage: 'extraction',
+  message: 'Extracting records from S3'
+});
+
+await tracker.updateJob(jobId, {
+  stage: 'transformation',
+  message: 'Mapping 1000 records',
+  details: { recordCount: 1000 }
+});
+
+// Mark as completed
+await tracker.markCompleted(jobId, {
+  recordCount: 1000,
+  successCount: 998,
+  failedCount: 2
+});
+
+// Or mark as failed
+try {
+  // ... job logic ...
+} catch (error) {
+  await tracker.markFailed(jobId, error);
+}
+```
+
+### Scheduled Workflow Integration
+
+```typescript
+import { schedule } from '@versori/run';
+import { JobTracker, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
+
+export const dailyInventorySync = schedule('daily-inventory', '0 2 * * *')
+  .execute(async ({ log, connections, vars, kv }) => {
+    const jobId = `inventory_${Date.now()}`;
+    const tracker = new JobTracker(new VersoriKVAdapter(kv), log);
+
+    try {
+      // Create job
+      await tracker.createJob(jobId, {
+        triggeredBy: 'schedule',
+        stage: 'start',
+        details: { schedule: 'daily 2am' }
+      });
+
+      // Stage 1: Extraction
+      await tracker.updateJob(jobId, {
+        status: 'processing',
+        stage: 'extraction',
+        message: 'Querying virtual positions'
+      });
+
+      const data = await extractFromFluent();
+
+      // Stage 2: Transformation
+      await tracker.updateJob(jobId, {
+        stage: 'transformation',
+        message: `Processing ${data.length} records`
+      });
+
+      const transformed = await transformData(data);
+
+      // Stage 3: Upload
+      await tracker.updateJob(jobId, {
+        stage: 'upload',
+        message: 'Uploading to SFTP'
+      });
+
+      await uploadToSFTP(transformed);
+
+      // Completed
+      await tracker.markCompleted(jobId, {
+        recordCount: data.length,
+        fileName: `inventory_${jobId}.xml`
+      });
+
+      log.info('Job completed successfully', { jobId });
+
+    } catch (error) {
+      await tracker.markFailed(jobId, error);
+      log.error('Job failed', error);
+      throw error;
+    }
+  });
+```
+
+### Webhook Workflow Integration
+
+```typescript
+import { webhook, fn } from '@versori/run';
+import { JobTracker, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
+
+export const orderWebhook = webhook('order-webhook')
+  .then(fn('track-start', async ({ request, kv, log }) => {
+    const jobId = request.headers.get('x-request-id') || crypto.randomUUID();
+    const tracker = new JobTracker(new VersoriKVAdapter(kv), log);
+
+    await tracker.createJob(jobId, {
+      triggeredBy: 'webhook',
+      stage: 'validation',
+      details: {
+        source: request.headers.get('user-agent')
+      }
+    });
+
+    return { jobId };
+  }))
+  .then(fn('process', async ({ data, kv, log }) => {
+    const tracker = new JobTracker(new VersoriKVAdapter(kv), log);
+
+    await tracker.updateJob(data.jobId, {
+      status: 'processing',
+      stage: 'transformation'
+    });
+
+    // Process order...
+    const result = await processOrder(data);
+
+    await tracker.markCompleted(data.jobId, {
+      orderId: result.orderId
+    });
+
+    return result;
+  }))
+  .catch(async ({ error, data, kv, log }) => {
+    const tracker = new JobTracker(new VersoriKVAdapter(kv), log);
+
+    if (data?.jobId) {
+      await tracker.markFailed(data.jobId, error);
+    }
+
+    throw error;
+  });
+```
+
+### Querying Job Status
+
+```typescript
+// Get job status
+const status = await tracker.getJob(jobId);
+
+if (status) {
+  console.log(`Job ${jobId}:`, {
+    status: status.status,
+    stage: status.stage,
+    message: status.message,
+    createdAt: status.createdAt,
+    completedAt: status.completedAt
+  });
+}
+
+// Check if job is still running
+if (status.status === 'processing') {
+  console.log(`Job in progress: ${status.stage}`);
+}
+
+// Check for errors
+if (status.status === 'failed') {
+  console.error('Job failed:', {
+    error: status.error,
+    stack: status.errorStack
+  });
+}
+```
+
+### Custom TTL Configuration
+
+```typescript
+// Default TTL: 7 days
+const tracker = new JobTracker(kvAdapter, logger);
+
+// Custom TTL: 24 hours
+const shortTracker = new JobTracker(
+  kvAdapter,
+  logger,
+  86400 // 24 hours in seconds
+);
+
+// Custom TTL: 30 days
+const longTracker = new JobTracker(
+  kvAdapter,
+  logger,
+  2592000 // 30 days in seconds
+);
+```
+
+---
+
+## Preflight Validator
+
+### What It Does
+
+**Validates data BEFORE sending to Fluent API** to:
+- Catch errors early and save API quota
+- Validate against GraphQL schema requirements
+- Check for duplicates and data quality issues
+- Provide actionable error messages
+
+### Key Features
+
+- ✅ **Required field validation** - Ensure mandatory fields present
+- ✅ **Type validation** - Check field types (string, number, etc.)
+- ✅ **Duplicate detection** - Find duplicate refs in batch
+- ✅ **Batch size limits** - Enforce max batch size
+- ✅ **Custom validators** - Add domain-specific rules
+- ✅ **Detailed error reports** - Per-record error details
+
+### Basic Usage
+
+```typescript
+import { PreflightValidator } from '@fluentcommerce/fc-connect-sdk';
+
+const validator = new PreflightValidator(logger);
+
+// Validate batch before sending
+const result = await validator.validateBatch(records, {
+  entityType: 'INVENTORY',
+  requiredFields: ['ref', 'qty', 'productRef', 'locationRef'],
+  checkDuplicates: true,
+  maxBatchSize: 5000,
+  validateTypes: true
+});
+
+if (!result.isValid) {
+  console.error(`Validation failed: ${result.errors.length} errors`);
+
+  // Log first 10 errors
+  result.errors.slice(0, 10).forEach(err => {
+    console.error(`Record ${err.index}: ${err.message}`, {
+      field: err.field,
+      value: err.value
+    });
+  });
+
+  // Don't send to API - save quota
+  throw new Error(`Validation failed: ${result.summary}`);
+}
+
+console.log(`✓ Validation passed: ${result.summary}`);
+
+// Safe to send to API
+await sendToFluentAPI(records);
+```
+
+### Integration with Batch API
+
+```typescript
+import {
+  createClient,
+  PreflightValidator
+} from '@fluentcommerce/fc-connect-sdk';
+
+async function batchIngestionWithValidation(records: any[]) {
+  const validator = new PreflightValidator(logger);
+  const client = await createClient({ config });
+
+  // Step 1: Preflight validation
+  logger.info('Running preflight validation', { recordCount: records.length });
+
+  const validationResult = await validator.validateBatch(records, {
+    entityType: 'INVENTORY',
+    requiredFields: ['ref', 'qty', 'productRef', 'locationRef'],
+    checkDuplicates: true,
+    maxBatchSize: 5000,
+    validateTypes: true
+  });
+
+  if (!validationResult.isValid) {
+    logger.error('Preflight validation failed', {
+      errorCount: validationResult.errors.length,
+      validRecords: validationResult.validRecords
+    });
+
+    // Export validation errors
+    await fs.writeFile(
+      'validation-errors.json',
+      JSON.stringify(validationResult.errors, null, 2)
+    );
+
+    throw new Error(`Validation failed: ${validationResult.summary}`);
+  }
+
+  logger.info('Preflight validation passed', {
+    validRecords: validationResult.validRecords,
+    warnings: validationResult.warnings.length
+  });
+
+  // Step 2: Send to API (data is valid)
+  const job = await client.createJob({
+    name: 'Validated Inventory Ingestion',
+    retailerId: 'my-retailer'
+  });
+
+  await client.sendBatch(job.id, {
+    action: 'UPSERT',
+    entityType: 'INVENTORY',
+    entities: records
+  });
+
+  return { jobId: job.id, validationResult };
+}
+```
+
+### Custom Validation Rules
+
+```typescript
+const result = await validator.validateBatch(records, {
+  entityType: 'INVENTORY',
+  requiredFields: ['ref', 'qty'],
+  validateTypes: true,
+  // Custom validation function
+  customValidator: (record, index) => {
+    // Business rule: qty must be >= 0
+    if (record.qty < 0) {
+      return `Quantity cannot be negative (got ${record.qty})`;
+    }
+
+    // Business rule: ref must follow pattern
+    if (!/^[A-Z0-9-]+$/.test(record.ref)) {
+      return `Invalid ref format (must be alphanumeric with hyphens)`;
+    }
+
+    // Business rule: locationRef must be valid
+    if (!isValidLocation(record.locationRef)) {
+      return `Invalid locationRef: ${record.locationRef}`;
+    }
+
+    return null; // Validation passed
+  }
+});
+```
+
+### Quick Validation (Fast Mode)
+
+```typescript
+// Quick validation - checks first record only
+const quickResult = await validator.validateQuick(records, {
+  entityType: 'INVENTORY',
+  requiredFields: ['ref', 'qty'],
+  maxBatchSize: 5000
+});
+
+if (!quickResult.isValid) {
+  console.error('Quick validation failed:', quickResult.error);
+  throw new Error(`Data format invalid: ${quickResult.error}`);
+}
+
+// Optionally do full validation
+const fullResult = await validator.validateBatch(records, options);
+```
+
+### Duplicate Detection
+
+```typescript
+const result = await validator.validateBatch(records, {
+  entityType: 'INVENTORY',
+  requiredFields: ['ref'],
+  checkDuplicates: true  // Enable duplicate detection
+});
+
+if (result.warnings.length > 0) {
+  console.warn('Validation warnings:', result.warnings);
+}
+
+if (result.duplicates && result.duplicates.length > 0) {
+  console.warn('Duplicate refs found:', result.duplicates);
+
+  // Option 1: Remove duplicates
+  const uniqueRecords = records.filter((r, i, arr) =>
+    arr.findIndex(x => x.ref === r.ref) === i
+  );
+
+  // Option 2: Fail on duplicates
+  if (result.duplicates.length > 10) {
+    throw new Error(`Too many duplicates: ${result.duplicates.length}`);
+  }
+}
+```
+
+### Error Reporting
+
+```typescript
+const result = await validator.validateBatch(records, options);
+
+if (!result.isValid) {
+  // Generate detailed error report
+  const report = {
+    summary: result.summary,
+    totalRecords: result.totalRecords,
+    validRecords: result.validRecords,
+    errorCount: result.errors.length,
+    errors: result.errors.map(err => ({
+      record: err.index,
+      field: err.field,
+      message: err.message,
+      value: err.value,
+      severity: err.severity
+    }))
+  };
+
+  // Export to file
+  await fs.writeFile(
+    `validation-report-${Date.now()}.json`,
+    JSON.stringify(report, null, 2)
+  );
+
+  // Send to monitoring
+  logger.error('Validation failed', report);
+}
+```
+
+---
+
+## Integration Patterns
+
+### Pattern 1: Secure Webhook Endpoint
+
+**Webhook validation + Job tracking + Error handling**
+
+```typescript
+import {
+  webhook,
+  fn
+} from '@versori/run';
+import {
+  FluentClient,
+  JobTracker,
+  VersoriKVAdapter
+} from '@fluentcommerce/fc-connect-sdk';
+
+export const secureWebhook = webhook('secure-order', {
+  response: {
+    mode: 'sync',
+    onSuccess: (ctx) => new Response(JSON.stringify({ success: true }), {
+      status: 200,
+      headers: { 'Content-Type': 'application/json' }
+    }),
+    onError: (ctx) => new Response(JSON.stringify({
+      error: ctx.error.message
+    }), {
+      status: ctx.error.message.includes('signature') ? 401 : 500,
+      headers: { 'Content-Type': 'application/json' }
+    })
+  }
+})
+  .then(fn('validate-signature', async ({ request, vars, log, kv }) => {
+    const jobId = request.headers.get('x-request-id') || crypto.randomUUID();
+    const tracker = new JobTracker(new VersoriKVAdapter(kv), log);
+
+    // Track job start
+    await tracker.createJob(jobId, {
+      triggeredBy: 'webhook',
+      stage: 'validation'
+    });
+
+    // Get raw body
+    const rawBody = await request.text();
+    const payload = JSON.parse(rawBody);
+    const signature = request.headers.get('fluent-signature');
+
+    if (!signature) {
+      await tracker.markFailed(jobId, new Error('Missing signature'));
+      throw new Error('Missing fluent-signature header');
+    }
+
+    // Validate signature
+    const client = new FluentClient({
+      baseUrl: vars.FLUENT_BASE_URL,
+      clientId: vars.FLUENT_CLIENT_ID,
+      clientSecret: vars.FLUENT_CLIENT_SECRET,
+      username: vars.FLUENT_USERNAME,
+      password: vars.FLUENT_PASSWORD,
+      retailerId: vars.FLUENT_RETAILER_ID,
+      publicKey: vars.FLUENT_WEBHOOK_PUBLIC_KEY
+    }, log);
+
+    const isValid = await client.validateWebhook(payload, signature, rawBody);
+
+    if (!isValid) {
+      await tracker.markFailed(jobId, new Error('Invalid signature'));
+      throw new Error('Invalid webhook signature');
+    }
+
+    await tracker.updateJob(jobId, {
+      status: 'processing',
+      stage: 'processing',
+      message: 'Signature validated'
+    });
+
+    return { jobId, payload };
+  }))
+  .then(fn('process-order', async ({ data, kv, log }) => {
+    const tracker = new JobTracker(new VersoriKVAdapter(kv), log);
+
+    await tracker.updateJob(data.jobId, {
+      stage: 'transformation',
+      message: `Processing order ${data.payload.entityRef}`
+    });
+
+    // Process order...
+    const result = await processOrder(data.payload);
+
+    await tracker.markCompleted(data.jobId, {
+      orderId: result.orderId
+    });
+
+    return { success: true, orderId: result.orderId };
+  }));
+```
+
+### Pattern 2: Validated Batch Ingestion with Recovery
+
+**Preflight validation + Partial batch recovery + Job tracking**
+
+```typescript
+import {
+  createClient,
+  PreflightValidator,
+  PartialBatchRecovery,
+  JobTracker,
+  VersoriKVAdapter
+} from '@fluentcommerce/fc-connect-sdk';
+
+async function validatedBatchIngestion(
+  records: any[],
+  config: any,
+  logger: any,
+  kv: any
+) {
+  const client = await createClient({ config });
+  const validator = new PreflightValidator(logger);
+  const recovery = new PartialBatchRecovery(logger);
+  const tracker = new JobTracker(new VersoriKVAdapter(kv), logger);
+
+  const jobId = `batch_${Date.now()}`;
+
+  try {
+    // Track job
+    await tracker.createJob(jobId, {
+      triggeredBy: 'schedule',
+      stage: 'validation',
+      details: { recordCount: records.length }
+    });
+
+    // Step 1: Preflight validation
+    await tracker.updateJob(jobId, {
+      status: 'processing',
+      stage: 'preflight-validation',
+      message: `Validating ${records.length} records`
+    });
+
+    const validationResult = await validator.validateBatch(records, {
+      entityType: 'INVENTORY',
+      requiredFields: ['ref', 'qty', 'productRef', 'locationRef'],
+      checkDuplicates: true,
+      maxBatchSize: 5000,
+      validateTypes: true,
+      customValidator: (record) => {
+        if (record.qty < 0) return 'Quantity cannot be negative';
+        return null;
+      }
+    });
+
+    if (!validationResult.isValid) {
+      await tracker.markFailed(jobId, new Error(validationResult.summary));
+      throw new Error(`Validation failed: ${validationResult.summary}`);
+    }
+
+    // Step 2: Create Fluent job
+    await tracker.updateJob(jobId, {
+      stage: 'batch-creation',
+      message: 'Creating Fluent batch job'
+    });
+
+    const fluentJob = await client.createJob({
+      name: `Validated Ingestion ${jobId}`,
+      retailerId: config.retailerId
+    });
+
+    // Step 3: Send with recovery
+    await tracker.updateJob(jobId, {
+      stage: 'batch-processing',
+      message: `Sending ${records.length} records with recovery`
+    });
+
+    const recoveryResult = await recovery.processBatchWithRecovery(
+      records,
+      async (batch) => {
+        return await client.sendBatch(fluentJob.id, {
+          action: 'UPSERT',
+          entityType: 'INVENTORY',
+          entities: batch
+        });
+      },
+      {
+        maxRetries: 3,
+        retryOnlyFailed: true,
+        checkpointKey: jobId,
+        retryBatchSize: 100
+      }
+    );
+
+    // Step 4: Complete
+    await tracker.markCompleted(jobId, {
+      fluentJobId: fluentJob.id,
+      totalRecords: recoveryResult.totalRecords,
+      successCount: recoveryResult.successCount,
+      failedCount: recoveryResult.failedCount,
+      checkpointId: recoveryResult.checkpointId
+    });
+
+    return {
+      jobId,
+      fluentJobId: fluentJob.id,
+      validation: validationResult,
+      recovery: recoveryResult
+    };
+
+  } catch (error) {
+    await tracker.markFailed(jobId, error);
+    throw error;
+  }
+}
+```
+
+### Pattern 3: Scheduled Extraction with Tracking
+
+**Job tracking + Error handling**
+
+```typescript
+import { schedule } from '@versori/run';
+import {
+  createClient,
+  ExtractionOrchestrator,
+  JobTracker,
+  VersoriKVAdapter,
+  SftpDataSource
+} from '@fluentcommerce/fc-connect-sdk';
+
+export const dailyExtraction = schedule('daily-extraction', '0 3 * * *')
+  .execute(async ({ log, connections, vars, kv }) => {
+    const jobId = `extraction_${Date.now()}`;
+    const tracker = new JobTracker(new VersoriKVAdapter(kv), log);
+
+    try {
+      await tracker.createJob(jobId, {
+        triggeredBy: 'schedule',
+        stage: 'initialization',
+        details: { schedule: 'daily 3am' }
+      });
+
+      // Stage 1: Extraction
+      await tracker.updateJob(jobId, {
+        status: 'processing',
+        stage: 'extraction',
+        message: 'Querying Fluent API'
+      });
+
+      const client = await createClient(ctx); // Auto-detects Versori context
+      const orchestrator = new ExtractionOrchestrator(client, log);
+
+      const data = await orchestrator.extract({
+        entityType: 'virtualPositions',
+        fields: ['ref', 'type', 'quantity', 'productRef', 'groupRef'],
+        pagination: { pageSize: 1000 }
+      });
+
+      // Stage 2: Transformation
+      await tracker.updateJob(jobId, {
+        stage: 'transformation',
+        message: `Transforming ${data.length} records`
+      });
+
+      const xml = transformToXML(data);
+
+      // Stage 3: Upload
+      await tracker.updateJob(jobId, {
+        stage: 'upload',
+        message: 'Uploading to SFTP'
+      });
+
+      const sftp = new SftpDataSource({
+        host: vars.SFTP_HOST,
+        username: vars.SFTP_USERNAME,
+        privateKey: vars.SFTP_PRIVATE_KEY
+      }, log);
+
+      const fileName = `inventory_${jobId}.xml`;
+      await sftp.writeFile(`/uploads/${fileName}`, xml);
+
+      // Complete
+      await tracker.markCompleted(jobId, {
+        recordCount: data.length,
+        fileName,
+        fileSize: xml.length
+      });
+
+      log.info('Extraction completed', { jobId, recordCount: data.length });
+
+    } catch (error) {
+      await tracker.markFailed(jobId, error);
+      log.error('Extraction failed', error);
+      throw error;
+    }
+  });
+```
+
+---
+
+## Production Examples
+
+### Complete Production Workflow
+
+```typescript
+/**
+ * Production-ready inventory ingestion with all advanced services
+ */
+
+import { schedule } from '@versori/run';
+import {
+  createClient,
+  PreflightValidator,
+  PartialBatchRecovery,
+  JobTracker,
+  VersoriKVAdapter,
+  S3DataSource,
+  CSVParserService,
+  UniversalMapper
+} from '@fluentcommerce/fc-connect-sdk';
+
+export const productionInventorySync = schedule('inventory-sync', '0 */6 * * *')
+  .execute(async ({ log, connections, vars, kv }) => {
+    const jobId = `inventory_${Date.now()}`;
+    const tracker = new JobTracker(new VersoriKVAdapter(kv), log, 2592000); // 30 day TTL
+    const validator = new PreflightValidator(log);
+    const recovery = new PartialBatchRecovery(log);
+
+    try {
+      // ========================================
+      // Stage 1: Job Initialization
+      // ========================================
+      await tracker.createJob(jobId, {
+        triggeredBy: 'schedule',
+        stage: 'initialization',
+        details: {
+          schedule: 'every 6 hours',
+          bucket: vars.S3_BUCKET
+        }
+      });
+
+      log.info('Starting production inventory sync', { jobId });
+
+      // ========================================
+      // Stage 2: Data Extraction
+      // ========================================
+      await tracker.updateJob(jobId, {
+        status: 'processing',
+        stage: 'extraction',
+        message: 'Reading CSV from S3'
+      });
+
+      const s3 = new S3DataSource({
+        region: vars.AWS_REGION,
+        accessKeyId: vars.AWS_ACCESS_KEY_ID,
+        secretAccessKey: vars.AWS_SECRET_ACCESS_KEY
+      }, log);
+
+      const csvContent = await s3.readFile(vars.S3_BUCKET, 'inventory/latest.csv');
+
+      const parser = new CSVParserService({ hasHeaders: true }, log);
+      const rawRecords = await parser.parseToArray(csvContent);
+
+      log.info('CSV parsed', { recordCount: rawRecords.length });
+
+      // ========================================
+      // Stage 3: Data Transformation
+      // ========================================
+      await tracker.updateJob(jobId, {
+        stage: 'transformation',
+        message: `Mapping ${rawRecords.length} records`
+      });
+
+      const mapper = new UniversalMapper({
+        fields: {
+          ref: { source: 'sku', required: true },
+          type: { resolver: () => 'INVENTORY_POSITION' },
+          qty: { source: 'quantity', resolver: 'sdk.parseInt', required: true },
+          productRef: { source: 'product_id', required: true },
+          locationRef: { source: 'location_id', required: true },
+          condition: { source: 'condition', defaultValue: 'NEW' }
+        }
+      });
+
+      const mappedRecords = [];
+      const mappingErrors = [];
+
+      for (let i = 0; i < rawRecords.length; i++) {
+        const result = await mapper.map(rawRecords[i]);
+        if (result.success) {
+          mappedRecords.push(result.data);
+        } else {
+          mappingErrors.push({ index: i, errors: result.errors });
+        }
+      }
+
+      if (mappingErrors.length > 0) {
+        log.warn('Mapping errors', {
+          errorCount: mappingErrors.length,
+          totalRecords: rawRecords.length
+        });
+      }
+
+      // ========================================
+      // Stage 4: Preflight Validation
+      // ========================================
+      await tracker.updateJob(jobId, {
+        stage: 'validation',
+        message: `Validating ${mappedRecords.length} records`
+      });
+
+      const validationResult = await validator.validateBatch(mappedRecords, {
+        entityType: 'INVENTORY',
+        requiredFields: ['ref', 'qty', 'productRef', 'locationRef'],
+        checkDuplicates: true,
+        maxBatchSize: 5000,
+        validateTypes: true,
+        customValidator: (record) => {
+          if (record.qty < 0) {
+            return 'Quantity cannot be negative';
+          }
+          if (!record.ref.match(/^[A-Z0-9-]+$/)) {
+            return 'Invalid ref format';
+          }
+          return null;
+        }
+      });
+
+      if (!validationResult.isValid) {
+        await tracker.markFailed(jobId, new Error(validationResult.summary));
+
+        // Export validation errors
+        await s3.writeFile(
+          vars.S3_BUCKET,
+          `errors/validation-${jobId}.json`,
+          JSON.stringify(validationResult.errors, null, 2)
+        );
+
+        throw new Error(`Validation failed: ${validationResult.summary}`);
+      }
+
+      log.info('Validation passed', {
+        validRecords: validationResult.validRecords,
+        warnings: validationResult.warnings.length
+      });
+
+      // ========================================
+      // Stage 5: Fluent API Ingestion
+      // ========================================
+      await tracker.updateJob(jobId, {
+        stage: 'ingestion',
+        message: 'Creating Fluent batch job'
+      });
+
+      const client = await createClient({
+        connection: connections.fluent_commerce,
+        logger: log
+      });
+
+      const fluentJob = await client.createJob({
+        name: `Production Inventory Sync ${jobId}`,
+        retailerId: vars.FLUENT_RETAILER_ID,
+        meta: {
+          preprocessing: 'default', // Enable BPP
+          source: 's3-csv',
+          jobId
+        }
+      });
+
+      log.info('Fluent job created', { fluentJobId: fluentJob.id });
+
+      // ========================================
+      // Stage 6: Batch Processing with Recovery
+      // ========================================
+      await tracker.updateJob(jobId, {
+        stage: 'batch-processing',
+        message: `Sending ${mappedRecords.length} records`
+      });
+
+      const recoveryResult = await recovery.processBatchWithRecovery(
+        mappedRecords,
+        async (batch) => {
+          log.info('Sending batch', { batchSize: batch.length });
+
+          return await client.sendBatch(fluentJob.id, {
+            action: 'UPSERT',
+            entityType: 'INVENTORY',
+            entities: batch
+          });
+        },
+        {
+          maxRetries: 5,
+          retryOnlyFailed: true,
+          retryDelayMs: 2000,
+          retryBatchSize: 100,
+          checkpointKey: jobId,
+          shouldRetry: (error, attemptCount) => {
+            // Don't retry validation errors
+            if (error.message.includes('validation')) {
+              return false;
+            }
+            // Max 5 attempts
+            return attemptCount <= 5;
+          }
+        }
+      );
+
+      log.info('Batch processing complete', {
+        successCount: recoveryResult.successCount,
+        failedCount: recoveryResult.failedCount,
+        checkpointId: recoveryResult.checkpointId
+      });
+
+      // ========================================
+      // Stage 7: Job Status Verification
+      // ========================================
+      await tracker.updateJob(jobId, {
+        stage: 'verification',
+        message: 'Verifying Fluent job status'
+      });
+
+      // Poll for completion
+      let attempts = 0;
+      const maxAttempts = 30;
+      let fluentStatus;
+
+      while (attempts < maxAttempts) {
+        fluentStatus = await client.getJobStatus(fluentJob.id);
+
+        if (fluentStatus.status === 'COMPLETED' || fluentStatus.status === 'FAILED') {
+          break;
+        }
+
+        await new Promise(resolve => setTimeout(resolve, 10000)); // Wait 10s
+        attempts++;
+      }
+
+      log.info('Fluent job status', {
+        status: fluentStatus.status,
+        errorSummary: fluentStatus.errorSummary
+      });
+
+      // ========================================
+      // Stage 8: Completion
+      // ========================================
+      const finalDetails = {
+        fluentJobId: fluentJob.id,
+        fluentJobStatus: fluentStatus.status,
+        sourceRecords: rawRecords.length,
+        mappedRecords: mappedRecords.length,
+        mappingErrors: mappingErrors.length,
+        validationResult: {
+          validRecords: validationResult.validRecords,
+          warnings: validationResult.warnings.length
+        },
+        recoveryResult: {
+          successCount: recoveryResult.successCount,
+          failedCount: recoveryResult.failedCount,
+          checkpointId: recoveryResult.checkpointId
+        },
+        fluentErrors: fluentStatus.errorSummary?.totalErrors || 0
+      };
+
+      if (recoveryResult.failedCount > 0 || (fluentStatus.errorSummary?.totalErrors || 0) > 0) {
+        await tracker.updateJob(jobId, {
+          status: 'completed',
+          stage: 'completed-with-errors',
+          message: `Completed with ${recoveryResult.failedCount} recovery errors, ${fluentStatus.errorSummary?.totalErrors || 0} Fluent errors`,
+          details: finalDetails
+        });
+      } else {
+        await tracker.markCompleted(jobId, finalDetails);
+      }
+
+      return {
+        success: true,
+        jobId,
+        ...finalDetails
+      };
+
+    } catch (error) {
+      await tracker.markFailed(jobId, error);
+      log.error('Production sync failed', error);
+      throw error;
+    }
+  });
+```
+
+---
+
+## Summary
+
+### Key Takeaways
+
+1. **Webhook Validation** - ALWAYS validate Fluent Commerce webhook signatures
+2. **Partial Batch Recovery** - Retry only failed records, not entire batch
+3. **Job Tracker** - Track async workflow progress in KV store
+4. **Preflight Validator** - Validate before API calls to save quota
+
+### Service Comparison
+
+| Service | Primary Benefit | When to Use | Complexity |
+|---------|----------------|-------------|------------|
+| **Webhook Validation** | Security | All webhook endpoints | Low |
+| **Partial Batch Recovery** | Reliability | Batch ingestion | Medium |
+| **Job Tracker** | Observability | Scheduled workflows | Low |
+| **Preflight Validator** | Cost savings | Large batch operations | Low |
+
+### Integration Checklist
+
+Production integration should include:
+
+- [ ] **Webhook Validation** - Verify all incoming webhooks
+- [ ] **Preflight Validator** - Validate before API submission
+- [ ] **Partial Batch Recovery** - Handle batch failures gracefully
+- [ ] **Job Tracker** - Track workflow lifecycle
+- [ ] **Structured Logging** - Log all stages with context
+- [ ] **Error Handling** - Catch and log all errors
+- [ ] **Monitoring** - Track metrics and job status
+
+---
+
+## Next Steps
+
+Continue your learning journey:
+
+- [Quick Reference](../integration-patterns-quick-reference.md) - All patterns at a glance
+- [Use Cases](../../../01-TEMPLATES/readme.md) - Complete production examples
+- [Error Handling](./integration-patterns-05-error-handling.md) - Comprehensive error patterns
+
+Or explore related guides:
+- [Auto-Pagination](../../../02-CORE-GUIDES/auto-pagination/auto-pagination-readme.md)
+- [Universal Mapping](../../../02-CORE-GUIDES/mapping/mapping-readme.md)
+- [Batch API Guide](../../../02-CORE-GUIDES/ingestion/modules/02-core-guides-ingestion-06-batch-api.md)
+
+---
+
+[← Back to Index](../integration-patterns-readme.md) | [Previous: Error Handling](./integration-patterns-05-error-handling.md)