@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/02-CORE-GUIDES/api-reference/modules/api-reference-05-services.md

@@ -1,1198 +1,1198 @@
-# Module 5: Services
-
-**Level:** Intermediate
-**Category:** Core Services
-
-## Overview
-
-The SDK provides a comprehensive set of services for data transformation, state management, extraction, webhook validation, logging, and S3 operations.
-
-## Table of Contents
-
-- [Universal Mapper](#universal-mapper)
-- [FluentBatchManager](#fluentbatchmanager)
-- [State Management Service](#state-management-service)
-- [Webhook Validation Service](#webhook-validation-service)
-- [Logging Utilities](#logging-utilities)
-- [S3Service](#s3service)
-- [S3PresignService](#s3presignservice)
-- [JobTracker](#jobtracker-new)
-- [PartialBatchRecovery](#partialbatchrecovery-new)
-- [PreflightValidator](#preflightvalidator-new)
-- [Versori Adapters](#versori-adapters-new)
-- [See Also](#see-also)
-
----
-
-## Universal Mapper
-
-Map and transform data between schemas using the universal `fields` configuration.
-
-```typescript
-import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-
-const mapper = new UniversalMapper({
-  version: '1.0',
-  description: 'Inventory ingestion',
-  fields: {
-    skuRef: { source: 'SKU', required: true },
-    locationRef: { source: 'LOCATION', required: true },
-    qty: { source: 'QTY', resolver: 'sdk.parseInt', required: true },
-    status: { source: 'status', resolver: 'sdk.uppercase' },
-  },
-});
-
-const result = await mapper.map(record);
-if (result.success) {
-  console.log(result.data);
-}
-```
-
-## FluentBatchManager
-
-Thin orchestration layer for Fluent Commerce job and batch operations. Wraps FluentClient with stateless methods for job creation, batch submission, and status polling.
-
-**Export Name:**
-- Use: `import { FluentBatchManager } from '@fluentcommerce/fc-connect-sdk';`
-
-```typescript
-import { FluentBatchManager } from '@fluentcommerce/fc-connect-sdk';
-
-const manager = new FluentBatchManager(fluentVersoriClient, logger);
-
-// Create a new job
-const job = await manager.createJob('Daily Inventory Sync', {
-  retailerId: '1',
-  description: 'Daily inventory synchronization',
-  maxBatchCount: 100,
-});
-
-// Submit a batch to the job
-await manager.submitBatch(job.id, {
-  action: 'UPSERT',
-  entityType: 'INVENTORY',
-  entities: inventoryRecords,
-});
-
-// Check job status
-const jobStatus = await manager.getJobStatus(job.id);
-console.log(`Job status: ${jobStatus.status}`);
-
-// Check specific batch status
-const batchStatus = await manager.getBatchStatus(job.id, batch.id);
-console.log(`Batch status: ${batchStatus.status}`);
-```
-
-**Constructor:**
-
-```typescript
-new FluentBatchManager(
-  client: FluentVersoriClient,  // Fluent Versori client
-  logger?: Logger               // Optional logger
-)
-```
-
-**Methods:**
-
-- `createJob(name: string, metadata?: any): Promise<FluentJobResponse>` - Create a new job with optional metadata
-- `submitBatch(jobId: string, batch: FluentBatchPayload): Promise<void>` - Submit a batch to a job
-- `getJobStatus(jobId: string): Promise<any>` - Get current job status
-- `getBatchStatus(jobId: string, batchId: string): Promise<any>` - Get specific batch status
-
-**Use Cases:**
-
-- Simple ingestion flows (createJob → sendBatch → pollStatus)
-- Direct job management without state tracking
-- Thin wrapper around FluentVersoriClient batch operations
-
-**Note:** For complex workflows with state management, compose SDK services manually with StateService.
-
-## State Management Service
-
-Track processing state and prevent duplicate operations.
-
-```typescript
-import { StateService, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
-// ✅ CORRECT: Access openKv from Versori context
-// import { openKv } from '@versori/run'; // ❌ WRONG - Not a direct export
-
-const logger = console;
-const stateService = new StateService(logger);
-// In Versori workflow handler:
-const { openKv } = ctx;
-const kv = new VersoriKVAdapter(openKv(':project:')); // Implements KVStore
-
-// Acquire/release distributed lock
-const acquired = await stateService.acquireLock('critical-section', kv, 15);
-try {
-  if (acquired) {
-    // Critical section
-  }
-} finally {
-  await stateService.releaseLock('critical-section', kv);
-}
-
-// Check if a file was processed (deduplication)
-const isProcessed = await stateService.isFileProcessed(kv as any, 'file.csv', 'inventory-sync');
-
-// Update sync state after processing
-await stateService.updateSyncState(
-  kv as any,
-  [
-    {
-      fileName: 'file.csv',
-      lastModified: new Date().toISOString(),
-      recordCount: 1000,
-    },
-  ],
-  'inventory-sync'
-);
-```
-
-**Methods:**
-
-- `acquireLock(lockName: string, kv: KVStore, timeoutMinutes?: number): Promise<boolean>`
-- `releaseLock(lockName: string, kv: KVStore): Promise<void>`
-- `getSyncState(kv: KVStore, workflowId?: string): Promise<SyncState>`
-- `updateSyncState(kv: KVStore, processedFiles: ProcessedFile[], workflowId?: string): Promise<void>`
-- `getDailyJob(kv: KVStore, workflowId: string): Promise<DailyJob | null>`
-- `setDailyJob(kv: KVStore, workflowId: string, jobId: string, expirationHours?: number): Promise<void>`
-- `isFileProcessed(kv: KVStore, fileName: string, workflowId?: string): Promise<boolean>`
-- `getMetrics(kv: KVStore, workflowId?: string): Promise<{ totalFiles: number; totalRecords: number; lastProcessedTime?: string; }>`
-- `clearState(kv: KVStore, workflowId: string): Promise<void>`
-
-## Webhook Validation Service
-
-> **Warning: IMPORTANT WEBHOOK VALIDATION NOTICE**
->
-> This service is **ONLY** for validating webhooks sent from **Fluent Commerce Rubix workflows**.
->
-> These methods will **NOT** work with:
->
-> - Generic HTTP webhooks
-> - Third-party service webhooks
-> - Custom webhook implementations
->
-> Only use this service if you are receiving webhooks directly from Fluent Commerce Rubix workflow executions.
-
-The service uses RSA public key cryptography for signature validation.
-
-```typescript
-import {
-  WebhookValidationService,
-  WebhookValidationFactory,
-  SignatureAlgorithm,
-} from '@fluentcommerce/fc-connect-sdk';
-
-// IMPORTANT: This validation is ONLY for webhooks from Fluent Commerce Rubix workflows
-const validator = new WebhookValidationService(
-  {
-    algorithm: SignatureAlgorithm.SHA512_WITH_RSA, // Recommended
-    strictValidation: true, // Enforce strict checks
-    maxTimestampAge: 300000, // 5 minutes (optional)
-  },
-  logger
-);
-
-// Get public key from environment or connector variables
-const publicKey = process.env.FLUENT_WEBHOOK_PUBLIC_KEY;
-
-// Validate Fluent Commerce Rubix webhook signature
-const result = await validator.validateWebhookSignature(
-  JSON.stringify(requestBody),
-  headers['fluent-signature'],
-  publicKey,
-  SignatureAlgorithm.SHA512_WITH_RSA
-);
-
-if (!result.isValid) {
-  throw new Error(`Validation failed: ${result.error}`);
-}
-```
-
-**Configuration Options:**
-
-```typescript
-interface WebhookValidationConfig {
-  algorithm?: SignatureAlgorithm; // Default: SHA512_WITH_RSA
-  strictValidation?: boolean; // Default: true
-  maxTimestampAge?: number; // Max age in ms (optional)
-}
-```
-
-**SignatureAlgorithm Enum:**
-
-```typescript
-enum SignatureAlgorithm {
-  SHA512_WITH_RSA = 'SHA512withRSA',
-  MD5_WITH_RSA = 'MD5withRSA',
-}
-```
-
-**Methods:**
-
-- `validateWebhookSignature(payload: string, signature: string, publicKey: string, algorithm?: SignatureAlgorithm): Promise<ValidationResult>` - Validate Fluent Rubix webhook signature
-- `validateSignature(payload: string, signature: string, publicKey: string): Promise<boolean>` - Simple signature validation
-- `verifyTimestamp(timestamp: string | number): boolean` - Verify timestamp freshness
-
-**ValidationResult Interface:**
-
-```typescript
-interface ValidationResult {
-  isValid: boolean;
-  error?: string;
-  details?: {
-    signatureValid?: boolean;
-    timestampValid?: boolean;
-    algorithm?: string;
-  };
-}
-```
-
-**Factory Pattern:**
-
-```typescript
-// Use factory for creating validators with different configs
-const factory = new WebhookValidationFactory();
-
-// Create validator for SHA512 (for Fluent Commerce Rubix workflows)
-const sha512Validator = factory.createValidator(SignatureAlgorithm.SHA512_WITH_RSA, logger);
-
-// Create validator for MD5 (for Flex workflows)
-const md5Validator = factory.createValidator(SignatureAlgorithm.MD5_WITH_RSA, logger);
-```
-
-**Public Key Format:**
-The public key should be in PEM format. You can obtain this from:
-
-- Fluent Commerce support team
-- Your Fluent Commerce dashboard (if available)
-- Different retailers may have different public keys
-
-```bash
-# Example public key format in .env file
-FLUENT_WEBHOOK_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----
-MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
-...
------END PUBLIC KEY-----"
-```
-
-**Complete Example:**
-
-```typescript
-import {
-  WebhookValidationService,
-  SignatureAlgorithm,
-  parseWebhookRequest,
-  validateFluentEvent,
-  createConsoleLogger,
-  toStructuredLogger,
-} from '@fluentcommerce/fc-connect-sdk';
-
-const logger = toStructuredLogger(createConsoleLogger(), {
-  logLevel: 'info',
-});
-
-// IMPORTANT: This validation is ONLY for webhooks from Fluent Commerce Rubix workflows
-const validator = new WebhookValidationService(
-  {
-    algorithm: SignatureAlgorithm.SHA512_WITH_RSA,
-    strictValidation: true,
-  },
-  logger
-);
-
-export async function handleFluentWebhook(req, res) {
-  try {
-    // Extract signature from headers
-    const signature = req.headers['fluent-signature'] || req.headers['x-fluent-signature'];
-
-    if (!signature) {
-      return res.status(401).json({ error: 'Missing signature' });
-    }
-
-    // Get public key from environment
-    const publicKey = process.env.FLUENT_WEBHOOK_PUBLIC_KEY;
-
-    // Validate Fluent Commerce Rubix webhook
-    const validationResult = await validator.validateWebhookSignature(
-      JSON.stringify(req.body),
-      signature,
-      publicKey,
-      SignatureAlgorithm.SHA512_WITH_RSA
-    );
-
-    if (!validationResult.isValid) {
-      logger.error('Fluent Commerce Rubix webhook validation failed', validationResult);
-      return res.status(401).json({
-        error: 'Invalid Fluent Rubix webhook signature',
-        details: validationResult.error,
-      });
-    }
-
-    // Parse and validate payload
-    const payload = parseWebhookRequest(req.body, logger, 'webhook');
-    const validation = validateFluentEvent(payload, logger, 'webhook');
-
-    if (!validation.isValid) {
-      return res.status(400).json({
-        error: 'Invalid payload',
-        warnings: validation.warnings,
-      });
-    }
-
-    // Process webhook
-    await processWebhookPayload(payload);
-
-    return res.status(200).json({ success: true });
-  } catch (error) {
-    logger.error('Webhook processing failed', { error: error.message });
-    return res.status(500).json({ error: 'Internal server error' });
-  }
-}
-```
-
-## Logging Utilities
-
-The SDK provides minimal logging utilities for standalone environments. **Versori users should always use native platform logs.**
-
-**Historical Note:** The `LoggingService` class (684 lines) was refactored to function-based utilities (~390 lines) for better composability.
-
-### Platform-Specific Guidance
-
-| Runtime | Use | Example |
-|---------|-----|---------|
-| **Versori Platform** | Native `log` from context | `const { log } = ctx;` |
-| **Standalone Node.js** | Function-based utilities | `createConsoleLogger()` + `toStructuredLogger()` |
-| **Standalone Deno** | Function-based utilities | Same as Node.js |
-| **Other Platforms** | Implement `Logger` interface | Custom adapter |
-
-**✅ Versori Platform (Recommended - Use Native Log):**
-
-Always use native `log` from context - don't wrap it:
-
-```typescript
-import { schedule, http } from '@versori/run';
-import { createClient, SftpDataSource } from '@fluentcommerce/fc-connect-sdk';
-
-export const myWorkflow = schedule('my-workflow', '0 * * * *')
-  .then(http('process', { connection: 'fluent' }, async (ctx) => {
-    const { log } = ctx; // Only extract what you need
-
-    // ✅ Pass native log directly to SDK services
-    const client = await createClient(ctx); // Auto-detects Versori context
-    const sftp = new SftpDataSource(config, log);
-
-    log.info('Processing started');
-    log.error('Failed to process', { error: err.message });
-  }));
-```
-
-**✅ Standalone Node.js/Deno (Use Minimal Utilities):**
-
-```typescript
-import {
-  FluentClient,
-  createConsoleLogger,
-  toStructuredLogger,
-  SftpDataSource,
-} from '@fluentcommerce/fc-connect-sdk';
-
-// Simple console logger
-const logger = createConsoleLogger();
-
-// Or with context
-const contextLogger = toStructuredLogger(logger, {
-  service: 'InventorySync',
-  logLevel: 'debug',
-});
-
-const client = await createClient({
-  config: config,
-  logger: contextLogger,
-});
-const sftp = new SftpDataSource(config, contextLogger);
-
-contextLogger.info('Processing started', { file: 'data.csv' });
-```
-
-### Core Functions
-
-**Logger Creation:**
-
-- `createConsoleLogger(): Logger` - Create basic console logger for standalone use
-- `toStructuredLogger(logger: Logger, context: LogContext): Logger` - Add context metadata to logger
-- `generateCorrelationId(): string` - Generate unique correlation ID for request tracking
-
-**Convenience Functions:**
-
-- `createWorkflowLogger(baseLogger: Logger, workflowName: string, debugMode?: boolean): Logger` - Pre-configured workflow logger with correlationId
-- `createServiceLogger(baseLogger: Logger, serviceName: string, debugMode?: boolean): Logger` - Pre-configured service logger
-- `createErrorLogger(baseLogger: Logger, error: Error, context?: Record<string, any>): Logger` - Error-specific logger with context
-
-### Logger Interface
-
-All logging utilities implement the `Logger` interface:
-
-```typescript
-interface Logger {
-  debug(message: string, meta?: Record<string, any>): void;
-  info(message: string, meta?: Record<string, any>): void;
-  warn(message: string, meta?: Record<string, any>): void;
-  error(message: string, err?: Error | unknown, meta?: Record<string, any>): void;
-}
-```
-
-### Quick Decision Guide
-
-| Runtime                | Use                                              | Reason                         |
-| ---------------------- | ------------------------------------------------ | ------------------------------ |
-| **Versori Platform**   | Native `log` from context                        | Platform provides logging      |
-| **Standalone Node.js** | `createConsoleLogger()` + `toStructuredLogger()` | Lightweight structured logging |
-| **Standalone Deno**    | `createConsoleLogger()` + `toStructuredLogger()` | Lightweight structured logging |
-| **Vercel/CF/Other**    | Implement `Logger` interface                     | Easy extensibility             |
-
-### Migration from LoggingService
-
-If you have existing code using `LoggingService`, update it as follows:
-
-```typescript
-// ❌ OLD (LoggingService class - removed)
-import { LoggingService } from '@fluentcommerce/fc-connect-sdk';
-const logger = new LoggingService({ service: 'MyService', debug: true });
-
-// ✅ NEW (function-based utilities)
-import {
-  createConsoleLogger,
-  createServiceLogger,
-} from '@fluentcommerce/fc-connect-sdk';
-const logger = createServiceLogger(createConsoleLogger(), 'MyService', true);
-```
-
-**See:** [Logging Guide](../../logging-guide.md) for complete documentation
-
-## S3Service
-
-High-performance S3 service for file operations with support for both SDK and presigned URL approaches.
-
-### Constructor
-
-```typescript
-import { S3Service } from '@fluentcommerce/fc-connect-sdk';
-
-// Default - uses AWS SDK
-const s3Service = new S3Service({
-  accessKeyId: 'your-access-key',
-  secretAccessKey: 'your-secret-key',
-  region: 'us-east-1',
-  sessionToken: 'optional-session-token', // Optional
-  bucket: 'my-bucket', // Optional default bucket
-  endpoint: 'https://s3.amazonaws.com', // Optional custom endpoint
-  forcePathStyle: false, // Optional path style
-});
-
-// Explicit presigned (for Versori with ctx.fetch)
-const s3ServicePresigned = new S3Service({
-  accessKeyId: 'your-access-key',
-  secretAccessKey: 'your-secret-key',
-  region: 'us-east-1',
-  usePresigned: true, // Enable presigned URL mode
-  fetch: ctx.fetch, // Required when usePresigned is true
-});
-```
-
-### listObjects Method
-
-List objects in an S3 bucket.
-
-```typescript
-const objects = await s3Service.listObjects(
-  bucket: string,
-  options?: ListOptions
-): Promise<S3Object[]>
-```
-
-**ListOptions:**
-
-```typescript
-interface ListOptions {
-  prefix?: string; // Filter by prefix
-  delimiter?: string; // Delimiter for grouping
-  maxKeys?: number; // Maximum objects to return
-  continuationToken?: string; // Pagination token
-  startAfter?: string; // Start after specific key
-}
-```
-
-**Example:**
-
-```typescript
-const objects = await s3Service.listObjects('my-bucket', {
-  prefix: 'inventory/2024/',
-  maxKeys: 1000,
-});
-
-objects.forEach(obj => {
-  console.log(`${obj.key}: ${obj.size} bytes, modified ${obj.lastModified}`);
-});
-```
-
-### getObject Method
-
-Retrieve an object from S3.
-
-```typescript
-const data = await s3Service.getObject(
-  bucket: string,
-  key: string,
-  options?: GetOptions
-): Promise<Buffer | string>
-```
-
-**Example:**
-
-```typescript
-const csvData = await s3Service.getObject('my-bucket', 'inventory/data.csv');
-const content = csvData.toString('utf-8');
-```
-
-### putObject Method
-
-Upload an object to S3.
-
-```typescript
-await s3Service.putObject(
-  bucket: string,
-  key: string,
-  body: Buffer | string | Uint8Array,
-  options?: PutOptions
-): Promise<void>
-```
-
-**PutOptions:**
-
-```typescript
-interface PutOptions {
-  contentType?: string;
-  contentEncoding?: string;
-  metadata?: Record<string, string>;
-  storageClass?: 'STANDARD' | 'REDUCED_REDUNDANCY' | 'GLACIER' | 'DEEP_ARCHIVE';
-  serverSideEncryption?: string;
-  tagging?: string;
-}
-```
-
-**Example:**
-
-```typescript
-await s3Service.putObject('my-bucket', 'results/output.json', JSON.stringify(data), {
-  contentType: 'application/json',
-  metadata: {
-    'processed-date': new Date().toISOString(),
-    'record-count': '1000',
-  },
-});
-```
-
-### deleteObject Method
-
-Delete an object from S3.
-
-```typescript
-await s3Service.deleteObject(
-  bucket: string,
-  key: string
-): Promise<void>
-```
-
-### copyObject Method
-
-Copy an object within S3.
-
-```typescript
-await s3Service.copyObject(
-  sourceBucket: string,
-  sourceKey: string,
-  destBucket: string,
-  destKey: string,
-  options?: CopyOptions
-): Promise<void>
-```
-
-**Example:**
-
-```typescript
-// Archive processed file
-await s3Service.copyObject(
-  'inventory-incoming',
-  'data/file.csv',
-  'inventory-archive',
-  `processed/${new Date().toISOString()}/file.csv`
-);
-```
-
-### headObject Method
-
-Get object metadata without downloading content.
-
-```typescript
-const metadata = await s3Service.headObject(
-  bucket: string,
-  key: string
-): Promise<S3Object>
-```
-
-### getPresignedUrl Method
-
-Generate presigned URLs for temporary access.
-
-```typescript
-const url = await s3Service.getPresignedUrl(
-  bucket: string,
-  key: string,
-  operation?: 'get' | 'put',  // Default: 'get'
-  expiresIn?: number          // Seconds, default 3600
-): Promise<string>
-```
-
-**Example:**
-
-```typescript
-// Generate download URL valid for 1 hour
-const downloadUrl = await s3Service.getPresignedUrl(
-  'my-bucket',
-  'reports/summary.pdf',
-  'get',
-  3600
-);
-
-// Generate upload URL valid for 10 minutes
-const uploadUrl = await s3Service.getPresignedUrl('my-bucket', 'uploads/new-file.csv', 'put', 600);
-```
-
-### S3ServiceError
-
-Custom error class for S3 operations.
-
-```typescript
-try {
-  await s3Service.getObject('bucket', 'key');
-} catch (error) {
-  if (error instanceof S3ServiceError) {
-    console.error(`S3 Error: ${error.message}`);
-    console.error(`Code: ${error.code}`);
-    console.error(`Status: ${error.statusCode}`);
-    console.error(`Request ID: ${error.requestId}`);
-  }
-}
-```
-
-## S3PresignService
-
-AWS S3 Presigned URL Service that generates presigned URLs for S3 operations using AWS Signature Version 4.
-
-```typescript
-import { S3PresignService } from '@fluentcommerce/fc-connect-sdk';
-
-const presignService = new S3PresignService(
-  {
-    accessKeyId: 'your-access-key',
-    secretAccessKey: 'your-secret-key',
-    region: 'us-east-1',
-    bucket: 'my-bucket', // Optional default bucket
-    sessionToken: 'xxx', // Optional session token
-  },
-  logger
-);
-
-// Generate presigned URL for getting an object
-const getUrl = presignService.presignGetObject({
-  bucket: 'my-bucket',
-  key: 'data/file.csv',
-  accessKeyId: 'xxx',
-  secretAccessKey: 'yyy',
-  region: 'us-east-1',
-  expiresIn: 3600, // Optional, defaults to 3600 seconds (1 hour)
-});
-
-// Generate presigned URL for putting an object
-const { url, headers } = presignService.presignPutObject({
-  bucket: 'my-bucket',
-  key: 'uploads/new-file.csv',
-  accessKeyId: 'xxx',
-  secretAccessKey: 'yyy',
-  region: 'us-east-1',
-  expiresIn: 600, // 10 minutes
-});
-
-// Generate presigned URL for copying an object
-const { url: copyUrl, headers: copyHeaders } = presignService.presignCopyObject({
-  sourceBucket: 'source-bucket',
-  sourceKey: 'path/to/source.csv',
-  bucket: 'dest-bucket',
-  key: 'path/to/dest.csv',
-  accessKeyId: 'xxx',
-  secretAccessKey: 'yyy',
-  region: 'us-east-1',
-  metadata: { 'custom-header': 'value' }, // Optional metadata
-});
-
-// Generate presigned URL for deleting an object
-const deleteUrl = presignService.presignDeleteObject({
-  bucket: 'my-bucket',
-  key: 'file-to-delete.csv',
-  accessKeyId: 'xxx',
-  secretAccessKey: 'yyy',
-  region: 'us-east-1',
-});
-
-// Generate presigned URL for listing objects
-const listUrl = presignService.presignListObjects({
-  bucket: 'my-bucket',
-  prefix: 'data/', // Optional prefix filter
-  delimiter: '/', // Optional delimiter
-  maxKeys: 1000, // Optional max keys
-  accessKeyId: 'xxx',
-  secretAccessKey: 'yyy',
-  region: 'us-east-1',
-  expiresIn: 3600,
-});
-```
-
-**Constructor:**
-
-```typescript
-new S3PresignService(
-  config: S3Config,            // S3 configuration
-  logger?: StructuredLogger    // Optional logger
-)
-```
-
-**Methods:**
-
-- `presignListObjects(params: PresignListParams): string` - Generate presigned URL for listing objects
-- `presignGetObject(params: PresignObjectParams): string` - Generate presigned URL for getting an object
-- `presignPutObject(params: PresignObjectParams): { url: string; headers: Record<string, string> }` - Generate presigned URL and headers for putting an object
-- `presignCopyObject(params: PresignCopyParams): { url: string; headers: Record<string, string> }` - Generate presigned URL and headers for copying an object
-- `presignDeleteObject(params: PresignDeleteParams): string` - Generate presigned URL for deleting an object
-- `updateConfig(config: Partial<S3Config>): void` - Update S3 configuration
-- `getConfigSummary(): Omit<S3Config, 'secretAccessKey' | 'sessionToken'>` - Get current configuration (without secrets)
-- `validateConfig(): { isValid: boolean; errors: string[] }` - Validate S3 configuration
-
-**Parameter Types:**
-
-```typescript
-interface PresignObjectParams {
-  bucket: string;
-  key: string;
-  accessKeyId: string;
-  secretAccessKey: string;
-  region: string;
-  sessionToken?: string;
-  expiresIn?: number; // Seconds, default 3600
-}
-
-interface PresignListParams {
-  bucket: string;
-  prefix?: string;
-  delimiter?: string;
-  maxKeys?: number;
-  accessKeyId: string;
-  secretAccessKey: string;
-  region: string;
-  sessionToken?: string;
-  expiresIn?: number;
-}
-
-interface PresignCopyParams {
-  sourceBucket?: string; // Defaults to bucket if not specified
-  sourceKey: string;
-  bucket: string;
-  key: string;
-  accessKeyId: string;
-  secretAccessKey: string;
-  region: string;
-  sessionToken?: string;
-  metadata?: Record<string, string>;
-  expiresIn?: number;
-}
-
-interface PresignDeleteParams {
-  bucket: string;
-  key: string;
-  accessKeyId: string;
-  secretAccessKey: string;
-  region: string;
-  sessionToken?: string;
-  expiresIn?: number;
-}
-```
-
-## JobTracker (NEW)
-
-Track job lifecycle and metrics in a KV store. Provides standardized job status tracking for async workflows with automatic timestamp management and TTL support.
-
-```typescript
-import { JobTracker } from '@fluentcommerce/fc-connect-sdk';
-import { 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,
-  604800 // Optional TTL in seconds (default: 7 days)
-);
-
-// Create a new job
-await tracker.createJob('scheduled_1729681200000', {
-  triggeredBy: 'schedule',
-  stage: 'initialization',
-  details: { catalogueRef: 'DEFAULT:1' },
-});
-
-// Update job status
-await tracker.updateJob('scheduled_1729681200000', {
-  status: 'processing',
-  stage: 'extraction',
-  message: 'Extracting 1000 records',
-  details: { recordCount: 1000 },
-});
-
-// Mark as completed
-await tracker.markCompleted('scheduled_1729681200000', {
-  recordCount: 1000,
-  fileName: 'export.xml',
-  sftpPath: '/uploads/export.xml',
-});
-
-// Mark as failed (in catch block)
-try {
-  // ... job logic ...
-} catch (error) {
-  await tracker.markFailed('scheduled_1729681200000', error);
-}
-
-// Get job status
-const jobStatus = await tracker.getJob('scheduled_1729681200000');
-console.log(jobStatus);
-// {
-//   status: 'completed',
-//   stage: 'finished',
-//   message: 'Job completed successfully',
-//   createdAt: '2025-01-24T10:00:00.000Z',
-//   startedAt: '2025-01-24T10:00:05.000Z',
-//   completedAt: '2025-01-24T10:05:30.000Z',
-//   triggeredBy: 'schedule',
-//   details: { recordCount: 1000, fileName: 'export.xml', ... }
-// }
-```
-
-**Constructor:**
-
-```typescript
-new JobTracker(
-  kv: KVAdapter,                // KV adapter (VersoriKVAdapter or custom)
-  logger: StructuredLogger,     // Logger instance
-  ttl?: number                  // Optional TTL in seconds (default: 604800 = 7 days)
-)
-```
-
-**Methods:**
-
-- `createJob(jobId: string, metadata: Partial<Omit<JobStatus, 'status' | 'createdAt'>>): Promise<void>` - Create a new job with 'queued' status
-- `updateJob(jobId: string, update: Partial<JobStatus>): Promise<void>` - Update job status (auto-updates timestamps)
-- `getJob(jobId: string): Promise<JobStatus | undefined>` - Retrieve job status
-- `markCompleted(jobId: string, details?: Record<string, any>): Promise<void>` - Mark job as completed
-- `markFailed(jobId: string, error: Error | string): Promise<void>` - Mark job as failed
-
-**JobStatus Interface:**
-
-```typescript
-interface JobStatus {
-  status: 'queued' | 'processing' | 'completed' | 'failed';
-  stage?: string;
-  message?: string;
-  createdAt?: string;
-  startedAt?: string;
-  completedAt?: string;
-  failedAt?: string;
-  triggeredBy: 'schedule' | 'webhook' | 'manual';
-  details?: Record<string, any>;
-  error?: string;
-  errorStack?: string;
-}
-```
-
-**Key Features:**
-
-- Standardized job status tracking
-- Automatic timestamp management (createdAt, startedAt, completedAt, failedAt)
-- TTL support for automatic cleanup
-- Safe error handling (never throws on KV errors)
-- Detailed logging
-
-## PartialBatchRecovery (NEW)
-
-Tracks per-record success/failure in batch operations and enables retrying only failed records instead of entire batches. Provides checkpoint/resume functionality and detailed error reporting.
-
-```typescript
-import { PartialBatchRecovery } from '@fluentcommerce/fc-connect-sdk';
-
-const recovery = new PartialBatchRecovery<InventoryRecord>(logger);
-
-// Process batch with automatic recovery and retry
-const result = await recovery.processBatchWithRecovery(
-  records,
-  async batch =>
-    await client.sendBatch(jobId, {
-      action: 'UPSERT',
-      entityType: 'INVENTORY',
-      entities: batch,
-    }),
-  {
-    maxRetries: 3,
-    retryOnlyFailed: true,
-    retryBatchSize: 100,
-    checkpointKey: 'inventory-2025-01-24',
-    retryDelayMs: 1000,
-    shouldRetry: (error, attemptCount) => {
-      // Custom retry logic
-      return attemptCount <= 3 && !error.message.includes('permanent');
-    },
-  }
-);
-
-console.log(`Success: ${result.successCount}, Failed: ${result.failedCount}`);
-console.log(`Duration: ${result.durationMs}ms`);
-console.log(result.summary);
-
-if (result.failedRecords.length > 0) {
-  console.log('Failed records:', result.failedRecords);
-
-  // Export failed records for manual review
-  const failures = result.failedRecords.map(f => ({
-    index: f.index,
-    record: f.record,
-    error: f.error.message,
-    attempts: f.attemptCount,
-  }));
-}
-
-// Resume from checkpoint later
-if (result.checkpointId) {
-  const resumeResult = await recovery.resumeFromCheckpoint(
-    result.checkpointId,
-    async batch =>
-      await client.sendBatch(jobId, {
-        action: 'UPSERT',
-        entityType: 'INVENTORY',
-        entities: batch,
-      })
-  );
-}
-```
-
-**Constructor:**
-
-```typescript
-new PartialBatchRecovery<T = any>(
-  logger?: StructuredLogger  // Optional logger
-)
-```
-
-**Methods:**
-
-- `processBatchWithRecovery(records: T[], batchProcessor: (records: T[]) => Promise<any>, options?: BatchRecoveryOptions): Promise<BatchRecoveryResult<T>>` - Process batch with automatic recovery and retry
-- `resumeFromCheckpoint(checkpointId: string, batchProcessor: (records: T[]) => Promise<any>, options?: BatchRecoveryOptions): Promise<BatchRecoveryResult<T>>` - Resume processing from a saved checkpoint
-- `getCheckpoint(checkpointId: string): BatchCheckpoint<T> | undefined` - Get checkpoint by ID
-- `listCheckpoints(): BatchCheckpoint<T>[]` - List all checkpoints
-- `deleteCheckpoint(checkpointId: string): boolean` - Delete a checkpoint
-- `clearCheckpoints(): void` - Clear all checkpoints
-
-**BatchRecoveryOptions:**
-
-```typescript
-interface BatchRecoveryOptions {
-  maxRetries?: number; // Max retry attempts per record (default: 3)
-  retryOnlyFailed?: boolean; // Retry only failed records (default: true)
-  checkpointKey?: string; // Checkpoint key for resume
-  retryDelayMs?: number; // Delay between retries in ms (default: 1000)
-  shouldRetry?: (error: Error, attemptCount: number) => boolean; // Custom retry predicate
-  retryBatchSize?: number; // Batch size for retries (default: 100)
-}
-```
-
-**BatchRecoveryResult:**
-
-```typescript
-interface BatchRecoveryResult<T = any> {
-  totalRecords: number; // Total records processed
-  successCount: number; // Successfully processed records
-  failedCount: number; // Failed records after all retries
-  failedRecords: RecordFailure<T>[]; // Details of failed records
-  checkpointId?: string; // Checkpoint ID for resuming
-  summary: string; // Processing summary
-  durationMs: number; // Total time taken
-}
-
-interface RecordFailure<T = any> {
-  index: number; // Original record index
-  record: T; // The record that failed
-  error: Error; // Error that occurred
-  attemptCount: number; // Number of retry attempts
-  timestamp: string; // Timestamp of failure
-}
-```
-
-**Key Features:**
-
-- Per-record retry logic (avoids reprocessing successful records)
-- Exponential backoff for retries
-- Checkpoint/resume functionality
-- Detailed failure tracking with attempt counts
-- Custom retry predicates
-- Configurable batch sizes for retries
-
-## PreflightValidator (NEW)
-
-Validates data BEFORE sending to Fluent API to catch errors early, save API quota, validate against GraphQL schema requirements, and check for data quality issues.
-
-```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'],
-  checkDuplicates: true,
-  maxBatchSize: 1000,
-  validateTypes: true,
-  customValidator: (record, index) => {
-    if (record.qty < 0) {
-      return `Record ${index}: qty must be non-negative`;
-    }
-    return null;
-  },
-});
-
-if (!result.isValid) {
-  console.error(`Validation failed: ${result.errors.length} errors`);
-  result.errors.forEach(err => {
-    console.error(`[Record ${err.index}] ${err.field}: ${err.message}`);
-  });
-  throw new Error('Batch validation failed');
-}
-
-console.log(result.summary);
-// "Validation passed: 1000/1000 records valid"
-
-// Quick validation - returns first error only (faster)
-const quickResult = await validator.validateQuick(records, {
-  entityType: 'INVENTORY',
-  requiredFields: ['ref', 'qty'],
-  maxBatchSize: 1000,
-});
-
-if (!quickResult.isValid) {
-  console.error(`Quick validation failed: ${quickResult.error}`);
-}
-```
-
-**Constructor:**
-
-```typescript
-new PreflightValidator(
-  logger?: StructuredLogger  // Optional logger
-)
-```
-
-**Methods:**
-
-- `validateBatch(records: any[], options: PreflightValidationOptions): Promise<PreflightValidationResult>` - Validate entire batch with detailed error reporting
-- `validateQuick(records: any[], options: PreflightValidationOptions): Promise<{ isValid: boolean; error?: string }>` - Quick validation that returns first error only (faster for fail-fast scenarios)
-
-**PreflightValidationOptions:**
-
-```typescript
-interface PreflightValidationOptions {
-  entityType: 'INVENTORY' | 'CONTROL' | 'LOCATION' | 'ARTICLE' | string;
-  requiredFields?: string[]; // Fields that must be present
-  checkDuplicates?: boolean; // Check for duplicate refs
-  maxBatchSize?: number; // Maximum batch size
-  validateTypes?: boolean; // Validate field types
-  customValidator?: (record: any, index: number) => string | null; // Custom validation function
-}
-```
-
-**PreflightValidationResult:**
-
-```typescript
-interface PreflightValidationResult {
-  isValid: boolean; // Whether validation passed
-  totalRecords: number; // Total records validated
-  validRecords: number; // Number of valid records
-  errors: PreflightValidationError[]; // All validation errors
-  warnings: PreflightValidationError[]; // All validation warnings
-  summary: string; // Summary message
-  duplicates?: string[]; // Duplicate refs found (if checkDuplicates enabled)
-}
-
-interface PreflightValidationError {
-  index: number; // Record index where error occurred
-  field?: string; // Field that failed validation
-  message: string; // Error message
-  severity: 'error' | 'warning'; // Error severity
-  value?: any; // The problematic value
-}
-```
-
-**Key Features:**
-
-- Catches errors early (saves API quota)
-- Validates against GraphQL schema requirements
-- Checks for duplicates and data quality issues
-- Provides actionable error messages
-- Type validation for common fields (qty, ref, etc.)
-- Custom validation functions
-- Fast "quick validation" mode for fail-fast scenarios
-
-## Versori Adapters (NEW)
-
-Helpers for Versori platform integrations.
-
-```typescript
-import { VersoriKVAdapter, VersoriFileTracker } 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 kv = new VersoriKVAdapter(openKv(':project:'));
-await kv.set('processed:file1', { at: Date.now() }, 3600);
-
-// File tracker to dedupe processed files
-const fileTracker = new VersoriFileTracker(openKv(':project:'), 'my-workflow');
-const already = await fileTracker.wasFileProcessed('incoming/products_20250101.xml');
-if (!already) {
-  await fileTracker.markFileProcessed('incoming/products_20250101.xml', { size: 2048 });
-}
-```
-
-## See Also
-
-- [Ingestion Guide](../../ingestion/ingestion-readme.md) - Complete ingestion workflows
-- [Extraction Guide](../../extraction/extraction-readme.md) - Data extraction patterns
-- [Module 3: Authentication](./api-reference-03-authentication.md) - OAuth2 and auth providers
-- [Module 6: Data Sources](./api-reference-06-data-sources.md) - S3 and SFTP data sources
-- [Module 9: Error Handling](./api-reference-09-error-handling.md) - Error types and handling
-- [Module 8: Types](./api-reference-08-types.md) - Service-related types
-
----
-
-**[← Previous: GraphQL Mapping](./api-reference-04-graphql-mapping.md)** | **[API Reference Home](../api-reference-readme.md)** | **[Next: Data Sources →](./api-reference-06-data-sources.md)**
+# Module 5: Services
+
+**Level:** Intermediate
+**Category:** Core Services
+
+## Overview
+
+The SDK provides a comprehensive set of services for data transformation, state management, extraction, webhook validation, logging, and S3 operations.
+
+## Table of Contents
+
+- [Universal Mapper](#universal-mapper)
+- [FluentBatchManager](#fluentbatchmanager)
+- [State Management Service](#state-management-service)
+- [Webhook Validation Service](#webhook-validation-service)
+- [Logging Utilities](#logging-utilities)
+- [S3Service](#s3service)
+- [S3PresignService](#s3presignservice)
+- [JobTracker](#jobtracker-new)
+- [PartialBatchRecovery](#partialbatchrecovery-new)
+- [PreflightValidator](#preflightvalidator-new)
+- [Versori Adapters](#versori-adapters-new)
+- [See Also](#see-also)
+
+---
+
+## Universal Mapper
+
+Map and transform data between schemas using the universal `fields` configuration.
+
+```typescript
+import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+
+const mapper = new UniversalMapper({
+  version: '1.0',
+  description: 'Inventory ingestion',
+  fields: {
+    skuRef: { source: 'SKU', required: true },
+    locationRef: { source: 'LOCATION', required: true },
+    qty: { source: 'QTY', resolver: 'sdk.parseInt', required: true },
+    status: { source: 'status', resolver: 'sdk.uppercase' },
+  },
+});
+
+const result = await mapper.map(record);
+if (result.success) {
+  console.log(result.data);
+}
+```
+
+## FluentBatchManager
+
+Thin orchestration layer for Fluent Commerce job and batch operations. Wraps FluentClient with stateless methods for job creation, batch submission, and status polling.
+
+**Export Name:**
+- Use: `import { FluentBatchManager } from '@fluentcommerce/fc-connect-sdk';`
+
+```typescript
+import { FluentBatchManager } from '@fluentcommerce/fc-connect-sdk';
+
+const manager = new FluentBatchManager(fluentVersoriClient, logger);
+
+// Create a new job
+const job = await manager.createJob('Daily Inventory Sync', {
+  retailerId: '1',
+  description: 'Daily inventory synchronization',
+  maxBatchCount: 100,
+});
+
+// Submit a batch to the job
+await manager.submitBatch(job.id, {
+  action: 'UPSERT',
+  entityType: 'INVENTORY',
+  entities: inventoryRecords,
+});
+
+// Check job status
+const jobStatus = await manager.getJobStatus(job.id);
+console.log(`Job status: ${jobStatus.status}`);
+
+// Check specific batch status
+const batchStatus = await manager.getBatchStatus(job.id, batch.id);
+console.log(`Batch status: ${batchStatus.status}`);
+```
+
+**Constructor:**
+
+```typescript
+new FluentBatchManager(
+  client: FluentVersoriClient,  // Fluent Versori client
+  logger?: Logger               // Optional logger
+)
+```
+
+**Methods:**
+
+- `createJob(name: string, metadata?: any): Promise<FluentJobResponse>` - Create a new job with optional metadata
+- `submitBatch(jobId: string, batch: FluentBatchPayload): Promise<void>` - Submit a batch to a job
+- `getJobStatus(jobId: string): Promise<any>` - Get current job status
+- `getBatchStatus(jobId: string, batchId: string): Promise<any>` - Get specific batch status
+
+**Use Cases:**
+
+- Simple ingestion flows (createJob → sendBatch → pollStatus)
+- Direct job management without state tracking
+- Thin wrapper around FluentVersoriClient batch operations
+
+**Note:** For complex workflows with state management, compose SDK services manually with StateService.
+
+## State Management Service
+
+Track processing state and prevent duplicate operations.
+
+```typescript
+import { StateService, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
+// ✅ CORRECT: Access openKv from Versori context
+// import { openKv } from '@versori/run'; // ❌ WRONG - Not a direct export
+
+const logger = console;
+const stateService = new StateService(logger);
+// In Versori workflow handler:
+const { openKv } = ctx;
+const kv = new VersoriKVAdapter(openKv(':project:')); // Implements KVStore
+
+// Acquire/release distributed lock
+const acquired = await stateService.acquireLock('critical-section', kv, 15);
+try {
+  if (acquired) {
+    // Critical section
+  }
+} finally {
+  await stateService.releaseLock('critical-section', kv);
+}
+
+// Check if a file was processed (deduplication)
+const isProcessed = await stateService.isFileProcessed(kv as any, 'file.csv', 'inventory-sync');
+
+// Update sync state after processing
+await stateService.updateSyncState(
+  kv as any,
+  [
+    {
+      fileName: 'file.csv',
+      lastModified: new Date().toISOString(),
+      recordCount: 1000,
+    },
+  ],
+  'inventory-sync'
+);
+```
+
+**Methods:**
+
+- `acquireLock(lockName: string, kv: KVStore, timeoutMinutes?: number): Promise<boolean>`
+- `releaseLock(lockName: string, kv: KVStore): Promise<void>`
+- `getSyncState(kv: KVStore, workflowId?: string): Promise<SyncState>`
+- `updateSyncState(kv: KVStore, processedFiles: ProcessedFile[], workflowId?: string): Promise<void>`
+- `getDailyJob(kv: KVStore, workflowId: string): Promise<DailyJob | null>`
+- `setDailyJob(kv: KVStore, workflowId: string, jobId: string, expirationHours?: number): Promise<void>`
+- `isFileProcessed(kv: KVStore, fileName: string, workflowId?: string): Promise<boolean>`
+- `getMetrics(kv: KVStore, workflowId?: string): Promise<{ totalFiles: number; totalRecords: number; lastProcessedTime?: string; }>`
+- `clearState(kv: KVStore, workflowId: string): Promise<void>`
+
+## Webhook Validation Service
+
+> **Warning: IMPORTANT WEBHOOK VALIDATION NOTICE**
+>
+> This service is **ONLY** for validating webhooks sent from **Fluent Commerce Rubix workflows**.
+>
+> These methods will **NOT** work with:
+>
+> - Generic HTTP webhooks
+> - Third-party service webhooks
+> - Custom webhook implementations
+>
+> Only use this service if you are receiving webhooks directly from Fluent Commerce Rubix workflow executions.
+
+The service uses RSA public key cryptography for signature validation.
+
+```typescript
+import {
+  WebhookValidationService,
+  WebhookValidationFactory,
+  SignatureAlgorithm,
+} from '@fluentcommerce/fc-connect-sdk';
+
+// IMPORTANT: This validation is ONLY for webhooks from Fluent Commerce Rubix workflows
+const validator = new WebhookValidationService(
+  {
+    algorithm: SignatureAlgorithm.SHA512_WITH_RSA, // Recommended
+    strictValidation: true, // Enforce strict checks
+    maxTimestampAge: 300000, // 5 minutes (optional)
+  },
+  logger
+);
+
+// Get public key from environment or connector variables
+const publicKey = process.env.FLUENT_WEBHOOK_PUBLIC_KEY;
+
+// Validate Fluent Commerce Rubix webhook signature
+const result = await validator.validateWebhookSignature(
+  JSON.stringify(requestBody),
+  headers['fluent-signature'],
+  publicKey,
+  SignatureAlgorithm.SHA512_WITH_RSA
+);
+
+if (!result.isValid) {
+  throw new Error(`Validation failed: ${result.error}`);
+}
+```
+
+**Configuration Options:**
+
+```typescript
+interface WebhookValidationConfig {
+  algorithm?: SignatureAlgorithm; // Default: SHA512_WITH_RSA
+  strictValidation?: boolean; // Default: true
+  maxTimestampAge?: number; // Max age in ms (optional)
+}
+```
+
+**SignatureAlgorithm Enum:**
+
+```typescript
+enum SignatureAlgorithm {
+  SHA512_WITH_RSA = 'SHA512withRSA',
+  MD5_WITH_RSA = 'MD5withRSA',
+}
+```
+
+**Methods:**
+
+- `validateWebhookSignature(payload: string, signature: string, publicKey: string, algorithm?: SignatureAlgorithm): Promise<ValidationResult>` - Validate Fluent Rubix webhook signature
+- `validateSignature(payload: string, signature: string, publicKey: string): Promise<boolean>` - Simple signature validation
+- `verifyTimestamp(timestamp: string | number): boolean` - Verify timestamp freshness
+
+**ValidationResult Interface:**
+
+```typescript
+interface ValidationResult {
+  isValid: boolean;
+  error?: string;
+  details?: {
+    signatureValid?: boolean;
+    timestampValid?: boolean;
+    algorithm?: string;
+  };
+}
+```
+
+**Factory Pattern:**
+
+```typescript
+// Use factory for creating validators with different configs
+const factory = new WebhookValidationFactory();
+
+// Create validator for SHA512 (for Fluent Commerce Rubix workflows)
+const sha512Validator = factory.createValidator(SignatureAlgorithm.SHA512_WITH_RSA, logger);
+
+// Create validator for MD5 (for Flex workflows)
+const md5Validator = factory.createValidator(SignatureAlgorithm.MD5_WITH_RSA, logger);
+```
+
+**Public Key Format:**
+The public key should be in PEM format. You can obtain this from:
+
+- Fluent Commerce support team
+- Your Fluent Commerce dashboard (if available)
+- Different retailers may have different public keys
+
+```bash
+# Example public key format in .env file
+FLUENT_WEBHOOK_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----
+MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
+...
+-----END PUBLIC KEY-----"
+```
+
+**Complete Example:**
+
+```typescript
+import {
+  WebhookValidationService,
+  SignatureAlgorithm,
+  parseWebhookRequest,
+  validateFluentEvent,
+  createConsoleLogger,
+  toStructuredLogger,
+} from '@fluentcommerce/fc-connect-sdk';
+
+const logger = toStructuredLogger(createConsoleLogger(), {
+  logLevel: 'info',
+});
+
+// IMPORTANT: This validation is ONLY for webhooks from Fluent Commerce Rubix workflows
+const validator = new WebhookValidationService(
+  {
+    algorithm: SignatureAlgorithm.SHA512_WITH_RSA,
+    strictValidation: true,
+  },
+  logger
+);
+
+export async function handleFluentWebhook(req, res) {
+  try {
+    // Extract signature from headers
+    const signature = req.headers['fluent-signature'] || req.headers['x-fluent-signature'];
+
+    if (!signature) {
+      return res.status(401).json({ error: 'Missing signature' });
+    }
+
+    // Get public key from environment
+    const publicKey = process.env.FLUENT_WEBHOOK_PUBLIC_KEY;
+
+    // Validate Fluent Commerce Rubix webhook
+    const validationResult = await validator.validateWebhookSignature(
+      JSON.stringify(req.body),
+      signature,
+      publicKey,
+      SignatureAlgorithm.SHA512_WITH_RSA
+    );
+
+    if (!validationResult.isValid) {
+      logger.error('Fluent Commerce Rubix webhook validation failed', validationResult);
+      return res.status(401).json({
+        error: 'Invalid Fluent Rubix webhook signature',
+        details: validationResult.error,
+      });
+    }
+
+    // Parse and validate payload
+    const payload = parseWebhookRequest(req.body, logger, 'webhook');
+    const validation = validateFluentEvent(payload, logger, 'webhook');
+
+    if (!validation.isValid) {
+      return res.status(400).json({
+        error: 'Invalid payload',
+        warnings: validation.warnings,
+      });
+    }
+
+    // Process webhook
+    await processWebhookPayload(payload);
+
+    return res.status(200).json({ success: true });
+  } catch (error) {
+    logger.error('Webhook processing failed', { error: error.message });
+    return res.status(500).json({ error: 'Internal server error' });
+  }
+}
+```
+
+## Logging Utilities
+
+The SDK provides minimal logging utilities for standalone environments. **Versori users should always use native platform logs.**
+
+**Historical Note:** The `LoggingService` class (684 lines) was refactored to function-based utilities (~390 lines) for better composability.
+
+### Platform-Specific Guidance
+
+| Runtime | Use | Example |
+|---------|-----|---------|
+| **Versori Platform** | Native `log` from context | `const { log } = ctx;` |
+| **Standalone Node.js** | Function-based utilities | `createConsoleLogger()` + `toStructuredLogger()` |
+| **Standalone Deno** | Function-based utilities | Same as Node.js |
+| **Other Platforms** | Implement `Logger` interface | Custom adapter |
+
+**✅ Versori Platform (Recommended - Use Native Log):**
+
+Always use native `log` from context - don't wrap it:
+
+```typescript
+import { schedule, http } from '@versori/run';
+import { createClient, SftpDataSource } from '@fluentcommerce/fc-connect-sdk';
+
+export const myWorkflow = schedule('my-workflow', '0 * * * *')
+  .then(http('process', { connection: 'fluent' }, async (ctx) => {
+    const { log } = ctx; // Only extract what you need
+
+    // ✅ Pass native log directly to SDK services
+    const client = await createClient(ctx); // Auto-detects Versori context
+    const sftp = new SftpDataSource(config, log);
+
+    log.info('Processing started');
+    log.error('Failed to process', { error: err.message });
+  }));
+```
+
+**✅ Standalone Node.js/Deno (Use Minimal Utilities):**
+
+```typescript
+import {
+  FluentClient,
+  createConsoleLogger,
+  toStructuredLogger,
+  SftpDataSource,
+} from '@fluentcommerce/fc-connect-sdk';
+
+// Simple console logger
+const logger = createConsoleLogger();
+
+// Or with context
+const contextLogger = toStructuredLogger(logger, {
+  service: 'InventorySync',
+  logLevel: 'debug',
+});
+
+const client = await createClient({
+  config: config,
+  logger: contextLogger,
+});
+const sftp = new SftpDataSource(config, contextLogger);
+
+contextLogger.info('Processing started', { file: 'data.csv' });
+```
+
+### Core Functions
+
+**Logger Creation:**
+
+- `createConsoleLogger(): Logger` - Create basic console logger for standalone use
+- `toStructuredLogger(logger: Logger, context: LogContext): Logger` - Add context metadata to logger
+- `generateCorrelationId(): string` - Generate unique correlation ID for request tracking
+
+**Convenience Functions:**
+
+- `createWorkflowLogger(baseLogger: Logger, workflowName: string, debugMode?: boolean): Logger` - Pre-configured workflow logger with correlationId
+- `createServiceLogger(baseLogger: Logger, serviceName: string, debugMode?: boolean): Logger` - Pre-configured service logger
+- `createErrorLogger(baseLogger: Logger, error: Error, context?: Record<string, any>): Logger` - Error-specific logger with context
+
+### Logger Interface
+
+All logging utilities implement the `Logger` interface:
+
+```typescript
+interface Logger {
+  debug(message: string, meta?: Record<string, any>): void;
+  info(message: string, meta?: Record<string, any>): void;
+  warn(message: string, meta?: Record<string, any>): void;
+  error(message: string, err?: Error | unknown, meta?: Record<string, any>): void;
+}
+```
+
+### Quick Decision Guide
+
+| Runtime                | Use                                              | Reason                         |
+| ---------------------- | ------------------------------------------------ | ------------------------------ |
+| **Versori Platform**   | Native `log` from context                        | Platform provides logging      |
+| **Standalone Node.js** | `createConsoleLogger()` + `toStructuredLogger()` | Lightweight structured logging |
+| **Standalone Deno**    | `createConsoleLogger()` + `toStructuredLogger()` | Lightweight structured logging |
+| **Vercel/CF/Other**    | Implement `Logger` interface                     | Easy extensibility             |
+
+### Migration from LoggingService
+
+If you have existing code using `LoggingService`, update it as follows:
+
+```typescript
+// ❌ OLD (LoggingService class - removed)
+import { LoggingService } from '@fluentcommerce/fc-connect-sdk';
+const logger = new LoggingService({ service: 'MyService', debug: true });
+
+// ✅ NEW (function-based utilities)
+import {
+  createConsoleLogger,
+  createServiceLogger,
+} from '@fluentcommerce/fc-connect-sdk';
+const logger = createServiceLogger(createConsoleLogger(), 'MyService', true);
+```
+
+**See:** [Logging Guide](../../logging-guide.md) for complete documentation
+
+## S3Service
+
+High-performance S3 service for file operations with support for both SDK and presigned URL approaches.
+
+### Constructor
+
+```typescript
+import { S3Service } from '@fluentcommerce/fc-connect-sdk';
+
+// Default - uses AWS SDK
+const s3Service = new S3Service({
+  accessKeyId: 'your-access-key',
+  secretAccessKey: 'your-secret-key',
+  region: 'us-east-1',
+  sessionToken: 'optional-session-token', // Optional
+  bucket: 'my-bucket', // Optional default bucket
+  endpoint: 'https://s3.amazonaws.com', // Optional custom endpoint
+  forcePathStyle: false, // Optional path style
+});
+
+// Explicit presigned (for Versori with ctx.fetch)
+const s3ServicePresigned = new S3Service({
+  accessKeyId: 'your-access-key',
+  secretAccessKey: 'your-secret-key',
+  region: 'us-east-1',
+  usePresigned: true, // Enable presigned URL mode
+  fetch: ctx.fetch, // Required when usePresigned is true
+});
+```
+
+### listObjects Method
+
+List objects in an S3 bucket.
+
+```typescript
+const objects = await s3Service.listObjects(
+  bucket: string,
+  options?: ListOptions
+): Promise<S3Object[]>
+```
+
+**ListOptions:**
+
+```typescript
+interface ListOptions {
+  prefix?: string; // Filter by prefix
+  delimiter?: string; // Delimiter for grouping
+  maxKeys?: number; // Maximum objects to return
+  continuationToken?: string; // Pagination token
+  startAfter?: string; // Start after specific key
+}
+```
+
+**Example:**
+
+```typescript
+const objects = await s3Service.listObjects('my-bucket', {
+  prefix: 'inventory/2024/',
+  maxKeys: 1000,
+});
+
+objects.forEach(obj => {
+  console.log(`${obj.key}: ${obj.size} bytes, modified ${obj.lastModified}`);
+});
+```
+
+### getObject Method
+
+Retrieve an object from S3.
+
+```typescript
+const data = await s3Service.getObject(
+  bucket: string,
+  key: string,
+  options?: GetOptions
+): Promise<Buffer | string>
+```
+
+**Example:**
+
+```typescript
+const csvData = await s3Service.getObject('my-bucket', 'inventory/data.csv');
+const content = csvData.toString('utf-8');
+```
+
+### putObject Method
+
+Upload an object to S3.
+
+```typescript
+await s3Service.putObject(
+  bucket: string,
+  key: string,
+  body: Buffer | string | Uint8Array,
+  options?: PutOptions
+): Promise<void>
+```
+
+**PutOptions:**
+
+```typescript
+interface PutOptions {
+  contentType?: string;
+  contentEncoding?: string;
+  metadata?: Record<string, string>;
+  storageClass?: 'STANDARD' | 'REDUCED_REDUNDANCY' | 'GLACIER' | 'DEEP_ARCHIVE';
+  serverSideEncryption?: string;
+  tagging?: string;
+}
+```
+
+**Example:**
+
+```typescript
+await s3Service.putObject('my-bucket', 'results/output.json', JSON.stringify(data), {
+  contentType: 'application/json',
+  metadata: {
+    'processed-date': new Date().toISOString(),
+    'record-count': '1000',
+  },
+});
+```
+
+### deleteObject Method
+
+Delete an object from S3.
+
+```typescript
+await s3Service.deleteObject(
+  bucket: string,
+  key: string
+): Promise<void>
+```
+
+### copyObject Method
+
+Copy an object within S3.
+
+```typescript
+await s3Service.copyObject(
+  sourceBucket: string,
+  sourceKey: string,
+  destBucket: string,
+  destKey: string,
+  options?: CopyOptions
+): Promise<void>
+```
+
+**Example:**
+
+```typescript
+// Archive processed file
+await s3Service.copyObject(
+  'inventory-incoming',
+  'data/file.csv',
+  'inventory-archive',
+  `processed/${new Date().toISOString()}/file.csv`
+);
+```
+
+### headObject Method
+
+Get object metadata without downloading content.
+
+```typescript
+const metadata = await s3Service.headObject(
+  bucket: string,
+  key: string
+): Promise<S3Object>
+```
+
+### getPresignedUrl Method
+
+Generate presigned URLs for temporary access.
+
+```typescript
+const url = await s3Service.getPresignedUrl(
+  bucket: string,
+  key: string,
+  operation?: 'get' | 'put',  // Default: 'get'
+  expiresIn?: number          // Seconds, default 3600
+): Promise<string>
+```
+
+**Example:**
+
+```typescript
+// Generate download URL valid for 1 hour
+const downloadUrl = await s3Service.getPresignedUrl(
+  'my-bucket',
+  'reports/summary.pdf',
+  'get',
+  3600
+);
+
+// Generate upload URL valid for 10 minutes
+const uploadUrl = await s3Service.getPresignedUrl('my-bucket', 'uploads/new-file.csv', 'put', 600);
+```
+
+### S3ServiceError
+
+Custom error class for S3 operations.
+
+```typescript
+try {
+  await s3Service.getObject('bucket', 'key');
+} catch (error) {
+  if (error instanceof S3ServiceError) {
+    console.error(`S3 Error: ${error.message}`);
+    console.error(`Code: ${error.code}`);
+    console.error(`Status: ${error.statusCode}`);
+    console.error(`Request ID: ${error.requestId}`);
+  }
+}
+```
+
+## S3PresignService
+
+AWS S3 Presigned URL Service that generates presigned URLs for S3 operations using AWS Signature Version 4.
+
+```typescript
+import { S3PresignService } from '@fluentcommerce/fc-connect-sdk';
+
+const presignService = new S3PresignService(
+  {
+    accessKeyId: 'your-access-key',
+    secretAccessKey: 'your-secret-key',
+    region: 'us-east-1',
+    bucket: 'my-bucket', // Optional default bucket
+    sessionToken: 'xxx', // Optional session token
+  },
+  logger
+);
+
+// Generate presigned URL for getting an object
+const getUrl = presignService.presignGetObject({
+  bucket: 'my-bucket',
+  key: 'data/file.csv',
+  accessKeyId: 'xxx',
+  secretAccessKey: 'yyy',
+  region: 'us-east-1',
+  expiresIn: 3600, // Optional, defaults to 3600 seconds (1 hour)
+});
+
+// Generate presigned URL for putting an object
+const { url, headers } = presignService.presignPutObject({
+  bucket: 'my-bucket',
+  key: 'uploads/new-file.csv',
+  accessKeyId: 'xxx',
+  secretAccessKey: 'yyy',
+  region: 'us-east-1',
+  expiresIn: 600, // 10 minutes
+});
+
+// Generate presigned URL for copying an object
+const { url: copyUrl, headers: copyHeaders } = presignService.presignCopyObject({
+  sourceBucket: 'source-bucket',
+  sourceKey: 'path/to/source.csv',
+  bucket: 'dest-bucket',
+  key: 'path/to/dest.csv',
+  accessKeyId: 'xxx',
+  secretAccessKey: 'yyy',
+  region: 'us-east-1',
+  metadata: { 'custom-header': 'value' }, // Optional metadata
+});
+
+// Generate presigned URL for deleting an object
+const deleteUrl = presignService.presignDeleteObject({
+  bucket: 'my-bucket',
+  key: 'file-to-delete.csv',
+  accessKeyId: 'xxx',
+  secretAccessKey: 'yyy',
+  region: 'us-east-1',
+});
+
+// Generate presigned URL for listing objects
+const listUrl = presignService.presignListObjects({
+  bucket: 'my-bucket',
+  prefix: 'data/', // Optional prefix filter
+  delimiter: '/', // Optional delimiter
+  maxKeys: 1000, // Optional max keys
+  accessKeyId: 'xxx',
+  secretAccessKey: 'yyy',
+  region: 'us-east-1',
+  expiresIn: 3600,
+});
+```
+
+**Constructor:**
+
+```typescript
+new S3PresignService(
+  config: S3Config,            // S3 configuration
+  logger?: StructuredLogger    // Optional logger
+)
+```
+
+**Methods:**
+
+- `presignListObjects(params: PresignListParams): string` - Generate presigned URL for listing objects
+- `presignGetObject(params: PresignObjectParams): string` - Generate presigned URL for getting an object
+- `presignPutObject(params: PresignObjectParams): { url: string; headers: Record<string, string> }` - Generate presigned URL and headers for putting an object
+- `presignCopyObject(params: PresignCopyParams): { url: string; headers: Record<string, string> }` - Generate presigned URL and headers for copying an object
+- `presignDeleteObject(params: PresignDeleteParams): string` - Generate presigned URL for deleting an object
+- `updateConfig(config: Partial<S3Config>): void` - Update S3 configuration
+- `getConfigSummary(): Omit<S3Config, 'secretAccessKey' | 'sessionToken'>` - Get current configuration (without secrets)
+- `validateConfig(): { isValid: boolean; errors: string[] }` - Validate S3 configuration
+
+**Parameter Types:**
+
+```typescript
+interface PresignObjectParams {
+  bucket: string;
+  key: string;
+  accessKeyId: string;
+  secretAccessKey: string;
+  region: string;
+  sessionToken?: string;
+  expiresIn?: number; // Seconds, default 3600
+}
+
+interface PresignListParams {
+  bucket: string;
+  prefix?: string;
+  delimiter?: string;
+  maxKeys?: number;
+  accessKeyId: string;
+  secretAccessKey: string;
+  region: string;
+  sessionToken?: string;
+  expiresIn?: number;
+}
+
+interface PresignCopyParams {
+  sourceBucket?: string; // Defaults to bucket if not specified
+  sourceKey: string;
+  bucket: string;
+  key: string;
+  accessKeyId: string;
+  secretAccessKey: string;
+  region: string;
+  sessionToken?: string;
+  metadata?: Record<string, string>;
+  expiresIn?: number;
+}
+
+interface PresignDeleteParams {
+  bucket: string;
+  key: string;
+  accessKeyId: string;
+  secretAccessKey: string;
+  region: string;
+  sessionToken?: string;
+  expiresIn?: number;
+}
+```
+
+## JobTracker (NEW)
+
+Track job lifecycle and metrics in a KV store. Provides standardized job status tracking for async workflows with automatic timestamp management and TTL support.
+
+```typescript
+import { JobTracker } from '@fluentcommerce/fc-connect-sdk';
+import { 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,
+  604800 // Optional TTL in seconds (default: 7 days)
+);
+
+// Create a new job
+await tracker.createJob('scheduled_1729681200000', {
+  triggeredBy: 'schedule',
+  stage: 'initialization',
+  details: { catalogueRef: 'DEFAULT:1' },
+});
+
+// Update job status
+await tracker.updateJob('scheduled_1729681200000', {
+  status: 'processing',
+  stage: 'extraction',
+  message: 'Extracting 1000 records',
+  details: { recordCount: 1000 },
+});
+
+// Mark as completed
+await tracker.markCompleted('scheduled_1729681200000', {
+  recordCount: 1000,
+  fileName: 'export.xml',
+  sftpPath: '/uploads/export.xml',
+});
+
+// Mark as failed (in catch block)
+try {
+  // ... job logic ...
+} catch (error) {
+  await tracker.markFailed('scheduled_1729681200000', error);
+}
+
+// Get job status
+const jobStatus = await tracker.getJob('scheduled_1729681200000');
+console.log(jobStatus);
+// {
+//   status: 'completed',
+//   stage: 'finished',
+//   message: 'Job completed successfully',
+//   createdAt: '2025-01-24T10:00:00.000Z',
+//   startedAt: '2025-01-24T10:00:05.000Z',
+//   completedAt: '2025-01-24T10:05:30.000Z',
+//   triggeredBy: 'schedule',
+//   details: { recordCount: 1000, fileName: 'export.xml', ... }
+// }
+```
+
+**Constructor:**
+
+```typescript
+new JobTracker(
+  kv: KVAdapter,                // KV adapter (VersoriKVAdapter or custom)
+  logger: StructuredLogger,     // Logger instance
+  ttl?: number                  // Optional TTL in seconds (default: 604800 = 7 days)
+)
+```
+
+**Methods:**
+
+- `createJob(jobId: string, metadata: Partial<Omit<JobStatus, 'status' | 'createdAt'>>): Promise<void>` - Create a new job with 'queued' status
+- `updateJob(jobId: string, update: Partial<JobStatus>): Promise<void>` - Update job status (auto-updates timestamps)
+- `getJob(jobId: string): Promise<JobStatus | undefined>` - Retrieve job status
+- `markCompleted(jobId: string, details?: Record<string, any>): Promise<void>` - Mark job as completed
+- `markFailed(jobId: string, error: Error | string): Promise<void>` - Mark job as failed
+
+**JobStatus Interface:**
+
+```typescript
+interface JobStatus {
+  status: 'queued' | 'processing' | 'completed' | 'failed';
+  stage?: string;
+  message?: string;
+  createdAt?: string;
+  startedAt?: string;
+  completedAt?: string;
+  failedAt?: string;
+  triggeredBy: 'schedule' | 'webhook' | 'manual';
+  details?: Record<string, any>;
+  error?: string;
+  errorStack?: string;
+}
+```
+
+**Key Features:**
+
+- Standardized job status tracking
+- Automatic timestamp management (createdAt, startedAt, completedAt, failedAt)
+- TTL support for automatic cleanup
+- Safe error handling (never throws on KV errors)
+- Detailed logging
+
+## PartialBatchRecovery (NEW)
+
+Tracks per-record success/failure in batch operations and enables retrying only failed records instead of entire batches. Provides checkpoint/resume functionality and detailed error reporting.
+
+```typescript
+import { PartialBatchRecovery } from '@fluentcommerce/fc-connect-sdk';
+
+const recovery = new PartialBatchRecovery<InventoryRecord>(logger);
+
+// Process batch with automatic recovery and retry
+const result = await recovery.processBatchWithRecovery(
+  records,
+  async batch =>
+    await client.sendBatch(jobId, {
+      action: 'UPSERT',
+      entityType: 'INVENTORY',
+      entities: batch,
+    }),
+  {
+    maxRetries: 3,
+    retryOnlyFailed: true,
+    retryBatchSize: 100,
+    checkpointKey: 'inventory-2025-01-24',
+    retryDelayMs: 1000,
+    shouldRetry: (error, attemptCount) => {
+      // Custom retry logic
+      return attemptCount <= 3 && !error.message.includes('permanent');
+    },
+  }
+);
+
+console.log(`Success: ${result.successCount}, Failed: ${result.failedCount}`);
+console.log(`Duration: ${result.durationMs}ms`);
+console.log(result.summary);
+
+if (result.failedRecords.length > 0) {
+  console.log('Failed records:', result.failedRecords);
+
+  // Export failed records for manual review
+  const failures = result.failedRecords.map(f => ({
+    index: f.index,
+    record: f.record,
+    error: f.error.message,
+    attempts: f.attemptCount,
+  }));
+}
+
+// Resume from checkpoint later
+if (result.checkpointId) {
+  const resumeResult = await recovery.resumeFromCheckpoint(
+    result.checkpointId,
+    async batch =>
+      await client.sendBatch(jobId, {
+        action: 'UPSERT',
+        entityType: 'INVENTORY',
+        entities: batch,
+      })
+  );
+}
+```
+
+**Constructor:**
+
+```typescript
+new PartialBatchRecovery<T = any>(
+  logger?: StructuredLogger  // Optional logger
+)
+```
+
+**Methods:**
+
+- `processBatchWithRecovery(records: T[], batchProcessor: (records: T[]) => Promise<any>, options?: BatchRecoveryOptions): Promise<BatchRecoveryResult<T>>` - Process batch with automatic recovery and retry
+- `resumeFromCheckpoint(checkpointId: string, batchProcessor: (records: T[]) => Promise<any>, options?: BatchRecoveryOptions): Promise<BatchRecoveryResult<T>>` - Resume processing from a saved checkpoint
+- `getCheckpoint(checkpointId: string): BatchCheckpoint<T> | undefined` - Get checkpoint by ID
+- `listCheckpoints(): BatchCheckpoint<T>[]` - List all checkpoints
+- `deleteCheckpoint(checkpointId: string): boolean` - Delete a checkpoint
+- `clearCheckpoints(): void` - Clear all checkpoints
+
+**BatchRecoveryOptions:**
+
+```typescript
+interface BatchRecoveryOptions {
+  maxRetries?: number; // Max retry attempts per record (default: 3)
+  retryOnlyFailed?: boolean; // Retry only failed records (default: true)
+  checkpointKey?: string; // Checkpoint key for resume
+  retryDelayMs?: number; // Delay between retries in ms (default: 1000)
+  shouldRetry?: (error: Error, attemptCount: number) => boolean; // Custom retry predicate
+  retryBatchSize?: number; // Batch size for retries (default: 100)
+}
+```
+
+**BatchRecoveryResult:**
+
+```typescript
+interface BatchRecoveryResult<T = any> {
+  totalRecords: number; // Total records processed
+  successCount: number; // Successfully processed records
+  failedCount: number; // Failed records after all retries
+  failedRecords: RecordFailure<T>[]; // Details of failed records
+  checkpointId?: string; // Checkpoint ID for resuming
+  summary: string; // Processing summary
+  durationMs: number; // Total time taken
+}
+
+interface RecordFailure<T = any> {
+  index: number; // Original record index
+  record: T; // The record that failed
+  error: Error; // Error that occurred
+  attemptCount: number; // Number of retry attempts
+  timestamp: string; // Timestamp of failure
+}
+```
+
+**Key Features:**
+
+- Per-record retry logic (avoids reprocessing successful records)
+- Exponential backoff for retries
+- Checkpoint/resume functionality
+- Detailed failure tracking with attempt counts
+- Custom retry predicates
+- Configurable batch sizes for retries
+
+## PreflightValidator (NEW)
+
+Validates data BEFORE sending to Fluent API to catch errors early, save API quota, validate against GraphQL schema requirements, and check for data quality issues.
+
+```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'],
+  checkDuplicates: true,
+  maxBatchSize: 1000,
+  validateTypes: true,
+  customValidator: (record, index) => {
+    if (record.qty < 0) {
+      return `Record ${index}: qty must be non-negative`;
+    }
+    return null;
+  },
+});
+
+if (!result.isValid) {
+  console.error(`Validation failed: ${result.errors.length} errors`);
+  result.errors.forEach(err => {
+    console.error(`[Record ${err.index}] ${err.field}: ${err.message}`);
+  });
+  throw new Error('Batch validation failed');
+}
+
+console.log(result.summary);
+// "Validation passed: 1000/1000 records valid"
+
+// Quick validation - returns first error only (faster)
+const quickResult = await validator.validateQuick(records, {
+  entityType: 'INVENTORY',
+  requiredFields: ['ref', 'qty'],
+  maxBatchSize: 1000,
+});
+
+if (!quickResult.isValid) {
+  console.error(`Quick validation failed: ${quickResult.error}`);
+}
+```
+
+**Constructor:**
+
+```typescript
+new PreflightValidator(
+  logger?: StructuredLogger  // Optional logger
+)
+```
+
+**Methods:**
+
+- `validateBatch(records: any[], options: PreflightValidationOptions): Promise<PreflightValidationResult>` - Validate entire batch with detailed error reporting
+- `validateQuick(records: any[], options: PreflightValidationOptions): Promise<{ isValid: boolean; error?: string }>` - Quick validation that returns first error only (faster for fail-fast scenarios)
+
+**PreflightValidationOptions:**
+
+```typescript
+interface PreflightValidationOptions {
+  entityType: 'INVENTORY' | 'CONTROL' | 'LOCATION' | 'ARTICLE' | string;
+  requiredFields?: string[]; // Fields that must be present
+  checkDuplicates?: boolean; // Check for duplicate refs
+  maxBatchSize?: number; // Maximum batch size
+  validateTypes?: boolean; // Validate field types
+  customValidator?: (record: any, index: number) => string | null; // Custom validation function
+}
+```
+
+**PreflightValidationResult:**
+
+```typescript
+interface PreflightValidationResult {
+  isValid: boolean; // Whether validation passed
+  totalRecords: number; // Total records validated
+  validRecords: number; // Number of valid records
+  errors: PreflightValidationError[]; // All validation errors
+  warnings: PreflightValidationError[]; // All validation warnings
+  summary: string; // Summary message
+  duplicates?: string[]; // Duplicate refs found (if checkDuplicates enabled)
+}
+
+interface PreflightValidationError {
+  index: number; // Record index where error occurred
+  field?: string; // Field that failed validation
+  message: string; // Error message
+  severity: 'error' | 'warning'; // Error severity
+  value?: any; // The problematic value
+}
+```
+
+**Key Features:**
+
+- Catches errors early (saves API quota)
+- Validates against GraphQL schema requirements
+- Checks for duplicates and data quality issues
+- Provides actionable error messages
+- Type validation for common fields (qty, ref, etc.)
+- Custom validation functions
+- Fast "quick validation" mode for fail-fast scenarios
+
+## Versori Adapters (NEW)
+
+Helpers for Versori platform integrations.
+
+```typescript
+import { VersoriKVAdapter, VersoriFileTracker } 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 kv = new VersoriKVAdapter(openKv(':project:'));
+await kv.set('processed:file1', { at: Date.now() }, 3600);
+
+// File tracker to dedupe processed files
+const fileTracker = new VersoriFileTracker(openKv(':project:'), 'my-workflow');
+const already = await fileTracker.wasFileProcessed('incoming/products_20250101.xml');
+if (!already) {
+  await fileTracker.markFileProcessed('incoming/products_20250101.xml', { size: 2048 });
+}
+```
+
+## See Also
+
+- [Ingestion Guide](../../ingestion/ingestion-readme.md) - Complete ingestion workflows
+- [Extraction Guide](../../extraction/extraction-readme.md) - Data extraction patterns
+- [Module 3: Authentication](./api-reference-03-authentication.md) - OAuth2 and auth providers
+- [Module 6: Data Sources](./api-reference-06-data-sources.md) - S3 and SFTP data sources
+- [Module 9: Error Handling](./api-reference-09-error-handling.md) - Error types and handling
+- [Module 8: Types](./api-reference-08-types.md) - Service-related types
+
+---
+
+**[← Previous: GraphQL Mapping](./api-reference-04-graphql-mapping.md)** | **[API Reference Home](../api-reference-readme.md)** | **[Next: Data Sources →](./api-reference-06-data-sources.md)**