@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/00-START-HERE/troubleshooting-quick-reference.md

@@ -1,1086 +1,1086 @@
-# Troubleshooting Quick Reference
-
-**When things don't work - start here**
-
-## 📋 Quick Logger Setup
-
-**Versori Platform** - Use native `log` from context:
-```typescript
-const { log } = ctx; // Native Versori logger
-const client = await createClient({ ...ctx, log });
-```
-
-**Standalone (Node.js/Deno)** - Use minimal utilities:
-```typescript
-import { createConsoleLogger, toStructuredLogger } from '@fluentcommerce/fc-connect-sdk';
-
-const logger = toStructuredLogger(createConsoleLogger(), { logLevel: 'debug' });
-const client = await createClient({ config: { ...config, logger } });
-```
-
-**Minimal logger snippet** (when you need Logger interface):
-```typescript
-const logger: import('@fluentcommerce/fc-connect-sdk').Logger = {
-  debug: (m, meta) => log.debug(m, meta),
-  info: (m, meta) => log.info(m, meta),
-  warn: (m, meta) => log.warn(m, meta),
-  error: (m, err, meta) => log.error(m, { ...(meta ?? {}), error: err?.message }),
-};
-```
-
-## 🚨 Common Errors & Fixes (90% of Issues)
-
-### Error: `invalid key` from NATS KV (VersoriFileTracker / KV keys)
-
-**Meaning:** Your KV key contains characters not allowed by NATS KV (e.g. `:` or spaces/brackets/parentheses).
-
-**Allowed characters:** `a-z A-Z 0-9 _ - . = /`
-
-**Fix (SDK ≥ current):** `VersoriFileTracker` now uses NATS-safe keys (slash-separated prefix and filename sanitization). Just pass the raw filename; the tracker will sanitize internally.
-
-```typescript
-import { VersoriFileTracker } from '@fluentcommerce/fc-connect-sdk';
-
-const tracker = new VersoriFileTracker(openKv(':project:'), 'fc-sdk');
-
-// Raw basename is OK; tracker sanitizes to NATS-safe key
-const alreadyProcessed = await tracker.wasFileProcessed('[SAMPLE] - file (1).xml');
-if (!alreadyProcessed) {
-  // ... process ...
-  await tracker.markFileProcessed('[SAMPLE] - file (1).xml', { recordCount: 123 });
-}
-```
-
-**Workaround:** Use your own dot/slash-separated keys and sanitize names before KV get/set.
-
-```typescript
-const safe = (name: string) => name.replace(/[^A-Za-z0-9._=\/-]/g, '_');
-await kv.set(`fc_sdk.processed_files.${safe(baseName)}`, { processedAt: new Date().toISOString() });
-```
-
----
-
-### Error: `Buffer is not defined` (Deno/Versori runtime)
-
-**Meaning:** You're using `Buffer.from()` or `Buffer.alloc()` but haven't imported Buffer in Deno/Versori runtime.
-
-**Why:** Unlike Node.js, Deno doesn't have `Buffer` as a global. You must explicitly import it from Node.js built-ins.
-
-**Fix:** Add the import at the top of your file (before SDK imports):
-
-```typescript
-// ✅ CORRECT - Import Buffer for Deno/Versori
-import { Buffer } from 'node:buffer';
-import {
-  createClient,
-  SftpDataSource,
-  XMLBuilder,
-} from '@fluentcommerce/fc-connect-sdk';
-
-// Now Buffer works
-const xmlContent = '<VirtualPositions>...</VirtualPositions>';
-await sftp.uploadFile('/path/to/file.xml', Buffer.from(xmlContent, 'utf8'));
-
-// Decode base64 credentials
-const decoded = Buffer.from(base64String, 'base64').toString('utf-8');
-```
-
-**Common use cases requiring Buffer import:**
-- SFTP uploads: `Buffer.from(content, 'utf8')`
-- Base64 decode: `Buffer.from(str, 'base64').toString('utf-8')`
-- Binary data: `Buffer.from(data)`
-- Encoding conversion: `Buffer.from(str, 'latin1').toString('utf8')`
-
-**Note:** All SDK templates (v0.1.22+) include this import automatically. If you're using templates from earlier versions, add it manually.
-
----
-
-### Error: GraphQL errors from Fluent Commerce API
-
-**Meaning:** The GraphQL mutation returned errors (e.g., order already exists, missing required field, server error).
-
-**Fix:** Use error classification to determine if error is retryable:
-
-```typescript
-import { classifyErrors } from '@fluentcommerce/fc-connect-sdk';
-
-const result = await client.graphql({ query, variables });
-
-if (result.errors) {
-  const classification = classifyErrors(result.errors);
-  
-  log.error('GraphQL error:', {
-    errorCode: classification.errorCode,
-    retryable: classification.retryable,
-    action: classification.action,
-    message: classification.userMessage,
-  });
-  
-  // Don't retry non-retryable errors (e.g., C0121E = order already exists)
-  if (!classification.retryable) {
-    throw new Error(classification.userMessage);
-  }
-  
-  // Retry retryable errors (e.g., S0002E = server error)
-  if (classification.retryable) {
-    await delay(classification.retryDelaySeconds * 1000);
-    // retry logic...
-  }
-}
-```
-
-**Common Error Codes:**
-- **C0121E** - Order already exists (non-retryable, verify payload)
-- **C0140E** - Missing required variables (non-retryable, fix payload)
-- **S0002E** - Server error (retryable, retry later)
-- **C0011E** - Rate limit exceeded (retryable, wait and retry)
-
-See [GraphQL Error Classification Guide](../02-CORE-GUIDES/api-reference/graphql-error-classification.md) for complete error code reference.
-
----
-
-### Error: `OAuth2 authentication failed` or `Token refresh failed`
-
-**Meaning:** Your Fluent API credentials are invalid or the OAuth2 token exchange is failing.
-
-**Why:** Common causes include wrong credentials, expired credentials, network issues, or incorrect OAuth2 endpoint.
-
-**Fix:**
-
-```typescript
-// ✅ CORRECT - Verify all required credentials are set
-const client = new FluentClient({
-  baseUrl: 'https://api.fluentcommerce.com', // Or your environment URL
-  clientId: process.env.FLUENT_CLIENT_ID,
-  clientSecret: process.env.FLUENT_CLIENT_SECRET,
-  username: process.env.FLUENT_USERNAME,
-  password: process.env.FLUENT_PASSWORD,
-  retailerId: process.env.FLUENT_RETAILER_ID, // Required!
-  logger, // Enable logging to see authentication details
-});
-
-// Test authentication
-try {
-  const result = await client.graphql({
-    query: 'query { viewer { id } }',
-  });
-  console.log('Authentication successful:', result);
-} catch (error) {
-  console.error('Authentication failed:', error.message);
-  // Check: Are credentials correct? Is baseUrl correct? Is network accessible?
-}
-```
-
-**Common causes:**
-
-1. **Missing retailerId**: Required for Fluent API authentication
-2. **Wrong baseUrl**: Should match your Fluent environment (production/staging/sandbox)
-3. **Expired credentials**: Password may have been changed in Fluent settings
-4. **Network issues**: Check if baseUrl is accessible from your environment
-5. **Wrong OAuth2 grant**: SDK uses password grant for standalone, connection-based auth for Versori
-
-**Debug checklist:**
-
-```bash
-# 1. Verify environment variables are set
-echo $FLUENT_CLIENT_ID
-echo $FLUENT_CLIENT_SECRET
-echo $FLUENT_USERNAME
-echo $FLUENT_RETAILER_ID
-
-# 2. Test API endpoint is accessible
-curl https://api.fluentcommerce.com/graphql
-
-# 3. Enable debug logging to see OAuth2 token exchange
-# (Add logger to client config as shown above)
-```
-
----
-
-### Error: `Cannot resolve path 'order.missing-field'`
-
-**Meaning:** Your mapping config path doesn't exist in your source data.
-
-**Fix in 3 steps:**
-
-```typescript
-// 1. Print your actual source data structure
-console.log('Source data:', JSON.stringify(sourceData, null, 2));
-
-// 2. Find the correct path in the output
-// Looking for "customer-email"? Search the JSON output
-
-// 3. Update your mapping config
-{
-  "email": {
-    "source": "order.customer.email", // ✅ Correct path from step 1
-    "required": true
-  }
-}
-```
-
-**Quick Debug:**
-
-```typescript
-// Add this before mapping
-import { get } from '@fluentcommerce/fc-connect-sdk';
-
-const value = get(sourceData, 'order.customer.email');
-console.log('Testing path:', value);
-// undefined = wrong path, value = correct path
-```
-
----
-
-### Error: `Required field 'ref' is missing or empty`
-
-**Meaning:** The field mapped successfully, but the value is null/undefined/empty string.
-
-**Fix:**
-
-```typescript
-// Option 1: Provide a default value
-{
-  "ref": {
-    "source": "order.ref",
-    "defaultValue": "ORDER-UNKNOWN" // ✅ Fallback if missing
-  }
-}
-
-// Option 2: Make it optional
-{
-  "ref": {
-    "source": "order.ref",
-    "required": false // ✅ Allow null/undefined
-  }
-}
-
-// Option 3: Transform empty to valid value
-{
-  "ref": {
-    "source": "order.ref",
-    "resolver": "sdk.coalesce", // ✅ Use first non-empty value
-    "resolverConfig": {
-      "values": ["order.ref", "order.id", "ORDER-FALLBACK"]
-    }
-  }
-}
-```
-
----
-
-### Error: `Expected array but got object at path 'items'`
-
-**Meaning:** Your source has a single object, but GraphQL expects an array.
-
-**Fix:**
-
-```typescript
-{
-  "items": {
-    "_array": true,
-    "_autoWrap": true, // ✅ Automatically wrap single objects into [object]
-    "source": "order.items"
-  }
-}
-```
-
-**Alternative - Always make it an array:**
-
-```typescript
-{
-  "items": {
-    "source": "order.items",
-    "resolver": "custom.ensureArray"
-  }
-}
-
-// Custom resolver
-const customResolvers = {
-  "custom.ensureArray": (value) => Array.isArray(value) ? value : [value]
-};
-```
-
----
-
-### Error: Custom Resolver Failed
-
-**Meaning:** Your custom resolver threw an error.
-
-**Fix - Add Defensive Coding:**
-
-```typescript
-// ❌ BAD - Will crash if value is null
-const badResolver = value => value.toUpperCase();
-
-// ✅ GOOD - Handle edge cases
-const goodResolver = value => {
-  if (value == null) return null; // Handle null/undefined
-  if (typeof value !== 'string') return String(value); // Coerce to string
-  return value.toUpperCase();
-};
-
-// ✅ BETTER - Use helpers
-const bestResolver = (value, sourceData, config, helpers) => {
-  const str = helpers.toString(value); // Safe conversion
-  return str ? str.toUpperCase() : null;
-};
-```
-
-**Debug Custom Resolvers:**
-
-```typescript
-const myResolver = (value, sourceData, config, helpers) => {
-  // Log everything
-  console.log('Resolver input:', { value, sourceData, config });
-
-  try {
-    const result = value.toUpperCase();
-    console.log('Resolver output:', result);
-    return result;
-  } catch (error) {
-    console.error('Resolver error:', error.message);
-    throw error; // Re-throw after logging
-  }
-};
-```
-
----
-
-### Error: `setAutoPadding(false) not supported for Aes128Gcm yet`
-
-**Meaning:** SFTP connection is failing on Versori platform (Deno runtime) because AES-GCM ciphers aren't supported.
-
-**Fix:** None needed! The SDK automatically detects Deno and uses compatible ciphers.
-
-**Just upgrade to SDK v0.1.7+:**
-
-```bash
-npm install @fluentcommerce/fc-connect-sdk@latest
-```
-
-**What the SDK does:**
-
-```typescript
-// Automatic - no configuration needed in your connector
-const sftp = new SftpDataSource(
-  {
-    settings: {
-      host: 's-xxxxx.server.transfer.amazonaws.com',
-      // SDK auto-detects Deno and configures compatible algorithms
-    },
-  },
-  logger
-);
-```
-
-**Verification:**
-Check logs for: `"Deno runtime detected - using compatible SFTP algorithms (NO GCM)"`
-
-**📖 Full details:** [Deno SFTP Compatibility Guide](../04-REFERENCE/troubleshooting/troubleshooting-deno-sftp-compatibility.md)
-
----
-
-## SFTP transient errors (timeouts, ECONNRESET)
-
-Symptoms:
-
-- Intermittent failures during SFTP upload/download/list
-
-Fix:
-
-- SDK includes built-in retries for SFTP operations (list, download, upload, delete, mkdir).
-- Configure via `settings.retry` on `SftpDataSource`:
-
-```typescript
-const sftp = new SftpDataSource(
-  {
-    type: 'SFTP_XML',
-    connectionId: 'sftp',
-    name: 'sftp',
-    settings: {
-      host,
-      port,
-      username,
-      password,
-      remotePath: '/upload',
-      filePattern: '*.xml',
-      retry: {
-        maxAttempts: 3,
-        baseDelayMs: 1000,
-        backoffFactor: 2,
-        maxDelayMs: 8000,
-        jitter: 'full',
-        reconnectOnFailure: true,
-      },
-    },
-  },
-  logger
-);
-```
-
-Notes:
-
-- Crypto/algorithm errors (e.g., AES-GCM unsupported) are not retryable.
-
----
-
-## S3 transient HTTP errors (503, 504, 429)
-
-Symptoms:
-
-- Occasional 5xx or 429 from S3 presigned URL requests
-
-Fix:
-
-- SDK applies exponential backoff retries around HTTP fetch for S3 operations.
-- Control attempts via `s3Config.maxAttempts` (default 3).
-
-```typescript
-const ds = new S3DataSource(
-  {
-    type: 'S3_JSON',
-    connectionId: 's3',
-    name: 's3',
-    settings: {},
-    s3Config: { accessKeyId, secretAccessKey, region, bucket, maxAttempts: 5 },
-  },
-  logger
-);
-```
-
----
-
-## ExtractionOrchestrator errors
-
-Symptoms:
-
-- `ExtractionOrchestrator.extract()` fails with path resolution errors
-- Data not extracted from nested GraphQL response
-
-Fix:
-
-**1. Verify `resultPath` matches your GraphQL response structure:**
-
-```typescript
-// ❌ WRONG - dataPath doesn't match response structure
-const result = await orchestrator.extract({
-  query: `query { inventoryPositions { edges { node { ref } } } }`,
-  resultPath: 'inventory.edges.node', // Wrong! Should be 'inventoryPositions.edges.node'
-});
-
-// ✅ CORRECT - dataPath matches response
-const result = await orchestrator.extract({
-  query: `query { inventoryPositions { edges { node { ref } } } }`,
-  resultPath: 'inventoryPositions.edges.node',
-});
-```
-
-**2. Enable debug logging to see extraction process:**
-
-```typescript
-import { createConsoleLogger, toStructuredLogger } from '@fluentcommerce/fc-connect-sdk';
-
-const logger = toStructuredLogger(createConsoleLogger(), {
-  logLevel: 'debug',
-});
-const orchestrator = new ExtractionOrchestrator(client, logger);
-
-// You'll see logs like:
-// [DEBUG] Extracting data from path: inventoryPositions
-// [DEBUG] Found 100 records in current page
-// [DEBUG] Processing page 2 of estimated 10 pages
-```
-
-**3. Check pagination configuration:**
-
-```typescript
-// For cursor-based pagination (most common)
-const result = await orchestrator.extract({
-  query: `query GetData($first: Int!, $after: String) { ... }`,
-  variables: { first: 100 },
-  maxRecords: 5000, // Stop after 5000 records
-});
-
-// Query MUST include pagination variables ($first, $after) for auto-pagination
-```
-
----
-
-## Webhook validation errors
-
-Symptoms:
-
-- `client.validateWebhook()` returns `false`
-- Signature verification failing for legitimate webhooks
-
-Fix:
-
-**1. Ensure you have the correct public key from Fluent:**
-
-```typescript
-// Get your public key from Fluent Commerce settings
-const FLUENT_WEBHOOK_PUBLIC_KEY = process.env.FLUENT_WEBHOOK_PUBLIC_KEY;
-
-// Configure client with public key
-const client = new FluentClient({
-  baseUrl: 'https://api.fluentcommerce.com',
-  clientId: process.env.FLUENT_CLIENT_ID,
-  clientSecret: process.env.FLUENT_CLIENT_SECRET,
-  username: process.env.FLUENT_USERNAME,
-  password: process.env.FLUENT_PASSWORD,
-  retailerId: process.env.FLUENT_RETAILER_ID,
-  publicKey: FLUENT_WEBHOOK_PUBLIC_KEY, // Add public key for webhook validation
-});
-
-// validateWebhook returns boolean
-const isValid = await client.validateWebhook(payload, signature, rawPayload);
-```
-
-**2. Verify you're passing the raw payload for signature validation:**
-
-```typescript
-// ✅ CORRECT - Pass signature and raw payload
-const signature = headers['fluent-signature'];
-const rawPayload = await request.text(); // Get raw body before parsing
-const payload = JSON.parse(rawPayload);
-
-const isValid = await client.validateWebhook(payload, signature, rawPayload);
-
-// ❌ WRONG - Missing signature or raw payload
-const payload = await request.json(); // Already parsed, can't verify signature
-const isValid = await client.validateWebhook(payload); // No signature check
-```
-
-**3. Check for payload modification:**
-
-```typescript
-// ❌ WRONG - Modifying payload before validation
-const payload = await request.json();
-payload.processed = true; // Modifying payload breaks signature!
-const isValid = await client.validateWebhook(payload);
-
-// ✅ CORRECT - Validate first, then modify
-const rawPayload = await request.text();
-const payload = JSON.parse(rawPayload);
-const isValid = await client.validateWebhook(payload, signature, rawPayload);
-if (isValid) {
-  payload.processed = true; // Now safe to modify
-}
-```
-
-**Documentation:** See [Webhook Validation Guide](../02-CORE-GUIDES/webhook-validation/webhook-validation-readme.md)
-
----
-
-## Partial batch recovery
-
-Symptoms:
-
-- Some records in a batch fail, but you want to retry only failures
-- Need to track which specific records failed in a large batch
-
-Fix:
-
-**Use PartialBatchRecovery service:**
-
-```typescript
-import { PartialBatchRecovery } from '@fluentcommerce/fc-connect-sdk';
-
-const recovery = new PartialBatchRecovery(client, logger);
-
-// Record failures during batch processing
-const failures: RecordFailure[] = [];
-
-for (const record of batchRecords) {
-  try {
-    await client.graphql({ query: mutation, variables: record });
-  } catch (error) {
-    failures.push({
-      record,
-      error: error.message,
-      attemptNumber: 1,
-    });
-  }
-}
-
-// Retry only failed records
-const recoveryResult = await recovery.retryFailedRecords({
-  jobId,
-  failures,
-  maxRetries: 3,
-  retryDelayMs: 1000,
-});
-
-console.log(`Recovered: ${recoveryResult.successCount}/${recoveryResult.totalAttempted}`);
-```
-
----
-
-## Job tracking issues
-
-Symptoms:
-
-- Need to track job lifecycle across multiple executions
-- Want to resume job from last checkpoint
-
-Fix:
-
-**Use JobTracker service:**
-
-```typescript
-import { JobTracker, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
-
-const kvAdapter = new VersoriKVAdapter(openKv());
-const jobTracker = new JobTracker(kvAdapter, logger);
-
-// Create or resume job
-const jobStatus = await jobTracker.getOrCreateJob({
-  jobId: 'daily-inventory-sync',
-  trigger: 'scheduled',
-});
-
-if (jobStatus.status === 'running') {
-  console.log('Job already running, skipping...');
-  return;
-}
-
-// Update job status
-await jobTracker.updateJobStatus('daily-inventory-sync', 'running');
-
-try {
-  // Your processing logic
-  await processInventory();
-
-  await jobTracker.updateJobStatus('daily-inventory-sync', 'completed');
-} catch (error) {
-  await jobTracker.updateJobStatus('daily-inventory-sync', 'failed', {
-    error: error.message,
-  });
-}
-```
-
----
-
-## Preflight validation failures
-
-Symptoms:
-
-- Want to validate configuration before execution
-- Need to check credentials, file access, etc. before running connector
-
-Fix:
-
-**Use PreflightValidator service:**
-
-```typescript
-import { PreflightValidator } from '@fluentcommerce/fc-connect-sdk';
-
-const validator = new PreflightValidator(logger);
-
-const validationResult = await validator.validate({
-  client,
-  s3Config: {
-    bucket: 'my-bucket',
-    region: 'us-east-1',
-    accessKeyId,
-    secretAccessKey,
-  },
-  checks: [
-    'fluent-auth', // Verify Fluent credentials
-    's3-access', // Verify S3 bucket access
-    'file-exists', // Check if source files exist
-  ],
-});
-
-if (!validationResult.success) {
-  console.error('Preflight validation failed:', validationResult.errors);
-  return;
-}
-
-// Safe to proceed with actual processing
-await runConnector();
-```
-
----
-
-## 🔍 Debugging Techniques
-
-### 1. Enable Debug Logging
-
-```typescript
-const logger = {
-  debug: (msg, meta) => console.log('[DEBUG]', msg, meta),
-  info: (msg, meta) => console.log('[INFO]', msg, meta),
-  warn: (msg, meta) => console.warn('[WARN]', msg, meta),
-  error: (msg, err, meta) => console.error('[ERROR]', msg, err, meta),
-};
-
-const mapper = new GraphQLMutationMapper(config, logger, { fluentClient: client });
-```
-
-**Output:**
-
-```
-[DEBUG] Processing node: radial { source: '...', parseAs: 'xml' }
-[DEBUG] Applying resolver 'sdk.uppercase' to field 'ref' { fieldPath: 'input.ref' }
-[INFO] Mapped order data { orderRef: 'ORDER-123' }
-```
-
----
-
-### 2. Inspect Intermediate Results
-
-```typescript
-// After parsing
-const parsed = await parser.parse(xmlString);
-console.log('Parsed data:', JSON.stringify(parsed, null, 2));
-
-// After mapping (before mutation)
-const result = await mapper.map(parsed);
-console.log('Mapped variables:', JSON.stringify(result.variables, null, 2));
-
-// The actual GraphQL that will be sent
-console.log('GraphQL mutation:', result.mutation);
-console.log('Variables:', JSON.stringify(result.variables, null, 2));
-```
-
----
-
-### 3. Test Paths Independently
-
-```typescript
-import { get } from '@fluentcommerce/fc-connect-sdk';
-
-const testPaths = [
-  'order.customer.email',
-  'order.items[0].sku',
-  'order@order-no', // XML attribute
-  '$radial.Order.Items.Item[]', // Node reference with array
-];
-
-testPaths.forEach(path => {
-  const value = get(sourceData, path);
-  console.log(`${path} = ${JSON.stringify(value)}`);
-});
-```
-
----
-
-### 4. Test Resolvers Independently
-
-```typescript
-import { sdkResolvers } from '@fluentcommerce/fc-connect-sdk';
-
-// Test SDK resolver
-const uppercase = sdkResolvers['sdk.uppercase'];
-console.log(uppercase('hello', {}, {}, {})); // "HELLO"
-
-// Test custom resolver
-const myResolver = customResolvers['custom.calculateTax'];
-const testValue = 100;
-const testSource = { country: 'US' };
-const result = myResolver(testValue, testSource, {}, {});
-console.log('Tax result:', result);
-```
-
----
-
-## 🛠️ Debugging Workflow (Step-by-Step)
-
-**When mapping fails, follow these steps:**
-
-### Step 1: Verify Source Data Structure
-
-```typescript
-// Save actual data to file for inspection
-fs.writeFileSync('debug-source.json', JSON.stringify(sourceData, null, 2));
-
-// Or log to console
-console.log('Source:', JSON.stringify(sourceData, null, 2));
-```
-
-✅ **Check:** Does the source data have the structure you expect?
-
----
-
-### Step 2: Test Paths
-
-```typescript
-import { get } from '@fluentcommerce/fc-connect-sdk';
-
-// Test each path from your mapping config
-const paths = ['order.ref', 'order.customer.email', 'order.items[]'];
-
-paths.forEach(path => {
-  console.log(`Testing ${path}:`, get(sourceData, path));
-});
-```
-
-✅ **Check:** Do all paths resolve to values (not `undefined`)?
-
----
-
-### Step 3: Test Resolvers
-
-```typescript
-// Test each custom resolver independently
-const value = 'test-value';
-const sourceData = {
-  /* your data */
-};
-
-try {
-  const result = customResolvers`'custom.myResolver'`;
-  console.log('Resolver output:', result);
-} catch (error) {
-  console.error('Resolver failed:', error.message);
-}
-```
-
-✅ **Check:** Do resolvers return expected values? Do they handle null/undefined?
-
----
-
-### Step 4: Enable Debug Logging
-
-```typescript
-const logger = {
-  debug: console.log,
-  info: console.log,
-  warn: console.warn,
-  error: console.error,
-};
-
-const mapper = new GraphQLMutationMapper(config, logger, { fluentClient: client });
-```
-
-✅ **Check:** What does the debug output show? Where does it fail?
-
----
-
-### Step 5: Inspect Generated Mutation
-
-```typescript
-const result = await mapper.map(sourceData);
-
-// Log the actual GraphQL that will be sent
-console.log('Mutation:', result.mutation);
-console.log('Variables:', JSON.stringify(result.variables, null, 2));
-
-// Save to file for detailed inspection
-fs.writeFileSync('debug-mutation.graphql', result.mutation);
-fs.writeFileSync('debug-variables.json', JSON.stringify(result.variables, null, 2));
-```
-
-✅ **Check:** Does the generated mutation match GraphQL schema? Are required fields present?
-
----
-
-## 📋 Quick Debugging Checklist
-
-Copy this checklist when troubleshooting:
-
-```
-□ Print source data structure to console/file
-□ Test each mapping path with get() function
-□ Verify required fields are not null/undefined
-□ Test custom resolvers independently
-□ Enable debug logging
-□ Check generated mutation syntax
-□ Verify variables match GraphQL schema types
-□ Test mutation in GraphQL playground first
-□ Check Fluent API error response for schema issues
-```
-
----
-
-## 🎯 Common Patterns & Solutions
-
-### Pattern: Conditional Field Mapping
-
-**Problem:** Only include field if condition is met.
-
-**Solution:**
-
-```typescript
-{
-  "priority": {
-    "source": "order.urgency",
-    "resolver": "custom.mapPriority"
-  }
-}
-
-// Resolver
-const customResolvers = {
-  "custom.mapPriority": (value) => {
-    if (value === 'RUSH') return 'HIGH';
-    if (value === 'STANDARD') return 'NORMAL';
-    return 'LOW'; // Default
-  }
-};
-```
-
----
-
-### Pattern: Combine Multiple Fields
-
-**Problem:** Create fullName from firstName + lastName.
-
-**Solution:**
-
-```typescript
-{
-  "fullName": {
-    "source": "customer",
-    "resolver": "custom.fullName"
-  }
-}
-
-// Resolver
-const customResolvers = {
-  "custom.fullName": (value, sourceData) => {
-    const { firstName, lastName } = value;
-    return `${firstName} ${lastName}`.trim();
-  }
-};
-```
-
----
-
-### Pattern: Lookup from API
-
-**Problem:** Get customer ID from email via API call.
-
-**Solution:**
-
-```typescript
-{
-  "customerId": {
-    "source": "customer.email",
-    "resolver": "custom.lookupCustomer"
-  }
-}
-
-// Resolver (async allowed!)
-const customResolvers = {
-  "custom.lookupCustomer": async (email, sourceData, config, helpers) => {
-    const client = helpers.fluentClient;
-    if (!client) throw new Error('FluentClient not available in helpers');
-
-    const result = await client.graphql({
-      query: `query GetCustomer($email: String!) {
-        customers(email: $email) {
-          edges { node { id } }
-        }
-      }`,
-      variables: { email }
-    });
-
-    return result.data.customers.edges[0]?.node.id || null;
-  }
-};
-```
-
----
-
-### Pattern: Transform Array Items
-
-**Problem:** Transform each item in an array.
-
-**Solution:**
-
-```typescript
-{
-  "items": {
-    "_array": true,
-    "source": "order.items",
-    "fields": {
-      "sku": { "source": "product-id" },
-      "quantity": {
-        "source": "qty",
-        "resolver": "sdk.parseInt" // Transform each item's qty
-      }
-    }
-  }
-}
-```
-
----
-
-## 💡 Pro Tips
-
-### Tip 1: Use Safe Helpers
-
-```typescript
-// ❌ Don't do this
-const value = data.order.customer.email; // Crashes if order is null
-
-// ✅ Use get() helper
-import { get } from '@fluentcommerce/fc-connect-sdk';
-const value = get(data, 'order.customer.email'); // Returns undefined safely
-
-// Or use helpers.get() in resolvers
-const value = helpers.get(data, 'order.customer.email');
-```
-
-### Tip 2: Always Validate Resolver Inputs
-
-```typescript
-const myResolver = (value, sourceData, config, helpers) => {
-  // Validate inputs
-  if (value == null) {
-    helpers.logger?.warn('Resolver received null value');
-    return null;
-  }
-
-  // Your logic
-  return value.toUpperCase();
-};
-```
-
-### Tip 3: Use defaultValue for Required Fields
-
-```typescript
-// Instead of crashing on missing data
-{
-  "ref": {
-    "source": "order.ref",
-    "required": true,
-    "defaultValue": () => `ORDER-${Date.now()}` // Generate if missing
-  }
-}
-```
-
-### Tip 4: Save Intermediate Results
-
-```typescript
-// Add to your workflow for debugging
-fs.writeFileSync('01-source-data.json', JSON.stringify(sourceData, null, 2));
-fs.writeFileSync('02-mapped-variables.json', JSON.stringify(result.variables, null, 2));
-fs.writeFileSync('03-mutation.graphql', result.mutation);
-fs.writeFileSync('04-response.json', JSON.stringify(response, null, 2));
-```
-
----
-
-## 🔗 Related Documentation
-
-- [Error Handling Guide](../02-CORE-GUIDES/mapping/graphql-mutation-mapping/modules/graphql-mutation-mapping-11-error-handling.md) - Complete error reference
-- [Custom Resolvers Guide](../02-CORE-GUIDES/mapping/resolvers/mapping-resolvers-resolver-guide.md) - How to write resolvers
-- [Path Syntax Reference](../02-CORE-GUIDES/mapping/graphql-mutation-mapping/modules/graphql-mutation-mapping-06-path-syntax.md) - Understanding paths
-- [Decision Tree](./decision-tree.md) - Which approach to use
-
----
-
-## 📞 Still Stuck?
-
-If you've tried everything above and still have issues:
-
-1. **Check Examples:** Look in `docs/01-TEMPLATES/` for similar scenarios
-2. **Enable Full Debug Logging:** Capture all SDK output
-3. **Save All Intermediate Data:** Source → Parsed → Mapped → Response
-4. **Test in Isolation:** Remove resolvers, simplify mapping, add back one at a time
-5. **Check GraphQL Schema:** Validate mutation in GraphQL playground first
-
-**Remember:** 90% of issues are path resolution or null values. Start there!
+# Troubleshooting Quick Reference
+
+**When things don't work - start here**
+
+## 📋 Quick Logger Setup
+
+**Versori Platform** - Use native `log` from context:
+```typescript
+const { log } = ctx; // Native Versori logger
+const client = await createClient({ ...ctx, log });
+```
+
+**Standalone (Node.js/Deno)** - Use minimal utilities:
+```typescript
+import { createConsoleLogger, toStructuredLogger } from '@fluentcommerce/fc-connect-sdk';
+
+const logger = toStructuredLogger(createConsoleLogger(), { logLevel: 'debug' });
+const client = await createClient({ config: { ...config, logger } });
+```
+
+**Minimal logger snippet** (when you need Logger interface):
+```typescript
+const logger: import('@fluentcommerce/fc-connect-sdk').Logger = {
+  debug: (m, meta) => log.debug(m, meta),
+  info: (m, meta) => log.info(m, meta),
+  warn: (m, meta) => log.warn(m, meta),
+  error: (m, err, meta) => log.error(m, { ...(meta ?? {}), error: err?.message }),
+};
+```
+
+## 🚨 Common Errors & Fixes (90% of Issues)
+
+### Error: `invalid key` from NATS KV (VersoriFileTracker / KV keys)
+
+**Meaning:** Your KV key contains characters not allowed by NATS KV (e.g. `:` or spaces/brackets/parentheses).
+
+**Allowed characters:** `a-z A-Z 0-9 _ - . = /`
+
+**Fix (SDK ≥ current):** `VersoriFileTracker` now uses NATS-safe keys (slash-separated prefix and filename sanitization). Just pass the raw filename; the tracker will sanitize internally.
+
+```typescript
+import { VersoriFileTracker } from '@fluentcommerce/fc-connect-sdk';
+
+const tracker = new VersoriFileTracker(openKv(':project:'), 'fc-sdk');
+
+// Raw basename is OK; tracker sanitizes to NATS-safe key
+const alreadyProcessed = await tracker.wasFileProcessed('[SAMPLE] - file (1).xml');
+if (!alreadyProcessed) {
+  // ... process ...
+  await tracker.markFileProcessed('[SAMPLE] - file (1).xml', { recordCount: 123 });
+}
+```
+
+**Workaround:** Use your own dot/slash-separated keys and sanitize names before KV get/set.
+
+```typescript
+const safe = (name: string) => name.replace(/[^A-Za-z0-9._=\/-]/g, '_');
+await kv.set(`fc_sdk.processed_files.${safe(baseName)}`, { processedAt: new Date().toISOString() });
+```
+
+---
+
+### Error: `Buffer is not defined` (Deno/Versori runtime)
+
+**Meaning:** You're using `Buffer.from()` or `Buffer.alloc()` but haven't imported Buffer in Deno/Versori runtime.
+
+**Why:** Unlike Node.js, Deno doesn't have `Buffer` as a global. You must explicitly import it from Node.js built-ins.
+
+**Fix:** Add the import at the top of your file (before SDK imports):
+
+```typescript
+// ✅ CORRECT - Import Buffer for Deno/Versori
+import { Buffer } from 'node:buffer';
+import {
+  createClient,
+  SftpDataSource,
+  XMLBuilder,
+} from '@fluentcommerce/fc-connect-sdk';
+
+// Now Buffer works
+const xmlContent = '<VirtualPositions>...</VirtualPositions>';
+await sftp.uploadFile('/path/to/file.xml', Buffer.from(xmlContent, 'utf8'));
+
+// Decode base64 credentials
+const decoded = Buffer.from(base64String, 'base64').toString('utf-8');
+```
+
+**Common use cases requiring Buffer import:**
+- SFTP uploads: `Buffer.from(content, 'utf8')`
+- Base64 decode: `Buffer.from(str, 'base64').toString('utf-8')`
+- Binary data: `Buffer.from(data)`
+- Encoding conversion: `Buffer.from(str, 'latin1').toString('utf8')`
+
+**Note:** All SDK templates (v0.1.22+) include this import automatically. If you're using templates from earlier versions, add it manually.
+
+---
+
+### Error: GraphQL errors from Fluent Commerce API
+
+**Meaning:** The GraphQL mutation returned errors (e.g., order already exists, missing required field, server error).
+
+**Fix:** Use error classification to determine if error is retryable:
+
+```typescript
+import { classifyErrors } from '@fluentcommerce/fc-connect-sdk';
+
+const result = await client.graphql({ query, variables });
+
+if (result.errors) {
+  const classification = classifyErrors(result.errors);
+  
+  log.error('GraphQL error:', {
+    errorCode: classification.errorCode,
+    retryable: classification.retryable,
+    action: classification.action,
+    message: classification.userMessage,
+  });
+  
+  // Don't retry non-retryable errors (e.g., C0121E = order already exists)
+  if (!classification.retryable) {
+    throw new Error(classification.userMessage);
+  }
+  
+  // Retry retryable errors (e.g., S0002E = server error)
+  if (classification.retryable) {
+    await delay(classification.retryDelaySeconds * 1000);
+    // retry logic...
+  }
+}
+```
+
+**Common Error Codes:**
+- **C0121E** - Order already exists (non-retryable, verify payload)
+- **C0140E** - Missing required variables (non-retryable, fix payload)
+- **S0002E** - Server error (retryable, retry later)
+- **C0011E** - Rate limit exceeded (retryable, wait and retry)
+
+See [GraphQL Error Classification Guide](../02-CORE-GUIDES/api-reference/graphql-error-classification.md) for complete error code reference.
+
+---
+
+### Error: `OAuth2 authentication failed` or `Token refresh failed`
+
+**Meaning:** Your Fluent API credentials are invalid or the OAuth2 token exchange is failing.
+
+**Why:** Common causes include wrong credentials, expired credentials, network issues, or incorrect OAuth2 endpoint.
+
+**Fix:**
+
+```typescript
+// ✅ CORRECT - Verify all required credentials are set
+const client = new FluentClient({
+  baseUrl: 'https://api.fluentcommerce.com', // Or your environment URL
+  clientId: process.env.FLUENT_CLIENT_ID,
+  clientSecret: process.env.FLUENT_CLIENT_SECRET,
+  username: process.env.FLUENT_USERNAME,
+  password: process.env.FLUENT_PASSWORD,
+  retailerId: process.env.FLUENT_RETAILER_ID, // Required!
+  logger, // Enable logging to see authentication details
+});
+
+// Test authentication
+try {
+  const result = await client.graphql({
+    query: 'query { viewer { id } }',
+  });
+  console.log('Authentication successful:', result);
+} catch (error) {
+  console.error('Authentication failed:', error.message);
+  // Check: Are credentials correct? Is baseUrl correct? Is network accessible?
+}
+```
+
+**Common causes:**
+
+1. **Missing retailerId**: Required for Fluent API authentication
+2. **Wrong baseUrl**: Should match your Fluent environment (production/staging/sandbox)
+3. **Expired credentials**: Password may have been changed in Fluent settings
+4. **Network issues**: Check if baseUrl is accessible from your environment
+5. **Wrong OAuth2 grant**: SDK uses password grant for standalone, connection-based auth for Versori
+
+**Debug checklist:**
+
+```bash
+# 1. Verify environment variables are set
+echo $FLUENT_CLIENT_ID
+echo $FLUENT_CLIENT_SECRET
+echo $FLUENT_USERNAME
+echo $FLUENT_RETAILER_ID
+
+# 2. Test API endpoint is accessible
+curl https://api.fluentcommerce.com/graphql
+
+# 3. Enable debug logging to see OAuth2 token exchange
+# (Add logger to client config as shown above)
+```
+
+---
+
+### Error: `Cannot resolve path 'order.missing-field'`
+
+**Meaning:** Your mapping config path doesn't exist in your source data.
+
+**Fix in 3 steps:**
+
+```typescript
+// 1. Print your actual source data structure
+console.log('Source data:', JSON.stringify(sourceData, null, 2));
+
+// 2. Find the correct path in the output
+// Looking for "customer-email"? Search the JSON output
+
+// 3. Update your mapping config
+{
+  "email": {
+    "source": "order.customer.email", // ✅ Correct path from step 1
+    "required": true
+  }
+}
+```
+
+**Quick Debug:**
+
+```typescript
+// Add this before mapping
+import { get } from '@fluentcommerce/fc-connect-sdk';
+
+const value = get(sourceData, 'order.customer.email');
+console.log('Testing path:', value);
+// undefined = wrong path, value = correct path
+```
+
+---
+
+### Error: `Required field 'ref' is missing or empty`
+
+**Meaning:** The field mapped successfully, but the value is null/undefined/empty string.
+
+**Fix:**
+
+```typescript
+// Option 1: Provide a default value
+{
+  "ref": {
+    "source": "order.ref",
+    "defaultValue": "ORDER-UNKNOWN" // ✅ Fallback if missing
+  }
+}
+
+// Option 2: Make it optional
+{
+  "ref": {
+    "source": "order.ref",
+    "required": false // ✅ Allow null/undefined
+  }
+}
+
+// Option 3: Transform empty to valid value
+{
+  "ref": {
+    "source": "order.ref",
+    "resolver": "sdk.coalesce", // ✅ Use first non-empty value
+    "resolverConfig": {
+      "values": ["order.ref", "order.id", "ORDER-FALLBACK"]
+    }
+  }
+}
+```
+
+---
+
+### Error: `Expected array but got object at path 'items'`
+
+**Meaning:** Your source has a single object, but GraphQL expects an array.
+
+**Fix:**
+
+```typescript
+{
+  "items": {
+    "_array": true,
+    "_autoWrap": true, // ✅ Automatically wrap single objects into [object]
+    "source": "order.items"
+  }
+}
+```
+
+**Alternative - Always make it an array:**
+
+```typescript
+{
+  "items": {
+    "source": "order.items",
+    "resolver": "custom.ensureArray"
+  }
+}
+
+// Custom resolver
+const customResolvers = {
+  "custom.ensureArray": (value) => Array.isArray(value) ? value : [value]
+};
+```
+
+---
+
+### Error: Custom Resolver Failed
+
+**Meaning:** Your custom resolver threw an error.
+
+**Fix - Add Defensive Coding:**
+
+```typescript
+// ❌ BAD - Will crash if value is null
+const badResolver = value => value.toUpperCase();
+
+// ✅ GOOD - Handle edge cases
+const goodResolver = value => {
+  if (value == null) return null; // Handle null/undefined
+  if (typeof value !== 'string') return String(value); // Coerce to string
+  return value.toUpperCase();
+};
+
+// ✅ BETTER - Use helpers
+const bestResolver = (value, sourceData, config, helpers) => {
+  const str = helpers.toString(value); // Safe conversion
+  return str ? str.toUpperCase() : null;
+};
+```
+
+**Debug Custom Resolvers:**
+
+```typescript
+const myResolver = (value, sourceData, config, helpers) => {
+  // Log everything
+  console.log('Resolver input:', { value, sourceData, config });
+
+  try {
+    const result = value.toUpperCase();
+    console.log('Resolver output:', result);
+    return result;
+  } catch (error) {
+    console.error('Resolver error:', error.message);
+    throw error; // Re-throw after logging
+  }
+};
+```
+
+---
+
+### Error: `setAutoPadding(false) not supported for Aes128Gcm yet`
+
+**Meaning:** SFTP connection is failing on Versori platform (Deno runtime) because AES-GCM ciphers aren't supported.
+
+**Fix:** None needed! The SDK automatically detects Deno and uses compatible ciphers.
+
+**Just upgrade to SDK v0.1.7+:**
+
+```bash
+npm install @fluentcommerce/fc-connect-sdk@latest
+```
+
+**What the SDK does:**
+
+```typescript
+// Automatic - no configuration needed in your connector
+const sftp = new SftpDataSource(
+  {
+    settings: {
+      host: 's-xxxxx.server.transfer.amazonaws.com',
+      // SDK auto-detects Deno and configures compatible algorithms
+    },
+  },
+  logger
+);
+```
+
+**Verification:**
+Check logs for: `"Deno runtime detected - using compatible SFTP algorithms (NO GCM)"`
+
+**📖 Full details:** [Deno SFTP Compatibility Guide](../04-REFERENCE/troubleshooting/troubleshooting-deno-sftp-compatibility.md)
+
+---
+
+## SFTP transient errors (timeouts, ECONNRESET)
+
+Symptoms:
+
+- Intermittent failures during SFTP upload/download/list
+
+Fix:
+
+- SDK includes built-in retries for SFTP operations (list, download, upload, delete, mkdir).
+- Configure via `settings.retry` on `SftpDataSource`:
+
+```typescript
+const sftp = new SftpDataSource(
+  {
+    type: 'SFTP_XML',
+    connectionId: 'sftp',
+    name: 'sftp',
+    settings: {
+      host,
+      port,
+      username,
+      password,
+      remotePath: '/upload',
+      filePattern: '*.xml',
+      retry: {
+        maxAttempts: 3,
+        baseDelayMs: 1000,
+        backoffFactor: 2,
+        maxDelayMs: 8000,
+        jitter: 'full',
+        reconnectOnFailure: true,
+      },
+    },
+  },
+  logger
+);
+```
+
+Notes:
+
+- Crypto/algorithm errors (e.g., AES-GCM unsupported) are not retryable.
+
+---
+
+## S3 transient HTTP errors (503, 504, 429)
+
+Symptoms:
+
+- Occasional 5xx or 429 from S3 presigned URL requests
+
+Fix:
+
+- SDK applies exponential backoff retries around HTTP fetch for S3 operations.
+- Control attempts via `s3Config.maxAttempts` (default 3).
+
+```typescript
+const ds = new S3DataSource(
+  {
+    type: 'S3_JSON',
+    connectionId: 's3',
+    name: 's3',
+    settings: {},
+    s3Config: { accessKeyId, secretAccessKey, region, bucket, maxAttempts: 5 },
+  },
+  logger
+);
+```
+
+---
+
+## ExtractionOrchestrator errors
+
+Symptoms:
+
+- `ExtractionOrchestrator.extract()` fails with path resolution errors
+- Data not extracted from nested GraphQL response
+
+Fix:
+
+**1. Verify `resultPath` matches your GraphQL response structure:**
+
+```typescript
+// ❌ WRONG - dataPath doesn't match response structure
+const result = await orchestrator.extract({
+  query: `query { inventoryPositions { edges { node { ref } } } }`,
+  resultPath: 'inventory.edges.node', // Wrong! Should be 'inventoryPositions.edges.node'
+});
+
+// ✅ CORRECT - dataPath matches response
+const result = await orchestrator.extract({
+  query: `query { inventoryPositions { edges { node { ref } } } }`,
+  resultPath: 'inventoryPositions.edges.node',
+});
+```
+
+**2. Enable debug logging to see extraction process:**
+
+```typescript
+import { createConsoleLogger, toStructuredLogger } from '@fluentcommerce/fc-connect-sdk';
+
+const logger = toStructuredLogger(createConsoleLogger(), {
+  logLevel: 'debug',
+});
+const orchestrator = new ExtractionOrchestrator(client, logger);
+
+// You'll see logs like:
+// [DEBUG] Extracting data from path: inventoryPositions
+// [DEBUG] Found 100 records in current page
+// [DEBUG] Processing page 2 of estimated 10 pages
+```
+
+**3. Check pagination configuration:**
+
+```typescript
+// For cursor-based pagination (most common)
+const result = await orchestrator.extract({
+  query: `query GetData($first: Int!, $after: String) { ... }`,
+  variables: { first: 100 },
+  maxRecords: 5000, // Stop after 5000 records
+});
+
+// Query MUST include pagination variables ($first, $after) for auto-pagination
+```
+
+---
+
+## Webhook validation errors
+
+Symptoms:
+
+- `client.validateWebhook()` returns `false`
+- Signature verification failing for legitimate webhooks
+
+Fix:
+
+**1. Ensure you have the correct public key from Fluent:**
+
+```typescript
+// Get your public key from Fluent Commerce settings
+const FLUENT_WEBHOOK_PUBLIC_KEY = process.env.FLUENT_WEBHOOK_PUBLIC_KEY;
+
+// Configure client with public key
+const client = new FluentClient({
+  baseUrl: 'https://api.fluentcommerce.com',
+  clientId: process.env.FLUENT_CLIENT_ID,
+  clientSecret: process.env.FLUENT_CLIENT_SECRET,
+  username: process.env.FLUENT_USERNAME,
+  password: process.env.FLUENT_PASSWORD,
+  retailerId: process.env.FLUENT_RETAILER_ID,
+  publicKey: FLUENT_WEBHOOK_PUBLIC_KEY, // Add public key for webhook validation
+});
+
+// validateWebhook returns boolean
+const isValid = await client.validateWebhook(payload, signature, rawPayload);
+```
+
+**2. Verify you're passing the raw payload for signature validation:**
+
+```typescript
+// ✅ CORRECT - Pass signature and raw payload
+const signature = headers['fluent-signature'];
+const rawPayload = await request.text(); // Get raw body before parsing
+const payload = JSON.parse(rawPayload);
+
+const isValid = await client.validateWebhook(payload, signature, rawPayload);
+
+// ❌ WRONG - Missing signature or raw payload
+const payload = await request.json(); // Already parsed, can't verify signature
+const isValid = await client.validateWebhook(payload); // No signature check
+```
+
+**3. Check for payload modification:**
+
+```typescript
+// ❌ WRONG - Modifying payload before validation
+const payload = await request.json();
+payload.processed = true; // Modifying payload breaks signature!
+const isValid = await client.validateWebhook(payload);
+
+// ✅ CORRECT - Validate first, then modify
+const rawPayload = await request.text();
+const payload = JSON.parse(rawPayload);
+const isValid = await client.validateWebhook(payload, signature, rawPayload);
+if (isValid) {
+  payload.processed = true; // Now safe to modify
+}
+```
+
+**Documentation:** See [Webhook Validation Guide](../02-CORE-GUIDES/webhook-validation/webhook-validation-readme.md)
+
+---
+
+## Partial batch recovery
+
+Symptoms:
+
+- Some records in a batch fail, but you want to retry only failures
+- Need to track which specific records failed in a large batch
+
+Fix:
+
+**Use PartialBatchRecovery service:**
+
+```typescript
+import { PartialBatchRecovery } from '@fluentcommerce/fc-connect-sdk';
+
+const recovery = new PartialBatchRecovery(client, logger);
+
+// Record failures during batch processing
+const failures: RecordFailure[] = [];
+
+for (const record of batchRecords) {
+  try {
+    await client.graphql({ query: mutation, variables: record });
+  } catch (error) {
+    failures.push({
+      record,
+      error: error.message,
+      attemptNumber: 1,
+    });
+  }
+}
+
+// Retry only failed records
+const recoveryResult = await recovery.retryFailedRecords({
+  jobId,
+  failures,
+  maxRetries: 3,
+  retryDelayMs: 1000,
+});
+
+console.log(`Recovered: ${recoveryResult.successCount}/${recoveryResult.totalAttempted}`);
+```
+
+---
+
+## Job tracking issues
+
+Symptoms:
+
+- Need to track job lifecycle across multiple executions
+- Want to resume job from last checkpoint
+
+Fix:
+
+**Use JobTracker service:**
+
+```typescript
+import { JobTracker, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
+
+const kvAdapter = new VersoriKVAdapter(openKv());
+const jobTracker = new JobTracker(kvAdapter, logger);
+
+// Create or resume job
+const jobStatus = await jobTracker.getOrCreateJob({
+  jobId: 'daily-inventory-sync',
+  trigger: 'scheduled',
+});
+
+if (jobStatus.status === 'running') {
+  console.log('Job already running, skipping...');
+  return;
+}
+
+// Update job status
+await jobTracker.updateJobStatus('daily-inventory-sync', 'running');
+
+try {
+  // Your processing logic
+  await processInventory();
+
+  await jobTracker.updateJobStatus('daily-inventory-sync', 'completed');
+} catch (error) {
+  await jobTracker.updateJobStatus('daily-inventory-sync', 'failed', {
+    error: error.message,
+  });
+}
+```
+
+---
+
+## Preflight validation failures
+
+Symptoms:
+
+- Want to validate configuration before execution
+- Need to check credentials, file access, etc. before running connector
+
+Fix:
+
+**Use PreflightValidator service:**
+
+```typescript
+import { PreflightValidator } from '@fluentcommerce/fc-connect-sdk';
+
+const validator = new PreflightValidator(logger);
+
+const validationResult = await validator.validate({
+  client,
+  s3Config: {
+    bucket: 'my-bucket',
+    region: 'us-east-1',
+    accessKeyId,
+    secretAccessKey,
+  },
+  checks: [
+    'fluent-auth', // Verify Fluent credentials
+    's3-access', // Verify S3 bucket access
+    'file-exists', // Check if source files exist
+  ],
+});
+
+if (!validationResult.success) {
+  console.error('Preflight validation failed:', validationResult.errors);
+  return;
+}
+
+// Safe to proceed with actual processing
+await runConnector();
+```
+
+---
+
+## 🔍 Debugging Techniques
+
+### 1. Enable Debug Logging
+
+```typescript
+const logger = {
+  debug: (msg, meta) => console.log('[DEBUG]', msg, meta),
+  info: (msg, meta) => console.log('[INFO]', msg, meta),
+  warn: (msg, meta) => console.warn('[WARN]', msg, meta),
+  error: (msg, err, meta) => console.error('[ERROR]', msg, err, meta),
+};
+
+const mapper = new GraphQLMutationMapper(config, logger, { fluentClient: client });
+```
+
+**Output:**
+
+```
+[DEBUG] Processing node: radial { source: '...', parseAs: 'xml' }
+[DEBUG] Applying resolver 'sdk.uppercase' to field 'ref' { fieldPath: 'input.ref' }
+[INFO] Mapped order data { orderRef: 'ORDER-123' }
+```
+
+---
+
+### 2. Inspect Intermediate Results
+
+```typescript
+// After parsing
+const parsed = await parser.parse(xmlString);
+console.log('Parsed data:', JSON.stringify(parsed, null, 2));
+
+// After mapping (before mutation)
+const result = await mapper.map(parsed);
+console.log('Mapped variables:', JSON.stringify(result.variables, null, 2));
+
+// The actual GraphQL that will be sent
+console.log('GraphQL mutation:', result.mutation);
+console.log('Variables:', JSON.stringify(result.variables, null, 2));
+```
+
+---
+
+### 3. Test Paths Independently
+
+```typescript
+import { get } from '@fluentcommerce/fc-connect-sdk';
+
+const testPaths = [
+  'order.customer.email',
+  'order.items[0].sku',
+  'order@order-no', // XML attribute
+  '$radial.Order.Items.Item[]', // Node reference with array
+];
+
+testPaths.forEach(path => {
+  const value = get(sourceData, path);
+  console.log(`${path} = ${JSON.stringify(value)}`);
+});
+```
+
+---
+
+### 4. Test Resolvers Independently
+
+```typescript
+import { sdkResolvers } from '@fluentcommerce/fc-connect-sdk';
+
+// Test SDK resolver
+const uppercase = sdkResolvers['sdk.uppercase'];
+console.log(uppercase('hello', {}, {}, {})); // "HELLO"
+
+// Test custom resolver
+const myResolver = customResolvers['custom.calculateTax'];
+const testValue = 100;
+const testSource = { country: 'US' };
+const result = myResolver(testValue, testSource, {}, {});
+console.log('Tax result:', result);
+```
+
+---
+
+## 🛠️ Debugging Workflow (Step-by-Step)
+
+**When mapping fails, follow these steps:**
+
+### Step 1: Verify Source Data Structure
+
+```typescript
+// Save actual data to file for inspection
+fs.writeFileSync('debug-source.json', JSON.stringify(sourceData, null, 2));
+
+// Or log to console
+console.log('Source:', JSON.stringify(sourceData, null, 2));
+```
+
+✅ **Check:** Does the source data have the structure you expect?
+
+---
+
+### Step 2: Test Paths
+
+```typescript
+import { get } from '@fluentcommerce/fc-connect-sdk';
+
+// Test each path from your mapping config
+const paths = ['order.ref', 'order.customer.email', 'order.items[]'];
+
+paths.forEach(path => {
+  console.log(`Testing ${path}:`, get(sourceData, path));
+});
+```
+
+✅ **Check:** Do all paths resolve to values (not `undefined`)?
+
+---
+
+### Step 3: Test Resolvers
+
+```typescript
+// Test each custom resolver independently
+const value = 'test-value';
+const sourceData = {
+  /* your data */
+};
+
+try {
+  const result = customResolvers`'custom.myResolver'`;
+  console.log('Resolver output:', result);
+} catch (error) {
+  console.error('Resolver failed:', error.message);
+}
+```
+
+✅ **Check:** Do resolvers return expected values? Do they handle null/undefined?
+
+---
+
+### Step 4: Enable Debug Logging
+
+```typescript
+const logger = {
+  debug: console.log,
+  info: console.log,
+  warn: console.warn,
+  error: console.error,
+};
+
+const mapper = new GraphQLMutationMapper(config, logger, { fluentClient: client });
+```
+
+✅ **Check:** What does the debug output show? Where does it fail?
+
+---
+
+### Step 5: Inspect Generated Mutation
+
+```typescript
+const result = await mapper.map(sourceData);
+
+// Log the actual GraphQL that will be sent
+console.log('Mutation:', result.mutation);
+console.log('Variables:', JSON.stringify(result.variables, null, 2));
+
+// Save to file for detailed inspection
+fs.writeFileSync('debug-mutation.graphql', result.mutation);
+fs.writeFileSync('debug-variables.json', JSON.stringify(result.variables, null, 2));
+```
+
+✅ **Check:** Does the generated mutation match GraphQL schema? Are required fields present?
+
+---
+
+## 📋 Quick Debugging Checklist
+
+Copy this checklist when troubleshooting:
+
+```
+□ Print source data structure to console/file
+□ Test each mapping path with get() function
+□ Verify required fields are not null/undefined
+□ Test custom resolvers independently
+□ Enable debug logging
+□ Check generated mutation syntax
+□ Verify variables match GraphQL schema types
+□ Test mutation in GraphQL playground first
+□ Check Fluent API error response for schema issues
+```
+
+---
+
+## 🎯 Common Patterns & Solutions
+
+### Pattern: Conditional Field Mapping
+
+**Problem:** Only include field if condition is met.
+
+**Solution:**
+
+```typescript
+{
+  "priority": {
+    "source": "order.urgency",
+    "resolver": "custom.mapPriority"
+  }
+}
+
+// Resolver
+const customResolvers = {
+  "custom.mapPriority": (value) => {
+    if (value === 'RUSH') return 'HIGH';
+    if (value === 'STANDARD') return 'NORMAL';
+    return 'LOW'; // Default
+  }
+};
+```
+
+---
+
+### Pattern: Combine Multiple Fields
+
+**Problem:** Create fullName from firstName + lastName.
+
+**Solution:**
+
+```typescript
+{
+  "fullName": {
+    "source": "customer",
+    "resolver": "custom.fullName"
+  }
+}
+
+// Resolver
+const customResolvers = {
+  "custom.fullName": (value, sourceData) => {
+    const { firstName, lastName } = value;
+    return `${firstName} ${lastName}`.trim();
+  }
+};
+```
+
+---
+
+### Pattern: Lookup from API
+
+**Problem:** Get customer ID from email via API call.
+
+**Solution:**
+
+```typescript
+{
+  "customerId": {
+    "source": "customer.email",
+    "resolver": "custom.lookupCustomer"
+  }
+}
+
+// Resolver (async allowed!)
+const customResolvers = {
+  "custom.lookupCustomer": async (email, sourceData, config, helpers) => {
+    const client = helpers.fluentClient;
+    if (!client) throw new Error('FluentClient not available in helpers');
+
+    const result = await client.graphql({
+      query: `query GetCustomer($email: String!) {
+        customers(email: $email) {
+          edges { node { id } }
+        }
+      }`,
+      variables: { email }
+    });
+
+    return result.data.customers.edges[0]?.node.id || null;
+  }
+};
+```
+
+---
+
+### Pattern: Transform Array Items
+
+**Problem:** Transform each item in an array.
+
+**Solution:**
+
+```typescript
+{
+  "items": {
+    "_array": true,
+    "source": "order.items",
+    "fields": {
+      "sku": { "source": "product-id" },
+      "quantity": {
+        "source": "qty",
+        "resolver": "sdk.parseInt" // Transform each item's qty
+      }
+    }
+  }
+}
+```
+
+---
+
+## 💡 Pro Tips
+
+### Tip 1: Use Safe Helpers
+
+```typescript
+// ❌ Don't do this
+const value = data.order.customer.email; // Crashes if order is null
+
+// ✅ Use get() helper
+import { get } from '@fluentcommerce/fc-connect-sdk';
+const value = get(data, 'order.customer.email'); // Returns undefined safely
+
+// Or use helpers.get() in resolvers
+const value = helpers.get(data, 'order.customer.email');
+```
+
+### Tip 2: Always Validate Resolver Inputs
+
+```typescript
+const myResolver = (value, sourceData, config, helpers) => {
+  // Validate inputs
+  if (value == null) {
+    helpers.logger?.warn('Resolver received null value');
+    return null;
+  }
+
+  // Your logic
+  return value.toUpperCase();
+};
+```
+
+### Tip 3: Use defaultValue for Required Fields
+
+```typescript
+// Instead of crashing on missing data
+{
+  "ref": {
+    "source": "order.ref",
+    "required": true,
+    "defaultValue": () => `ORDER-${Date.now()}` // Generate if missing
+  }
+}
+```
+
+### Tip 4: Save Intermediate Results
+
+```typescript
+// Add to your workflow for debugging
+fs.writeFileSync('01-source-data.json', JSON.stringify(sourceData, null, 2));
+fs.writeFileSync('02-mapped-variables.json', JSON.stringify(result.variables, null, 2));
+fs.writeFileSync('03-mutation.graphql', result.mutation);
+fs.writeFileSync('04-response.json', JSON.stringify(response, null, 2));
+```
+
+---
+
+## 🔗 Related Documentation
+
+- [Error Handling Guide](../02-CORE-GUIDES/mapping/graphql-mutation-mapping/modules/graphql-mutation-mapping-11-error-handling.md) - Complete error reference
+- [Custom Resolvers Guide](../02-CORE-GUIDES/mapping/resolvers/mapping-resolvers-resolver-guide.md) - How to write resolvers
+- [Path Syntax Reference](../02-CORE-GUIDES/mapping/graphql-mutation-mapping/modules/graphql-mutation-mapping-06-path-syntax.md) - Understanding paths
+- [Decision Tree](./decision-tree.md) - Which approach to use
+
+---
+
+## 📞 Still Stuck?
+
+If you've tried everything above and still have issues:
+
+1. **Check Examples:** Look in `docs/01-TEMPLATES/` for similar scenarios
+2. **Enable Full Debug Logging:** Capture all SDK output
+3. **Save All Intermediate Data:** Source → Parsed → Mapped → Response
+4. **Test in Isolation:** Remove resolvers, simplify mapping, add back one at a time
+5. **Check GraphQL Schema:** Validate mutation in GraphQL playground first
+
+**Remember:** 90% of issues are path resolution or null values. Start there!