@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/03-PATTERN-GUIDES/multiple-connections/modules/multiple-connections-05-best-practices.md

@@ -1,624 +1,624 @@
-# Module 5: Best Practices
-
-**Level:** Advanced
-**Estimated Time:** 25 minutes
-
-**SDK Version:** Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
-
-## Overview
-
-This module consolidates production-ready patterns, performance optimizations, and troubleshooting techniques for multi-connection scenarios.
-
-## Learning Objectives
-
-By the end of this module, you will:
-- ✅ Know when to use each multi-connection pattern
-- ✅ Implement production-ready error handling
-- ✅ Optimize performance for large-scale exports
-- ✅ Debug common issues effectively
-- ✅ Apply security and reliability best practices
-
-## Decision Matrix: Which Pattern to Use?
-
-### Quick Decision Tree
-
-```
-Do you need ALL connections fully paginated?
-├─ YES → Use parallel queries (Promise.all)
-│
-└─ NO → Do you need MORE THAN ONE connection paginated?
-   ├─ YES → Use parallel queries (Promise.all)
-   │
-   └─ NO → Use single query with connectionPath
-```
-
-### Detailed Comparison
-
-| Scenario | Pattern | Why |
-|----------|---------|-----|
-| Export all products + all locations | Parallel | Both need full pagination |
-| Export all products + first page locations | Single + connectionPath | Only products need pagination |
-| Export 3+ different entities | Parallel | Multiple connections need pagination |
-| Get order with all items | Single + connectionPath | Nested connection |
-| Export with different limits per entity | Parallel | Independent limit control |
-
-## Best Practice 1: Always Use connectionPath
-
-### ✅ DO: Be Explicit
-
-```typescript
-// ✅ Good - explicit and predictable
-const result = await client.graphql({
-  query: multiConnectionQuery,
-  pagination: {
-    connectionPath: 'products',
-    maxPages: 10
-  }
-});
-```
-
-### ❌ DON'T: Rely on Auto-Detection
-
-```typescript
-// ❌ Risky - which connection gets paginated?
-const result = await client.graphql({
-  query: multiConnectionQuery,
-  pagination: { maxPages: 10 }  // Auto-detection is unpredictable
-});
-```
-
-**Exception:** Only one connection exists and path is obvious.
-
-## Best Practice 2: Use Parallel Queries for Multiple Full Pagination
-
-### ✅ DO: Separate Queries
-
-```typescript
-// ✅ Good - parallel queries with independent configs
-const [products, locations] = await Promise.all([
-  client.graphql({
-    query: productsQuery,
-    variables: { first: 100 },
-    pagination: { maxPages: 10, maxRecords: 1000 }
-  }),
-  client.graphql({
-    query: locationsQuery,
-    variables: { first: 50 },
-    pagination: { maxPages: 5, maxRecords: 250 }
-  })
-]);
-```
-
-### ❌ DON'T: Single Query Expecting Multiple Pagination
-
-```typescript
-// ❌ Bad - only one connection will be paginated
-const result = await client.graphql({
-  query: multiConnectionQuery,
-  pagination: {
-    connectionPath: 'products',  // locations won't be paginated
-    maxPages: 10
-  }
-});
-```
-
-## Best Practice 3: Monitor Progress Per Connection
-
-### ✅ DO: Separate Progress Tracking
-
-```typescript
-const [products, locations] = await Promise.all([
-  client.graphql({
-    query: productsQuery,
-    pagination: {
-      maxPages: 10,
-      onProgress: (page, records) => {
-        console.log(`[Products] Page ${page}: ${records} records`);
-      }
-    }
-  }),
-  client.graphql({
-    query: locationsQuery,
-    pagination: {
-      maxPages: 5,
-      onProgress: (page, records) => {
-        console.log(`[Locations] Page ${page}: ${records} records`);
-      }
-    }
-  })
-]);
-```
-
-### ❌ DON'T: Generic Logging
-
-```typescript
-// ❌ Bad - can't tell which connection
-const result = await client.graphql({
-  query: multiConnectionQuery,
-  pagination: {
-    connectionPath: 'products',
-    onProgress: (page, records) => {
-      console.log(`Page ${page}: ${records}`);  // Which connection?
-    }
-  }
-});
-```
-
-## Best Practice 4: Use Promise.allSettled for Resilience
-
-### ✅ DO: Handle Partial Failures
-
-```typescript
-const results = await Promise.allSettled([
-  client.graphql({ query: productsQuery, pagination: { maxPages: 10 } }),
-  client.graphql({ query: locationsQuery, pagination: { maxPages: 5 } }),
-  client.graphql({ query: virtualPositionsQuery, pagination: { maxPages: 20 } })
-]);
-
-const successful = results.filter(r => r.status === 'fulfilled');
-const failed = results.filter(r => r.status === 'rejected');
-
-console.log(`✅ Successful: ${successful.length}`);
-console.log(`❌ Failed: ${failed.length}`);
-
-// Process successful results
-successful.forEach((result, index) => {
-  if (result.status === 'fulfilled') {
-    const data = result.value;
-    // Process data
-  }
-});
-
-// Log failures
-failed.forEach((result, index) => {
-  if (result.status === 'rejected') {
-    console.error(`Failed query ${index}:`, result.reason);
-  }
-});
-```
-
-### ❌ DON'T: Use Promise.all Without Error Handling
-
-```typescript
-// ❌ Bad - one failure loses all results
-try {
-  const [products, locations] = await Promise.all([
-    client.graphql({ query: productsQuery, pagination: { maxPages: 10 } }),
-    client.graphql({ query: locationsQuery, pagination: { maxPages: 5 } })
-  ]);
-} catch (error) {
-  // Both results lost if one fails
-}
-```
-
-## Best Practice 5: Set Appropriate Safety Limits
-
-### ✅ DO: Use OR-Logic Limits
-
-```typescript
-const result = await client.graphql({
-  query: productsQuery,
-  pagination: {
-    maxPages: 100,        // OR
-    maxRecords: 10000,    // OR
-    timeoutMs: 60000      // OR (60 seconds)
-  }
-});
-```
-
-**Whichever limit is hit first stops pagination.**
-
-### ✅ DO: Match Limits to Entity Complexity
-
-```typescript
-// Simple entities - higher limits
-const virtualPositions = await client.graphql({
-  query: virtualPositionsQuery,
-  pagination: {
-    maxPages: 200,
-    maxRecords: 20000
-  }
-});
-
-// Complex entities - lower limits
-const orders = await client.graphql({
-  query: ordersWithItemsQuery,
-  pagination: {
-    maxPages: 50,
-    maxRecords: 2000
-  }
-});
-```
-
-## Best Practice 6: Optimize Page Sizes
-
-### ✅ DO: Match Page Size to Entity
-
-| Entity Type | Recommended Page Size | Reasoning |
-|-------------|----------------------|-----------|
-| VirtualPositions | 200-500 | Very simple fields |
-| Locations | 100-200 | Simple fields |
-| Products | 50-100 | Medium complexity |
-| Orders (no items) | 50-100 | Medium complexity |
-| Orders (with items) | 20-50 | High complexity, nested |
-
-```typescript
-const [virtualPositions, products, orders] = await Promise.all([
-  client.graphql({
-    query: virtualPositionsQuery,
-    variables: { first: 200 },  // ← Large page size
-    pagination: { maxRecords: 10000 }
-  }),
-  client.graphql({
-    query: productsQuery,
-    variables: { first: 75 },   // ← Medium page size
-    pagination: { maxRecords: 5000 }
-  }),
-  client.graphql({
-    query: ordersQuery,
-    variables: { first: 30 },   // ← Small page size
-    pagination: { maxRecords: 1000 }
-  })
-]);
-```
-
-## Best Practice 7: Reuse Client Instances
-
-### ✅ DO: Share Client
-
-```typescript
-// ✅ Good - create once, reuse
-const client = await createClient({
-  config: {
-    baseUrl: process.env.FLUENT_BASE_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!
-  }
-});
-
-const [products, locations, virtualPositions] = await Promise.all([
-  client.graphql({ query: productsQuery, pagination: { maxPages: 10 } }),
-  client.graphql({ query: locationsQuery, pagination: { maxPages: 5 } }),
-  client.graphql({ query: virtualPositionsQuery, pagination: { maxPages: 20 } })
-]);
-```
-
-### ❌ DON'T: Create Multiple Clients
-
-```typescript
-// ❌ Bad - creates new auth token for each query
-const results = await Promise.all([
-  createClient({ config: {...} }).then(c => c.graphql({ ... })),
-  createClient({ config: {...} }).then(c => c.graphql({ ... })),
-  createClient({ config: {...} }).then(c => c.graphql({ ... }))
-]);
-```
-
-## Best Practice 8: Use Appropriate Logging
-
-### ✅ DO: Use Native Log in Versori
-
-```typescript
-// ✅ Versori Platform - use native log
-import { schedule, http } from '@versori/run';
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-export const workflow = schedule('multi-export', '0 * * * *').then(
-  http('process', { connection: 'fluent' }, async (ctx) => {
-    const { log } = ctx;
-
-    // Pass native log to SDK
-    const client = await createClient(ctx); // Auto-detects Versori context
-
-    log.info('Starting parallel export');
-    const [products, locations] = await Promise.all([
-      client.graphql({ query: productsQuery, pagination: { maxPages: 10 } }),
-      client.graphql({ query: locationsQuery, pagination: { maxPages: 5 } })
-    ]);
-
-    log.info('Export complete', {
-      products: products.extensions.autoPagination.totalRecords,
-      locations: locations.extensions.autoPagination.totalRecords
-    });
-  })
-);
-```
-
-### ✅ DO: Use Minimal Logging in Standalone
-
-```typescript
-// ✅ Standalone Node.js/Deno - use minimal logging utilities
-import {
-  createClient,
-  createConsoleLogger,
-  toStructuredLogger
-} from '@fluentcommerce/fc-connect-sdk';
-
-const logger = toStructuredLogger(createConsoleLogger(), {
-  service: 'MultiConnectionExport',
-  correlationId: 'export-123'
-});
-
-const client = await createClient({
-  config: { /* ... */ }
-});
-
-logger.info('Starting parallel export');
-const [products, locations] = await Promise.all([
-  client.graphql({ query: productsQuery, pagination: { maxPages: 10 } }),
-  client.graphql({ query: locationsQuery, pagination: { maxPages: 5 } })
-]);
-
-logger.info('Export complete', {
-  products: products.extensions.autoPagination.totalRecords,
-  locations: locations.extensions.autoPagination.totalRecords
-});
-```
-
-## Best Practice 9: Batch Parallel Queries
-
-### ✅ DO: Limit Concurrent Queries
-
-```typescript
-async function batchedParallelQueries(queries: any[], batchSize = 3) {
-  const results = [];
-
-  for (let i = 0; i < queries.length; i += batchSize) {
-    const batch = queries.slice(i, i + batchSize);
-    console.log(`Processing batch ${i / batchSize + 1}...`);
-
-    const batchResults = await Promise.all(
-      batch.map(q => client.graphql(q))
-    );
-
-    results.push(...batchResults);
-  }
-
-  return results;
-}
-
-// Use it
-const queries = [
-  { query: productsQuery, pagination: { maxPages: 10 } },
-  { query: locationsQuery, pagination: { maxPages: 5 } },
-  { query: virtualPositionsQuery, pagination: { maxPages: 20 } },
-  { query: ordersQuery, pagination: { maxPages: 15 } },
-  { query: fulfilmentsQuery, pagination: { maxPages: 8 } }
-];
-
-const results = await batchedParallelQueries(queries, 3);
-```
-
-### ❌ DON'T: Too Many Concurrent Queries
-
-```typescript
-// ❌ Bad - 10+ parallel queries may overwhelm API/network
-const results = await Promise.all([...Array(10)].map(/* query */));
-```
-
-## Troubleshooting
-
-### Issue 1: Only First Page Returned
-
-**Symptoms:**
-- `maxPages: 10` set, but only first page returned
-- `totalPages: 1` in metadata
-
-**Causes & Fixes:**
-
-```typescript
-// Cause 1: No $after variable in query
-// ❌ Wrong
-query GetProducts($first: Int!) {
-  products(first: $first) { ... }  // Missing $after
-}
-
-// ✅ Fix
-query GetProducts($first: Int!, $after: String) {
-  products(first: $first, after: $after) { ... }
-}
-
-// Cause 2: connectionPath pointing to wrong field
-// ❌ Wrong
-pagination: { connectionPath: 'product' }  // Typo
-
-// ✅ Fix
-pagination: { connectionPath: 'products' }  // Correct field name
-
-// Cause 3: No more pages available
-// ✅ Check hasNextPage in first response
-const firstPage = await client.graphql({
-  query,
-  variables: { first: 100 }
-});
-
-console.log(firstPage.data.products.pageInfo.hasNextPage);
-// If false, only one page exists
-```
-
-### Issue 2: "Connection not found at path"
-
-**Symptoms:**
-- Error: "No connection found at path 'products'"
-
-**Causes & Fixes:**
-
-```typescript
-// Cause 1: Typo in connectionPath
-// ❌ Wrong
-pagination: { connectionPath: 'product' }
-
-// ✅ Fix
-pagination: { connectionPath: 'products' }
-
-// Cause 2: Path doesn't match query structure
-// ❌ Wrong
-query { order { items { ... } } }
-pagination: { connectionPath: 'items' }
-
-// ✅ Fix
-pagination: { connectionPath: 'order.items' }
-
-// Cause 3: Using alias but targeting original name
-// ❌ Wrong
-query { myProducts: products { ... } }
-pagination: { connectionPath: 'products' }
-
-// ✅ Fix
-pagination: { connectionPath: 'myProducts' }
-```
-
-### Issue 3: Slow Performance
-
-**Symptoms:**
-- Queries taking very long
-- High memory usage
-
-**Optimizations:**
-
-```typescript
-// Optimization 1: Reduce page size for complex queries
-// ❌ Slow
-variables: { first: 200 }  // Too large for orders with items
-
-// ✅ Fast
-variables: { first: 30 }   // Appropriate for complex entities
-
-// Optimization 2: Add timeoutMs limit
-pagination: {
-  maxPages: 100,
-  timeoutMs: 60000  // ← Stop after 60 seconds
-}
-
-// Optimization 3: Reduce maxRecords
-pagination: {
-  maxRecords: 5000  // ← Prevent excessive fetching
-}
-
-// Optimization 4: Use batching for many queries
-await batchedParallelQueries(queries, 3);  // 3 at a time
-```
-
-### Issue 4: Unexpected Record Counts
-
-**Symptoms:**
-- Getting more/fewer records than expected
-
-**Diagnostic Steps:**
-
-```typescript
-// Step 1: Check metadata
-console.log(result.extensions.autoPagination);
-// {
-//   totalPages: 8,
-//   totalRecords: 743,
-//   truncated: true  // ← Hit a limit
-// }
-
-// Step 2: Check which limit was hit
-if (result.extensions.autoPagination.truncated) {
-  // Check configured limits
-  console.log('Configured limits:', {
-    maxPages: 10,
-    maxRecords: 1000,
-    timeoutMs: 30000
-  });
-
-  // If totalPages < maxPages, likely hit maxRecords or timeoutMs
-}
-
-// Step 3: Verify page size
-const { totalRecords, totalPages } = result.extensions.autoPagination;
-const avgPageSize = totalRecords / totalPages;
-console.log(`Average page size: ${avgPageSize}`);
-// Should match variables.first (approximately)
-```
-
-### Issue 5: Deduplication Issues
-
-**Symptoms:**
-- Seeing duplicate records
-- Record count higher than expected
-
-**Causes & Fixes:**
-
-```typescript
-// Cause: Entities don't have 'id' field
-// ❌ Missing id
-query GetProducts($first: Int!, $after: String) {
-  products(first: $first, after: $after) {
-    edges {
-      node { ref type }  // ← No 'id' field
-      cursor
-    }
-    pageInfo { hasNextPage }
-  }
-}
-
-// ✅ Include id for deduplication
-query GetProducts($first: Int!, $after: String) {
-  products(first: $first, after: $after) {
-    edges {
-      node { id ref type }  // ← Include 'id'
-      cursor
-    }
-    pageInfo { hasNextPage }
-  }
-}
-```
-
-**Note:** SDK deduplicates by `id` field automatically. Always include `id` in your queries.
-
-## Production Checklist
-
-Before deploying multi-connection pagination:
-
-- [ ] ✅ **Best Practice 1**: Used `connectionPath` for all multi-connection queries
-- [ ] ✅ **Best Practice 2**: Used parallel queries (`Promise.all`) for multiple full pagination
-- [ ] ✅ **Best Practice 3**: Added separate progress monitoring with `onProgress` callbacks per connection
-- [ ] ✅ **Best Practice 4**: Implemented error handling with `Promise.allSettled` for resilience
-- [ ] ✅ **Best Practice 5**: Set appropriate safety limits (`maxPages`, `maxRecords`, `timeoutMs`)
-- [ ] ✅ **Best Practice 6**: Optimized page sizes for entity complexity
-- [ ] ✅ **Best Practice 7**: Reused client instances (not creating new clients per query)
-- [ ] ✅ **Best Practice 8**: Used appropriate logging (native log for Versori, minimal utilities for standalone)
-- [ ] ✅ **Best Practice 9**: Batched parallel queries (limit concurrent queries to 3-5)
-- [ ] ✅ Included `id` field in all queries for deduplication
-- [ ] ✅ Tested with small limits first (`maxPages: 2`)
-- [ ] ✅ Tested edge cases (empty results, single page, errors)
-
-## Performance Benchmarks
-
-Based on real Fluent Commerce API testing:
-
-| Scenario | Page Size | Pages | Records | Time | Notes |
-|----------|-----------|-------|---------|------|-------|
-| Virtual Positions | 200 | 50 | 10,000 | ~45s | Simple fields |
-| Products | 100 | 50 | 5,000 | ~60s | Medium complexity |
-| Orders (no items) | 75 | 20 | 1,500 | ~35s | Medium complexity |
-| Orders (with items) | 30 | 20 | 600 | ~50s | High complexity |
-
-**Parallel vs Sequential:**
-- **Parallel** (3 queries): ~60-70s total (overlapping execution)
-- **Sequential** (3 queries): ~140-150s total (sum of individual times)
-
-**Speedup:** ~2-2.5x faster with parallel execution
-
-## Key Takeaways
-
-- 🎯 **Always use `connectionPath`** - Explicit is better than implicit (Best Practice 1)
-- 🎯 **Parallel for multiple** - Use `Promise.all()` when all need pagination (Best Practice 2)
-- 🎯 **Monitor progress** - Separate `onProgress` callbacks per connection (Best Practice 3)
-- 🎯 **Handle errors gracefully** - Use `Promise.allSettled()` (Best Practice 4)
-- 🎯 **Set safety limits** - Use OR-logic: maxPages, maxRecords, timeoutMs (Best Practice 5)
-- 🎯 **Optimize page sizes** - Match entity complexity (Best Practice 6)
-- 🎯 **Reuse clients** - Don't create multiple instances (Best Practice 7)
-- 🎯 **Use appropriate logging** - Native log for Versori, minimal utilities for standalone (Best Practice 8)
-- 🎯 **Batch parallel queries** - Limit concurrent queries to 3-5 (Best Practice 9)
-- 🎯 **Test small first** - Verify with `maxPages: 2` before production
-
-## Next Steps
-
-Continue to [Module 6: API Reference](./multiple-connections-06-api-reference.md) for complete interface documentation and reference material.
+# Module 5: Best Practices
+
+**Level:** Advanced
+**Estimated Time:** 25 minutes
+
+**SDK Version:** Use latest - `npm install @fluentcommerce/fc-connect-sdk@latest`
+
+## Overview
+
+This module consolidates production-ready patterns, performance optimizations, and troubleshooting techniques for multi-connection scenarios.
+
+## Learning Objectives
+
+By the end of this module, you will:
+- ✅ Know when to use each multi-connection pattern
+- ✅ Implement production-ready error handling
+- ✅ Optimize performance for large-scale exports
+- ✅ Debug common issues effectively
+- ✅ Apply security and reliability best practices
+
+## Decision Matrix: Which Pattern to Use?
+
+### Quick Decision Tree
+
+```
+Do you need ALL connections fully paginated?
+├─ YES → Use parallel queries (Promise.all)
+│
+└─ NO → Do you need MORE THAN ONE connection paginated?
+   ├─ YES → Use parallel queries (Promise.all)
+   │
+   └─ NO → Use single query with connectionPath
+```
+
+### Detailed Comparison
+
+| Scenario | Pattern | Why |
+|----------|---------|-----|
+| Export all products + all locations | Parallel | Both need full pagination |
+| Export all products + first page locations | Single + connectionPath | Only products need pagination |
+| Export 3+ different entities | Parallel | Multiple connections need pagination |
+| Get order with all items | Single + connectionPath | Nested connection |
+| Export with different limits per entity | Parallel | Independent limit control |
+
+## Best Practice 1: Always Use connectionPath
+
+### ✅ DO: Be Explicit
+
+```typescript
+// ✅ Good - explicit and predictable
+const result = await client.graphql({
+  query: multiConnectionQuery,
+  pagination: {
+    connectionPath: 'products',
+    maxPages: 10
+  }
+});
+```
+
+### ❌ DON'T: Rely on Auto-Detection
+
+```typescript
+// ❌ Risky - which connection gets paginated?
+const result = await client.graphql({
+  query: multiConnectionQuery,
+  pagination: { maxPages: 10 }  // Auto-detection is unpredictable
+});
+```
+
+**Exception:** Only one connection exists and path is obvious.
+
+## Best Practice 2: Use Parallel Queries for Multiple Full Pagination
+
+### ✅ DO: Separate Queries
+
+```typescript
+// ✅ Good - parallel queries with independent configs
+const [products, locations] = await Promise.all([
+  client.graphql({
+    query: productsQuery,
+    variables: { first: 100 },
+    pagination: { maxPages: 10, maxRecords: 1000 }
+  }),
+  client.graphql({
+    query: locationsQuery,
+    variables: { first: 50 },
+    pagination: { maxPages: 5, maxRecords: 250 }
+  })
+]);
+```
+
+### ❌ DON'T: Single Query Expecting Multiple Pagination
+
+```typescript
+// ❌ Bad - only one connection will be paginated
+const result = await client.graphql({
+  query: multiConnectionQuery,
+  pagination: {
+    connectionPath: 'products',  // locations won't be paginated
+    maxPages: 10
+  }
+});
+```
+
+## Best Practice 3: Monitor Progress Per Connection
+
+### ✅ DO: Separate Progress Tracking
+
+```typescript
+const [products, locations] = await Promise.all([
+  client.graphql({
+    query: productsQuery,
+    pagination: {
+      maxPages: 10,
+      onProgress: (page, records) => {
+        console.log(`[Products] Page ${page}: ${records} records`);
+      }
+    }
+  }),
+  client.graphql({
+    query: locationsQuery,
+    pagination: {
+      maxPages: 5,
+      onProgress: (page, records) => {
+        console.log(`[Locations] Page ${page}: ${records} records`);
+      }
+    }
+  })
+]);
+```
+
+### ❌ DON'T: Generic Logging
+
+```typescript
+// ❌ Bad - can't tell which connection
+const result = await client.graphql({
+  query: multiConnectionQuery,
+  pagination: {
+    connectionPath: 'products',
+    onProgress: (page, records) => {
+      console.log(`Page ${page}: ${records}`);  // Which connection?
+    }
+  }
+});
+```
+
+## Best Practice 4: Use Promise.allSettled for Resilience
+
+### ✅ DO: Handle Partial Failures
+
+```typescript
+const results = await Promise.allSettled([
+  client.graphql({ query: productsQuery, pagination: { maxPages: 10 } }),
+  client.graphql({ query: locationsQuery, pagination: { maxPages: 5 } }),
+  client.graphql({ query: virtualPositionsQuery, pagination: { maxPages: 20 } })
+]);
+
+const successful = results.filter(r => r.status === 'fulfilled');
+const failed = results.filter(r => r.status === 'rejected');
+
+console.log(`✅ Successful: ${successful.length}`);
+console.log(`❌ Failed: ${failed.length}`);
+
+// Process successful results
+successful.forEach((result, index) => {
+  if (result.status === 'fulfilled') {
+    const data = result.value;
+    // Process data
+  }
+});
+
+// Log failures
+failed.forEach((result, index) => {
+  if (result.status === 'rejected') {
+    console.error(`Failed query ${index}:`, result.reason);
+  }
+});
+```
+
+### ❌ DON'T: Use Promise.all Without Error Handling
+
+```typescript
+// ❌ Bad - one failure loses all results
+try {
+  const [products, locations] = await Promise.all([
+    client.graphql({ query: productsQuery, pagination: { maxPages: 10 } }),
+    client.graphql({ query: locationsQuery, pagination: { maxPages: 5 } })
+  ]);
+} catch (error) {
+  // Both results lost if one fails
+}
+```
+
+## Best Practice 5: Set Appropriate Safety Limits
+
+### ✅ DO: Use OR-Logic Limits
+
+```typescript
+const result = await client.graphql({
+  query: productsQuery,
+  pagination: {
+    maxPages: 100,        // OR
+    maxRecords: 10000,    // OR
+    timeoutMs: 60000      // OR (60 seconds)
+  }
+});
+```
+
+**Whichever limit is hit first stops pagination.**
+
+### ✅ DO: Match Limits to Entity Complexity
+
+```typescript
+// Simple entities - higher limits
+const virtualPositions = await client.graphql({
+  query: virtualPositionsQuery,
+  pagination: {
+    maxPages: 200,
+    maxRecords: 20000
+  }
+});
+
+// Complex entities - lower limits
+const orders = await client.graphql({
+  query: ordersWithItemsQuery,
+  pagination: {
+    maxPages: 50,
+    maxRecords: 2000
+  }
+});
+```
+
+## Best Practice 6: Optimize Page Sizes
+
+### ✅ DO: Match Page Size to Entity
+
+| Entity Type | Recommended Page Size | Reasoning |
+|-------------|----------------------|-----------|
+| VirtualPositions | 200-500 | Very simple fields |
+| Locations | 100-200 | Simple fields |
+| Products | 50-100 | Medium complexity |
+| Orders (no items) | 50-100 | Medium complexity |
+| Orders (with items) | 20-50 | High complexity, nested |
+
+```typescript
+const [virtualPositions, products, orders] = await Promise.all([
+  client.graphql({
+    query: virtualPositionsQuery,
+    variables: { first: 200 },  // ← Large page size
+    pagination: { maxRecords: 10000 }
+  }),
+  client.graphql({
+    query: productsQuery,
+    variables: { first: 75 },   // ← Medium page size
+    pagination: { maxRecords: 5000 }
+  }),
+  client.graphql({
+    query: ordersQuery,
+    variables: { first: 30 },   // ← Small page size
+    pagination: { maxRecords: 1000 }
+  })
+]);
+```
+
+## Best Practice 7: Reuse Client Instances
+
+### ✅ DO: Share Client
+
+```typescript
+// ✅ Good - create once, reuse
+const client = await createClient({
+  config: {
+    baseUrl: process.env.FLUENT_BASE_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!
+  }
+});
+
+const [products, locations, virtualPositions] = await Promise.all([
+  client.graphql({ query: productsQuery, pagination: { maxPages: 10 } }),
+  client.graphql({ query: locationsQuery, pagination: { maxPages: 5 } }),
+  client.graphql({ query: virtualPositionsQuery, pagination: { maxPages: 20 } })
+]);
+```
+
+### ❌ DON'T: Create Multiple Clients
+
+```typescript
+// ❌ Bad - creates new auth token for each query
+const results = await Promise.all([
+  createClient({ config: {...} }).then(c => c.graphql({ ... })),
+  createClient({ config: {...} }).then(c => c.graphql({ ... })),
+  createClient({ config: {...} }).then(c => c.graphql({ ... }))
+]);
+```
+
+## Best Practice 8: Use Appropriate Logging
+
+### ✅ DO: Use Native Log in Versori
+
+```typescript
+// ✅ Versori Platform - use native log
+import { schedule, http } from '@versori/run';
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+export const workflow = schedule('multi-export', '0 * * * *').then(
+  http('process', { connection: 'fluent' }, async (ctx) => {
+    const { log } = ctx;
+
+    // Pass native log to SDK
+    const client = await createClient(ctx); // Auto-detects Versori context
+
+    log.info('Starting parallel export');
+    const [products, locations] = await Promise.all([
+      client.graphql({ query: productsQuery, pagination: { maxPages: 10 } }),
+      client.graphql({ query: locationsQuery, pagination: { maxPages: 5 } })
+    ]);
+
+    log.info('Export complete', {
+      products: products.extensions.autoPagination.totalRecords,
+      locations: locations.extensions.autoPagination.totalRecords
+    });
+  })
+);
+```
+
+### ✅ DO: Use Minimal Logging in Standalone
+
+```typescript
+// ✅ Standalone Node.js/Deno - use minimal logging utilities
+import {
+  createClient,
+  createConsoleLogger,
+  toStructuredLogger
+} from '@fluentcommerce/fc-connect-sdk';
+
+const logger = toStructuredLogger(createConsoleLogger(), {
+  service: 'MultiConnectionExport',
+  correlationId: 'export-123'
+});
+
+const client = await createClient({
+  config: { /* ... */ }
+});
+
+logger.info('Starting parallel export');
+const [products, locations] = await Promise.all([
+  client.graphql({ query: productsQuery, pagination: { maxPages: 10 } }),
+  client.graphql({ query: locationsQuery, pagination: { maxPages: 5 } })
+]);
+
+logger.info('Export complete', {
+  products: products.extensions.autoPagination.totalRecords,
+  locations: locations.extensions.autoPagination.totalRecords
+});
+```
+
+## Best Practice 9: Batch Parallel Queries
+
+### ✅ DO: Limit Concurrent Queries
+
+```typescript
+async function batchedParallelQueries(queries: any[], batchSize = 3) {
+  const results = [];
+
+  for (let i = 0; i < queries.length; i += batchSize) {
+    const batch = queries.slice(i, i + batchSize);
+    console.log(`Processing batch ${i / batchSize + 1}...`);
+
+    const batchResults = await Promise.all(
+      batch.map(q => client.graphql(q))
+    );
+
+    results.push(...batchResults);
+  }
+
+  return results;
+}
+
+// Use it
+const queries = [
+  { query: productsQuery, pagination: { maxPages: 10 } },
+  { query: locationsQuery, pagination: { maxPages: 5 } },
+  { query: virtualPositionsQuery, pagination: { maxPages: 20 } },
+  { query: ordersQuery, pagination: { maxPages: 15 } },
+  { query: fulfilmentsQuery, pagination: { maxPages: 8 } }
+];
+
+const results = await batchedParallelQueries(queries, 3);
+```
+
+### ❌ DON'T: Too Many Concurrent Queries
+
+```typescript
+// ❌ Bad - 10+ parallel queries may overwhelm API/network
+const results = await Promise.all([...Array(10)].map(/* query */));
+```
+
+## Troubleshooting
+
+### Issue 1: Only First Page Returned
+
+**Symptoms:**
+- `maxPages: 10` set, but only first page returned
+- `totalPages: 1` in metadata
+
+**Causes & Fixes:**
+
+```typescript
+// Cause 1: No $after variable in query
+// ❌ Wrong
+query GetProducts($first: Int!) {
+  products(first: $first) { ... }  // Missing $after
+}
+
+// ✅ Fix
+query GetProducts($first: Int!, $after: String) {
+  products(first: $first, after: $after) { ... }
+}
+
+// Cause 2: connectionPath pointing to wrong field
+// ❌ Wrong
+pagination: { connectionPath: 'product' }  // Typo
+
+// ✅ Fix
+pagination: { connectionPath: 'products' }  // Correct field name
+
+// Cause 3: No more pages available
+// ✅ Check hasNextPage in first response
+const firstPage = await client.graphql({
+  query,
+  variables: { first: 100 }
+});
+
+console.log(firstPage.data.products.pageInfo.hasNextPage);
+// If false, only one page exists
+```
+
+### Issue 2: "Connection not found at path"
+
+**Symptoms:**
+- Error: "No connection found at path 'products'"
+
+**Causes & Fixes:**
+
+```typescript
+// Cause 1: Typo in connectionPath
+// ❌ Wrong
+pagination: { connectionPath: 'product' }
+
+// ✅ Fix
+pagination: { connectionPath: 'products' }
+
+// Cause 2: Path doesn't match query structure
+// ❌ Wrong
+query { order { items { ... } } }
+pagination: { connectionPath: 'items' }
+
+// ✅ Fix
+pagination: { connectionPath: 'order.items' }
+
+// Cause 3: Using alias but targeting original name
+// ❌ Wrong
+query { myProducts: products { ... } }
+pagination: { connectionPath: 'products' }
+
+// ✅ Fix
+pagination: { connectionPath: 'myProducts' }
+```
+
+### Issue 3: Slow Performance
+
+**Symptoms:**
+- Queries taking very long
+- High memory usage
+
+**Optimizations:**
+
+```typescript
+// Optimization 1: Reduce page size for complex queries
+// ❌ Slow
+variables: { first: 200 }  // Too large for orders with items
+
+// ✅ Fast
+variables: { first: 30 }   // Appropriate for complex entities
+
+// Optimization 2: Add timeoutMs limit
+pagination: {
+  maxPages: 100,
+  timeoutMs: 60000  // ← Stop after 60 seconds
+}
+
+// Optimization 3: Reduce maxRecords
+pagination: {
+  maxRecords: 5000  // ← Prevent excessive fetching
+}
+
+// Optimization 4: Use batching for many queries
+await batchedParallelQueries(queries, 3);  // 3 at a time
+```
+
+### Issue 4: Unexpected Record Counts
+
+**Symptoms:**
+- Getting more/fewer records than expected
+
+**Diagnostic Steps:**
+
+```typescript
+// Step 1: Check metadata
+console.log(result.extensions.autoPagination);
+// {
+//   totalPages: 8,
+//   totalRecords: 743,
+//   truncated: true  // ← Hit a limit
+// }
+
+// Step 2: Check which limit was hit
+if (result.extensions.autoPagination.truncated) {
+  // Check configured limits
+  console.log('Configured limits:', {
+    maxPages: 10,
+    maxRecords: 1000,
+    timeoutMs: 30000
+  });
+
+  // If totalPages < maxPages, likely hit maxRecords or timeoutMs
+}
+
+// Step 3: Verify page size
+const { totalRecords, totalPages } = result.extensions.autoPagination;
+const avgPageSize = totalRecords / totalPages;
+console.log(`Average page size: ${avgPageSize}`);
+// Should match variables.first (approximately)
+```
+
+### Issue 5: Deduplication Issues
+
+**Symptoms:**
+- Seeing duplicate records
+- Record count higher than expected
+
+**Causes & Fixes:**
+
+```typescript
+// Cause: Entities don't have 'id' field
+// ❌ Missing id
+query GetProducts($first: Int!, $after: String) {
+  products(first: $first, after: $after) {
+    edges {
+      node { ref type }  // ← No 'id' field
+      cursor
+    }
+    pageInfo { hasNextPage }
+  }
+}
+
+// ✅ Include id for deduplication
+query GetProducts($first: Int!, $after: String) {
+  products(first: $first, after: $after) {
+    edges {
+      node { id ref type }  // ← Include 'id'
+      cursor
+    }
+    pageInfo { hasNextPage }
+  }
+}
+```
+
+**Note:** SDK deduplicates by `id` field automatically. Always include `id` in your queries.
+
+## Production Checklist
+
+Before deploying multi-connection pagination:
+
+- [ ] ✅ **Best Practice 1**: Used `connectionPath` for all multi-connection queries
+- [ ] ✅ **Best Practice 2**: Used parallel queries (`Promise.all`) for multiple full pagination
+- [ ] ✅ **Best Practice 3**: Added separate progress monitoring with `onProgress` callbacks per connection
+- [ ] ✅ **Best Practice 4**: Implemented error handling with `Promise.allSettled` for resilience
+- [ ] ✅ **Best Practice 5**: Set appropriate safety limits (`maxPages`, `maxRecords`, `timeoutMs`)
+- [ ] ✅ **Best Practice 6**: Optimized page sizes for entity complexity
+- [ ] ✅ **Best Practice 7**: Reused client instances (not creating new clients per query)
+- [ ] ✅ **Best Practice 8**: Used appropriate logging (native log for Versori, minimal utilities for standalone)
+- [ ] ✅ **Best Practice 9**: Batched parallel queries (limit concurrent queries to 3-5)
+- [ ] ✅ Included `id` field in all queries for deduplication
+- [ ] ✅ Tested with small limits first (`maxPages: 2`)
+- [ ] ✅ Tested edge cases (empty results, single page, errors)
+
+## Performance Benchmarks
+
+Based on real Fluent Commerce API testing:
+
+| Scenario | Page Size | Pages | Records | Time | Notes |
+|----------|-----------|-------|---------|------|-------|
+| Virtual Positions | 200 | 50 | 10,000 | ~45s | Simple fields |
+| Products | 100 | 50 | 5,000 | ~60s | Medium complexity |
+| Orders (no items) | 75 | 20 | 1,500 | ~35s | Medium complexity |
+| Orders (with items) | 30 | 20 | 600 | ~50s | High complexity |
+
+**Parallel vs Sequential:**
+- **Parallel** (3 queries): ~60-70s total (overlapping execution)
+- **Sequential** (3 queries): ~140-150s total (sum of individual times)
+
+**Speedup:** ~2-2.5x faster with parallel execution
+
+## Key Takeaways
+
+- 🎯 **Always use `connectionPath`** - Explicit is better than implicit (Best Practice 1)
+- 🎯 **Parallel for multiple** - Use `Promise.all()` when all need pagination (Best Practice 2)
+- 🎯 **Monitor progress** - Separate `onProgress` callbacks per connection (Best Practice 3)
+- 🎯 **Handle errors gracefully** - Use `Promise.allSettled()` (Best Practice 4)
+- 🎯 **Set safety limits** - Use OR-logic: maxPages, maxRecords, timeoutMs (Best Practice 5)
+- 🎯 **Optimize page sizes** - Match entity complexity (Best Practice 6)
+- 🎯 **Reuse clients** - Don't create multiple instances (Best Practice 7)
+- 🎯 **Use appropriate logging** - Native log for Versori, minimal utilities for standalone (Best Practice 8)
+- 🎯 **Batch parallel queries** - Limit concurrent queries to 3-5 (Best Practice 9)
+- 🎯 **Test small first** - Verify with `maxPages: 2` before production
+
+## Next Steps
+
+Continue to [Module 6: API Reference](./multiple-connections-06-api-reference.md) for complete interface documentation and reference material.