npm - @fluentcommerce/fc-connect-sdk - Versions diffs - 0.1.54 → 0.1.56 - Mend

@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

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

Files changed (476) hide show

package/docs/03-PATTERN-GUIDES/integration-patterns/integration-patterns-quick-reference.md CHANGED Viewed

@@ -1,962 +1,962 @@
-# Integration Patterns - Quick Reference
-> Cheat sheet for common integration patterns with the Fluent Connect SDK
-## Pattern Selection Guide
-### Decision Tree
-```
-What's your integration scenario?
-├─ Single event (< 10/hour)
-│  └─ Use: Real-Time Processing (Module 1)
-│     └─ Pattern: Webhook → GraphQL mutation
-│
-├─ Multiple events (10-1000/hour)
-│  ├─ Immediate response required?
-│  │  ├─ YES → Real-Time Processing (Module 1)
-│  │  └─ NO → Batch Processing (Module 2)
-│  │
-│  └─ Pattern: Hourly batch jobs
-│
-├─ Large files (1K+ records)
-│  └─ Use: Batch Processing (Module 2)
-│     └─ Pattern: S3 CSV → Batch API
-│
-└─ Frequent syncs (hourly/15min)
-   └─ Use: Delta Sync (Module 3)
-      └─ Pattern: Timestamp-based change detection
-```
----
-## Quick Patterns
-### Real-Time: JSON Webhook → Fluent
-```typescript
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-export default async function webhook(ctx) {
-  const client = await createClient(ctx); // Auto-detects Versori context
-  const result = await client.graphql({
-    query: `mutation CreateOrder($input: CreateOrderInput!) {
-      createOrder(input: $input) { id ref }
-    }`,
-    variables: { input: mapData(activation.body) },
-  });
-  return { status: 200, body: { orderId: result.id } };
-}
-```
-**Use when**: < 100 events/hour, need < 5 sec response
----
-### Batch: CSV File → Fluent Batch API
-```typescript
-import {
-  createClient,
-  S3DataSource,
-  CSVParserService,
-  UniversalMapper,
-} from '@fluentcommerce/fc-connect-sdk';
-async function batchSync() {
-  // Download CSV
-  const s3 = new S3DataSource(config, console);
-  const csv = await s3.downloadFile('inventory.csv');
-  // Parse
-  const parser = new CSVParserService({ headers: true });
-  const records = await parser.parse(csv);
-  // Map
-  const mapper = new UniversalMapper(mappingConfig);
-  const mapped = records.map(r => mapper.map(r).data);
-  // Batch API
-  const client = await createClient({ config });
-  const job = await client.createJob({ name: 'Sync', retailerId: '2' });
-  for (let i = 0; i < mapped.length; i += 100) {
-    await client.sendBatch(job.id, {
-      entities: mapped.slice(i, i + 100),
-    });
-  }
-  // Poll
-  let status = await client.getJobStatus(job.id);
-  while (status.status === 'PROCESSING') {
-    await sleep(30000);
-    status = await client.getJobStatus(job.id);
-  }
-}
-```
-**Use when**: 1K+ records, scheduled processing, non-critical
----
-### Delta Sync: Timestamp-Based
-```typescript
-import { StateService, FileKVAdapter } from '@fluentcommerce/fc-connect-sdk';
-async function deltaSync() {
-  const stateService = new StateService(logger);
-  // Get last sync time
-  let lastSync = (await stateService.getState('last-sync')) || new Date(0).toISOString();
-  // Filter changed records
-  const allRecords = await loadAllRecords();
-  const changed = allRecords.filter(r => new Date(r.lastModified).toISOString() > lastSync);
-  console.log(`${changed.length} of ${allRecords.length} changed`);
-  // Process only changed
-  await processBatch(changed);
-  // Update timestamp
-  await stateService.setState('last-sync', new Date().toISOString());
-}
-```
-**Use when**: Frequent syncs, large datasets, < 5% change rate
----
-### Webhook: XML → GraphQL
-```typescript
-import { GraphQLMutationMapper } from '@fluentcommerce/fc-connect-sdk';
-const mappingConfig = {
-  mutation: 'createOrder',
-  nodes: {
-    radial: {
-      extract: 'orders.order.custom-attribute[attribute-id=CreateOrderServiceRequest]',
-      parse: 'xml',
-    },
-  },
-  fields: {
-    ref: { source: '$radial.Order@customerOrderId' },
-    totalPrice: { source: '$radial.Order.Payment.Amount', resolver: 'sdk.parseFloat' },
-  },
-};
-const mapper = new GraphQLMutationMapper(mappingConfig, log, { fluentClient: client });
-const result = await mapper.mapWithNodes(xmlData, customResolvers, context);
-// Check success (errors are returned, not thrown)
-if (!result.success) {
-  console.error('Mapping failed:', result.errors);
-  return;
-}
-// Execute mutation (query is auto-generated in result)
-await client.graphql({ query: result.query, variables: result.variables });  // ✅ Use variables
-```
-**Use when**: SFCC, Radial, SOAP webhooks with nested XML
----
-### Error Handling: Retry with Backoff
-```typescript
-async function retryWithBackoff<T>(fn: () => Promise<T>, maxRetries = 5): Promise<T> {
-  for (let attempt = 0; attempt <= maxRetries; attempt++) {
-    try {
-      return await fn();
-    } catch (error: any) {
-      if (error.statusCode < 500) throw error; // Don't retry client errors
-      if (attempt < maxRetries) {
-        const delay = Math.min(1000 * Math.pow(2, attempt), 30000);
-        await sleep(delay);
-      } else {
-        throw error;
-      }
-    }
-  }
-}
-// Usage
-const result = await retryWithBackoff(() => client.graphql({ query, variables }));
-```
-**Use when**: Network errors, rate limits, server errors
----
-### Partial Batch Recovery
-```typescript
-import { PartialBatchRecovery, createClient } from '@fluentcommerce/fc-connect-sdk';
-async function resilientBatchSync() {
-  const client = await createClient({ config });
-  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,
-      checkpointKey: 'daily-inventory-sync',
-    }
-  );
-  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}`);
-  }
-  // Later: Resume from checkpoint
-  if (result.checkpointId) {
-    const resumeResult = await recovery.resumeFromCheckpoint(result.checkpointId, processBatch, {
-      maxRetries: 5,
-    });
-  }
-}
-```
-**Use when**: Sending 50+ batches, unstable network, long-running jobs
----
-### Job Tracker
-```typescript
-import { JobTracker, VersoriKVAdapter, createClient } from '@fluentcommerce/fc-connect-sdk';
-async function batchSyncWithTracking(kv, logger) {
-  const client = await createClient({ config });
-  const tracker = new JobTracker(new VersoriKVAdapter(kv), logger);
-  const jobId = `batch_${Date.now()}`;
-  try {
-    // Create job
-    await tracker.createJob(jobId, {
-      triggeredBy: 'schedule',
-      stage: 'initialization',
-      details: {
-        fileName: 'inventory.csv',
-        recordCount: 5000,
-      },
-    });
-    // Update progress
-    await tracker.updateJob(jobId, {
-      status: 'processing',
-      stage: 'extraction',
-      message: 'Extracting records',
-    });
-    // Create Fluent job
-    const batchJob = await client.createJob({
-      name: 'Daily Inventory Sync',
-      retailerId: '2',
-    });
-    await tracker.updateJob(jobId, {
-      stage: 'ingestion',
-      message: `Sending batches`,
-      details: { fluentJobId: batchJob.id },
-    });
-    // Send batches
-    for (let i = 0; i < batches.length; i++) {
-      await client.sendBatch(batchJob.id, { entities: batches[i] });
-    }
-    // Complete
-    await tracker.markCompleted(jobId, {
-      batchesSent: batches.length,
-      fluentJobId: batchJob.id,
-    });
-  } catch (error) {
-    await tracker.markFailed(jobId, error);
-    throw error;
-  }
-}
-// Query job status
-const status = await tracker.getJob(jobId);
-console.log(`Job ${jobId}: ${status.status} at stage ${status.stage}`);
-```
-**Use when**: Need job history, monitoring, debugging, performance tracking
----
-### Preflight Validator: Validate Before API
-```typescript
-import { PreflightValidator } from '@fluentcommerce/fc-connect-sdk';
-const validator = new PreflightValidator(logger);
-// Validate before sending to API
-const result = await validator.validateBatch(records, {
-  entityType: 'INVENTORY',
-  requiredFields: ['ref', 'qty', 'productRef'],
-  checkDuplicates: true,
-  maxBatchSize: 5000,
-  validateTypes: true,
-});
-if (!result.isValid) {
-  console.error(`Validation failed: ${result.errors.length} errors`);
-  throw new Error(`Validation failed: ${result.summary}`);
-}
-// Safe to send to API (saves quota)
-await sendToFluentAPI(records);
-```
-**Use when**: Large batch operations, cost optimization
----
-## SDK Components Cheat Sheet
-### Client Creation
-```typescript
-// Versori
-const client = await createClient(ctx); // Auto-detects Versori context
-// Standalone
-const client = await createClient({
-  config: {
-    baseUrl: 'https://api.fluentcommerce.com',
-    clientId: process.env.FLUENT_CLIENT_ID,
-    clientSecret: process.env.FLUENT_CLIENT_SECRET,
-    retailerId: process.env.FLUENT_RETAILER_ID,
-  },
-});
-```
-### Client Methods
-```typescript
-// Query (simple)
-const data = await client.graphql({ query, variables });
-// Mutation (simple)
-const data = await client.graphql({ query, variables });
-// GraphQL (advanced - with pagination)
-const result = await client.graphql({
-  query,
-  variables,
-  pagination: { maxPages: 50 },
-});
-// Batch API
-const job = await client.createJob({ name: 'Job', retailerId: '2' });
-const batch = await client.sendBatch(job.id, { entities: records });
-const status = await client.getJobStatus(job.id);
-```
-### Data Sources
-```typescript
-// S3
-import { S3DataSource } from '@fluentcommerce/fc-connect-sdk';
-const s3 = new S3DataSource(
-  {
-    type: 'S3_CSV',
-    connectionId: 'my-s3',
-    name: 'My S3 Source',
-    s3Config: {
-      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
-      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
-      region: 'us-east-1',
-      bucket: 'my-bucket',
-    },
-  },
-  logger
-);
-const files = await s3.listFiles('prefix/');
-const content = await s3.downloadFile('file.csv');
-await s3.uploadFile('output.json', data);
-await s3.moveFile('source.csv', 'archive/source.csv');
-```
-### Parsers
-```typescript
-// CSV
-import { CSVParserService } from '@fluentcommerce/fc-connect-sdk';
-const parser = new CSVParserService({ headers: true });
-const records = await parser.parse(csvContent);
-// XML
-import { XMLParserService } from '@fluentcommerce/fc-connect-sdk';
-const parser = new XMLParserService();
-const data = await parser.parse(xmlString);
-const value = await parser.parseWithPath(xmlString, 'order.items[0].sku');
-```
-### Mapping
-```typescript
-// UniversalMapper (for CSV, JSON, simple XML)
-import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-const mapper = new UniversalMapper({
-  fields: {
-    ref: { source: 'sku', required: true },
-    onHand: { source: 'qty', resolver: 'sdk.parseInt' },
-  },
-});
-const result = await mapper.map(sourceData);
-// GraphQLMutationMapper (for complex XML → GraphQL)
-import { GraphQLMutationMapper } from '@fluentcommerce/fc-connect-sdk';
-const mapper = new GraphQLMutationMapper(mappingConfig, logger, { fluentClient: client });
-const result = await mapper.mapWithNodes(xmlData, customResolvers, context);
-// Query is auto-generated in result.query - no need to call buildMutation()
-```
-### State Management
-```typescript
-import { StateService, VersoriKVAdapter, FileKVAdapter } from '@fluentcommerce/fc-connect-sdk';
-// Versori
-const kvAdapter = new VersoriKVAdapter(openKv());
-// Standalone
-const kvAdapter = new FileKVAdapter('./state');
-const stateService = new StateService(logger);
-await stateService.setState('key', value);
-const value = await stateService.getState('key');
-await stateService.markFileProcessed('file-key', { processedAt: new Date() });
-const processed = await stateService.isFileProcessed('file-key');
-```
-### Advanced Integration Services
-**See Module 6 for complete examples and detailed documentation**
-```typescript
-// Webhook Validation (Fluent Commerce webhooks only)
-const client = await createClient(ctx); // Auto-detects Versori context
-const isValid = await client.validateWebhook(payload, signature, rawBody);
-// Partial Batch Recovery
-const recovery = new PartialBatchRecovery(logger);
-const result = await recovery.processBatchWithRecovery(
-  records,
-  async batch => {
-    return await client.sendBatch(jobId, {
-      action: 'UPSERT',
-      entityType: 'INVENTORY',
-      entities: batch,
-    });
-  },
-  {
-    maxRetries: 3,
-    retryOnlyFailed: true,
-    checkpointKey: 'daily-sync',
-  }
-);
-// Job Tracker (for Versori KV storage)
-const tracker = new JobTracker(new VersoriKVAdapter(kv), logger);
-await tracker.createJob(jobId, { triggeredBy: 'schedule', stage: 'start' });
-await tracker.updateJob(jobId, { status: 'processing', stage: 'extraction' });
-await tracker.markCompleted(jobId, { recordCount: 1000 });
-// Preflight Validator
-const validator = new PreflightValidator(logger);
-const result = await validator.validateBatch(records, {
-  entityType: 'INVENTORY',
-  requiredFields: ['ref', 'qty'],
-  checkDuplicates: true,
-  maxBatchSize: 5000,
-});
-```
----
-## SDK Resolvers
-### Built-in Resolvers
-```typescript
-// String
-'sdk.uppercase'; // "hello" → "HELLO"
-'sdk.lowercase'; // "HELLO" → "hello"
-'sdk.trim'; // " hello " → "hello"
-'sdk.toString'; // 123 → "123"
-// Number
-'sdk.parseInt'; // "123" → 123
-'sdk.parseFloat'; // "12.99" → 12.99
-'sdk.number'; // "123" → 123
-// Date
-'sdk.formatDate'; // "2025-01-15" → "2025-01-15T00:00:00.000Z"
-'sdk.parseDate'; // Parse various date formats
-// Type
-'sdk.boolean'; // "true" → true
-'sdk.toJson'; // { foo: 'bar' } → '{"foo":"bar"}'
-'sdk.parseJson'; // '{"foo":"bar"}' → { foo: 'bar' }
-// Utility
-'sdk.identity'; // Returns value unchanged
-'sdk.coalesce'; // Returns first non-null value
-```
-### Custom Resolvers
-```typescript
-const customResolvers = {
-  'custom.buildRef': (value, data) => {
-    return `${data.sku}-${data.location}`;
-  },
-  'custom.lookupCustomer': async (value, data, config, helpers) => {
-    const result = await helpers.fluentClient.graphql({
-      query: CUSTOMER_QUERY,
-      variables: { email: data.email },
-    });
-    return result?.customers?.edges?.[0]?.node?.id;
-  },
-};
-// Use in mapper
-const mapper = new UniversalMapper(mappingConfig, { customResolvers });
-```
----
-## Common GraphQL Patterns
-### Query with Pagination
-```typescript
-const result = await client.graphql({
-  query: `
-    query GetProducts($first: Int!, $after: String) {
-      products(first: $first, after: $after) {
-        edges {
-          node {
-            id
-            ref
-            name
-          }
-          cursor
-        }
-        pageInfo {
-          hasNextPage
-        }
-      }
-    }
-  `,
-  variables: { first: 100 },
-  pagination: {
-    maxPages: 50,
-    maxRecords: 5000,
-    onProgress: (page, total) => console.log(`Page ${page}/${total}`),
-  },
-});
-const products = result.data.products.edges.map(e => e.node);
-```
-### Create Mutation
-```typescript
-const result = await client.graphql({
-  query: `
-    mutation CreateOrder($input: CreateOrderInput!) {
-      createOrder(input: $input) {
-        id
-        ref
-        status
-      }
-    }
-  `,
-  variables: {
-    input: {
-      ref: 'ORD-123',
-      type: 'HD',
-      totalPrice: 99.99,
-      currency: 'USD',
-      retailer: { id: '2' },
-      items: [
-        {
-          ref: '1',
-          productRef: 'SKU-001',
-          quantity: 2,
-          price: 49.99,
-          currency: 'USD',
-        },
-      ],
-    },
-  },
-});
-const order = result.data.createOrder;
-```
-### Update Mutation
-```typescript
-const result = await client.graphql({
-  query: `
-    mutation UpdateInventory($input: UpdateInventoryQuantityInput!) {
-      updateInventoryQuantity(input: $input) {
-        id
-        ref
-        onHand
-      }
-    }
-  `,
-  variables: {
-    input: {
-      ref: 'SKU-001-WH01',
-      onHand: 100,
-    },
-  },
-});
-```
----
-## Error Handling Patterns
-### Error Categories
-```typescript
-// Transient (RETRY)
-429 - Rate Limit
-500 - Server Error
-503 - Service Unavailable
-504 - Gateway Timeout
-// Permanent (DON'T RETRY)
-400 - Bad Request
-401 - Unauthorized
-403 - Forbidden
-404 - Not Found
-422 - Unprocessable Entity
-```
-### Try-Catch Pattern
-```typescript
-try {
-  const result = await client.graphql({ query, variables });
-  return { status: 200, body: { orderId: result.id } };
-} catch (error: any) {
-  if (error.message.includes('required field')) {
-    return { status: 400, body: { error: 'Validation failed' } };
-  }
-  if (error.statusCode === 429) {
-    return { status: 429, body: { error: 'Rate limit', retryAfter: 60 } };
-  }
-  return { status: 500, body: { error: 'Internal error', retryable: true } };
-}
-```
-### Logging Pattern
-```typescript
-import {
-  createConsoleLogger,
-  toStructuredLogger,
-  generateCorrelationId,
-} from '@fluentcommerce/fc-connect-sdk';
-// Basic console logger
-const logger = createConsoleLogger();
-// Or with structured context
-const contextLogger = toStructuredLogger(logger, {
-  service: 'InventorySync',
-  correlationId: generateCorrelationId(),
-});
-contextLogger.info('Processing file', { fileName: 'inventory.csv', recordCount: 5000 });
-contextLogger.error('Batch failed', error, { jobId: job.id });
-// For Versori: Use native log from context
-export const workflow = schedule('sync', '0 * * * *').execute(async ({ log }) => {
-  log.info('Processing started');
-  log.error('Processing failed', error);
-});
-```
----
-## Performance Optimization
-### Batch Size Guidelines
-| Total Records | Batch Size | Processing Time |
-| ------------- | ---------- | --------------- |
-| < 1,000       | 100        | 1-2 minutes     |
-| 1,000-10,000  | 150        | 3-10 minutes    |
-| 10,000-50,000 | 200        | 5-15 minutes    |
-| > 50,000      | 250 (max)  | 10-30 minutes   |
-### Polling Intervals
-| Job Size       | Poll Interval |
-| -------------- | ------------- |
-| < 10 batches   | 10 seconds    |
-| 10-100 batches | 30 seconds    |
-| > 100 batches  | 60 seconds    |
-### Memory Optimization
-```typescript
-// ❌ BAD - Load entire file
-const allRecords = await parser.parse(csvContent);
-for (const record of allRecords) {
-  /* process */
-}
-// ✅ GOOD - Stream records
-for await (const record of parser.streamParse(csvStream)) {
-  await processRecord(record);
-}
-```
----
-## Common Recipes
-### Recipe: S3 CSV → Batch API (Complete)
-```typescript
-import {
-  createClient,
-  S3DataSource,
-  CSVParserService,
-  UniversalMapper,
-} from '@fluentcommerce/fc-connect-sdk';
-async function s3ToBatchAPI() {
-  // 1. Download CSV
-  const s3 = new S3DataSource(
-    {
-      type: 'S3_CSV',
-      connectionId: 'my-s3',
-      name: 'My S3 Source',
-      s3Config: {
-        accessKeyId: process.env.AWS_ACCESS_KEY_ID,
-        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
-        region: process.env.AWS_REGION,
-        bucket: process.env.AWS_BUCKET,
-      },
-    },
-    console
-  );
-  const csv = await s3.downloadFile('inventory/current.csv');
-  // 2. Parse CSV
-  const parser = new CSVParserService({ headers: true });
-  const records = await parser.parse(csv);
-  // 3. Map fields
-  const mapper = new UniversalMapper(
-    {
-      fields: {
-        ref: { source: 'sku', resolver: 'custom.buildRef' },
-        type: { value: 'INVENTORY' },
-        productRef: { source: 'sku', required: true },
-        locationRef: { source: 'location', required: true },
-        onHand: { source: 'qty', resolver: 'sdk.parseInt' },
-      },
-    },
-    {
-      customResolvers: {
-        'custom.buildRef': (v, d) => `${d.sku}-${d.location}`,
-      },
-    }
-  );
-  const mapped = [];
-  for (const r of records) {
-    const result = await mapper.map(r);
-    if (result.success) mapped.push(result.data);
-  }
-  // 4. Create job
-  const client = await createClient({
-    config: {
-      baseUrl: process.env.FLUENT_BASE_URL,
-      clientId: process.env.FLUENT_CLIENT_ID,
-      clientSecret: process.env.FLUENT_CLIENT_SECRET,
-      retailerId: process.env.FLUENT_RETAILER_ID,
-    },
-  });
-  const job = await client.createJob({ name: 'Inventory Sync', retailerId: '2' });
-  // 5. Send batches
-  for (let i = 0; i < mapped.length; i += 100) {
-    await client.sendBatch(job.id, {
-      entities: mapped.slice(i, i + 100),
-    });
-  }
-  // 6. Poll status
-  let status = await client.getJobStatus(job.id);
-  while (status.status === 'PENDING' || status.status === 'PROCESSING') {
-    await new Promise(r => setTimeout(r, 30000));
-    status = await client.getJobStatus(job.id);
-  }
-  // 7. Archive
-  if (status.status === 'COMPLETED') {
-    await s3.moveFile('inventory/current.csv', 'inventory/archive/current.csv');
-  }
-  console.log(`✓ Processed ${mapped.length} records`);
-}
-```
-### Recipe: Webhook → GraphQL (JSON)
-```typescript
-import { createClient, UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-export default async function jsonWebhook(ctx) {
-  const client = await createClient(ctx); // Auto-detects Versori context
-  const mapper = new UniversalMapper({
-    fields: {
-      ref: { source: 'order_id', required: true },
-      type: { value: 'HD' },
-      totalPrice: { source: 'total', resolver: 'sdk.parseFloat' },
-      currency: { source: 'currency' },
-      'retailer.id': { value: '2' },
-    },
-  });
-  const mapResult = await mapper.map(ctx.activation.body);
-  if (!mapResult.success) {
-    return { status: 400, body: { error: 'Mapping failed' } };
-  }
-  const order = await client.graphql({
-    query: `mutation CreateOrder($input: CreateOrderInput!) {
-      createOrder(input: $input) { id ref }
-    }`,
-    variables: { input: mapResult.data },
-  });
-  return { status: 200, body: { orderId: order.id } };
-}
-```
-### Recipe: Delta Sync (Hash-Based)
-```typescript
-import crypto from 'crypto';
-import { StateService, FileKVAdapter } from '@fluentcommerce/fc-connect-sdk';
-function hash(record: any): string {
-  const str = `${record.sku}|${record.location}|${record.qty}`;
-  return crypto.createHash('md5').update(str).digest('hex');
-}
-async function hashDeltaSync() {
-  const stateService = new StateService(logger);
-  const prevHashes = (await stateService.getState('hashes')) || {};
-  const currHashes: Record<string, string> = {};
-  const changed = [];
-  const records = await loadAllRecords();
-  for (const record of records) {
-    const key = `${record.sku}-${record.location}`;
-    const currHash = hash(record);
-    currHashes[key] = currHash;
-    if (prevHashes[key] !== currHash) {
-      changed.push(record);
-    }
-  }
-  console.log(`${changed.length} of ${records.length} changed`);
-  await processBatch(changed);
-  await stateService.setState('hashes', currHashes);
-}
-```
----
-## Troubleshooting
-### Common Issues
-| Issue                | Cause                  | Solution                            |
-| -------------------- | ---------------------- | ----------------------------------- |
-| **401 Unauthorized** | Invalid credentials    | Check clientId/clientSecret         |
-| **429 Rate Limit**   | Too many requests      | Add retry with backoff              |
-| **504 Timeout**      | Request too slow       | Reduce batch size or use pagination |
-| **Validation Error** | Missing required field | Check mapping config                |
-| **Hash mismatch**    | State out of sync      | Reset state, run full sync          |
-### Debug Commands
-```bash
-# Introspect GraphQL schema
-npx @fluentcommerce/fc-connect-sdk introspect-schema --url https://api.fluentcommerce.com/graphql
-# Validate mapping config
-npx @fluentcommerce/fc-connect-sdk validate-schema --mapping mappings/config.json
-# Test Deno compatibility
-npm run test:deno
-```
----
-[← Back to Index](./integration-patterns-readme.md) | [View Complete Modules](./modules/)
+# Integration Patterns - Quick Reference
+> Cheat sheet for common integration patterns with the Fluent Connect SDK
+## Pattern Selection Guide
+### Decision Tree
+```
+What's your integration scenario?
+├─ Single event (< 10/hour)
+│  └─ Use: Real-Time Processing (Module 1)
+│     └─ Pattern: Webhook → GraphQL mutation
+│
+├─ Multiple events (10-1000/hour)
+│  ├─ Immediate response required?
+│  │  ├─ YES → Real-Time Processing (Module 1)
+│  │  └─ NO → Batch Processing (Module 2)
+│  │
+│  └─ Pattern: Hourly batch jobs
+│
+├─ Large files (1K+ records)
+│  └─ Use: Batch Processing (Module 2)
+│     └─ Pattern: S3 CSV → Batch API
+│
+└─ Frequent syncs (hourly/15min)
+   └─ Use: Delta Sync (Module 3)
+      └─ Pattern: Timestamp-based change detection
+```
+---
+## Quick Patterns
+### Real-Time: JSON Webhook → Fluent
+```typescript
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+export default async function webhook(ctx) {
+  const client = await createClient(ctx); // Auto-detects Versori context
+  const result = await client.graphql({
+    query: `mutation CreateOrder($input: CreateOrderInput!) {
+      createOrder(input: $input) { id ref }
+    }`,
+    variables: { input: mapData(activation.body) },
+  });
+  return { status: 200, body: { orderId: result.id } };
+}
+```
+**Use when**: < 100 events/hour, need < 5 sec response
+---
+### Batch: CSV File → Fluent Batch API
+```typescript
+import {
+  createClient,
+  S3DataSource,
+  CSVParserService,
+  UniversalMapper,
+} from '@fluentcommerce/fc-connect-sdk';
+async function batchSync() {
+  // Download CSV
+  const s3 = new S3DataSource(config, console);
+  const csv = await s3.downloadFile('inventory.csv');
+  // Parse
+  const parser = new CSVParserService({ headers: true });
+  const records = await parser.parse(csv);
+  // Map
+  const mapper = new UniversalMapper(mappingConfig);
+  const mapped = records.map(r => mapper.map(r).data);
+  // Batch API
+  const client = await createClient({ config });
+  const job = await client.createJob({ name: 'Sync', retailerId: '2' });
+  for (let i = 0; i < mapped.length; i += 100) {
+    await client.sendBatch(job.id, {
+      entities: mapped.slice(i, i + 100),
+    });
+  }
+  // Poll
+  let status = await client.getJobStatus(job.id);
+  while (status.status === 'PROCESSING') {
+    await sleep(30000);
+    status = await client.getJobStatus(job.id);
+  }
+}
+```
+**Use when**: 1K+ records, scheduled processing, non-critical
+---
+### Delta Sync: Timestamp-Based
+```typescript
+import { StateService, FileKVAdapter } from '@fluentcommerce/fc-connect-sdk';
+async function deltaSync() {
+  const stateService = new StateService(logger);
+  // Get last sync time
+  let lastSync = (await stateService.getState('last-sync')) || new Date(0).toISOString();
+  // Filter changed records
+  const allRecords = await loadAllRecords();
+  const changed = allRecords.filter(r => new Date(r.lastModified).toISOString() > lastSync);
+  console.log(`${changed.length} of ${allRecords.length} changed`);
+  // Process only changed
+  await processBatch(changed);
+  // Update timestamp
+  await stateService.setState('last-sync', new Date().toISOString());
+}
+```
+**Use when**: Frequent syncs, large datasets, < 5% change rate
+---
+### Webhook: XML → GraphQL
+```typescript
+import { GraphQLMutationMapper } from '@fluentcommerce/fc-connect-sdk';
+const mappingConfig = {
+  mutation: 'createOrder',
+  nodes: {
+    radial: {
+      extract: 'orders.order.custom-attribute[attribute-id=CreateOrderServiceRequest]',
+      parse: 'xml',
+    },
+  },
+  fields: {
+    ref: { source: '$radial.Order@customerOrderId' },
+    totalPrice: { source: '$radial.Order.Payment.Amount', resolver: 'sdk.parseFloat' },
+  },
+};
+const mapper = new GraphQLMutationMapper(mappingConfig, log, { fluentClient: client });
+const result = await mapper.mapWithNodes(xmlData, customResolvers, context);
+// Check success (errors are returned, not thrown)
+if (!result.success) {
+  console.error('Mapping failed:', result.errors);
+  return;
+}
+// Execute mutation (query is auto-generated in result)
+await client.graphql({ query: result.query, variables: result.variables });  // ✅ Use variables
+```
+**Use when**: SFCC, Radial, SOAP webhooks with nested XML
+---
+### Error Handling: Retry with Backoff
+```typescript
+async function retryWithBackoff<T>(fn: () => Promise<T>, maxRetries = 5): Promise<T> {
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (error: any) {
+      if (error.statusCode < 500) throw error; // Don't retry client errors
+      if (attempt < maxRetries) {
+        const delay = Math.min(1000 * Math.pow(2, attempt), 30000);
+        await sleep(delay);
+      } else {
+        throw error;
+      }
+    }
+  }
+}
+// Usage
+const result = await retryWithBackoff(() => client.graphql({ query, variables }));
+```
+**Use when**: Network errors, rate limits, server errors
+---
+### Partial Batch Recovery
+```typescript
+import { PartialBatchRecovery, createClient } from '@fluentcommerce/fc-connect-sdk';
+async function resilientBatchSync() {
+  const client = await createClient({ config });
+  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,
+      checkpointKey: 'daily-inventory-sync',
+    }
+  );
+  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}`);
+  }
+  // Later: Resume from checkpoint
+  if (result.checkpointId) {
+    const resumeResult = await recovery.resumeFromCheckpoint(result.checkpointId, processBatch, {
+      maxRetries: 5,
+    });
+  }
+}
+```
+**Use when**: Sending 50+ batches, unstable network, long-running jobs
+---
+### Job Tracker
+```typescript
+import { JobTracker, VersoriKVAdapter, createClient } from '@fluentcommerce/fc-connect-sdk';
+async function batchSyncWithTracking(kv, logger) {
+  const client = await createClient({ config });
+  const tracker = new JobTracker(new VersoriKVAdapter(kv), logger);
+  const jobId = `batch_${Date.now()}`;
+  try {
+    // Create job
+    await tracker.createJob(jobId, {
+      triggeredBy: 'schedule',
+      stage: 'initialization',
+      details: {
+        fileName: 'inventory.csv',
+        recordCount: 5000,
+      },
+    });
+    // Update progress
+    await tracker.updateJob(jobId, {
+      status: 'processing',
+      stage: 'extraction',
+      message: 'Extracting records',
+    });
+    // Create Fluent job
+    const batchJob = await client.createJob({
+      name: 'Daily Inventory Sync',
+      retailerId: '2',
+    });
+    await tracker.updateJob(jobId, {
+      stage: 'ingestion',
+      message: `Sending batches`,
+      details: { fluentJobId: batchJob.id },
+    });
+    // Send batches
+    for (let i = 0; i < batches.length; i++) {
+      await client.sendBatch(batchJob.id, { entities: batches[i] });
+    }
+    // Complete
+    await tracker.markCompleted(jobId, {
+      batchesSent: batches.length,
+      fluentJobId: batchJob.id,
+    });
+  } catch (error) {
+    await tracker.markFailed(jobId, error);
+    throw error;
+  }
+}
+// Query job status
+const status = await tracker.getJob(jobId);
+console.log(`Job ${jobId}: ${status.status} at stage ${status.stage}`);
+```
+**Use when**: Need job history, monitoring, debugging, performance tracking
+---
+### Preflight Validator: Validate Before API
+```typescript
+import { PreflightValidator } from '@fluentcommerce/fc-connect-sdk';
+const validator = new PreflightValidator(logger);
+// Validate before sending to API
+const result = await validator.validateBatch(records, {
+  entityType: 'INVENTORY',
+  requiredFields: ['ref', 'qty', 'productRef'],
+  checkDuplicates: true,
+  maxBatchSize: 5000,
+  validateTypes: true,
+});
+if (!result.isValid) {
+  console.error(`Validation failed: ${result.errors.length} errors`);
+  throw new Error(`Validation failed: ${result.summary}`);
+}
+// Safe to send to API (saves quota)
+await sendToFluentAPI(records);
+```
+**Use when**: Large batch operations, cost optimization
+---
+## SDK Components Cheat Sheet
+### Client Creation
+```typescript
+// Versori
+const client = await createClient(ctx); // Auto-detects Versori context
+// Standalone
+const client = await createClient({
+  config: {
+    baseUrl: 'https://api.fluentcommerce.com',
+    clientId: process.env.FLUENT_CLIENT_ID,
+    clientSecret: process.env.FLUENT_CLIENT_SECRET,
+    retailerId: process.env.FLUENT_RETAILER_ID,
+  },
+});
+```
+### Client Methods
+```typescript
+// Query (simple)
+const data = await client.graphql({ query, variables });
+// Mutation (simple)
+const data = await client.graphql({ query, variables });
+// GraphQL (advanced - with pagination)
+const result = await client.graphql({
+  query,
+  variables,
+  pagination: { maxPages: 50 },
+});
+// Batch API
+const job = await client.createJob({ name: 'Job', retailerId: '2' });
+const batch = await client.sendBatch(job.id, { entities: records });
+const status = await client.getJobStatus(job.id);
+```
+### Data Sources
+```typescript
+// S3
+import { S3DataSource } from '@fluentcommerce/fc-connect-sdk';
+const s3 = new S3DataSource(
+  {
+    type: 'S3_CSV',
+    connectionId: 'my-s3',
+    name: 'My S3 Source',
+    s3Config: {
+      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+      region: 'us-east-1',
+      bucket: 'my-bucket',
+    },
+  },
+  logger
+);
+const files = await s3.listFiles('prefix/');
+const content = await s3.downloadFile('file.csv');
+await s3.uploadFile('output.json', data);
+await s3.moveFile('source.csv', 'archive/source.csv');
+```
+### Parsers
+```typescript
+// CSV
+import { CSVParserService } from '@fluentcommerce/fc-connect-sdk';
+const parser = new CSVParserService({ headers: true });
+const records = await parser.parse(csvContent);
+// XML
+import { XMLParserService } from '@fluentcommerce/fc-connect-sdk';
+const parser = new XMLParserService();
+const data = await parser.parse(xmlString);
+const value = await parser.parseWithPath(xmlString, 'order.items[0].sku');
+```
+### Mapping
+```typescript
+// UniversalMapper (for CSV, JSON, simple XML)
+import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+const mapper = new UniversalMapper({
+  fields: {
+    ref: { source: 'sku', required: true },
+    onHand: { source: 'qty', resolver: 'sdk.parseInt' },
+  },
+});
+const result = await mapper.map(sourceData);
+// GraphQLMutationMapper (for complex XML → GraphQL)
+import { GraphQLMutationMapper } from '@fluentcommerce/fc-connect-sdk';
+const mapper = new GraphQLMutationMapper(mappingConfig, logger, { fluentClient: client });
+const result = await mapper.mapWithNodes(xmlData, customResolvers, context);
+// Query is auto-generated in result.query - no need to call buildMutation()
+```
+### State Management
+```typescript
+import { StateService, VersoriKVAdapter, FileKVAdapter } from '@fluentcommerce/fc-connect-sdk';
+// Versori
+const kvAdapter = new VersoriKVAdapter(openKv());
+// Standalone
+const kvAdapter = new FileKVAdapter('./state');
+const stateService = new StateService(logger);
+await stateService.setState('key', value);
+const value = await stateService.getState('key');
+await stateService.markFileProcessed('file-key', { processedAt: new Date() });
+const processed = await stateService.isFileProcessed('file-key');
+```
+### Advanced Integration Services
+**See Module 6 for complete examples and detailed documentation**
+```typescript
+// Webhook Validation (Fluent Commerce webhooks only)
+const client = await createClient(ctx); // Auto-detects Versori context
+const isValid = await client.validateWebhook(payload, signature, rawBody);
+// Partial Batch Recovery
+const recovery = new PartialBatchRecovery(logger);
+const result = await recovery.processBatchWithRecovery(
+  records,
+  async batch => {
+    return await client.sendBatch(jobId, {
+      action: 'UPSERT',
+      entityType: 'INVENTORY',
+      entities: batch,
+    });
+  },
+  {
+    maxRetries: 3,
+    retryOnlyFailed: true,
+    checkpointKey: 'daily-sync',
+  }
+);
+// Job Tracker (for Versori KV storage)
+const tracker = new JobTracker(new VersoriKVAdapter(kv), logger);
+await tracker.createJob(jobId, { triggeredBy: 'schedule', stage: 'start' });
+await tracker.updateJob(jobId, { status: 'processing', stage: 'extraction' });
+await tracker.markCompleted(jobId, { recordCount: 1000 });
+// Preflight Validator
+const validator = new PreflightValidator(logger);
+const result = await validator.validateBatch(records, {
+  entityType: 'INVENTORY',
+  requiredFields: ['ref', 'qty'],
+  checkDuplicates: true,
+  maxBatchSize: 5000,
+});
+```
+---
+## SDK Resolvers
+### Built-in Resolvers
+```typescript
+// String
+'sdk.uppercase'; // "hello" → "HELLO"
+'sdk.lowercase'; // "HELLO" → "hello"
+'sdk.trim'; // " hello " → "hello"
+'sdk.toString'; // 123 → "123"
+// Number
+'sdk.parseInt'; // "123" → 123
+'sdk.parseFloat'; // "12.99" → 12.99
+'sdk.number'; // "123" → 123
+// Date
+'sdk.formatDate'; // "2025-01-15" → "2025-01-15T00:00:00.000Z"
+'sdk.parseDate'; // Parse various date formats
+// Type
+'sdk.boolean'; // "true" → true
+'sdk.toJson'; // { foo: 'bar' } → '{"foo":"bar"}'
+'sdk.parseJson'; // '{"foo":"bar"}' → { foo: 'bar' }
+// Utility
+'sdk.identity'; // Returns value unchanged
+'sdk.coalesce'; // Returns first non-null value
+```
+### Custom Resolvers
+```typescript
+const customResolvers = {
+  'custom.buildRef': (value, data) => {
+    return `${data.sku}-${data.location}`;
+  },
+  'custom.lookupCustomer': async (value, data, config, helpers) => {
+    const result = await helpers.fluentClient.graphql({
+      query: CUSTOMER_QUERY,
+      variables: { email: data.email },
+    });
+    return result?.customers?.edges?.[0]?.node?.id;
+  },
+};
+// Use in mapper
+const mapper = new UniversalMapper(mappingConfig, { customResolvers });
+```
+---
+## Common GraphQL Patterns
+### Query with Pagination
+```typescript
+const result = await client.graphql({
+  query: `
+    query GetProducts($first: Int!, $after: String) {
+      products(first: $first, after: $after) {
+        edges {
+          node {
+            id
+            ref
+            name
+          }
+          cursor
+        }
+        pageInfo {
+          hasNextPage
+        }
+      }
+    }
+  `,
+  variables: { first: 100 },
+  pagination: {
+    maxPages: 50,
+    maxRecords: 5000,
+    onProgress: (page, total) => console.log(`Page ${page}/${total}`),
+  },
+});
+const products = result.data.products.edges.map(e => e.node);
+```
+### Create Mutation
+```typescript
+const result = await client.graphql({
+  query: `
+    mutation CreateOrder($input: CreateOrderInput!) {
+      createOrder(input: $input) {
+        id
+        ref
+        status
+      }
+    }
+  `,
+  variables: {
+    input: {
+      ref: 'ORD-123',
+      type: 'HD',
+      totalPrice: 99.99,
+      currency: 'USD',
+      retailer: { id: '2' },
+      items: [
+        {
+          ref: '1',
+          productRef: 'SKU-001',
+          quantity: 2,
+          price: 49.99,
+          currency: 'USD',
+        },
+      ],
+    },
+  },
+});
+const order = result.data.createOrder;
+```
+### Update Mutation
+```typescript
+const result = await client.graphql({
+  query: `
+    mutation UpdateInventory($input: UpdateInventoryQuantityInput!) {
+      updateInventoryQuantity(input: $input) {
+        id
+        ref
+        onHand
+      }
+    }
+  `,
+  variables: {
+    input: {
+      ref: 'SKU-001-WH01',
+      onHand: 100,
+    },
+  },
+});
+```
+---
+## Error Handling Patterns
+### Error Categories
+```typescript
+// Transient (RETRY)
+429 - Rate Limit
+500 - Server Error
+503 - Service Unavailable
+504 - Gateway Timeout
+// Permanent (DON'T RETRY)
+400 - Bad Request
+401 - Unauthorized
+403 - Forbidden
+404 - Not Found
+422 - Unprocessable Entity
+```
+### Try-Catch Pattern
+```typescript
+try {
+  const result = await client.graphql({ query, variables });
+  return { status: 200, body: { orderId: result.id } };
+} catch (error: any) {
+  if (error.message.includes('required field')) {
+    return { status: 400, body: { error: 'Validation failed' } };
+  }
+  if (error.statusCode === 429) {
+    return { status: 429, body: { error: 'Rate limit', retryAfter: 60 } };
+  }
+  return { status: 500, body: { error: 'Internal error', retryable: true } };
+}
+```
+### Logging Pattern
+```typescript
+import {
+  createConsoleLogger,
+  toStructuredLogger,
+  generateCorrelationId,
+} from '@fluentcommerce/fc-connect-sdk';
+// Basic console logger
+const logger = createConsoleLogger();
+// Or with structured context
+const contextLogger = toStructuredLogger(logger, {
+  service: 'InventorySync',
+  correlationId: generateCorrelationId(),
+});
+contextLogger.info('Processing file', { fileName: 'inventory.csv', recordCount: 5000 });
+contextLogger.error('Batch failed', error, { jobId: job.id });
+// For Versori: Use native log from context
+export const workflow = schedule('sync', '0 * * * *').execute(async ({ log }) => {
+  log.info('Processing started');
+  log.error('Processing failed', error);
+});
+```
+---
+## Performance Optimization
+### Batch Size Guidelines
+| Total Records | Batch Size | Processing Time |
+| ------------- | ---------- | --------------- |
+| < 1,000       | 100        | 1-2 minutes     |
+| 1,000-10,000  | 150        | 3-10 minutes    |
+| 10,000-50,000 | 200        | 5-15 minutes    |
+| > 50,000      | 250 (max)  | 10-30 minutes   |
+### Polling Intervals
+| Job Size       | Poll Interval |
+| -------------- | ------------- |
+| < 10 batches   | 10 seconds    |
+| 10-100 batches | 30 seconds    |
+| > 100 batches  | 60 seconds    |
+### Memory Optimization
+```typescript
+// ❌ BAD - Load entire file
+const allRecords = await parser.parse(csvContent);
+for (const record of allRecords) {
+  /* process */
+}
+// ✅ GOOD - Stream records
+for await (const record of parser.streamParse(csvStream)) {
+  await processRecord(record);
+}
+```
+---
+## Common Recipes
+### Recipe: S3 CSV → Batch API (Complete)
+```typescript
+import {
+  createClient,
+  S3DataSource,
+  CSVParserService,
+  UniversalMapper,
+} from '@fluentcommerce/fc-connect-sdk';
+async function s3ToBatchAPI() {
+  // 1. Download CSV
+  const s3 = new S3DataSource(
+    {
+      type: 'S3_CSV',
+      connectionId: 'my-s3',
+      name: 'My S3 Source',
+      s3Config: {
+        accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+        region: process.env.AWS_REGION,
+        bucket: process.env.AWS_BUCKET,
+      },
+    },
+    console
+  );
+  const csv = await s3.downloadFile('inventory/current.csv');
+  // 2. Parse CSV
+  const parser = new CSVParserService({ headers: true });
+  const records = await parser.parse(csv);
+  // 3. Map fields
+  const mapper = new UniversalMapper(
+    {
+      fields: {
+        ref: { source: 'sku', resolver: 'custom.buildRef' },
+        type: { value: 'INVENTORY' },
+        productRef: { source: 'sku', required: true },
+        locationRef: { source: 'location', required: true },
+        onHand: { source: 'qty', resolver: 'sdk.parseInt' },
+      },
+    },
+    {
+      customResolvers: {
+        'custom.buildRef': (v, d) => `${d.sku}-${d.location}`,
+      },
+    }
+  );
+  const mapped = [];
+  for (const r of records) {
+    const result = await mapper.map(r);
+    if (result.success) mapped.push(result.data);
+  }
+  // 4. Create job
+  const client = await createClient({
+    config: {
+      baseUrl: process.env.FLUENT_BASE_URL,
+      clientId: process.env.FLUENT_CLIENT_ID,
+      clientSecret: process.env.FLUENT_CLIENT_SECRET,
+      retailerId: process.env.FLUENT_RETAILER_ID,
+    },
+  });
+  const job = await client.createJob({ name: 'Inventory Sync', retailerId: '2' });
+  // 5. Send batches
+  for (let i = 0; i < mapped.length; i += 100) {
+    await client.sendBatch(job.id, {
+      entities: mapped.slice(i, i + 100),
+    });
+  }
+  // 6. Poll status
+  let status = await client.getJobStatus(job.id);
+  while (status.status === 'PENDING' || status.status === 'PROCESSING') {
+    await new Promise(r => setTimeout(r, 30000));
+    status = await client.getJobStatus(job.id);
+  }
+  // 7. Archive
+  if (status.status === 'COMPLETED') {
+    await s3.moveFile('inventory/current.csv', 'inventory/archive/current.csv');
+  }
+  console.log(`✓ Processed ${mapped.length} records`);
+}
+```
+### Recipe: Webhook → GraphQL (JSON)
+```typescript
+import { createClient, UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+export default async function jsonWebhook(ctx) {
+  const client = await createClient(ctx); // Auto-detects Versori context
+  const mapper = new UniversalMapper({
+    fields: {
+      ref: { source: 'order_id', required: true },
+      type: { value: 'HD' },
+      totalPrice: { source: 'total', resolver: 'sdk.parseFloat' },
+      currency: { source: 'currency' },
+      'retailer.id': { value: '2' },
+    },
+  });
+  const mapResult = await mapper.map(ctx.activation.body);
+  if (!mapResult.success) {
+    return { status: 400, body: { error: 'Mapping failed' } };
+  }
+  const order = await client.graphql({
+    query: `mutation CreateOrder($input: CreateOrderInput!) {
+      createOrder(input: $input) { id ref }
+    }`,
+    variables: { input: mapResult.data },
+  });
+  return { status: 200, body: { orderId: order.id } };
+}
+```
+### Recipe: Delta Sync (Hash-Based)
+```typescript
+import crypto from 'crypto';
+import { StateService, FileKVAdapter } from '@fluentcommerce/fc-connect-sdk';
+function hash(record: any): string {
+  const str = `${record.sku}|${record.location}|${record.qty}`;
+  return crypto.createHash('md5').update(str).digest('hex');
+}
+async function hashDeltaSync() {
+  const stateService = new StateService(logger);
+  const prevHashes = (await stateService.getState('hashes')) || {};
+  const currHashes: Record<string, string> = {};
+  const changed = [];
+  const records = await loadAllRecords();
+  for (const record of records) {
+    const key = `${record.sku}-${record.location}`;
+    const currHash = hash(record);
+    currHashes[key] = currHash;
+    if (prevHashes[key] !== currHash) {
+      changed.push(record);
+    }
+  }
+  console.log(`${changed.length} of ${records.length} changed`);
+  await processBatch(changed);
+  await stateService.setState('hashes', currHashes);
+}
+```
+---
+## Troubleshooting
+### Common Issues
+| Issue                | Cause                  | Solution                            |
+| -------------------- | ---------------------- | ----------------------------------- |
+| **401 Unauthorized** | Invalid credentials    | Check clientId/clientSecret         |
+| **429 Rate Limit**   | Too many requests      | Add retry with backoff              |
+| **504 Timeout**      | Request too slow       | Reduce batch size or use pagination |
+| **Validation Error** | Missing required field | Check mapping config                |
+| **Hash mismatch**    | State out of sync      | Reset state, run full sync          |
+### Debug Commands
+```bash
+# Introspect GraphQL schema
+npx @fluentcommerce/fc-connect-sdk introspect-schema --url https://api.fluentcommerce.com/graphql
+# Validate mapping config
+npx @fluentcommerce/fc-connect-sdk validate-schema --mapping mappings/config.json
+# Test Deno compatibility
+npm run test:deno
+```
+---
+[← Back to Index](./integration-patterns-readme.md) | [View Complete Modules](./modules/)