@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/02-CORE-GUIDES/auto-pagination/modules/auto-pagination-03-configuration.md

@@ -1,754 +1,754 @@
-# Module 3: Configuration Mastery
-
-> **Learning Objective:** Master all pagination configuration options and learn entity-specific performance tuning strategies.
->
-> **Level:** Intermediate
-
-## Table of Contents
-
-1. [Complete Configuration Reference](#complete-configuration-reference)
-2. `Safety Limits (OR-Logic)`
-3. [Entity-Specific Recommendations](#entity-specific-recommendations)
-4. [Progress Tracking](#progress-tracking)
-5. [Pagination Direction](#pagination-direction)
-6. [Delay and Rate Limiting](#delay-and-rate-limiting)
-7. [Connection Path](#connection-path)
-8. [Abort Signal](#abort-signal)
-9. [Performance Tuning Guide](#performance-tuning-guide)
-10. [Configuration Patterns](#configuration-patterns)
-
----
-
-## Complete Configuration Reference
-
-```typescript
-interface PaginationConfig {
-  /** Enable/disable auto-pagination (default: auto-detected) */
-  enabled?: boolean;
-
-  /** Maximum pages to fetch (default: 100) */
-  maxPages?: number;
-
-  /** Maximum total records (default: 10,000) */
-  maxRecords?: number;
-
-  /** Timeout in milliseconds (default: 300,000 = 5 minutes) */
-  timeoutMs?: number;
-
-  /** Delay between page fetches in ms (default: 0) */
-  delayMs?: number;
-
-  /** Pagination direction (default: auto-detected) */
-  direction?: 'forward' | 'backward';
-
-  /** Path to connection in response (e.g., "order.items") */
-  connectionPath?: string;
-
-  /** AbortSignal to cancel pagination */
-  abortSignal?: AbortSignal;
-
-  /** Progress callback after each page */
-  onProgress?: (page: number, totalRecords: number) => void;
-
-  /** Warning callback for approaching limits */
-  onWarning?: (message: string) => void;
-}
-```
-
----
-
-## Safety Limits (OR-Logic)
-
-**CRITICAL:** Pagination stops when **the first limit is reached** (OR-logic, not AND-logic).
-
-```typescript
-pagination: {
-  maxPages: 50,        // Stop after 50 pages
-  maxRecords: 5000,    // OR stop after 5000 records
-  timeoutMs: 60000,    // OR stop after 60 seconds
-}
-
-// Whichever limit is reached FIRST stops pagination!
-```
-
-### Example Scenarios
-
-| Scenario | Result |
-|----------|--------|
-| Page 45 with 4800 records | Continue (no limit reached) |
-| Page 50 with 4950 records | Stop (maxPages reached) |
-| Page 48 with 5100 records | Stop (maxRecords reached) |
-| 55 seconds elapsed, page 48 | Stop (timeoutMs reached) |
-
-### Checking Truncation
-
-```typescript
-const result = await client.graphql({
-  query,
-  variables: { first: 100 },
-  pagination: { maxPages: 50, maxRecords: 5000, timeoutMs: 60000 }
-});
-
-if (result.extensions.autoPagination.truncated) {
-  console.warn(`⚠️ Results truncated!`);
-  console.warn(`Reason: ${result.extensions.autoPagination.truncationReason}`);
-  // Possible values: "maxPages" | "maxRecords" | "timeout"
-}
-```
-
----
-
-## Entity-Specific Recommendations
-
-Different Fluent entities have different complexities. Page size should match entity complexity:
-
-### Simple Entities (High Page Size)
-
-**Entities:** `virtualPositions`, `locations`, `inventoryQuantities`
-
-**Characteristics:**
-- Few fields
-- No nested connections
-- Simple scalar types
-
-**Recommended Configuration:**
-
-```typescript
-// ✅ OPTIMAL for simple entities
-pagination: {
-  maxPages: 100,
-  maxRecords: 10000,
-  timeoutMs: 120000  // 2 minutes
-}
-
-variables: {
-  first: 150  // Large page size OK
-}
-```
-
-**Example:**
-
-```typescript
-const positions = await client.graphql({
-  query: `
-    query GetVirtualPositions($first: Int!, $after: String) {
-      virtualPositions(first: $first, after: $after) {
-        edges {
-          node { id ref productRef quantity groupRef }
-          cursor
-        }
-        pageInfo { hasNextPage }
-      }
-    }
-  `,
-  variables: { first: 150 },  // High page size
-  pagination: {
-    maxPages: 100,
-    maxRecords: 15000,
-    timeoutMs: 120000
-  }
-});
-```
-
-### Medium Complexity Entities (Medium Page Size)
-
-**Entities:** `products`, `categories`, `carriers`
-
-**Characteristics:**
-- Multiple nested objects
-- Some arrays
-- Rich attribute data
-
-**Recommended Configuration:**
-
-```typescript
-// ✅ OPTIMAL for medium complexity
-pagination: {
-  maxPages: 50,
-  maxRecords: 5000,
-  timeoutMs: 180000  // 3 minutes
-}
-
-variables: {
-  first: 75  // Medium page size
-}
-```
-
-**Example:**
-
-```typescript
-const products = await client.graphql({
-  query: `
-    query GetProducts($first: Int!, $after: String) {
-      products(first: $first, after: $after) {
-        edges {
-          node {
-            id
-            ref
-            type
-            gtin
-            attributes { name type value }
-          }
-          cursor
-        }
-        pageInfo { hasNextPage }
-      }
-    }
-  `,
-  variables: { first: 75 },  // Medium page size
-  pagination: {
-    maxPages: 50,
-    maxRecords: 5000,
-    timeoutMs: 180000
-  }
-});
-```
-
-### Complex Entities (Low Page Size)
-
-**Entities:** `orders` (with items), `fulfilments` (with items), deeply nested queries
-
-**Characteristics:**
-- Multiple levels of nesting
-- Large arrays (order items)
-- Complex attribute structures
-
-**Recommended Configuration:**
-
-```typescript
-// ✅ OPTIMAL for complex entities
-pagination: {
-  maxPages: 30,
-  maxRecords: 1000,
-  timeoutMs: 240000,  // 4 minutes
-  delayMs: 100  // Rate limiting
-}
-
-variables: {
-  first: 20  // Small page size!
-}
-```
-
-**Example:**
-
-```typescript
-const orders = await client.graphql({
-  query: `
-    query GetOrders($first: Int!, $after: String) {
-      orders(first: $first, after: $after) {
-        edges {
-          node {
-            id
-            ref
-            status
-            items {
-              edges {
-                node {
-                  id
-                  ref
-                  productRef
-                  quantity
-                }
-              }
-            }
-          }
-          cursor
-        }
-        pageInfo { hasNextPage }
-      }
-    }
-  `,
-  variables: { first: 20 },  // Small page size for nested data
-  pagination: {
-    maxPages: 30,
-    maxRecords: 1000,
-    timeoutMs: 240000,
-    delayMs: 100
-  }
-});
-```
-
----
-
-## Progress Tracking
-
-Monitor pagination progress with callbacks:
-
-```typescript
-const result = await client.graphql({
-  query,
-  variables: { first: 100 },
-  pagination: {
-    maxRecords: 10000,
-
-    // Called after each page fetch
-    onProgress: (page, totalRecords) => {
-      console.log(`📄 Page ${page}: ${totalRecords} records fetched`);
-
-      // Custom logic
-      if (page % 10 === 0) {
-        console.log(`Checkpoint: ${page} pages completed`);
-      }
-    },
-
-    // Called when approaching limits
-    onWarning: (message) => {
-      console.warn(`⚠️ ${message}`);
-    }
-  }
-});
-```
-
-### Advanced Progress Example
-
-```typescript
-let startTime = Date.now();
-
-const result = await client.graphql({
-  query,
-  variables: { first: 100 },
-  pagination: {
-    maxPages: 100,
-    onProgress: (page, totalRecords) => {
-      const elapsed = ((Date.now() - startTime) / 1000).toFixed(2);
-      const recordsPerSec = (totalRecords / (Date.now() - startTime) * 1000).toFixed(0);
-
-      process.stdout.write(
-        `\r📊 Page ${page} | Records: ${totalRecords} | ` +
-        `Time: ${elapsed}s | Rate: ${recordsPerSec} records/sec`
-      );
-    },
-    onWarning: (message) => {
-      console.warn(`\n⚠️ Warning: ${message}`);
-    }
-  }
-});
-
-console.log('\n✅ Complete!');
-```
-
----
-
-## Pagination Direction
-
-### Forward Pagination (Default)
-
-Most common: fetch from beginning to end using `first` and `after`.
-
-```typescript
-// Forward pagination (default)
-const result = await client.graphql({
-  query: `
-    query GetItems($first: Int!, $after: String) {
-      items(first: $first, after: $after) {
-        edges { node { id ref } cursor }
-        pageInfo { hasNextPage }
-      }
-    }
-  `,
-  variables: { first: 100 },
-  pagination: {
-    direction: 'forward'  // Optional, auto-detected
-  }
-});
-```
-
-### Backward Pagination
-
-Fetch from end to beginning using `last` and `before`.
-
-```typescript
-// Backward pagination
-const result = await client.graphql({
-  query: `
-    query GetItems($last: Int!, $before: String) {
-      items(last: $last, before: $before) {
-        edges { node { id ref } cursor }
-        pageInfo { hasPreviousPage }
-      }
-    }
-  `,
-  variables: { last: 100 },
-  pagination: {
-    direction: 'backward',  // Required for backward
-    maxPages: 50
-  }
-});
-```
-
----
-
-## Understanding Cursor Selection
-
-The SDK automatically selects the correct cursor based on pagination direction:
-
-### Forward Pagination (`first`/`after`)
-
-Uses **last edge cursor** from each page:
-
-```typescript
-// SDK automatically does this:
-const edges = result.data.items.edges;
-const nextCursor = edges[edges.length - 1].cursor;  // Last edge
-// Next request: { first: 100, after: nextCursor }
-```
-
-**Why:** Next page starts AFTER the last item fetched, moving forward through the dataset.
-
-### Backward Pagination (`last`/`before`)
-
-Uses **first edge cursor** from each page:
-
-```typescript
-// SDK automatically does this:
-const edges = result.data.items.edges;
-const nextCursor = edges[0].cursor;  // First edge
-// Next request: { last: 100, before: nextCursor }
-```
-
-**Why:** Previous page ends BEFORE the first item fetched, moving backward through the dataset.
-
-### Key Differences
-
-| Direction | Cursor Position | Traversal Direction | Use Case |
-|-----------|----------------|-------------------|----------|
-| **Forward** | Last edge | Start → End | Full dataset exports, chronological processing |
-| **Backward** | First edge | End → Start | Recent records, reverse chronological feeds |
-
-### Common Mistakes
-
-```typescript
-// ❌ WRONG: Using wrong cursor for direction
-// Forward pagination with first cursor
-const cursor = edges[0].cursor;  // Wrong!
-variables: { first: 100, after: cursor }
-
-// ❌ WRONG: Backward pagination with last cursor
-const cursor = edges[edges.length - 1].cursor;  // Wrong!
-variables: { last: 100, before: cursor }
-
-// ✅ CORRECT: SDK handles this automatically
-const result = await orchestrator.extract({
-  direction: 'forward',  // or 'backward'
-  // SDK picks correct cursor based on direction
-});
-```
-
----
-
-## Delay and Rate Limiting
-
-Add delays between page fetches to respect rate limits:
-
-```typescript
-const result = await client.graphql({
-  query,
-  variables: { first: 100 },
-  pagination: {
-    maxPages: 100,
-    delayMs: 200  // Wait 200ms between each page
-  }
-});
-
-// Total time = (pages * delayMs) + (pages * requestTime)
-// Example: 50 pages * 200ms = 10 seconds of delays
-```
-
-### Use Cases for Delays
-
-| Use Case | delayMs | Reason |
-|----------|---------|--------|
-| **API Rate Limits** | 100-500 | Avoid 429 errors |
-| **Database Protection** | 200-300 | Reduce DB load |
-| **Concurrent Operations** | 100-200 | Prevent resource contention |
-| **Testing** | 1000+ | Simulate slow connections |
-| **No Rate Limits** | 0 | Maximum speed |
-
----
-
-## Connection Path
-
-Specify which connection to paginate when multiple exist:
-
-### Auto-Detection (Default)
-
-```typescript
-// SDK automatically finds first connection
-const result = await client.graphql({
-  query: `
-    query GetData($first: Int!, $after: String) {
-      items(first: $first, after: $after) {
-        edges { node { id ref } cursor }
-        pageInfo { hasNextPage }
-      }
-    }
-  `,
-  variables: { first: 100 }
-  // connectionPath not needed - only one connection
-});
-```
-
-### Explicit Path (Multiple Connections)
-
-```typescript
-// Multiple connections - must specify which to paginate
-const result = await client.graphql({
-  query: `
-    query GetMultiple($first: Int!, $after: String) {
-      locations(first: $first, after: $after) {
-        edges { node { id ref name type } cursor }
-        pageInfo { hasNextPage }
-      }
-      products(first: $first, after: $after) {
-        edges { node { id ref type gtin } cursor }
-        pageInfo { hasNextPage }
-      }
-    }
-  `,
-  variables: { first: 100 },
-  pagination: {
-    connectionPath: 'locations'  // Paginate locations only
-  }
-});
-```
-
-### Nested Connection Path
-
-```typescript
-// Paginate nested connection
-const result = await client.graphql({
-  query: `
-    query GetOrder($orderId: ID!, $first: Int!, $after: String) {
-      order(id: $orderId) {
-        id
-        ref
-        items(first: $first, after: $after) {
-          edges { node { id ref productRef quantity } cursor }
-          pageInfo { hasNextPage }
-        }
-      }
-    }
-  `,
-  variables: { orderId: 'ORDER123', first: 50 },
-  pagination: {
-    connectionPath: 'order.items',  // Dot notation for nested
-    maxPages: 20
-  }
-});
-```
-
----
-
-## Abort Signal
-
-Cancel pagination programmatically:
-
-```typescript
-const controller = new AbortController();
-
-// Start pagination
-const paginationPromise = client.graphql({
-  query,
-  variables: { first: 100 },
-  pagination: {
-    maxPages: 1000,
-    abortSignal: controller.signal
-  }
-});
-
-// Cancel after 10 seconds
-setTimeout(() => {
-  console.log('⏱️ Timeout reached, aborting pagination...');
-  controller.abort();
-}, 10000);
-
-try {
-  const result = await paginationPromise;
-} catch (error) {
-  if (error.name === 'AbortError') {
-    console.log('✅ Pagination aborted successfully');
-  }
-}
-```
-
----
-
-## Performance Tuning Guide
-
-### Scenario 1: Maximum Speed
-
-```typescript
-// Goal: Fetch as fast as possible
-pagination: {
-  maxPages: 500,     // High limit
-  maxRecords: 50000, // High limit
-  timeoutMs: 600000, // 10 minutes
-  delayMs: 0         // No delays!
-}
-
-variables: {
-  first: 200  // Large pages
-}
-```
-
-### Scenario 2: Maximum Safety
-
-```typescript
-// Goal: Conservative, fail-safe operation
-pagination: {
-  maxPages: 20,      // Low limit
-  maxRecords: 2000,  // Low limit
-  timeoutMs: 30000,  // 30 seconds
-  delayMs: 100,      // Small delays
-  onWarning: (msg) => console.warn(msg)
-}
-
-variables: {
-  first: 50  // Small pages
-}
-```
-
-### Scenario 3: Background Job
-
-```typescript
-// Goal: Thorough, scheduled task
-pagination: {
-  maxPages: 200,
-  maxRecords: 20000,
-  timeoutMs: 600000,  // 10 minutes
-  delayMs: 50,
-  onProgress: (page, records) => {
-    if (page % 25 === 0) {
-      console.log(`Progress: ${records} records`);
-    }
-  }
-}
-
-variables: {
-  first: 100
-}
-```
-
-### Scenario 4: User-Facing API
-
-```typescript
-// Goal: Fast response for UI
-pagination: {
-  maxPages: 10,      // Quick return
-  maxRecords: 1000,
-  timeoutMs: 5000,   // 5 seconds max
-  delayMs: 0
-}
-
-variables: {
-  first: 100
-}
-```
-
----
-
-## Configuration Patterns
-
-### Pattern 1: Progressive Loading with Checkpoints
-
-```typescript
-const checkpoint = { page: 0, records: 0 };
-
-const result = await client.graphql({
-  query,
-  variables: { first: 100 },
-  pagination: {
-    maxPages: 100,
-    onProgress: (page, records) => {
-      checkpoint.page = page;
-      checkpoint.records = records;
-
-      // Save checkpoint every 10 pages
-      if (page % 10 === 0) {
-        fs.writeFileSync('checkpoint.json', JSON.stringify(checkpoint));
-      }
-    }
-  }
-});
-```
-
-### Pattern 2: Adaptive Rate Limiting
-
-```typescript
-let delayMs = 0;
-const warnings: string[] = [];
-
-const result = await client.graphql({
-  query,
-  variables: { first: 100 },
-  pagination: {
-    maxPages: 100,
-    delayMs,
-    onWarning: (message) => {
-      warnings.push(message);
-
-      // Increase delay if getting warnings
-      if (warnings.length > 5) {
-        delayMs += 100;
-        console.log(`⚠️ Increasing delay to ${delayMs}ms due to warnings`);
-      }
-    }
-  }
-});
-```
-
-### Pattern 3: Time-Budgeted Pagination
-
-```typescript
-const timeBudgetMs = 60000;  // 1 minute budget
-const startTime = Date.now();
-
-const result = await client.graphql({
-  query,
-  variables: { first: 100 },
-  pagination: {
-    timeoutMs: timeBudgetMs,
-    maxRecords: 10000,
-    onProgress: (page, records) => {
-      const elapsed = Date.now() - startTime;
-      const remainingTime = timeBudgetMs - elapsed;
-      console.log(`⏱️ Remaining time: ${(remainingTime / 1000).toFixed(1)}s`);
-    }
-  }
-});
-
-if (result.extensions.autoPagination.truncated &&
-    result.extensions.autoPagination.truncationReason === 'timeout') {
-  console.log('⏰ Time budget exhausted - consider increasing timeout or page size');
-}
-```
-
----
-
-## Summary: Quick Configuration Guide
-
-| Entity Type | first | maxPages | maxRecords | timeoutMs | delayMs |
-|-------------|-------|----------|------------|-----------|---------|
-| Simple (positions, locations) | 150 | 100 | 15000 | 120000 | 0 |
-| Medium (products, categories) | 75 | 50 | 5000 | 180000 | 0-50 |
-| Complex (orders with items) | 20 | 30 | 1000 | 240000 | 100 |
-| Testing/Dev | 50 | 5 | 500 | 10000 | 0 |
-| Production Export | 100 | 100 | 10000 | 300000 | 0 |
-| Background Job | 100 | 200 | 20000 | 600000 | 50 |
-| User-Facing API | 100 | 10 | 1000 | 5000 | 0 |
-
----
-
-## Next Steps
-
-Now that you've mastered configuration, explore advanced query patterns:
-
-**Continue to:** [Module 4: Advanced Patterns →](./auto-pagination-04-advanced-patterns.md)
-
-Or dive deeper:
-- [Module 5: SDK Integration](./auto-pagination-05-sdk-integration.md) - Combine with other services
-- [Module 6: Troubleshooting](./auto-pagination-06-troubleshooting.md) - Fix common issues
-
----
-
-[← Back to Index](../../advanced-services/advanced-services-readme.md) | [← Previous: Quick Start](./auto-pagination-02-quick-start.md) | [Next: Advanced Patterns →](./auto-pagination-04-advanced-patterns.md)
+# Module 3: Configuration Mastery
+
+> **Learning Objective:** Master all pagination configuration options and learn entity-specific performance tuning strategies.
+>
+> **Level:** Intermediate
+
+## Table of Contents
+
+1. [Complete Configuration Reference](#complete-configuration-reference)
+2. `Safety Limits (OR-Logic)`
+3. [Entity-Specific Recommendations](#entity-specific-recommendations)
+4. [Progress Tracking](#progress-tracking)
+5. [Pagination Direction](#pagination-direction)
+6. [Delay and Rate Limiting](#delay-and-rate-limiting)
+7. [Connection Path](#connection-path)
+8. [Abort Signal](#abort-signal)
+9. [Performance Tuning Guide](#performance-tuning-guide)
+10. [Configuration Patterns](#configuration-patterns)
+
+---
+
+## Complete Configuration Reference
+
+```typescript
+interface PaginationConfig {
+  /** Enable/disable auto-pagination (default: auto-detected) */
+  enabled?: boolean;
+
+  /** Maximum pages to fetch (default: 100) */
+  maxPages?: number;
+
+  /** Maximum total records (default: 10,000) */
+  maxRecords?: number;
+
+  /** Timeout in milliseconds (default: 300,000 = 5 minutes) */
+  timeoutMs?: number;
+
+  /** Delay between page fetches in ms (default: 0) */
+  delayMs?: number;
+
+  /** Pagination direction (default: auto-detected) */
+  direction?: 'forward' | 'backward';
+
+  /** Path to connection in response (e.g., "order.items") */
+  connectionPath?: string;
+
+  /** AbortSignal to cancel pagination */
+  abortSignal?: AbortSignal;
+
+  /** Progress callback after each page */
+  onProgress?: (page: number, totalRecords: number) => void;
+
+  /** Warning callback for approaching limits */
+  onWarning?: (message: string) => void;
+}
+```
+
+---
+
+## Safety Limits (OR-Logic)
+
+**CRITICAL:** Pagination stops when **the first limit is reached** (OR-logic, not AND-logic).
+
+```typescript
+pagination: {
+  maxPages: 50,        // Stop after 50 pages
+  maxRecords: 5000,    // OR stop after 5000 records
+  timeoutMs: 60000,    // OR stop after 60 seconds
+}
+
+// Whichever limit is reached FIRST stops pagination!
+```
+
+### Example Scenarios
+
+| Scenario | Result |
+|----------|--------|
+| Page 45 with 4800 records | Continue (no limit reached) |
+| Page 50 with 4950 records | Stop (maxPages reached) |
+| Page 48 with 5100 records | Stop (maxRecords reached) |
+| 55 seconds elapsed, page 48 | Stop (timeoutMs reached) |
+
+### Checking Truncation
+
+```typescript
+const result = await client.graphql({
+  query,
+  variables: { first: 100 },
+  pagination: { maxPages: 50, maxRecords: 5000, timeoutMs: 60000 }
+});
+
+if (result.extensions.autoPagination.truncated) {
+  console.warn(`⚠️ Results truncated!`);
+  console.warn(`Reason: ${result.extensions.autoPagination.truncationReason}`);
+  // Possible values: "maxPages" | "maxRecords" | "timeout"
+}
+```
+
+---
+
+## Entity-Specific Recommendations
+
+Different Fluent entities have different complexities. Page size should match entity complexity:
+
+### Simple Entities (High Page Size)
+
+**Entities:** `virtualPositions`, `locations`, `inventoryQuantities`
+
+**Characteristics:**
+- Few fields
+- No nested connections
+- Simple scalar types
+
+**Recommended Configuration:**
+
+```typescript
+// ✅ OPTIMAL for simple entities
+pagination: {
+  maxPages: 100,
+  maxRecords: 10000,
+  timeoutMs: 120000  // 2 minutes
+}
+
+variables: {
+  first: 150  // Large page size OK
+}
+```
+
+**Example:**
+
+```typescript
+const positions = await client.graphql({
+  query: `
+    query GetVirtualPositions($first: Int!, $after: String) {
+      virtualPositions(first: $first, after: $after) {
+        edges {
+          node { id ref productRef quantity groupRef }
+          cursor
+        }
+        pageInfo { hasNextPage }
+      }
+    }
+  `,
+  variables: { first: 150 },  // High page size
+  pagination: {
+    maxPages: 100,
+    maxRecords: 15000,
+    timeoutMs: 120000
+  }
+});
+```
+
+### Medium Complexity Entities (Medium Page Size)
+
+**Entities:** `products`, `categories`, `carriers`
+
+**Characteristics:**
+- Multiple nested objects
+- Some arrays
+- Rich attribute data
+
+**Recommended Configuration:**
+
+```typescript
+// ✅ OPTIMAL for medium complexity
+pagination: {
+  maxPages: 50,
+  maxRecords: 5000,
+  timeoutMs: 180000  // 3 minutes
+}
+
+variables: {
+  first: 75  // Medium page size
+}
+```
+
+**Example:**
+
+```typescript
+const products = await client.graphql({
+  query: `
+    query GetProducts($first: Int!, $after: String) {
+      products(first: $first, after: $after) {
+        edges {
+          node {
+            id
+            ref
+            type
+            gtin
+            attributes { name type value }
+          }
+          cursor
+        }
+        pageInfo { hasNextPage }
+      }
+    }
+  `,
+  variables: { first: 75 },  // Medium page size
+  pagination: {
+    maxPages: 50,
+    maxRecords: 5000,
+    timeoutMs: 180000
+  }
+});
+```
+
+### Complex Entities (Low Page Size)
+
+**Entities:** `orders` (with items), `fulfilments` (with items), deeply nested queries
+
+**Characteristics:**
+- Multiple levels of nesting
+- Large arrays (order items)
+- Complex attribute structures
+
+**Recommended Configuration:**
+
+```typescript
+// ✅ OPTIMAL for complex entities
+pagination: {
+  maxPages: 30,
+  maxRecords: 1000,
+  timeoutMs: 240000,  // 4 minutes
+  delayMs: 100  // Rate limiting
+}
+
+variables: {
+  first: 20  // Small page size!
+}
+```
+
+**Example:**
+
+```typescript
+const orders = await client.graphql({
+  query: `
+    query GetOrders($first: Int!, $after: String) {
+      orders(first: $first, after: $after) {
+        edges {
+          node {
+            id
+            ref
+            status
+            items {
+              edges {
+                node {
+                  id
+                  ref
+                  productRef
+                  quantity
+                }
+              }
+            }
+          }
+          cursor
+        }
+        pageInfo { hasNextPage }
+      }
+    }
+  `,
+  variables: { first: 20 },  // Small page size for nested data
+  pagination: {
+    maxPages: 30,
+    maxRecords: 1000,
+    timeoutMs: 240000,
+    delayMs: 100
+  }
+});
+```
+
+---
+
+## Progress Tracking
+
+Monitor pagination progress with callbacks:
+
+```typescript
+const result = await client.graphql({
+  query,
+  variables: { first: 100 },
+  pagination: {
+    maxRecords: 10000,
+
+    // Called after each page fetch
+    onProgress: (page, totalRecords) => {
+      console.log(`📄 Page ${page}: ${totalRecords} records fetched`);
+
+      // Custom logic
+      if (page % 10 === 0) {
+        console.log(`Checkpoint: ${page} pages completed`);
+      }
+    },
+
+    // Called when approaching limits
+    onWarning: (message) => {
+      console.warn(`⚠️ ${message}`);
+    }
+  }
+});
+```
+
+### Advanced Progress Example
+
+```typescript
+let startTime = Date.now();
+
+const result = await client.graphql({
+  query,
+  variables: { first: 100 },
+  pagination: {
+    maxPages: 100,
+    onProgress: (page, totalRecords) => {
+      const elapsed = ((Date.now() - startTime) / 1000).toFixed(2);
+      const recordsPerSec = (totalRecords / (Date.now() - startTime) * 1000).toFixed(0);
+
+      process.stdout.write(
+        `\r📊 Page ${page} | Records: ${totalRecords} | ` +
+        `Time: ${elapsed}s | Rate: ${recordsPerSec} records/sec`
+      );
+    },
+    onWarning: (message) => {
+      console.warn(`\n⚠️ Warning: ${message}`);
+    }
+  }
+});
+
+console.log('\n✅ Complete!');
+```
+
+---
+
+## Pagination Direction
+
+### Forward Pagination (Default)
+
+Most common: fetch from beginning to end using `first` and `after`.
+
+```typescript
+// Forward pagination (default)
+const result = await client.graphql({
+  query: `
+    query GetItems($first: Int!, $after: String) {
+      items(first: $first, after: $after) {
+        edges { node { id ref } cursor }
+        pageInfo { hasNextPage }
+      }
+    }
+  `,
+  variables: { first: 100 },
+  pagination: {
+    direction: 'forward'  // Optional, auto-detected
+  }
+});
+```
+
+### Backward Pagination
+
+Fetch from end to beginning using `last` and `before`.
+
+```typescript
+// Backward pagination
+const result = await client.graphql({
+  query: `
+    query GetItems($last: Int!, $before: String) {
+      items(last: $last, before: $before) {
+        edges { node { id ref } cursor }
+        pageInfo { hasPreviousPage }
+      }
+    }
+  `,
+  variables: { last: 100 },
+  pagination: {
+    direction: 'backward',  // Required for backward
+    maxPages: 50
+  }
+});
+```
+
+---
+
+## Understanding Cursor Selection
+
+The SDK automatically selects the correct cursor based on pagination direction:
+
+### Forward Pagination (`first`/`after`)
+
+Uses **last edge cursor** from each page:
+
+```typescript
+// SDK automatically does this:
+const edges = result.data.items.edges;
+const nextCursor = edges[edges.length - 1].cursor;  // Last edge
+// Next request: { first: 100, after: nextCursor }
+```
+
+**Why:** Next page starts AFTER the last item fetched, moving forward through the dataset.
+
+### Backward Pagination (`last`/`before`)
+
+Uses **first edge cursor** from each page:
+
+```typescript
+// SDK automatically does this:
+const edges = result.data.items.edges;
+const nextCursor = edges[0].cursor;  // First edge
+// Next request: { last: 100, before: nextCursor }
+```
+
+**Why:** Previous page ends BEFORE the first item fetched, moving backward through the dataset.
+
+### Key Differences
+
+| Direction | Cursor Position | Traversal Direction | Use Case |
+|-----------|----------------|-------------------|----------|
+| **Forward** | Last edge | Start → End | Full dataset exports, chronological processing |
+| **Backward** | First edge | End → Start | Recent records, reverse chronological feeds |
+
+### Common Mistakes
+
+```typescript
+// ❌ WRONG: Using wrong cursor for direction
+// Forward pagination with first cursor
+const cursor = edges[0].cursor;  // Wrong!
+variables: { first: 100, after: cursor }
+
+// ❌ WRONG: Backward pagination with last cursor
+const cursor = edges[edges.length - 1].cursor;  // Wrong!
+variables: { last: 100, before: cursor }
+
+// ✅ CORRECT: SDK handles this automatically
+const result = await orchestrator.extract({
+  direction: 'forward',  // or 'backward'
+  // SDK picks correct cursor based on direction
+});
+```
+
+---
+
+## Delay and Rate Limiting
+
+Add delays between page fetches to respect rate limits:
+
+```typescript
+const result = await client.graphql({
+  query,
+  variables: { first: 100 },
+  pagination: {
+    maxPages: 100,
+    delayMs: 200  // Wait 200ms between each page
+  }
+});
+
+// Total time = (pages * delayMs) + (pages * requestTime)
+// Example: 50 pages * 200ms = 10 seconds of delays
+```
+
+### Use Cases for Delays
+
+| Use Case | delayMs | Reason |
+|----------|---------|--------|
+| **API Rate Limits** | 100-500 | Avoid 429 errors |
+| **Database Protection** | 200-300 | Reduce DB load |
+| **Concurrent Operations** | 100-200 | Prevent resource contention |
+| **Testing** | 1000+ | Simulate slow connections |
+| **No Rate Limits** | 0 | Maximum speed |
+
+---
+
+## Connection Path
+
+Specify which connection to paginate when multiple exist:
+
+### Auto-Detection (Default)
+
+```typescript
+// SDK automatically finds first connection
+const result = await client.graphql({
+  query: `
+    query GetData($first: Int!, $after: String) {
+      items(first: $first, after: $after) {
+        edges { node { id ref } cursor }
+        pageInfo { hasNextPage }
+      }
+    }
+  `,
+  variables: { first: 100 }
+  // connectionPath not needed - only one connection
+});
+```
+
+### Explicit Path (Multiple Connections)
+
+```typescript
+// Multiple connections - must specify which to paginate
+const result = await client.graphql({
+  query: `
+    query GetMultiple($first: Int!, $after: String) {
+      locations(first: $first, after: $after) {
+        edges { node { id ref name type } cursor }
+        pageInfo { hasNextPage }
+      }
+      products(first: $first, after: $after) {
+        edges { node { id ref type gtin } cursor }
+        pageInfo { hasNextPage }
+      }
+    }
+  `,
+  variables: { first: 100 },
+  pagination: {
+    connectionPath: 'locations'  // Paginate locations only
+  }
+});
+```
+
+### Nested Connection Path
+
+```typescript
+// Paginate nested connection
+const result = await client.graphql({
+  query: `
+    query GetOrder($orderId: ID!, $first: Int!, $after: String) {
+      order(id: $orderId) {
+        id
+        ref
+        items(first: $first, after: $after) {
+          edges { node { id ref productRef quantity } cursor }
+          pageInfo { hasNextPage }
+        }
+      }
+    }
+  `,
+  variables: { orderId: 'ORDER123', first: 50 },
+  pagination: {
+    connectionPath: 'order.items',  // Dot notation for nested
+    maxPages: 20
+  }
+});
+```
+
+---
+
+## Abort Signal
+
+Cancel pagination programmatically:
+
+```typescript
+const controller = new AbortController();
+
+// Start pagination
+const paginationPromise = client.graphql({
+  query,
+  variables: { first: 100 },
+  pagination: {
+    maxPages: 1000,
+    abortSignal: controller.signal
+  }
+});
+
+// Cancel after 10 seconds
+setTimeout(() => {
+  console.log('⏱️ Timeout reached, aborting pagination...');
+  controller.abort();
+}, 10000);
+
+try {
+  const result = await paginationPromise;
+} catch (error) {
+  if (error.name === 'AbortError') {
+    console.log('✅ Pagination aborted successfully');
+  }
+}
+```
+
+---
+
+## Performance Tuning Guide
+
+### Scenario 1: Maximum Speed
+
+```typescript
+// Goal: Fetch as fast as possible
+pagination: {
+  maxPages: 500,     // High limit
+  maxRecords: 50000, // High limit
+  timeoutMs: 600000, // 10 minutes
+  delayMs: 0         // No delays!
+}
+
+variables: {
+  first: 200  // Large pages
+}
+```
+
+### Scenario 2: Maximum Safety
+
+```typescript
+// Goal: Conservative, fail-safe operation
+pagination: {
+  maxPages: 20,      // Low limit
+  maxRecords: 2000,  // Low limit
+  timeoutMs: 30000,  // 30 seconds
+  delayMs: 100,      // Small delays
+  onWarning: (msg) => console.warn(msg)
+}
+
+variables: {
+  first: 50  // Small pages
+}
+```
+
+### Scenario 3: Background Job
+
+```typescript
+// Goal: Thorough, scheduled task
+pagination: {
+  maxPages: 200,
+  maxRecords: 20000,
+  timeoutMs: 600000,  // 10 minutes
+  delayMs: 50,
+  onProgress: (page, records) => {
+    if (page % 25 === 0) {
+      console.log(`Progress: ${records} records`);
+    }
+  }
+}
+
+variables: {
+  first: 100
+}
+```
+
+### Scenario 4: User-Facing API
+
+```typescript
+// Goal: Fast response for UI
+pagination: {
+  maxPages: 10,      // Quick return
+  maxRecords: 1000,
+  timeoutMs: 5000,   // 5 seconds max
+  delayMs: 0
+}
+
+variables: {
+  first: 100
+}
+```
+
+---
+
+## Configuration Patterns
+
+### Pattern 1: Progressive Loading with Checkpoints
+
+```typescript
+const checkpoint = { page: 0, records: 0 };
+
+const result = await client.graphql({
+  query,
+  variables: { first: 100 },
+  pagination: {
+    maxPages: 100,
+    onProgress: (page, records) => {
+      checkpoint.page = page;
+      checkpoint.records = records;
+
+      // Save checkpoint every 10 pages
+      if (page % 10 === 0) {
+        fs.writeFileSync('checkpoint.json', JSON.stringify(checkpoint));
+      }
+    }
+  }
+});
+```
+
+### Pattern 2: Adaptive Rate Limiting
+
+```typescript
+let delayMs = 0;
+const warnings: string[] = [];
+
+const result = await client.graphql({
+  query,
+  variables: { first: 100 },
+  pagination: {
+    maxPages: 100,
+    delayMs,
+    onWarning: (message) => {
+      warnings.push(message);
+
+      // Increase delay if getting warnings
+      if (warnings.length > 5) {
+        delayMs += 100;
+        console.log(`⚠️ Increasing delay to ${delayMs}ms due to warnings`);
+      }
+    }
+  }
+});
+```
+
+### Pattern 3: Time-Budgeted Pagination
+
+```typescript
+const timeBudgetMs = 60000;  // 1 minute budget
+const startTime = Date.now();
+
+const result = await client.graphql({
+  query,
+  variables: { first: 100 },
+  pagination: {
+    timeoutMs: timeBudgetMs,
+    maxRecords: 10000,
+    onProgress: (page, records) => {
+      const elapsed = Date.now() - startTime;
+      const remainingTime = timeBudgetMs - elapsed;
+      console.log(`⏱️ Remaining time: ${(remainingTime / 1000).toFixed(1)}s`);
+    }
+  }
+});
+
+if (result.extensions.autoPagination.truncated &&
+    result.extensions.autoPagination.truncationReason === 'timeout') {
+  console.log('⏰ Time budget exhausted - consider increasing timeout or page size');
+}
+```
+
+---
+
+## Summary: Quick Configuration Guide
+
+| Entity Type | first | maxPages | maxRecords | timeoutMs | delayMs |
+|-------------|-------|----------|------------|-----------|---------|
+| Simple (positions, locations) | 150 | 100 | 15000 | 120000 | 0 |
+| Medium (products, categories) | 75 | 50 | 5000 | 180000 | 0-50 |
+| Complex (orders with items) | 20 | 30 | 1000 | 240000 | 100 |
+| Testing/Dev | 50 | 5 | 500 | 10000 | 0 |
+| Production Export | 100 | 100 | 10000 | 300000 | 0 |
+| Background Job | 100 | 200 | 20000 | 600000 | 50 |
+| User-Facing API | 100 | 10 | 1000 | 5000 | 0 |
+
+---
+
+## Next Steps
+
+Now that you've mastered configuration, explore advanced query patterns:
+
+**Continue to:** [Module 4: Advanced Patterns →](./auto-pagination-04-advanced-patterns.md)
+
+Or dive deeper:
+- [Module 5: SDK Integration](./auto-pagination-05-sdk-integration.md) - Combine with other services
+- [Module 6: Troubleshooting](./auto-pagination-06-troubleshooting.md) - Fix common issues
+
+---
+
+[← Back to Index](../../advanced-services/advanced-services-readme.md) | [← Previous: Quick Start](./auto-pagination-02-quick-start.md) | [Next: Advanced Patterns →](./auto-pagination-04-advanced-patterns.md)