@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/01-TEMPLATES/faq.md

@@ -1,686 +1,686 @@
-# FC Connect SDK - Use Cases FAQ
-
-**Consolidated troubleshooting guide from all use-case documentation**
-
-Last Updated: 2025-01-18
-
----
-
-## 📋 Table of Contents
-
-- [File Processing Issues](#file-processing-issues)
-- [State Management & Locking](#state-management-locking)
-- [Mapping & Transformation Errors](#mapping-transformation-errors)
-- [GraphQL & API Issues](#graphql-api-issues)
-- [XML Processing](#xml-processing)
-- [Versori Platform](#versori-platform)
-- [Performance & Memory](#performance-memory)
-- [Authentication & Security](#authentication-security)
-- [Deployment & Configuration](#deployment-configuration)
-
----
-
-## File Processing Issues
-
-### Q: How do I prevent processing the same file twice?
-
-**Answer**: Use `VersoriFileTracker` (for Versori) or `StateService` (for standalone):
-
-```typescript
-// Versori
-import { VersoriFileTracker } from '@fluentcommerce/fc-connect-sdk';
-const tracker = new VersoriFileTracker(openKv(), 'workflow-id');
-
-if (await tracker.wasFileProcessed(fileName)) {
-  console.log('Already processed, skipping');
-  return;
-}
-
-await processFile(fileName);
-await tracker.markFileProcessed(fileName, { recordCount: 100 });
-```
-
-**Related Guides**:
-
-- [State Management Pattern](patterns/state-duplicate-prevention.md)
-- [Versori KV State Management](versori/patterns/kv-state-management.md)
-
----
-
-### Q: Why are my CSV files failing to parse?
-
-**Common Causes**:
-
-1. **Wrong delimiter**
-
-   ```typescript
-   // Solution: Specify correct delimiter
-   const records = await parser.parse(content, { delimiter: '|' }); // Not ','
-   ```
-
-2. **Missing header row**
-
-   ```typescript
-   // Solution: Enable headerless mode
-   const records = await parser.parse(content, { header: false });
-   ```
-
-3. **Quoted fields with embedded commas**
-   ```typescript
-   // Solution: Enable quote handling
-   const records = await parser.parse(content, { quote: '"', escape: '"' });
-   ```
-
----
-
-### Q: How do I handle large files that cause memory issues?
-
-**Answer**: Use streaming mode:
-
-```typescript
-import { CSVParserService } from '@fluentcommerce/fc-connect-sdk';
-
-const parser = new CSVParserService();
-
-// Stream in chunks
-for await (const chunk of parser.streamParse(fileStream, { chunkSize: 1000 })) {
-  await processBatch(chunk);
-}
-```
-
-**Related Guides**:
-
-- [Large File Splitting Pattern](patterns/large-file-splitting.md)
-- [Pagination & Streaming](patterns/pagination-streaming.md)
-
----
-
-## State Management & Locking
-
-### Q: My distributed lock is never released!
-
-**Cause**: Workflow crashed before releasing lock.
-
-**Solution**: Always release locks in `finally` blocks:
-
-```typescript
-const kvAdapter = new VersoriKVAdapter(openKv());
-const stateService = new StateService(logger);
-const lockName = 'my-lock';
-
-try {
-  await stateService.acquireLock(lockName, kvAdapter, 15);
-  await doWork();
-} finally {
-  // ALWAYS release, even on error
-  await stateService.releaseLock(lockName, kvAdapter);
-}
-```
-
-**Lock Timeouts**: Stale locks auto-expire after timeout (e.g., 15 minutes).
-
----
-
-### Q: How do I list all processed files in Versori?
-
-**Answer**: Use `VersoriIndexedFileTracker` (not standard `VersoriFileTracker`):
-
-```typescript
-import { VersoriIndexedFileTracker } from '@fluentcommerce/fc-connect-sdk';
-
-const tracker = new VersoriIndexedFileTracker(openKv(), 'workflow');
-
-// List all processed files
-const files = await tracker.listProcessedFiles();
-console.log(`Processed ${files.length} files`);
-
-// Get stats
-const stats = await tracker.getStats();
-```
-
-**Why**: Standard Versori KV doesn't support list operations.
-
----
-
-### Q: How do I implement checkpoint/resume for long workflows?
-
-**Answer**: Save state periodically using `StateService`:
-
-```typescript
-const stateService = new StateService(logger);
-const kvAdapter = new VersoriKVAdapter(openKv());
-
-// Restore from checkpoint
-const syncState = await stateService.getSyncState(kvAdapter, 'workflow-id');
-const lastProcessed = syncState.lastProcessedTimestamp;
-
-// Process batches
-for (const batch of batches) {
-  await processBatch(batch);
-
-  // Save checkpoint every 10 batches
-  if (batchIndex % 10 === 0) {
-    await stateService.updateSyncState(
-      kvAdapter,
-      [
-        {
-          fileName: `batch-${batchIndex}`,
-          lastModified: new Date().toISOString(),
-          recordCount: batch.length,
-        },
-      ],
-      'workflow-id'
-    );
-  }
-}
-```
-
----
-
-## Mapping & Transformation Errors
-
-### Q: "Required field 'skuRef' is missing or empty"
-
-**Cause**: Source field doesn't exist or mapping path is incorrect.
-
-**Solution**: Debug the source data structure:
-
-```typescript
-console.log('Source data:', JSON.stringify(sourceData, null, 2));
-
-// Verify source path matches actual structure
-const config = {
-  fields: {
-    skuRef: { source: 'sku', required: true }, // Check if sourceData.sku exists
-  },
-};
-```
-
-**Common Mistakes**:
-
-- `snake_case` vs `camelCase` mismatch
-- Nested path incorrect (`product.sku` vs `product.sku_id`)
-- Array access (`items[0].sku` vs `items.sku`)
-
----
-
-### Q: How do I map nested XML/JSON fields?
-
-**Answer**: Use dot notation for nested paths:
-
-```typescript
-const mapping = {
-  fields: {
-    // Nested object
-    'customer.email': { source: 'order.customer.email_address' },
-
-    // Array of objects
-    items: {
-      source: 'order.line_items',
-      isArray: true,
-      fields: {
-        productRef: { source: 'sku' },
-        quantity: { source: 'qty', resolver: 'sdk.parseInt' },
-      },
-    },
-
-    // XML attribute (use @ prefix)
-    orderId: { source: 'order@id' },
-  },
-};
-```
-
-**Related Guides**:
-
-- [Field Mapping Universal](patterns/field-mapping-universal.md)
-- [XML Order Ingestion](versori/webhooks/template-webhook-xml-order-ingestion.md)
-
----
-
-### Q: My custom resolver returns undefined!
-
-**Cause**: Incorrect resolver signature or accessing wrong data.
-
-**Solution**: Use correct 4-parameter signature:
-
-```typescript
-const customResolvers = {
-  'custom.myResolver': (value, sourceData, config, helpers) => {
-    // value: the extracted field value
-    // sourceData: full source object (access sibling fields)
-    // config: resolver configuration passed to mapper
-    // helpers: SDK utilities (get, parseFloatSafe, logger, etc.)
-
-    const siblingField = helpers.get(sourceData, 'other.field');
-    return helpers.parseFloatSafe(value, 0) * siblingField;
-  },
-};
-```
-
-**Related Guides**:
-
-- [Custom Resolvers Pattern](patterns/custom-resolvers.md)
-
----
-
-## GraphQL & API Issues
-
-### Q: "GraphQL errors: Field 'customer' is required"
-
-**Cause**: Missing required field in mutation input.
-
-**Solution**: Check GraphQL schema requirements:
-
-```typescript
-// Use introspection tool to view schema
-npx @fluentcommerce/fc-connect-sdk introspect-schema --url <graphql-url>
-
-// Ensure all required fields are mapped
-const mapping = {
-  mutation: 'createOrder',
-  fields: {
-    customer: {
-      id: { resolver: 'custom.lookupCustomer', required: true }, // REQUIRED
-      email: { source: 'email' }
-    }
-  }
-};
-```
-
----
-
-### Q: "Cannot read property 'customerOrderId' of undefined"
-
-**Cause**: Incorrect XML attribute access syntax.
-
-**Solution**: Use `@` WITHOUT dot before it:
-
-```typescript
-// ❌ WRONG
-"source": "$radial.OrderCreateRequest.Order.@customerOrderId"
-
-// ✅ CORRECT
-"source": "$radial.OrderCreateRequest.Order@customerOrderId"
-```
-
-**Why**: `@` is part of the path syntax, not a separate segment.
-
----
-
-### Q: How do I handle pagination in GraphQL queries?
-
-**Answer**: Use SDK's built-in auto-pagination:
-
-```typescript
-const result = await client.graphql({
-  query: inventoryQuery,
-  variables: { first: 50 },
-  pagination: {
-    maxPages: 100, // Limit total pages
-    onProgress: (page, total) => {
-      console.log(`Fetching page ${page}/${total}`);
-    },
-  },
-});
-
-// result.data contains ALL pages combined
-```
-
-**Related Guides**:
-
-- [Pagination & Streaming](patterns/pagination-streaming.md)
-- [GraphQL Query Export](standalone/graphql-query-export.md)
-
----
-
-## XML Processing
-
-### Q: "Expected array at path but got object"
-
-**Cause**: XML parser doesn't create arrays for single items.
-
-**Solution**: Use `helpers.ensureArray()` in resolvers:
-
-```typescript
-'custom.processItems': (value, sourceData, config, helpers) => {
-  // ❌ WRONG - assumes always array
-  const items = helpers.get(sourceData, 'OrderItems.OrderItem');
-  for (const item of items) { ... }  // ERROR if single item
-
-  // ✅ CORRECT - wraps single items
-  const items = helpers.ensureArray(
-    helpers.get(sourceData, 'OrderItems.OrderItem')
-  );
-  for (const item of items) { ... }  // Works for 1 or N items
-}
-```
-
----
-
-### Q: How do I extract nested/escaped XML from another XML document?
-
-**Answer**: Use `nodes` configuration in `GraphQLMutationMapper`:
-
-```json
-{
-  "nodes": {
-    "radial": {
-      "extract": "orders.order.custom-attributes.custom-attribute[attribute-id=CreateOrderServiceRequest]",
-      "parse": "xml"
-    }
-  },
-  "fields": {
-    "ref": {
-      "source": "$radial.OrderCreateRequest.Order@customerOrderId"
-    }
-  }
-}
-```
-
-**How it works**:
-
-1. **Extract**: Find nested XML string using path + attribute filter
-2. **Parse**: Re-parse extracted string as XML
-3. **Reference**: Use `$radial` prefix to access parsed node
-
-**Related Guides**:
-
-- [XML Order Ingestion](versori/webhooks/template-webhook-xml-order-ingestion.md)
-
----
-
-## Versori Platform
-
-### Q: How do I return non-JSON content (XML, HTML, CSV) from Versori webhooks?
-
-**Answer**: Use custom `Response` objects with proper `Content-Type`:
-
-```typescript
-import { webhook, fn } from '@versori/run';
-
-export const xmlResponse = webhook('xml-endpoint', {
-  response: {
-    mode: 'sync',
-    onSuccess: ctx =>
-      new Response(ctx.data, {
-        status: 200,
-        headers: { 'Content-Type': 'application/xml; charset=utf-8' },
-      }),
-    onError: ctx =>
-      new Response(ctx.data, {
-        status: 500,
-        headers: { 'Content-Type': 'application/xml; charset=utf-8' },
-      }),
-  },
-})
-  .then(fn('generate-xml', () => '<order><id>123</id></order>'))
-  .catch(({ data }) => '<error>Failed</error>');
-```
-
-**Why**: Default Versori behavior JSON-encodes all responses.
-
-**Related Guides**:
-
-- [XML Response Patterns](versori/patterns/xml-response-patterns.md)
-
----
-
-### Q: "Node 'radial' extraction returned null/undefined"
-
-**Cause**: Path in nodes config doesn't match XML structure.
-
-**Solution**: Check XML attribute syntax:
-
-```json
-// ❌ WRONG
-"extract": "custom-attribute[@attribute-id=CreateOrderServiceRequest]"
-
-// ✅ CORRECT
-"extract": "orders.order.custom-attributes.custom-attribute[attribute-id=CreateOrderServiceRequest]"
-```
-
-**Debug**: Add logging to see extraction result:
-
-```typescript
-const extractedData = pathResolver.resolve(rootData, nodeConfig.extract);
-console.log('Extracted data:', extractedData);
-```
-
----
-
-### Q: How do I reuse a single Fluent job for multiple batches?
-
-**Answer**: Use daily job strategy with `StateService`:
-
-```typescript
-const stateService = new StateService(logger);
-const kvAdapter = new VersoriKVAdapter(openKv());
-
-// Check for existing daily job
-let dailyJob = await stateService.getDailyJob(kvAdapter, 'workflow-id');
-
-if (!dailyJob) {
-  // Create new job
-  const client = await createClient({
-    config: {
-      baseUrl: 'https://api.fluentcommerce.com', // ✅ Correct
-      clientId: process.env.FLUENT_CLIENT_ID!,
-      clientSecret: process.env.FLUENT_CLIENT_SECRET!,
-      retailerId: process.env.FLUENT_RETAILER_ID!,
-    },
-    logger: console,
-  });
-  const job = await client.createJob({ name: 'daily-job', retailerId: '1' });
-  await stateService.setDailyJob(kvAdapter, 'workflow-id', job.id, 24); // Expires in 24h
-  dailyJob = { jobId: job.id };
-}
-
-// Reuse job for all batches
-await client.sendBatch(dailyJob.jobId, { entities: data });
-```
-
----
-
-## Performance & Memory
-
-### Q: My workflow times out processing large files!
-
-**Solutions**:
-
-1. **Use streaming mode**:
-
-   ```typescript
-   for await (const chunk of parser.streamParse(fileStream, { chunkSize: 1000 })) {
-     await processBatch(chunk);
-   }
-   ```
-
-2. **Split large files**:
-
-   ```typescript
-   const chunks = splitFileIntoChunks(largeFile, 10000); // 10K records per chunk
-   for (const chunk of chunks) {
-     await processChunk(chunk);
-   }
-   ```
-
-3. **Increase batch size limits**:
-   ```typescript
-   await client.sendBatch(jobId, {
-     entities: batchData,
-     batchSize: 5000, // Increase from default 2000
-   });
-   ```
-
-**Related Guides**:
-
-- [Large File Splitting](patterns/large-file-splitting.md)
-
----
-
-### Q: How do I optimize async resolver performance?
-
-**Solution**: Pre-fetch lookup data and use memoization:
-
-```typescript
-// ❌ SLOW - queries customer for every item
-'custom.getCustomerEmail': async (value, data, config, helpers) => {
-  const result = await helpers.fluentClient.graphql({ query });
-  return result.data?.customer?.email;
-}
-
-// ✅ FAST - cache customer lookup
-const customerCache = new Map();
-
-'custom.getCustomerEmail': async (value, data, config, helpers) => {
-  const customerId = data.customerId;
-
-  if (customerCache.has(customerId)) {
-    return customerCache.get(customerId).email;
-  }
-
-  const result = await helpers.fluentClient.graphql({ query });
-  customerCache.set(customerId, result.data?.customer);
-  return result.data?.customer?.email;
-}
-```
-
----
-
-## Authentication & Security
-
-### Q: "OAuth2 token refresh failed"
-
-**Causes & Solutions**:
-
-1. **Incorrect credentials**:
-
-   ```bash
-   # Verify credentials
-   export FLUENT_CLIENT_ID=your-client-id
-   export FLUENT_CLIENT_SECRET=your-client-secret
-   ```
-
-2. **Token endpoint unreachable**:
-
-   ```typescript
-   const client = await createClient({
-     config: {
-       baseUrl: 'https://api.fluentcommerce.com', // ✅ Correct
-       clientId: process.env.FLUENT_CLIENT_ID!,
-       clientSecret: process.env.FLUENT_CLIENT_SECRET!,
-       retailerId: process.env.FLUENT_RETAILER_ID!,
-     },
-     logger: console,
-   });
-   ```
-
-3. **Clock skew**:
-   ```bash
-   # Ensure system time is synced
-   sudo ntpdate -s time.nist.gov
-   ```
-
----
-
-### Q: How do I validate webhook signatures?
-
-**Answer**: Use `WebhookValidationService`:
-
-```typescript
-import { WebhookValidationService } from '@fluentcommerce/fc-connect-sdk';
-
-const validator = new WebhookValidationService({ strictValidation: true }, logger);
-
-const result = await validator.validateWebhook(
-  rawBody, // Raw webhook body (string)
-  headers, // HTTP headers with signature
-  publicKey // Public key from webhook provider
-);
-
-if (!result.isValid) {
-  throw new Error(`Validation failed: ${result.error}`);
-}
-```
-
-**Supported Algorithms**: HMAC-SHA256, RSA-SHA256
-
----
-
-## Deployment & Configuration
-
-### Q: How do I set environment-specific behavior?
-
-**Answer**: Use config parameter in resolvers:
-
-```typescript
-const mapper = new UniversalMapper(mapping, {
-  customResolvers,
-  context: {
-    environment: process.env.NODE_ENV,  // 'production' or 'development'
-    retailerId: process.env.FLUENT_RETAILER_ID,
-    skuPrefix: process.env.SKU_PREFIX || 'PROD'
-  }
-});
-
-// In resolver
-'custom.createOrderRef': (value, data, config, helpers) => {
-  const originalRef = String(value);
-
-  if (config.environment === 'production') {
-    return originalRef;  // Production: use as-is
-  } else {
-    return `${originalRef}_test_${Date.now()}`;  // Dev: add test suffix
-  }
-}
-```
-
----
-
-### Q: My Docker container fails with "Cannot find module '@fluentcommerce/fc-connect-sdk'"
-
-**Solution**: Ensure dependencies are installed in Docker:
-
-```dockerfile
-FROM node:18-alpine
-
-WORKDIR /app
-
-# Copy package files
-COPY package*.json ./
-
-# Install dependencies
-RUN npm ci --only=production
-
-# Copy source code
-COPY . .
-
-# Build TypeScript
-RUN npm run build
-
-CMD ["node", "dist/index.js"]
-```
-
----
-
-## Still Need Help?
-
-### Resources
-
-- **SDK Documentation**: [Complete Docs](../02-CORE-GUIDES/advanced-services/advanced-services-readme.md)
-- **API Reference**: [API Reference](../02-CORE-GUIDES/advanced-services/advanced-services-readme.md)
-- **GitHub Issues**: https://github.com/fluentcommerce/fc-connect-sdk/issues
-- **Fluent Commerce Docs**: https://docs.fluentcommerce.com
-
-### Reporting Issues
-
-When reporting issues, include:
-
-1. SDK version (`npm list @fluentcommerce/fc-connect-sdk`)
-2. Runtime environment (Node.js version, Deno version, or Versori)
-3. Minimal reproduction code
-4. Error messages and stack traces
-5. Sample data (anonymized)
-
----
-
+# FC Connect SDK - Use Cases FAQ
+
+**Consolidated troubleshooting guide from all use-case documentation**
+
+Last Updated: 2025-01-18
+
+---
+
+## 📋 Table of Contents
+
+- [File Processing Issues](#file-processing-issues)
+- [State Management & Locking](#state-management-locking)
+- [Mapping & Transformation Errors](#mapping-transformation-errors)
+- [GraphQL & API Issues](#graphql-api-issues)
+- [XML Processing](#xml-processing)
+- [Versori Platform](#versori-platform)
+- [Performance & Memory](#performance-memory)
+- [Authentication & Security](#authentication-security)
+- [Deployment & Configuration](#deployment-configuration)
+
+---
+
+## File Processing Issues
+
+### Q: How do I prevent processing the same file twice?
+
+**Answer**: Use `VersoriFileTracker` (for Versori) or `StateService` (for standalone):
+
+```typescript
+// Versori
+import { VersoriFileTracker } from '@fluentcommerce/fc-connect-sdk';
+const tracker = new VersoriFileTracker(openKv(), 'workflow-id');
+
+if (await tracker.wasFileProcessed(fileName)) {
+  console.log('Already processed, skipping');
+  return;
+}
+
+await processFile(fileName);
+await tracker.markFileProcessed(fileName, { recordCount: 100 });
+```
+
+**Related Guides**:
+
+- [State Management Pattern](patterns/state-duplicate-prevention.md)
+- [Versori KV State Management](versori/patterns/kv-state-management.md)
+
+---
+
+### Q: Why are my CSV files failing to parse?
+
+**Common Causes**:
+
+1. **Wrong delimiter**
+
+   ```typescript
+   // Solution: Specify correct delimiter
+   const records = await parser.parse(content, { delimiter: '|' }); // Not ','
+   ```
+
+2. **Missing header row**
+
+   ```typescript
+   // Solution: Enable headerless mode
+   const records = await parser.parse(content, { header: false });
+   ```
+
+3. **Quoted fields with embedded commas**
+   ```typescript
+   // Solution: Enable quote handling
+   const records = await parser.parse(content, { quote: '"', escape: '"' });
+   ```
+
+---
+
+### Q: How do I handle large files that cause memory issues?
+
+**Answer**: Use streaming mode:
+
+```typescript
+import { CSVParserService } from '@fluentcommerce/fc-connect-sdk';
+
+const parser = new CSVParserService();
+
+// Stream in chunks
+for await (const chunk of parser.streamParse(fileStream, { chunkSize: 1000 })) {
+  await processBatch(chunk);
+}
+```
+
+**Related Guides**:
+
+- [Large File Splitting Pattern](patterns/large-file-splitting.md)
+- [Pagination & Streaming](patterns/pagination-streaming.md)
+
+---
+
+## State Management & Locking
+
+### Q: My distributed lock is never released!
+
+**Cause**: Workflow crashed before releasing lock.
+
+**Solution**: Always release locks in `finally` blocks:
+
+```typescript
+const kvAdapter = new VersoriKVAdapter(openKv());
+const stateService = new StateService(logger);
+const lockName = 'my-lock';
+
+try {
+  await stateService.acquireLock(lockName, kvAdapter, 15);
+  await doWork();
+} finally {
+  // ALWAYS release, even on error
+  await stateService.releaseLock(lockName, kvAdapter);
+}
+```
+
+**Lock Timeouts**: Stale locks auto-expire after timeout (e.g., 15 minutes).
+
+---
+
+### Q: How do I list all processed files in Versori?
+
+**Answer**: Use `VersoriIndexedFileTracker` (not standard `VersoriFileTracker`):
+
+```typescript
+import { VersoriIndexedFileTracker } from '@fluentcommerce/fc-connect-sdk';
+
+const tracker = new VersoriIndexedFileTracker(openKv(), 'workflow');
+
+// List all processed files
+const files = await tracker.listProcessedFiles();
+console.log(`Processed ${files.length} files`);
+
+// Get stats
+const stats = await tracker.getStats();
+```
+
+**Why**: Standard Versori KV doesn't support list operations.
+
+---
+
+### Q: How do I implement checkpoint/resume for long workflows?
+
+**Answer**: Save state periodically using `StateService`:
+
+```typescript
+const stateService = new StateService(logger);
+const kvAdapter = new VersoriKVAdapter(openKv());
+
+// Restore from checkpoint
+const syncState = await stateService.getSyncState(kvAdapter, 'workflow-id');
+const lastProcessed = syncState.lastProcessedTimestamp;
+
+// Process batches
+for (const batch of batches) {
+  await processBatch(batch);
+
+  // Save checkpoint every 10 batches
+  if (batchIndex % 10 === 0) {
+    await stateService.updateSyncState(
+      kvAdapter,
+      [
+        {
+          fileName: `batch-${batchIndex}`,
+          lastModified: new Date().toISOString(),
+          recordCount: batch.length,
+        },
+      ],
+      'workflow-id'
+    );
+  }
+}
+```
+
+---
+
+## Mapping & Transformation Errors
+
+### Q: "Required field 'skuRef' is missing or empty"
+
+**Cause**: Source field doesn't exist or mapping path is incorrect.
+
+**Solution**: Debug the source data structure:
+
+```typescript
+console.log('Source data:', JSON.stringify(sourceData, null, 2));
+
+// Verify source path matches actual structure
+const config = {
+  fields: {
+    skuRef: { source: 'sku', required: true }, // Check if sourceData.sku exists
+  },
+};
+```
+
+**Common Mistakes**:
+
+- `snake_case` vs `camelCase` mismatch
+- Nested path incorrect (`product.sku` vs `product.sku_id`)
+- Array access (`items[0].sku` vs `items.sku`)
+
+---
+
+### Q: How do I map nested XML/JSON fields?
+
+**Answer**: Use dot notation for nested paths:
+
+```typescript
+const mapping = {
+  fields: {
+    // Nested object
+    'customer.email': { source: 'order.customer.email_address' },
+
+    // Array of objects
+    items: {
+      source: 'order.line_items',
+      isArray: true,
+      fields: {
+        productRef: { source: 'sku' },
+        quantity: { source: 'qty', resolver: 'sdk.parseInt' },
+      },
+    },
+
+    // XML attribute (use @ prefix)
+    orderId: { source: 'order@id' },
+  },
+};
+```
+
+**Related Guides**:
+
+- [Field Mapping Universal](patterns/field-mapping-universal.md)
+- [XML Order Ingestion](versori/webhooks/template-webhook-xml-order-ingestion.md)
+
+---
+
+### Q: My custom resolver returns undefined!
+
+**Cause**: Incorrect resolver signature or accessing wrong data.
+
+**Solution**: Use correct 4-parameter signature:
+
+```typescript
+const customResolvers = {
+  'custom.myResolver': (value, sourceData, config, helpers) => {
+    // value: the extracted field value
+    // sourceData: full source object (access sibling fields)
+    // config: resolver configuration passed to mapper
+    // helpers: SDK utilities (get, parseFloatSafe, logger, etc.)
+
+    const siblingField = helpers.get(sourceData, 'other.field');
+    return helpers.parseFloatSafe(value, 0) * siblingField;
+  },
+};
+```
+
+**Related Guides**:
+
+- [Custom Resolvers Pattern](patterns/custom-resolvers.md)
+
+---
+
+## GraphQL & API Issues
+
+### Q: "GraphQL errors: Field 'customer' is required"
+
+**Cause**: Missing required field in mutation input.
+
+**Solution**: Check GraphQL schema requirements:
+
+```typescript
+// Use introspection tool to view schema
+npx @fluentcommerce/fc-connect-sdk introspect-schema --url <graphql-url>
+
+// Ensure all required fields are mapped
+const mapping = {
+  mutation: 'createOrder',
+  fields: {
+    customer: {
+      id: { resolver: 'custom.lookupCustomer', required: true }, // REQUIRED
+      email: { source: 'email' }
+    }
+  }
+};
+```
+
+---
+
+### Q: "Cannot read property 'customerOrderId' of undefined"
+
+**Cause**: Incorrect XML attribute access syntax.
+
+**Solution**: Use `@` WITHOUT dot before it:
+
+```typescript
+// ❌ WRONG
+"source": "$radial.OrderCreateRequest.Order.@customerOrderId"
+
+// ✅ CORRECT
+"source": "$radial.OrderCreateRequest.Order@customerOrderId"
+```
+
+**Why**: `@` is part of the path syntax, not a separate segment.
+
+---
+
+### Q: How do I handle pagination in GraphQL queries?
+
+**Answer**: Use SDK's built-in auto-pagination:
+
+```typescript
+const result = await client.graphql({
+  query: inventoryQuery,
+  variables: { first: 50 },
+  pagination: {
+    maxPages: 100, // Limit total pages
+    onProgress: (page, total) => {
+      console.log(`Fetching page ${page}/${total}`);
+    },
+  },
+});
+
+// result.data contains ALL pages combined
+```
+
+**Related Guides**:
+
+- [Pagination & Streaming](patterns/pagination-streaming.md)
+- [GraphQL Query Export](standalone/graphql-query-export.md)
+
+---
+
+## XML Processing
+
+### Q: "Expected array at path but got object"
+
+**Cause**: XML parser doesn't create arrays for single items.
+
+**Solution**: Use `helpers.ensureArray()` in resolvers:
+
+```typescript
+'custom.processItems': (value, sourceData, config, helpers) => {
+  // ❌ WRONG - assumes always array
+  const items = helpers.get(sourceData, 'OrderItems.OrderItem');
+  for (const item of items) { ... }  // ERROR if single item
+
+  // ✅ CORRECT - wraps single items
+  const items = helpers.ensureArray(
+    helpers.get(sourceData, 'OrderItems.OrderItem')
+  );
+  for (const item of items) { ... }  // Works for 1 or N items
+}
+```
+
+---
+
+### Q: How do I extract nested/escaped XML from another XML document?
+
+**Answer**: Use `nodes` configuration in `GraphQLMutationMapper`:
+
+```json
+{
+  "nodes": {
+    "radial": {
+      "extract": "orders.order.custom-attributes.custom-attribute[attribute-id=CreateOrderServiceRequest]",
+      "parse": "xml"
+    }
+  },
+  "fields": {
+    "ref": {
+      "source": "$radial.OrderCreateRequest.Order@customerOrderId"
+    }
+  }
+}
+```
+
+**How it works**:
+
+1. **Extract**: Find nested XML string using path + attribute filter
+2. **Parse**: Re-parse extracted string as XML
+3. **Reference**: Use `$radial` prefix to access parsed node
+
+**Related Guides**:
+
+- [XML Order Ingestion](versori/webhooks/template-webhook-xml-order-ingestion.md)
+
+---
+
+## Versori Platform
+
+### Q: How do I return non-JSON content (XML, HTML, CSV) from Versori webhooks?
+
+**Answer**: Use custom `Response` objects with proper `Content-Type`:
+
+```typescript
+import { webhook, fn } from '@versori/run';
+
+export const xmlResponse = webhook('xml-endpoint', {
+  response: {
+    mode: 'sync',
+    onSuccess: ctx =>
+      new Response(ctx.data, {
+        status: 200,
+        headers: { 'Content-Type': 'application/xml; charset=utf-8' },
+      }),
+    onError: ctx =>
+      new Response(ctx.data, {
+        status: 500,
+        headers: { 'Content-Type': 'application/xml; charset=utf-8' },
+      }),
+  },
+})
+  .then(fn('generate-xml', () => '<order><id>123</id></order>'))
+  .catch(({ data }) => '<error>Failed</error>');
+```
+
+**Why**: Default Versori behavior JSON-encodes all responses.
+
+**Related Guides**:
+
+- [XML Response Patterns](versori/patterns/xml-response-patterns.md)
+
+---
+
+### Q: "Node 'radial' extraction returned null/undefined"
+
+**Cause**: Path in nodes config doesn't match XML structure.
+
+**Solution**: Check XML attribute syntax:
+
+```json
+// ❌ WRONG
+"extract": "custom-attribute[@attribute-id=CreateOrderServiceRequest]"
+
+// ✅ CORRECT
+"extract": "orders.order.custom-attributes.custom-attribute[attribute-id=CreateOrderServiceRequest]"
+```
+
+**Debug**: Add logging to see extraction result:
+
+```typescript
+const extractedData = pathResolver.resolve(rootData, nodeConfig.extract);
+console.log('Extracted data:', extractedData);
+```
+
+---
+
+### Q: How do I reuse a single Fluent job for multiple batches?
+
+**Answer**: Use daily job strategy with `StateService`:
+
+```typescript
+const stateService = new StateService(logger);
+const kvAdapter = new VersoriKVAdapter(openKv());
+
+// Check for existing daily job
+let dailyJob = await stateService.getDailyJob(kvAdapter, 'workflow-id');
+
+if (!dailyJob) {
+  // Create new job
+  const client = await createClient({
+    config: {
+      baseUrl: 'https://api.fluentcommerce.com', // ✅ Correct
+      clientId: process.env.FLUENT_CLIENT_ID!,
+      clientSecret: process.env.FLUENT_CLIENT_SECRET!,
+      retailerId: process.env.FLUENT_RETAILER_ID!,
+    },
+    logger: console,
+  });
+  const job = await client.createJob({ name: 'daily-job', retailerId: '1' });
+  await stateService.setDailyJob(kvAdapter, 'workflow-id', job.id, 24); // Expires in 24h
+  dailyJob = { jobId: job.id };
+}
+
+// Reuse job for all batches
+await client.sendBatch(dailyJob.jobId, { entities: data });
+```
+
+---
+
+## Performance & Memory
+
+### Q: My workflow times out processing large files!
+
+**Solutions**:
+
+1. **Use streaming mode**:
+
+   ```typescript
+   for await (const chunk of parser.streamParse(fileStream, { chunkSize: 1000 })) {
+     await processBatch(chunk);
+   }
+   ```
+
+2. **Split large files**:
+
+   ```typescript
+   const chunks = splitFileIntoChunks(largeFile, 10000); // 10K records per chunk
+   for (const chunk of chunks) {
+     await processChunk(chunk);
+   }
+   ```
+
+3. **Increase batch size limits**:
+   ```typescript
+   await client.sendBatch(jobId, {
+     entities: batchData,
+     batchSize: 5000, // Increase from default 2000
+   });
+   ```
+
+**Related Guides**:
+
+- [Large File Splitting](patterns/large-file-splitting.md)
+
+---
+
+### Q: How do I optimize async resolver performance?
+
+**Solution**: Pre-fetch lookup data and use memoization:
+
+```typescript
+// ❌ SLOW - queries customer for every item
+'custom.getCustomerEmail': async (value, data, config, helpers) => {
+  const result = await helpers.fluentClient.graphql({ query });
+  return result.data?.customer?.email;
+}
+
+// ✅ FAST - cache customer lookup
+const customerCache = new Map();
+
+'custom.getCustomerEmail': async (value, data, config, helpers) => {
+  const customerId = data.customerId;
+
+  if (customerCache.has(customerId)) {
+    return customerCache.get(customerId).email;
+  }
+
+  const result = await helpers.fluentClient.graphql({ query });
+  customerCache.set(customerId, result.data?.customer);
+  return result.data?.customer?.email;
+}
+```
+
+---
+
+## Authentication & Security
+
+### Q: "OAuth2 token refresh failed"
+
+**Causes & Solutions**:
+
+1. **Incorrect credentials**:
+
+   ```bash
+   # Verify credentials
+   export FLUENT_CLIENT_ID=your-client-id
+   export FLUENT_CLIENT_SECRET=your-client-secret
+   ```
+
+2. **Token endpoint unreachable**:
+
+   ```typescript
+   const client = await createClient({
+     config: {
+       baseUrl: 'https://api.fluentcommerce.com', // ✅ Correct
+       clientId: process.env.FLUENT_CLIENT_ID!,
+       clientSecret: process.env.FLUENT_CLIENT_SECRET!,
+       retailerId: process.env.FLUENT_RETAILER_ID!,
+     },
+     logger: console,
+   });
+   ```
+
+3. **Clock skew**:
+   ```bash
+   # Ensure system time is synced
+   sudo ntpdate -s time.nist.gov
+   ```
+
+---
+
+### Q: How do I validate webhook signatures?
+
+**Answer**: Use `WebhookValidationService`:
+
+```typescript
+import { WebhookValidationService } from '@fluentcommerce/fc-connect-sdk';
+
+const validator = new WebhookValidationService({ strictValidation: true }, logger);
+
+const result = await validator.validateWebhook(
+  rawBody, // Raw webhook body (string)
+  headers, // HTTP headers with signature
+  publicKey // Public key from webhook provider
+);
+
+if (!result.isValid) {
+  throw new Error(`Validation failed: ${result.error}`);
+}
+```
+
+**Supported Algorithms**: HMAC-SHA256, RSA-SHA256
+
+---
+
+## Deployment & Configuration
+
+### Q: How do I set environment-specific behavior?
+
+**Answer**: Use config parameter in resolvers:
+
+```typescript
+const mapper = new UniversalMapper(mapping, {
+  customResolvers,
+  context: {
+    environment: process.env.NODE_ENV,  // 'production' or 'development'
+    retailerId: process.env.FLUENT_RETAILER_ID,
+    skuPrefix: process.env.SKU_PREFIX || 'PROD'
+  }
+});
+
+// In resolver
+'custom.createOrderRef': (value, data, config, helpers) => {
+  const originalRef = String(value);
+
+  if (config.environment === 'production') {
+    return originalRef;  // Production: use as-is
+  } else {
+    return `${originalRef}_test_${Date.now()}`;  // Dev: add test suffix
+  }
+}
+```
+
+---
+
+### Q: My Docker container fails with "Cannot find module '@fluentcommerce/fc-connect-sdk'"
+
+**Solution**: Ensure dependencies are installed in Docker:
+
+```dockerfile
+FROM node:18-alpine
+
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+
+# Install dependencies
+RUN npm ci --only=production
+
+# Copy source code
+COPY . .
+
+# Build TypeScript
+RUN npm run build
+
+CMD ["node", "dist/index.js"]
+```
+
+---
+
+## Still Need Help?
+
+### Resources
+
+- **SDK Documentation**: [Complete Docs](../02-CORE-GUIDES/advanced-services/advanced-services-readme.md)
+- **API Reference**: [API Reference](../02-CORE-GUIDES/advanced-services/advanced-services-readme.md)
+- **GitHub Issues**: https://github.com/fluentcommerce/fc-connect-sdk/issues
+- **Fluent Commerce Docs**: https://docs.fluentcommerce.com
+
+### Reporting Issues
+
+When reporting issues, include:
+
+1. SDK version (`npm list @fluentcommerce/fc-connect-sdk`)
+2. Runtime environment (Node.js version, Deno version, or Versori)
+3. Minimal reproduction code
+4. Error messages and stack traces
+5. Sample data (anonymized)
+
+---
+